Force Workspace V2 export to manifest schema and block non-manifest session wrappers - PR_11_277

DavidQ · DavidQ · commit bdc26e240fbb · 2026-05-02T14:03:10.000-04:00
diff --git a/docs/dev/reports/PR_11_277_workspace_v2_manifest_only_export_enforcement_report.md b/docs/dev/reports/PR_11_277_workspace_v2_manifest_only_export_enforcement_report.md
@@ -0,0 +1,48 @@
+# PR_11_277 Workspace V2 Manifest-Only Export Enforcement Report
+
+## Scope
+Workspace V2 export/import only, plus minimal workspace manifest schema support required for Workspace V2 portable session persistence.
+
+## Files Changed
+- tools/workspace-v2/index.html
+- tools/workspace-v2/index.js
+- tools/schemas/workspace.manifest.schema.json
+- tests/runtime/V2CurrentSessionExport.test.mjs
+- docs/pr/PLAN_PR_11_277_WORKSPACE_V2_MANIFEST_ONLY_EXPORT_ENFORCEMENT.md
+- docs/pr/BUILD_PR_11_277_WORKSPACE_V2_MANIFEST_ONLY_EXPORT_ENFORCEMENT.md
+- docs/dev/reports/PR_11_277_workspace_v2_manifest_only_export_enforcement_report.md
+
+## Implementation Summary
+- Replaced Workspace V2 custom wrapper export (`version/toolId/workspaceSession`) with workspace manifest root export shape.
+- Added `workspaceV2Session` as a manifest-schema-approved session block for Workspace V2 portable session data.
+- Export path now validates manifest contract before download and blocks with explicit actionable messages if invalid.
+- Import path now accepts manifest-root payload and restores session data from `workspaceV2Session`.
+- Added explicit wrapper guard: `workspaceSession` root is rejected.
+- Kept Save/Load/Diff/Merge logic paths unchanged and preserved the same active-session source (`readActiveSessionPayloadForLibraryActions`).
+
+## Validation Commands Run
+1. `node --check tools/workspace-v2/index.js`
+   - PASS
+2. `node --check tests/runtime/V2CurrentSessionExport.test.mjs`
+   - PASS
+3. `node tests/runtime/V2CurrentSessionExport.test.mjs`
+   - PASS
+   - Results: `tmp/v2-current-session-export-results.json`
+
+## Manifest Contract Evidence
+- Export root shape is now workspace manifest fields (`documentKind/schema/version/id/name/tools`) with `workspaceV2Session`.
+- Export no longer emits `workspaceSession` wrapper.
+- Runtime validator blocks wrapper payloads and blocks runtime-only fields.
+- Export/import success path preserves active tool session payload under `workspaceV2Session.toolSessions`.
+
+## Save/Load/Diff/Merge Compatibility Note
+- Session library, diff, and merge action methods remain in Workspace V2 unchanged and still bind to the same active session source.
+- This PR only changed Workspace V2 export/import contract wiring and schema gating.
+
+## Additional Targeted Regression Notes
+- Existing broad standalone tests `V2SessionLibrary.test.mjs` and `V2SessionDiff.test.mjs` currently fail on pre-existing baseline token/contract expectations unrelated to PR_11_277 export/import contract changes.
+- `V2SessionMerge.test.mjs` passes.
+
+## Full Samples Smoke Decision
+- Skipped full samples smoke test.
+- Reason: scope is limited to Workspace V2 export/import and workspace manifest schema contract gating; targeted runtime validation covers the changed behavior.
diff --git a/docs/pr/BUILD_PR_11_277_WORKSPACE_V2_MANIFEST_ONLY_EXPORT_ENFORCEMENT.md b/docs/pr/BUILD_PR_11_277_WORKSPACE_V2_MANIFEST_ONLY_EXPORT_ENFORCEMENT.md
@@ -0,0 +1,38 @@
+# BUILD_PR_11_277_WORKSPACE_V2_MANIFEST_ONLY_EXPORT_ENFORCEMENT
+
+## Purpose
+Implement manifest-only export/import enforcement for Workspace V2 with schema-gated validation and no custom wrapper.
+
+## Files
+- tools/workspace-v2/index.html
+- tools/workspace-v2/index.js
+- tools/schemas/workspace.manifest.schema.json
+- tests/runtime/V2CurrentSessionExport.test.mjs
+- docs/dev/reports/PR_11_277_workspace_v2_manifest_only_export_enforcement_report.md
+
+## Implementation
+1. Replace Workspace V2 export builder from custom `{ version, toolId, workspaceSession }` wrapper to manifest-root document:
+   - `documentKind`, `schema`, `version`, `id`, `name`, `tools`
+   - `workspaceV2Session` payload block for Workspace V2 session persistence.
+2. Enforce export/import validation through one manifest-contract validator method in Workspace V2 before export download/import apply.
+3. Block export/import when wrapper payload is supplied (`workspaceSession` root), with explicit actionable message.
+4. Keep runtime-only fields blocked from portable export/import payloads.
+5. Import path reads manifest-root `workspaceV2Session` and restores sessionStorage/library + active payload.
+6. Update runtime test to assert:
+   - no custom wrapper
+   - manifest-root shape
+   - schema field presence for `workspaceV2Session`
+   - active payload preservation under `workspaceV2Session.toolSessions`.
+7. Add only minimal workspace manifest schema additions needed for Workspace V2 session persistence.
+
+## Acceptance
+- Workspace export root is manifest shape, not wrapper.
+- Export/import are blocked when manifest contract is invalid.
+- No `workspaceSession` wrapper is emitted.
+- Runtime-only fields are excluded from portable payload.
+- Save/Load/Diff/Merge remain operational under same session source.
+
+## Validation
+- `node --check tools/workspace-v2/index.js`
+- `node --check tests/runtime/V2CurrentSessionExport.test.mjs`
+- `node tests/runtime/V2CurrentSessionExport.test.mjs`
diff --git a/docs/pr/PLAN_PR_11_277_WORKSPACE_V2_MANIFEST_ONLY_EXPORT_ENFORCEMENT.md b/docs/pr/PLAN_PR_11_277_WORKSPACE_V2_MANIFEST_ONLY_EXPORT_ENFORCEMENT.md
@@ -0,0 +1,29 @@
+# PLAN_PR_11_277_WORKSPACE_V2_MANIFEST_ONLY_EXPORT_ENFORCEMENT
+
+## Purpose
+Enforce manifest-only Workspace V2 export/import so exported JSON is workspace manifest root shape, not a custom wrapper.
+
+## Scope
+- tools/workspace-v2/index.html
+- tools/workspace-v2/index.js
+- tools/schemas/workspace.manifest.schema.json (minimal Workspace V2 session field support only)
+- tests/runtime/V2CurrentSessionExport.test.mjs
+- docs/dev/reports/PR_11_277_workspace_v2_manifest_only_export_enforcement_report.md
+
+## Goals
+- Export root shape is workspace manifest (`documentKind/schema/version/id/name/tools`).
+- No `workspaceSession` wrapper export.
+- Workspace V2 session persistence lives in manifest-allowed field(s) only.
+- Export path validates manifest contract before download and blocks with actionable error when invalid.
+- Import accepts manifest-root shape and restores Workspace V2 tool sessions/saved sessions.
+- Save/Load/Diff/Merge flows remain intact (no behavioral rewrites).
+
+## Out Of Scope
+- No tool schema changes.
+- No non-Workspace-V2 behavior changes.
+- No platformShell/tools/shared rewiring.
+
+## Validation
+- `node --check tools/workspace-v2/index.js`
+- `node --check tests/runtime/V2CurrentSessionExport.test.mjs`
+- `node tests/runtime/V2CurrentSessionExport.test.mjs`
diff --git a/tests/runtime/V2CurrentSessionExport.test.mjs b/tests/runtime/V2CurrentSessionExport.test.mjs
@@ -67,11 +67,15 @@ function simulateWorkspaceModeExport(activePayload, currentHostContextId, librar
     toolSessions[payloadToolId][sessionId] = payload;
   });
   const container = {
-    version: "v2",
-    toolId: "workspace-v2",
-    workspaceSession: {
-      workspaceToolId: "workspace-v2",
-      workspaceSessionId: activeHostContextId,
+    $schema: "../../tools/schemas/workspace.manifest.schema.json",
+    documentKind: "workspace-manifest",
+    schema: "html-js-gaming.project",
+    version: 1,
+    id: `workspace-v2-${activeHostContextId || "session"}`,
+    name: "Workspace V2 Session Export",
+    tools: {},
+    workspaceV2Session: {
+      schema: "html-js-gaming.workspace-v2-session/1",
       defaultToolId: "palette-manager-v2",
       activeToolId,
       activeHostContextId,
@@ -94,6 +98,9 @@ export function run() {
   const workspaceJsExists = fs.existsSync(workspaceJsPath);
   const workspaceHtml = workspaceHtmlExists ? fs.readFileSync(workspaceHtmlPath, "utf8") : "";
   const workspaceJs = workspaceJsExists ? fs.readFileSync(workspaceJsPath, "utf8") : "";
+  const workspaceManifestSchema = JSON.parse(
+    fs.readFileSync(path.join(repoRoot, "tools", "schemas", "workspace.manifest.schema.json"), "utf8")
+  );
   const workspaceJsSyntax = checkSyntax(workspaceJsPath);
   const testSyntax = checkSyntax(testPath);
 
@@ -132,17 +139,33 @@ export function run() {
   const requiredWorkspaceJsTokens = [
     "importWorkspaceSessionJson()",
     "exportWorkspaceSessionJson()",
-    "buildPortableWorkspaceSessionContainer()",
+    "buildWorkspaceManifestDocument()",
+    "validateWorkspaceManifestDocument(",
+    "workspaceV2Session",
     "runtime-only fields are not allowed in portable workspace payload",
     "toolSessions",
-    "savedSessions"
+    "savedSessions",
+    "workspaceSession wrapper is not allowed"
   ];
   requiredWorkspaceJsTokens.forEach((token) => {
     if (!workspaceJs.includes(token)) {
       failures.push(`Missing required workspace contract JS token: ${token}`);
     }
   });
 
+  const requiredSessionFlowTokens = [
+    "saveNamedSession(",
+    "loadNamedSession(",
+    "computeSelectedSessionDiff(",
+    "computeSelectedSessionMerge(",
+    "readActiveSessionPayloadForLibraryActions()"
+  ];
+  requiredSessionFlowTokens.forEach((token) => {
+    if (!workspaceJs.includes(token)) {
+      failures.push(`Missing expected session flow token: ${token}`);
+    }
+  });
+
   TOOL_IDS.forEach((toolId) => {
     const toolHtmlPath = path.join(repoRoot, "tools", toolId, "index.html");
     const toolHtmlExists = fs.existsSync(toolHtmlPath);
@@ -181,24 +204,49 @@ export function run() {
   if (!workspaceExport.ok) failures.push("Workspace export should succeed when active payload exists.");
   const workspaceExportParsed = workspaceExport.serialized ? JSON.parse(workspaceExport.serialized) : null;
   if (!workspaceExportParsed || typeof workspaceExportParsed !== "object" || Array.isArray(workspaceExportParsed)) {
-    failures.push("Workspace export should be an object container.");
-  } else if (!workspaceExportParsed.workspaceSession || typeof workspaceExportParsed.workspaceSession !== "object") {
-    failures.push("Workspace export should include workspaceSession container.");
+    failures.push("Workspace export should be an object.");
   } else {
-    if (Object.prototype.hasOwnProperty.call(workspaceExportParsed.workspaceSession, "sessionHistory")) {
+    if (Object.prototype.hasOwnProperty.call(workspaceExportParsed, "workspaceSession")) {
+      failures.push("Workspace export must not include workspaceSession wrapper.");
+    }
+    if (workspaceExportParsed.documentKind !== "workspace-manifest") {
+      failures.push("Workspace export documentKind must be workspace-manifest.");
+    }
+    if (!workspaceExportParsed.workspaceV2Session || typeof workspaceExportParsed.workspaceV2Session !== "object") {
+      failures.push("Workspace export should include workspaceV2Session payload.");
+    }
+    if (!workspaceExportParsed.tools || typeof workspaceExportParsed.tools !== "object" || Array.isArray(workspaceExportParsed.tools)) {
+      failures.push("Workspace export should include tools object.");
+    }
+    const requiredSchemaKeys = Array.isArray(workspaceManifestSchema.required) ? workspaceManifestSchema.required : [];
+    requiredSchemaKeys.forEach((schemaKey) => {
+      if (!Object.prototype.hasOwnProperty.call(workspaceExportParsed, schemaKey)) {
+        failures.push(`Workspace export is missing required schema key: ${schemaKey}`);
+      }
+    });
+    if (!Object.prototype.hasOwnProperty.call(workspaceManifestSchema.properties || {}, "workspaceV2Session")) {
+      failures.push("workspace.manifest schema should define workspaceV2Session property.");
+    }
+    if (!workspaceManifestSchema.properties?.workspaceV2Session?.properties?.toolSessions) {
+      failures.push("workspace.manifest schema should define workspaceV2Session.toolSessions.");
+    }
+    if (!workspaceManifestSchema.properties?.workspaceV2Session?.properties?.savedSessions) {
+      failures.push("workspace.manifest schema should define workspaceV2Session.savedSessions.");
+    }
+    if (Object.prototype.hasOwnProperty.call(workspaceExportParsed.workspaceV2Session, "sessionHistory")) {
       failures.push("Workspace export must not include sessionHistory runtime field.");
     }
-    if (Object.prototype.hasOwnProperty.call(workspaceExportParsed.workspaceSession, "sessionSelection")) {
+    if (Object.prototype.hasOwnProperty.call(workspaceExportParsed.workspaceV2Session, "sessionSelection")) {
       failures.push("Workspace export must not include sessionSelection runtime field.");
     }
-    if (Object.prototype.hasOwnProperty.call(workspaceExportParsed.workspaceSession, "mergeAuditLog")) {
+    if (Object.prototype.hasOwnProperty.call(workspaceExportParsed.workspaceV2Session, "mergeAuditLog")) {
       failures.push("Workspace export must not include mergeAuditLog runtime field.");
     }
-    if (Object.prototype.hasOwnProperty.call(workspaceExportParsed.workspaceSession, "activeSessionPayload")) {
+    if (Object.prototype.hasOwnProperty.call(workspaceExportParsed.workspaceV2Session, "activeSessionPayload")) {
       failures.push("Workspace export must not include lone activeSessionPayload runtime field.");
     }
     const activeEntry =
-      workspaceExportParsed.workspaceSession.toolSessions?.["palette-manager-v2"]?.["palette-manager-v2-1234567890123-abcd1234"];
+      workspaceExportParsed.workspaceV2Session.toolSessions?.["palette-manager-v2"]?.["palette-manager-v2-1234567890123-abcd1234"];
     if (JSON.stringify(activeEntry) !== JSON.stringify(activePayload)) {
       failures.push("Workspace export should preserve active payload under toolSessions by tool/session id.");
     }
diff --git a/tools/schemas/workspace.manifest.schema.json b/tools/schemas/workspace.manifest.schema.json
@@ -32,7 +32,7 @@
     },
     "tools": {
       "type": "object",
-      "required": ["palette-browser"],
+      "required": [],
       "additionalProperties": false,
       "description": "Workspace-owned tool entry map keyed by canonical registry ids; payload schemas are referenced, never inlined here.",
       "properties": {
@@ -88,6 +88,111 @@
           "$ref": "./tools/3d-camera-path-editor.schema.json"
         }
       }
+    },
+    "workspaceV2Session": {
+      "type": "object",
+      "required": ["schema", "defaultToolId", "activeToolId", "activeHostContextId", "toolSessions", "savedSessions", "exportedAt"],
+      "additionalProperties": false,
+      "properties": {
+        "schema": {
+          "type": "string",
+          "const": "html-js-gaming.workspace-v2-session/1"
+        },
+        "defaultToolId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "activeToolId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "activeHostContextId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "toolSessions": {
+          "type": "object",
+          "additionalProperties": false,
+          "patternProperties": {
+            "^.*$": {
+              "type": "object",
+              "additionalProperties": false,
+              "patternProperties": {
+                "^.*$": {
+                  "$ref": "#/$defs/jsonValue"
+                }
+              },
+              "propertyNames": {
+                "type": "string"
+              }
+            }
+          },
+          "propertyNames": {
+            "type": "string"
+          }
+        },
+        "savedSessions": {
+          "type": "object",
+          "additionalProperties": false,
+          "patternProperties": {
+            "^.*$": {
+              "$ref": "#/$defs/jsonValue"
+            }
+          },
+          "propertyNames": {
+            "type": "string"
+          }
+        },
+        "exportedAt": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  },
+  "$defs": {
+    "jsonValue": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "integer"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        },
+        {
+          "$ref": "#/$defs/jsonArray"
+        },
+        {
+          "$ref": "#/$defs/jsonObject"
+        }
+      ]
+    },
+    "jsonArray": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/jsonValue"
+      }
+    },
+    "jsonObject": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^.*$": {
+          "$ref": "#/$defs/jsonValue"
+        }
+      },
+      "propertyNames": {
+        "type": "string"
+      }
     }
   }
 }
diff --git a/tools/workspace-v2/index.html b/tools/workspace-v2/index.html
@@ -37,7 +37,7 @@ <h2>Producer</h2>
         <h2>Import / Export Session JSON</h2>
         <p>Workspace mode actions (navWorkspace): import/export a portable Workspace V2 session manifest.</p>
         <label for="workspaceV2ImportJson">Workspace Session JSON</label>
-        <textarea id="workspaceV2ImportJson" rows="12" spellcheck="false" placeholder='{"version":"v2","toolId":"workspace-v2","workspaceSession":{}}'></textarea>
+        <textarea id="workspaceV2ImportJson" rows="12" spellcheck="false" placeholder='{"documentKind":"workspace-manifest","schema":"html-js-gaming.project","version":1,"id":"workspace-v2-session","name":"Workspace V2 Session","tools":{},"workspaceV2Session":{}}'></textarea>
         <label for="workspaceV2ImportFile">Import File</label>
         <input id="workspaceV2ImportFile" type="file" accept="application/json,.json" />
         <div>
diff --git a/tools/workspace-v2/index.js b/tools/workspace-v2/index.js
