Lock game manifest boundary between runtime game data and editor workspace state - PR_26128_008-game-workspace-boundary-contract

Author: DavidQ

docs/dev/reports/game_workspace_boundary_contract.md

@@ -0,0 +1,31 @@
+# PR_26128_008 Game Workspace Boundary Contract
+
+## Summary
+- Clarified the `game.manifest.json` boundary in `tools/schemas/game.manifest.schema.json`.
+- `game.gameData` is the runtime contract.
+- `game.workspace` is the editor/tool contract.
+- Runtime must ignore `game.workspace`.
+- Tools may read `game.gameData`.
+- Tools may write `game.workspace`.
+- Tools may update `game.gameData` only through explicit validated apply/build/export actions.
+
+## Validation Alignment
+- Workspace Manager V2 Active Game discovery still validates discovered `game.manifest.json` files with the dedicated game manifest schema.
+- `game.gameData.workspace` is rejected with an actionable validation reason because runtime data must not depend on editor/tool workspace state.
+- `game.gameData.tools` is rejected because editor/tool state belongs in `game.workspace`.
+- The existing Workspace Manager V2 launch/session payload remains workspace-shaped and is derived from `game.workspace`; session/toolState behavior was not changed.
+- Workspace Manager V2 now reports the boundary contract in the status log when a valid game manifest is selected or imported.
+
+## Scope Notes
+- No separate `workspace.manifest.json` was introduced.
+- No sample JSON was modified.
+- No roadmap content was modified.
+- No cross-tool communication was added.
+- Full samples smoke test was skipped because this BUILD explicitly requested targeted Workspace Manager V2 validation and to skip full samples smoke.
+
+## Validation
+- PASS: `node --check tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js`
+- PASS: `node --check tools/workspace-manager-v2/js/WorkspaceManagerV2App.js`
+- PASS: `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- PASS: JSON parse for `tools/schemas/game.manifest.schema.json`, `games/Asteroids/game.manifest.json`, `games/GravityWell/game.manifest.json`, and `games/Pong/game.manifest.json`
+- PASS: `npm run test:workspace-v2` - 11 passed

docs/dev/reports/playwright_game_workspace_boundary_contract.md

@@ -0,0 +1,22 @@
+# Playwright Game Workspace Boundary Contract
+
+## Command
+`npm run test:workspace-v2`
+
+## Result
+PASS: 11 passed
+
+## Targeted Coverage
+- Verified Workspace Manager V2 still launches from the tools index.
+- Verified Active Game starts empty and disabled before repo selection.
+- Verified Active Game still discovers schema-valid `game.manifest.json` files.
+- Verified `game.manifest.json` remains the only required game project manifest for Active Game discovery.
+- Verified `game.gameData` is present as the runtime lane.
+- Verified `game.workspace` is present as the editor/tool lane and remains nested under the game manifest.
+- Verified root game manifests do not expose root `documentKind` or root `tools` as runtime-required data.
+- Verified `game.gameData.workspace` is rejected with an actionable boundary validation message.
+- Verified the nested `game.workspace` payload still validates as the existing Workspace Manager V2 launch/session context.
+- Verified Workspace Manager V2 status reporting includes the boundary contract when a game manifest is selected or imported.
+
+## Skipped
+- Full samples smoke test was skipped as requested. The targeted Workspace Manager V2 Playwright suite covers the changed schema boundary, Active Game discovery, invalid-manifest logging, and affected launch/session paths.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -285,18 +285,21 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         const manifest = await fetch("/games/Asteroids/game.manifest.json", { cache: "no-store" }).then((response) => response.json());
         const { WorkspaceManagerV2ContextService } = await import("/tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js");
         const service = new WorkspaceManagerV2ContextService();
+        const invalidRuntimeWorkspaceManifest = structuredClone(manifest);
+        invalidRuntimeWorkspaceManifest.game.gameData.workspace = {};
         return {
           gameManifestValidation: await service.validateGameManifest(manifest),
           hasGameData: Boolean(manifest.game?.gameData),
           hasRootTools: Boolean(manifest.tools),
           hasWorkspace: Boolean(manifest.game?.workspace),
+          runtimeWorkspaceValidation: await service.validateGameManifest(invalidRuntimeWorkspaceManifest),
           rootDocumentKind: manifest.documentKind || "",
           schema: manifest.schema,
           workspaceDocumentKind: manifest.game?.workspace?.documentKind,
           workspaceValidation: await service.validateGeneratedManifest(manifest.game.workspace)
         };
       });
-      expect(asteroidsGameManifestShape).toEqual({
+      expect(asteroidsGameManifestShape).toMatchObject({
         gameManifestValidation: { ok: true },
         hasGameData: true,
         hasRootTools: false,
@@ -306,6 +309,8 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         workspaceDocumentKind: "workspace-manifest",
         workspaceValidation: { ok: true }
       });
+      expect(asteroidsGameManifestShape.runtimeWorkspaceValidation.ok).toBe(false);
+      expect(asteroidsGameManifestShape.runtimeWorkspaceValidation.message).toContain("runtime data must not depend on editor/tool workspace state");
 
       await page.evaluate(() => {
         window.__workspaceManagerV2MockRepoConfig = {
@@ -478,6 +483,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         { height: 142, width: 180 },
         { height: 142, width: 180 }
       ]);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Boundary contract: game\.gameData is runtime data; game\.workspace is editor\/tool state\. Runtime ignores game\.workspace; tools may read game\.gameData, write game\.workspace, and update game\.gameData only through explicit validated apply\/build\/export actions\./);
       await expect(page.locator("#statusLog")).toHaveValue(/OK Loaded Asteroids from \/games\/Asteroids\/game\.manifest\.json with 11 active palette colors and 14 managed assets\./);
 
       const downloadPromise = page.waitForEvent("download");
@@ -773,6 +779,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"id": "workspace-manager-v2-Asteroids-imported"/);
       await expect(page.locator("#activeAssetRegistrySummary")).toHaveCount(0);
       await expect(page.locator('[data-workspace-tool-id="asset-manager-v2"]')).toBeEnabled();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Boundary contract: game\.gameData is runtime data; game\.workspace is editor\/tool state\. Runtime ignores game\.workspace; tools may read game\.gameData, write game\.workspace, and update game\.gameData only through explicit validated apply\/build\/export actions\./);
       await expect(page.locator("#statusLog")).toHaveValue(/OK Imported schema-valid Workspace Manager V2 manifest workspace-manager-v2-Asteroids-imported\./);
 
       const downloadPromise = page.waitForEvent("download");

tools/schemas/game.manifest.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "tools/schemas/game.manifest.schema.json",
   "title": "Game Manifest",
-  "description": "Schema for games/**/game.manifest.json as the single source of truth. Runtime game data lives in game.gameData; editor and workspace state lives in game.workspace.",
+  "description": "Schema for games/**/game.manifest.json as the single source of truth. game.gameData is the runtime contract. game.workspace is the editor/tool contract. Runtime code must ignore game.workspace. Tools may read game.gameData, may write game.workspace, and may update game.gameData only through explicit validated apply/build/export actions.",
   "type": "object",
   "required": ["schema", "version", "game"],
   "additionalProperties": false,
@@ -38,9 +38,11 @@
           "pattern": "^[^/\\\\]+$"
         },
         "gameData": {
+          "description": "Runtime contract for data the game needs to run. Editor/tool workspace state must not be required from this object.",
           "$ref": "#/$defs/gameData"
         },
         "workspace": {
+          "description": "Editor/tool contract for workspace state needed to edit and build the game. Runtime code must ignore this object.",
           "$ref": "#/$defs/gameWorkspace"
         }
       }
@@ -49,8 +51,21 @@
   "$defs": {
     "gameData": {
       "type": "object",
+      "description": "Runtime-only game data. Tools may read this object; writes are limited to explicit validated apply/build/export actions.",
       "required": ["launch"],
       "additionalProperties": true,
+      "allOf": [
+        {
+          "not": {
+            "required": ["workspace"]
+          }
+        },
+        {
+          "not": {
+            "required": ["tools"]
+          }
+        }
+      ],
       "properties": {
         "launch": {
           "type": "object",
@@ -74,6 +89,7 @@
     },
     "gameWorkspace": {
       "type": "object",
+      "description": "Editor/tool workspace state. Tools may write this object; runtime data belongs in game.gameData.",
       "required": ["documentKind", "schema", "version", "id", "name", "gameId", "gameRoot", "assetsPath", "tools"],
       "additionalProperties": false,
       "properties": {

tools/workspace-manager-v2/js/WorkspaceManagerV2App.js

@@ -150,6 +150,9 @@ export class WorkspaceManagerV2App {
     if (result.assetWarning) {
       this.statusLog.info(`Warning: ${result.assetWarning}`);
     }
+    if (result.boundaryContract) {
+      this.statusLog.ok(result.boundaryContract);
+    }
     this.statusLog.ok(`Loaded ${result.game.name} from ${result.game.manifestPath} with ${result.paletteSwatches.length} active palette colors and ${result.assetCount} managed assets.`);
     this.statusLog.ok("Asset Manager V2 production launch context is session/state based only.");
   }
@@ -292,6 +295,9 @@ export class WorkspaceManagerV2App {
       if (result.assetWarning) {
         this.statusLog.info(`Warning: ${result.assetWarning}`);
       }
+      if (result.boundaryContract) {
+        this.statusLog.ok(result.boundaryContract);
+      }
       this.statusLog.ok(`Imported schema-valid Workspace Manager V2 manifest ${result.context.id}.`);
     } catch (error) {
       this.statusLog.fail(`Import Manifest failed: ${error.message}`);

tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js

@@ -104,6 +104,10 @@ function isGameManifest(value) {
     && isPlainObject(value.game.workspace);
 }
 
+function gameManifestBoundaryContractMessage() {
+  return "Boundary contract: game.gameData is runtime data; game.workspace is editor/tool state. Runtime ignores game.workspace; tools may read game.gameData, write game.workspace, and update game.gameData only through explicit validated apply/build/export actions.";
+}
+
 function schemaProperties(schema) {
   return isPlainObject(schema?.properties) ? schema.properties : {};
 }
@@ -407,6 +411,7 @@ export class WorkspaceManagerV2ContextService {
       },
       assetCount,
       assetWarning,
+      boundaryContract: game.manifestKind === "game-manifest" ? gameManifestBoundaryContractMessage() : "",
       paletteSwatches
     };
   }
@@ -456,7 +461,16 @@ export class WorkspaceManagerV2ContextService {
     }
     const errors = validateSchemaValue(manifest, schemaResult.schema, "root", schemaResult.schema);
     const gameInfo = manifest?.game || {};
+    const gameData = gameInfo.gameData || {};
     const workspace = gameInfo.workspace || {};
+    if (isPlainObject(gameData)) {
+      if (Object.prototype.hasOwnProperty.call(gameData, "workspace")) {
+        errors.push("root.game.gameData.workspace is not allowed; runtime data must not depend on editor/tool workspace state");
+      }
+      if (Object.prototype.hasOwnProperty.call(gameData, "tools")) {
+        errors.push("root.game.gameData.tools is not allowed; tool/editor state belongs in root.game.workspace");
+      }
+    }
     if (isPlainObject(gameInfo) && isPlainObject(workspace)) {
       const expectedGameRoot = `games/${gameInfo.folder}/`;
       const expectedAssetsPath = `games/${gameInfo.folder}/assets`;