Add project type contract tests for GameFoundryStudio - PR_26152_080-project-type-contract-tests

ToolboxAid · ToolboxAid · commit 30d4331b66bc · 2026-06-02T12:49:09.000-04:00
diff --git a/docs/dev/reports/project_type_contract_tests_validation.md b/docs/dev/reports/project_type_contract_tests_validation.md
@@ -0,0 +1,58 @@
+# Project Type Contract Tests Validation
+
+PR: `PR_26152_080-project-type-contract-tests`
+
+## Scope
+
+- Added Project Type contract rules to `src/shared/contracts/projectContract.js`.
+- Updated Project contract fixtures and targeted contract tests.
+- Updated Project Workspace contract test fixture so Projects include `projectType`.
+- Added `docs/dev/specs/PROJECT_TYPE_CONTRACT.md`.
+
+No database, authentication, UI, CSS, HTML, or runtime page changes were made.
+
+## Contract Rules Validated
+
+- Every Project requires `projectType`.
+- Valid Project Types are accepted:
+  - `game`
+  - `asset-pack`
+  - `music-pack`
+  - `localization-pack`
+  - `template`
+  - `tutorial`
+- Invalid Project Types are rejected.
+- All Project Types still require owner.
+- All Project Types still require visibility.
+- Project Type determines expected outputs only.
+- Project Type does not bypass permissions.
+- Project Type does not create a different ownership model.
+- All Project Types share Project lifecycle and Project Workspace runtime-only model.
+
+## Validation Commands
+
+- `node tests/shared/ProjectContract.test.mjs` - PASS
+- `node tests/shared/ProjectWorkspaceRuntimeContract.test.mjs` - PASS
+- `node tests/shared/ToolStateContract.test.mjs` - PASS
+- `node tests/shared/IdentityPermissionsContract.test.mjs` - PASS
+- `$files = Get-ChildItem tests/shared/tools -Filter *.test.mjs | Sort-Object Name; foreach ($file in $files) { node $file.FullName; if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } }` - PASS, 36 tool contract tests ran
+- `git diff --check -- src/shared/contracts/projectContract.js tests/shared/ProjectContract.test.mjs tests/shared/ProjectWorkspaceRuntimeContract.test.mjs tests/fixtures/projects/project-scenarios.json docs/dev/specs/PROJECT_TYPE_CONTRACT.md` - PASS
+- `git diff --name-only -- '*.css' '*.html' '*.js' ':!src/shared/contracts/projectContract.js' ':!src/shared/contracts/projectWorkspaceRuntimeContract.js' ':!src/shared/contracts/tools/*.js'` - PASS, no output
+
+## Validation Lanes
+
+- Lanes executed: contract validation for Project Type, Project Workspace compatibility, Project, Tool State, Identity/Permissions, and Tool contracts.
+- Lanes skipped: runtime, integration, engine, samples, and recovery/UAT because this PR does not change runtime behavior, handoff contracts, engine surfaces, samples, or recovery behavior.
+- Samples decision: SKIP because this PR is limited to contract/docs/test surfaces.
+- Playwright impacted: No. This PR is contract/docs/test only and does not change UI or browser runtime behavior.
+
+## Expected PASS Behavior
+
+- Project contract rejects missing or invalid `projectType`.
+- Project contract accepts all approved Project Types.
+- Owner, visibility, permission, lifecycle, and Project Workspace behavior remain shared across all Project Types.
+- Existing Project Workspace, Tool State, Identity/Permissions, and Tool contract tests continue to pass.
+
+## Expected WARN Behavior
+
+- Git may report line-ending normalization warnings for existing working-copy files. These warnings do not indicate whitespace failures and did not fail `git diff --check`.
diff --git a/docs/dev/specs/PROJECT_TYPE_CONTRACT.md b/docs/dev/specs/PROJECT_TYPE_CONTRACT.md
@@ -0,0 +1,81 @@
+# Project Type Contract
+
+## Status
+
+This is a contract planning document for GameFoundryStudio Project Type behavior.
+
+It defines project type rules for persisted Project records before database, authentication, UI, runtime, publishing, marketplace, or storage implementation begins.
+
+This document does not authorize runtime changes, database implementation, authentication implementation, page changes, CSS changes, HTML changes, JavaScript changes, or schema migrations.
+
+## Project Type Values
+
+Approved first-pass Project Types:
+
+- `game`
+- `asset-pack`
+- `music-pack`
+- `localization-pack`
+- `template`
+- `tutorial`
+
+## Required Rules
+
+- Every Project requires a `projectType`.
+- Project is always the persisted ownership container.
+- Project Type determines expected outputs, not ownership behavior.
+- All Project Types share the same ownership model.
+- All Project Types share the same visibility model.
+- All Project Types share the same permissions model.
+- All Project Types share the same lifecycle model.
+- All Project Types share the same Project Workspace runtime-only model.
+
+## Expected Outputs
+
+| Project Type | Expected Outputs |
+| --- | --- |
+| `game` | Game Manifest, Release |
+| `asset-pack` | Asset outputs |
+| `music-pack` | Audio outputs, MIDI outputs |
+| `localization-pack` | Translation outputs |
+| `template` | Reusable starter content |
+| `tutorial` | Learning or community content |
+
+## Ownership Boundary
+
+Project Type does not create a separate ownership container.
+
+The Project remains the persisted ownership container for Project data, Tool States, project-owned assets, Game Manifest records, Releases, Marketplace Items, and other future child records unless a later object contract explicitly promotes separate ownership.
+
+## Visibility And Permissions Boundary
+
+Project Type does not bypass visibility or permissions.
+
+Private Projects remain private regardless of type.
+
+Collaborators, Viewers, Owners, Admins, Moderators, Reviewers, Players, and Guests continue to use the approved Identity/Permissions and Project contract rules.
+
+## Project Workspace Boundary
+
+Project Workspace remains runtime-only for every Project Type.
+
+Project Workspace may track active project, active tool, active tool state, dirty status, recovery availability, active palette context, and open/close/save flow state.
+
+Project Workspace does not persist tool payloads, own saved Tool State, duplicate Project storage, or create a separate Project Type storage model.
+
+## Non-Goals
+
+This document does not:
+
+- define SQL schema
+- define API routes
+- implement project persistence
+- implement authentication
+- implement authorization checks
+- implement Project Workspace storage
+- implement Admin pages
+- implement Account pages
+- implement publishing
+- implement marketplace behavior
+- change runtime behavior
+- change CSS, HTML, JavaScript, TypeScript, or JSON files outside the contract/test scope
diff --git a/src/shared/contracts/projectContract.js b/src/shared/contracts/projectContract.js
@@ -16,6 +16,24 @@ import {
 export const PROJECT_CONTRACT_ID = "gamefoundrystudio.project.lifecycle";
 export const PROJECT_CONTRACT_VERSION = "1.0.0";
 
+export const PROJECT_TYPES = Object.freeze({
+  GAME: "game",
+  ASSET_PACK: "asset-pack",
+  MUSIC_PACK: "music-pack",
+  LOCALIZATION_PACK: "localization-pack",
+  TEMPLATE: "template",
+  TUTORIAL: "tutorial",
+});
+
+export const PROJECT_TYPE_LIST = Object.freeze([
+  PROJECT_TYPES.GAME,
+  PROJECT_TYPES.ASSET_PACK,
+  PROJECT_TYPES.MUSIC_PACK,
+  PROJECT_TYPES.LOCALIZATION_PACK,
+  PROJECT_TYPES.TEMPLATE,
+  PROJECT_TYPES.TUTORIAL,
+]);
+
 export const PROJECT_STATES = Object.freeze({
   DRAFT: "draft",
   ACTIVE: "active",
@@ -78,6 +96,45 @@ export const PROJECT_RELATIONSHIP_LIST = Object.freeze([
   PROJECT_RELATIONSHIPS.MARKETPLACE_ITEMS,
 ]);
 
+export const PROJECT_TYPE_OUTPUTS = Object.freeze({
+  ASSET_OUTPUTS: "asset-outputs",
+  AUDIO_OUTPUTS: "audio-outputs",
+  MIDI_OUTPUTS: "midi-outputs",
+  TRANSLATION_OUTPUTS: "translation-outputs",
+  REUSABLE_STARTER_CONTENT: "reusable-starter-content",
+  LEARNING_COMMUNITY_CONTENT: "learning-community-content",
+});
+
+export const PROJECT_TYPE_EXPECTED_OUTPUTS = Object.freeze({
+  [PROJECT_TYPES.GAME]: Object.freeze([
+    PROJECT_RELATIONSHIPS.GAME_MANIFEST,
+    PROJECT_RELATIONSHIPS.RELEASES,
+  ]),
+  [PROJECT_TYPES.ASSET_PACK]: Object.freeze([
+    PROJECT_TYPE_OUTPUTS.ASSET_OUTPUTS,
+  ]),
+  [PROJECT_TYPES.MUSIC_PACK]: Object.freeze([
+    PROJECT_TYPE_OUTPUTS.AUDIO_OUTPUTS,
+    PROJECT_TYPE_OUTPUTS.MIDI_OUTPUTS,
+  ]),
+  [PROJECT_TYPES.LOCALIZATION_PACK]: Object.freeze([
+    PROJECT_TYPE_OUTPUTS.TRANSLATION_OUTPUTS,
+  ]),
+  [PROJECT_TYPES.TEMPLATE]: Object.freeze([
+    PROJECT_TYPE_OUTPUTS.REUSABLE_STARTER_CONTENT,
+  ]),
+  [PROJECT_TYPES.TUTORIAL]: Object.freeze([
+    PROJECT_TYPE_OUTPUTS.LEARNING_COMMUNITY_CONTENT,
+  ]),
+});
+
+export const PROJECT_TYPE_RULES = Object.freeze({
+  PROJECT_IS_PERSISTED_OWNERSHIP_CONTAINER: true,
+  PROJECT_TYPE_DETERMINES_EXPECTED_OUTPUTS_ONLY: true,
+  SHARES_OWNERSHIP_VISIBILITY_PERMISSIONS_LIFECYCLE: true,
+  SHARES_PROJECT_WORKSPACE_MODEL: true,
+});
+
 export const PROJECT_ROLE_PERMISSION_GRANTS = Object.freeze({
   [PROJECT_ROLES.OWNER]: Object.freeze([
     IDENTITY_PERMISSIONS.VIEW,
@@ -103,6 +160,8 @@ export const PROJECT_INACTIVE_STATES = Object.freeze([
 
 export const PROJECT_CONTRACT_ERRORS = Object.freeze({
   OWNER_REQUIRED: "PROJECT_OWNER_REQUIRED",
+  PROJECT_TYPE_REQUIRED: "PROJECT_TYPE_REQUIRED",
+  PROJECT_TYPE_INVALID: "PROJECT_TYPE_INVALID",
   VISIBILITY_REQUIRED: "PROJECT_VISIBILITY_REQUIRED",
   VISIBILITY_INVALID: "PROJECT_VISIBILITY_INVALID",
   STATE_REQUIRED: "PROJECT_STATE_REQUIRED",
@@ -115,6 +174,10 @@ export function isProjectState(value) {
   return PROJECT_STATE_LIST.includes(value);
 }
 
+export function isProjectType(value) {
+  return PROJECT_TYPE_LIST.includes(value);
+}
+
 export function isProjectRole(value) {
   return PROJECT_ROLE_LIST.includes(value);
 }
@@ -138,6 +201,20 @@ export function validateProjectContract(project) {
     ));
   }
 
+  if (!hasNonEmptyString(project?.projectType)) {
+    errors.push(createContractError(
+      PROJECT_CONTRACT_ERRORS.PROJECT_TYPE_REQUIRED,
+      "Project records require projectType.",
+      "projectType"
+    ));
+  } else if (!isProjectType(project.projectType)) {
+    errors.push(createContractError(
+      PROJECT_CONTRACT_ERRORS.PROJECT_TYPE_INVALID,
+      "Project type must be an allowed project type.",
+      "projectType"
+    ));
+  }
+
   if (!hasNonEmptyString(project?.visibility)) {
     errors.push(createContractError(
       PROJECT_CONTRACT_ERRORS.VISIBILITY_REQUIRED,
diff --git a/tests/fixtures/projects/project-scenarios.json b/tests/fixtures/projects/project-scenarios.json
@@ -5,6 +5,7 @@
       "project": {
         "id": "project.private.draft",
         "ownerId": "user.owner",
+        "projectType": "game",
         "state": "draft",
         "visibility": "private",
         "members": [
@@ -26,6 +27,7 @@
       "project": {
         "id": "project.public.published",
         "ownerId": "user.owner",
+        "projectType": "game",
         "state": "published",
         "visibility": "public",
         "members": [
@@ -43,6 +45,7 @@
       "project": {
         "id": "project.marketplace",
         "ownerId": "user.owner",
+        "projectType": "asset-pack",
         "state": "marketplace",
         "visibility": "public",
         "members": [],
@@ -56,16 +59,39 @@
       "name": "missing owner",
       "project": {
         "id": "project.missing.owner",
+        "projectType": "game",
         "state": "draft",
         "visibility": "private"
       },
       "expectedErrors": ["PROJECT_OWNER_REQUIRED"]
     },
+    {
+      "name": "missing project type",
+      "project": {
+        "id": "project.missing.type",
+        "ownerId": "user.owner",
+        "state": "draft",
+        "visibility": "private"
+      },
+      "expectedErrors": ["PROJECT_TYPE_REQUIRED"]
+    },
+    {
+      "name": "invalid project type",
+      "project": {
+        "id": "project.invalid.type",
+        "ownerId": "user.owner",
+        "projectType": "workspace",
+        "state": "active",
+        "visibility": "private"
+      },
+      "expectedErrors": ["PROJECT_TYPE_INVALID"]
+    },
     {
       "name": "missing visibility",
       "project": {
         "id": "project.missing.visibility",
         "ownerId": "user.owner",
+        "projectType": "game",
         "state": "active"
       },
       "expectedErrors": ["PROJECT_VISIBILITY_REQUIRED"]
@@ -75,6 +101,7 @@
       "project": {
         "id": "project.invalid.state",
         "ownerId": "user.owner",
+        "projectType": "game",
         "state": "deleted",
         "visibility": "private"
       },
@@ -85,6 +112,7 @@
       "project": {
         "id": "project.invalid.role",
         "ownerId": "user.owner",
+        "projectType": "game",
         "state": "active",
         "visibility": "project",
         "members": [
@@ -101,6 +129,7 @@
       "project": {
         "id": "project.invalid.relationship",
         "ownerId": "user.owner",
+        "projectType": "game",
         "state": "active",
         "visibility": "project",
         "relationships": ["tool-states", "database-table"]
diff --git a/tests/shared/ProjectContract.test.mjs b/tests/shared/ProjectContract.test.mjs
diff --git a/tests/shared/ProjectWorkspaceRuntimeContract.test.mjs b/tests/shared/ProjectWorkspaceRuntimeContract.test.mjs
