Remove obsolete Workspace schema usage in favor of manifest toolState contract - PR_26140_054-remove-workspace-schema-usage

Author: DavidQ

docs/dev/PLAN_PR.md

@@ -1,7 +1,7 @@
 # PLAN_PR: Move JSON schemas under tools ownership
 
 ## Purpose
-Move schema contracts out of the repository root and into the tools area so schema ownership matches the systems that load, edit, validate, and export tool/workspace/sample data.
+Move schema contracts out of the repository root and into the tools area so schema ownership matches the systems that load, edit, validate, and export tool/sample data.
 
 ## Scope
 - Do not change runtime behavior directly.
@@ -15,7 +15,6 @@ Use this structure:
 ```text
 tools/
   schemas/
-    workspace.manifest.schema.json
     tool.manifest.schema.json
     palette.schema.json
     samples/
@@ -35,7 +34,6 @@ Tool-specific schemas live at `tools/schemas/tools/<tool>.schema.json`.
 ## Acceptance criteria
 - No new schema files are added at repository root.
 - All JSON schema files are under `tools/schemas/`.
-- Workspace manifest validation uses `tools/schemas/workspace.manifest.schema.json`.
 - Tool manifest validation uses `tools/schemas/tool.manifest.schema.json`.
 - Tool-specific payload validation uses `tools/schemas/tools/<tool>.schema.json`.
 - Samples reference the same tool schema contracts used by tool manifests.

docs/dev/PROJECT_INSTRUCTIONS.md

@@ -345,17 +345,17 @@ Every PR must document:
 
 ## WORKSPACE V2 CURRENT CONTRACT
 
-Workspace manifest is the runtime contract.
+Workspace manifest/toolState context is the runtime contract.
 
 Rules:
-- workspace manifest is SSoT
+- game manifest root.tools is SSoT for persisted tool payloads
 - no `workspaceSession`
 - no `games[]`
 - tools own all tool payloads
 - no tool payloads at manifest root
 - no hidden fallback data
 - no silent defaults
-- schema validation is the only acceptance gate
+- game manifest validation and toolState payload validation are the acceptance gates; no separate Workspace validation contract is required
 
 Palette:
 - exactly one active palette

docs/dev/bundle_readme.md

@@ -4,7 +4,7 @@ This ZIP is repo-structured and contains docs-first PR instructions only.
 
 Files:
 
-- `docs/dev/plan_pr_tool_workspace_schema_manifest_boundaries.md`
+- `docs/dev/plan_pr_tool_workspace_manifest_boundaries.md`
 - `docs/dev/codex_commands.md`
 - `docs/dev/commit_comment.txt`
 - `docs/dev/next_command.txt`

…_workspace_schema_manifest_boundaries.md …pr_tool_workspace_manifest_boundaries.mddocs/dev/plan_pr_tool_workspace_schema_manifest_boundaries.md renamed to docs/dev/plan_pr_tool_workspace_manifest_boundaries.md docs/dev/plan_pr_tool_workspace_schema_manifest_boundaries.md renamed to docs/dev/plan_pr_tool_workspace_manifest_boundaries.md

@@ -1,8 +1,8 @@
-# PLAN_PR: Tool / Workspace Schema + Manifest Boundary Cleanup
+# PLAN_PR: Tool / Workspace Manifest Boundary Cleanup
 
 ## Purpose
 
-Make tool data, sample data, workspace data, palette rules, and valid UI actions explicit through schemas and manifests instead of scattered validation code or hidden payload builders.
+Make tool data, sample data, workspace toolState data, palette rules, and valid UI actions explicit through tool schemas, game manifests, and manifest/toolState contract checks instead of scattered validation code or hidden payload builders.
 
 ## Scope
 
@@ -13,15 +13,15 @@ One PR only:
   - 3D Camera Path Editor legacy payload assumptions
   - 3D JSON payload normalizer legacy assumptions
   - Viewer assets being separately saved/exported outside manifests
-- Introduce actual `*.schema` files for tool/workspace/sample payload validation.
+- Introduce actual `*.schema` files for tool/sample payload validation and keep Workspace Manager context validation on the manifest/toolState contract.
 - Clarify palette behavior:
   - Samples use named palettes only.
   - Samples are locked and cannot mutate palettes.
   - Workspaces use duplicated palettes.
   - Once a workspace palette swatch is used, that palette cannot be replaced with a different palette.
   - Used workspace palettes may allow swatch edits only.
   - Other palettes may be viewed for reference/copying swatches into the selected workspace palette.
-- Put all workspace-owned assets in `workspace.manifest`.
+- Put workspace-owned game assets in the game manifest/toolState payloads.
 - Allow only exportable/rendered artifacts such as PNG files to be saved/exported outside the manifest.
 - Ensure UI buttons/actions are enabled by loaded context:
   - Tool-loaded context enables only tool-valid actions.
@@ -38,11 +38,11 @@ One PR only:
 
 ## Desired Manifest Shape
 
-Workspace:
+Workspace Manager toolState context:
 
 ```json
 {
-  "palette": {},
+  "gameId": "example-game",
   "tools": {
     "<tool>": {
       "tool data": {}
@@ -67,9 +67,9 @@ The sample payload shape should match the same tool schema used by the tool mani
 
 - `buildDefaultPayload` is no longer required for current tool/sample/workspace loading paths, or it is reduced to a compatibility shim with clear deprecation comments.
 - Each active tool has a dedicated schema file.
-- Workspace manifest has a schema file.
+- Workspace Manager context is validated by the current manifest/toolState contract, with tool payloads validated against their direct tool schemas.
 - Sample tool payloads validate against the same schema used by the corresponding tool.
-- Viewer/vector assets that belong to a workspace are stored inside `workspace.manifest`.
+- Viewer/vector assets that belong to a workspace are stored inside game manifest/toolState payloads.
 - PNG or rendered output remains exportable outside the manifest.
 - Samples are locked to named palettes and cannot mutate palette data.
 - Workspaces duplicate palettes and enforce swatch-use locking rules.

docs/dev/reports/workspace_schema_removal_report.md

@@ -0,0 +1,55 @@
+# Workspace Schema Removal Report
+
+PR: `PR_26140_054-remove-workspace-schema-usage`
+
+## Summary
+- Removed the active Workspace schema file and its runtime validation path.
+- Replaced Workspace schema acceptance with direct manifest/toolState contract checks.
+- Kept browser `sessionStorage` toolState sessions intact; only obsolete Workspace schema assumptions were removed.
+- Preserved Workspace Manager V2 and tool launch behavior.
+
+## Removed Active Workspace Schema Usage
+- Deleted `tools/schemas/workspace.manifest.schema.json`.
+- Removed `WORKSPACE_MANIFEST_SCHEMA_PATH`, `WORKSPACE_SESSION_SCHEMA_REF`, and `loadWorkspaceManifestSchema()` from Workspace Manager V2.
+- Removed root `$schema` emission from generated Workspace Manager contexts and template workspace manifests.
+- Removed `workspaceSchemaRef` from workspace-launched tool session metadata.
+- Removed Workspace schema fallback from launch-context-only tool sessions.
+- Removed the stale current-session Workspace schema export test path.
+- Renamed the Workspace schema boundary test to `ToolManifestBoundary` and updated it to guard against the removed schema file.
+
+## Current Acceptance Gates
+- Game manifests validate through `tools/schemas/game.manifest.schema.json`.
+- Workspace Manager V2 generated contexts validate through an explicit manifest/toolState contract check.
+- Tool payloads validate directly against their current tool schemas:
+  - `tools/schemas/tools/asset-manager-v2.schema.json`
+  - `tools/schemas/tools/object-vector-studio-v2.schema.json`
+  - `tools/schemas/tools/palette-manager-v2.schema.json`
+  - `tools/schemas/tools/text2speech-V2.schema.json`
+- Normalized workspace tool sessions keep the existing `schema`, `workspace`, `data`, and `dirty` shape.
+
+## ToolState Save/Load/Import/Export Confirmation
+- Workspace Manager V2 still hydrates enabled tool sessions into `sessionStorage`.
+- Tool return refresh still writes dirty toolState data back into the active Workspace Manager context.
+- Save still validates the game manifest and root `tools` toolState payloads before manifest write-back.
+- Text to Speech V2 empty-array save, return, relaunch, and manifest write-back passed targeted validation.
+- Text to Speech V2 summary now defaults to `[]`, matching its root-array payload contract during async relaunch.
+
+## Active Reference Audit
+- Active search for `workspace schema`, `workspaceSchemaRef`, `workspace.manifest.schema`, `schema-valid workspace`, `workspace manifest schema`, and `schema-only workspace` returned no matches outside excluded historical or out-of-scope locations.
+- Excluded locations were `node_modules`, `tests/results`, `docs/dev/reports`, `tmp`, `docs/pr`, `tools/schemas/docs`, `docs/dev/roadmaps`, and `samples`.
+- Roadmaps and sample JSON were intentionally left untouched.
+
+## Validation
+- PASS: targeted syntax/import validation for changed runtime, tool, script, and test files.
+- PASS: template workspace manifest JSON and game manifest schema JSON parse checks.
+- PASS: targeted `ToolManifestBoundary` Node validation.
+- PASS: targeted `ToolSchemaStrictModeValidation` Node validation.
+- PASS: targeted Text to Speech V2 workspace return/write-back Playwright validation.
+- PASS: `npm run test:workspace-v2` with 58 passed.
+- PASS: `git diff --check`.
+
+## Out Of Scope
+- Full samples smoke test was skipped as requested.
+- Sample JSON was not modified.
+- Roadmap text was not modified.
+- Historical schema docs under `tools/schemas/docs` and PR snapshots were not modified.

docs/dev/restart_notes_11_123.md

@@ -1,8 +1,8 @@
 # Restart Notes — PR 11.123
 
 Current issue:
-- Palette schema details were moved into workspace.manifest.schema.json.
-- Revert that. Workspace manifest should reference palette-browser schema, not contain palette internals.
+- Palette schema details were moved into the old Workspace validation contract.
+- Revert that. Workspace Manager should route palette payloads to the palette tool contract, not contain palette internals in a separate Workspace validation contract.
 
 Target boundary:
 - Workspace/game validates parent document only.

games/_template/workspace-manager-v2-UAT.manifest.json

@@ -1,5 +1,4 @@
 {
-  "$schema": "tools/schemas/workspace.manifest.schema.json",
   "documentKind": "workspace-manifest",
   "schema": "html-js-gaming.project",
   "version": 1,

games/_template/workspace-manager-v2-template.manifest.json

@@ -1,5 +1,4 @@
 {
-  "$schema": "tools/schemas/workspace.manifest.schema.json",
   "documentKind": "workspace-manifest",
   "schema": "html-js-gaming.project",
   "version": 1,

scripts/validate-json-contracts.mjs

@@ -551,55 +551,6 @@ function validateToolPayloadShallow(toolId, payload, schema, pointer) {
   return errors;
 }
 
-function validateWorkspaceManifestShallow(document, schemaIndex) {
-  const errors = [];
-  const workspaceSchemaPath = "tools/schemas/workspace.manifest.schema.json";
-  const workspaceSchema = schemaIndex.get(workspaceSchemaPath);
-  if (!workspaceSchema) {
-    return [`missing schema ${workspaceSchemaPath}`];
-  }
-  if (!isPlainObject(document)) {
-    return ["workspace manifest must be an object"];
-  }
-
-  const requiredTopLevel = new Set(Array.isArray(workspaceSchema.required) ? workspaceSchema.required : []);
-  const topLevelProps = isPlainObject(workspaceSchema.properties) ? workspaceSchema.properties : {};
-
-  Object.keys(document).forEach((key) => {
-    if (!(key in topLevelProps)) {
-      errors.push(`root.${key} is not allowed by workspace.manifest schema`);
-    }
-  });
-  requiredTopLevel.forEach((key) => {
-    if (!(key in document)) {
-      errors.push(`root.${key} is required by workspace.manifest schema`);
-    }
-  });
-
-  if (!isPlainObject(document.tools)) {
-    errors.push("root.tools must be an object");
-    return errors;
-  }
-
-  const toolsSchema = topLevelProps.tools;
-  const allowedToolIds = new Set(Object.keys(isPlainObject(toolsSchema?.properties) ? toolsSchema.properties : {}));
-  Object.keys(document.tools).forEach((toolId) => {
-    if (!allowedToolIds.has(toolId)) {
-      errors.push(`root.tools.${toolId} is not allowed by workspace.manifest schema`);
-      return;
-    }
-    const toolSchemaPath = schemaPathForToolId(toolId);
-    const toolSchema = schemaIndex.get(toolSchemaPath);
-    if (!toolSchema) {
-      errors.push(`missing schema for tool ${toolId}: ${toolSchemaPath}`);
-      return;
-    }
-    errors.push(...validateToolPayloadShallow(toolId, document.tools[toolId], toolSchema, `root.tools.${toolId}`));
-  });
-
-  return errors;
-}
-
 function validateSamples(schemaIndex, validate) {
   const sampleFiles = walkFiles(path.join(ROOT, "samples"), (filePath) => filePath.endsWith(".json"));
   const rows = [];
@@ -616,7 +567,8 @@ function validateSamples(schemaIndex, validate) {
     const isWorkspaceManifest = String(document?.documentKind || "").trim() === "workspace-manifest"
       || String(document?.schema || "").trim().toLowerCase() === "html-js-gaming.project";
     if (isWorkspaceManifest) {
-      schemaPath = "tools/schemas/workspace.manifest.schema.json";
+      rows.push({ filePath: rel, schemaPath: "", status: "skipped", errorCount: 0, firstErrors: "", note: "separate workspace validation contract removed; sample workspace JSON is out of scope" });
+      return;
     } else if (typeof document?.tool === "string") {
       schemaPath = schemaPathForToolId(document.tool);
     }
@@ -645,9 +597,7 @@ function validateSamples(schemaIndex, validate) {
       return document;
     })();
 
-    const errors = schemaPath === "tools/schemas/workspace.manifest.schema.json"
-      ? validateWorkspaceManifestShallow(normalizedDocument, schemaIndex)
-      : validate(normalizedDocument, schema, schemaPath, "$");
+    const errors = validate(normalizedDocument, schema, schemaPath, "$");
     rows.push({
       filePath: rel,
       schemaPath,

tests/playwright/tools/AssetManagerV2.spec.mjs

@@ -1371,7 +1371,7 @@ test.describe("Asset Manager V2", () => {
     try {
       await expect(page.locator("#assetLaunchGuard")).toBeVisible();
       await expect(page.locator("#assetLaunchGuardMessage")).toHaveText("Asset Manager V2 is only available through Workspace Manager with a game manifest and palette.");
-      await expect(page.locator("#assetLaunchGuardReason")).toContainText("Workspace Manager V2 launch requires a schema-valid workspace manifest.");
+      await expect(page.locator("#assetLaunchGuardReason")).toContainText("Workspace Manager V2 launch requires a valid manifest/toolState context.");
       await expect(page.locator("body")).toHaveClass(/asset-manager-v2--launch-blocked/);
       expect(pageErrors).toEqual([]);
     } finally {
@@ -1380,7 +1380,7 @@ test.describe("Asset Manager V2", () => {
     }
   });
 
-  test("launches Asset Manager V2 from Workspace Manager V2 with schema-valid context and workspace return nav", async ({ page }) => {
+  test("launches Asset Manager V2 from Workspace Manager V2 with valid manifest context and workspace return nav", async ({ page }) => {
     const server = await openWorkspaceManagerV2(page, {
       assetFiles: [
         {