Continue schema resolution and Workspace Manager game discovery stabilization - PR_26139_025-schema-regression-followup

Author: DavidQ

docs/dev/reports/PR_26139_025-schema-regression-followup_report.md

@@ -0,0 +1,44 @@
+# PR_26139_025-schema-regression-followup
+
+## Summary
+- Normalized Workspace Manager V2 schema reference loading through one recursive external `$ref` registry builder.
+- Updated game manifest and generated workspace manifest validation to resolve referenced tool schemas relative to their owning schema roots.
+- Removed the duplicate generated-workspace shallow validation plus separate tool-payload validation path.
+- Added a Workspace Manager V2 regression proving workspace schema refs validate `asset-manager-v2` and `palette-manager-v2` payloads without unresolved-ref errors.
+
+## Scope Notes
+- Changed only Workspace Manager V2 schema validation/discovery code and targeted Workspace Manager V2 Playwright coverage.
+- Tool schemas and game manifests were not changed.
+- Status-log spam cleanup was handled by removing the repeated validation path; no unrelated UI logging behavior was changed.
+
+## Validation
+- PASS: `npm run build:manifest`
+- PASS: `node scripts\validate-json-contracts.mjs --mode=games --details`
+  - `game_manifest_schema_validation: total=11 invalid=0`
+- PASS: `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs -g "resolves workspace manifest tool schema refs|resolves game manifest schema refs"`
+  - 2 passed.
+- PASS: `npm run test:workspace-v2`
+  - 58 passed.
+
+## Workspace Manager Checks
+- Select Repo path is covered by Workspace Manager V2 Playwright.
+- Game dropdown validation confirmed all 11 schema-valid games populate:
+  `AITargetDummy`, `Asteroids`, `Bouncing-ball`, `Breakout`, `GravityWell`, `Pacman`, `Pong`, `SolarSystem`, `SpaceDuel`, `SpaceInvaders`, `vector-arcade-sample`.
+- Regression assertions confirm no unresolved `asset-manager-v2.schema.json` or `palette-manager-v2.schema.json` refs appear during repo discovery.
+- Generated workspace validation now reports real schema failures for invalid Asset Manager V2 and Palette Manager V2 payload fields instead of unresolved schema refs.
+
+## Coverage
+- Playwright impacted: Yes.
+- V8 coverage report includes changed runtime JS:
+  `(93%) tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js - executed lines 1778/1778; executed functions 156/168`
+
+## Full Samples
+- Full samples smoke test was skipped.
+- Reason: scope is limited to Workspace Manager V2 schema validation/discovery stabilization; full Workspace V2 Playwright and all game manifest validation cover the impacted paths.
+
+## Manual Validation
+1. Open Workspace Manager V2.
+2. Click `Pick Repo Folder` and select the repo root.
+3. Confirm the Game dropdown populates with all schema-valid games, including `Asteroids` and `AITargetDummy`.
+4. Confirm the Status log has no unresolved `asset-manager-v2.schema.json` or `palette-manager-v2.schema.json` messages.
+5. Select `Asteroids` and confirm workspace JSON is generated and tools remain launchable.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -9968,6 +9968,47 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     }
   });
 
+  test("resolves workspace manifest tool schema refs from the workspace schema", async ({ page }) => {
+    const server = await openWorkspaceManagerV2(page);
+    const pageErrors = [];
+
+    page.on("pageerror", (error) => {
+      pageErrors.push(error.message);
+    });
+
+    try {
+      await selectMockRepo(page);
+      await page.locator("#activeGameSelect").selectOption("Asteroids");
+      await expect(page.locator("#workspaceContextOutput")).toHaveValue(/"gameId": "Asteroids"/);
+
+      const validation = await page.evaluate(async () => {
+        const app = window.__workspaceManagerV2App;
+        const validWorkspace = await app.contextService.validateGeneratedManifest(app.activeContext);
+        const invalidAssetWorkspace = structuredClone(app.activeContext);
+        invalidAssetWorkspace.tools["asset-manager-v2"].schemaRefProbe = true;
+        const invalidPaletteWorkspace = structuredClone(app.activeContext);
+        invalidPaletteWorkspace.tools["palette-manager-v2"].schemaRefProbe = true;
+        return {
+          asset: await app.contextService.validateGeneratedManifest(invalidAssetWorkspace),
+          palette: await app.contextService.validateGeneratedManifest(invalidPaletteWorkspace),
+          valid: validWorkspace
+        };
+      });
+
+      expect(validation.valid, validation.valid.message).toMatchObject({ ok: true });
+      expect(validation.asset.ok).toBe(false);
+      expect(validation.asset.message).toMatch(/root\.tools\.asset-manager-v2\.schemaRefProbe is not allowed/);
+      expect(validation.asset.message).not.toMatch(/unresolved schema reference/);
+      expect(validation.palette.ok).toBe(false);
+      expect(validation.palette.message).toMatch(/root\.tools\.palette-manager-v2\.schemaRefProbe is not allowed/);
+      expect(validation.palette.message).not.toMatch(/unresolved schema reference/);
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await coverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("uses header lifecycle controls and launches tools from fixed Workspace Manager V2 tiles", async ({ page }) => {
     const server = await openWorkspaceManagerV2(page);
     const pageErrors = [];

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

@@ -2,7 +2,6 @@
 const GAME_MANIFEST_SCHEMA_PATH = "/tools/schemas/game.manifest.schema.json";
 const WORKSPACE_MANIFEST_SCHEMA_PATH = "/tools/schemas/workspace.manifest.schema.json";
 const WORKSPACE_SESSION_SCHEMA_REF = "tools/schemas/workspace.manifest.schema.json";
-const OBJECT_VECTOR_STUDIO_V2_SCHEMA_PATH = "/tools/schemas/tools/object-vector-studio-v2.schema.json";
 const WORKSPACE_REPO_REFERENCE_SESSION_KEY = "workspace.repo.reference";
 const WORKSPACE_TOOL_SESSION_KEY_PREFIX = "workspace.tools.";
 const WORKSPACE_REPO_HANDLE_DB_NAME = "workspace-manager-v2-repo-handles";
@@ -320,6 +319,24 @@ function unsupportedFields(value, schema) {
     .filter((key) => !Object.prototype.hasOwnProperty.call(properties, key));
 }
 
+function collectExternalSchemaReferences(schema, refs = new Set()) {
+  if (Array.isArray(schema)) {
+    schema.forEach((entry) => collectExternalSchemaReferences(entry, refs));
+    return refs;
+  }
+  if (!isPlainObject(schema)) {
+    return refs;
+  }
+  if (typeof schema.$ref === "string") {
+    const [refPath] = schema.$ref.split("#");
+    if (refPath) {
+      refs.add(refPath);
+    }
+  }
+  Object.values(schema).forEach((entry) => collectExternalSchemaReferences(entry, refs));
+  return refs;
+}
+
 function resolvePointer(schema, pointer) {
   if (!pointer || pointer === "#") {
     return schema;
@@ -1290,12 +1307,47 @@ export class WorkspaceManagerV2ContextService {
       if (!isPlainObject(schema)) {
         return { ok: false, message: `${WORKSPACE_MANIFEST_SCHEMA_PATH} did not return a schema object.` };
       }
-      return { ok: true, schema };
+      const schemaRegistry = new Map();
+      registerSchemaReference(schemaRegistry, WORKSPACE_MANIFEST_SCHEMA_PATH, schema);
+      const referenceLoad = await this.loadSchemaReferences(schema, WORKSPACE_MANIFEST_SCHEMA_PATH, schemaRegistry);
+      if (!referenceLoad.ok) {
+        return referenceLoad;
+      }
+      return { ok: true, schema, schemaPath: WORKSPACE_MANIFEST_SCHEMA_PATH, schemaRegistry };
     } catch (error) {
       return { ok: false, message: `Unable to load ${WORKSPACE_MANIFEST_SCHEMA_PATH}: ${error.message}` };
     }
   }
 
+  async loadSchemaReferences(rootSchema, rootSchemaPath, schemaRegistry, loadedSchemas = new Map()) {
+    for (const schemaRef of collectExternalSchemaReferences(rootSchema)) {
+      const resolvedSchemaPath = resolveSchemaPathFromBase(rootSchemaPath, schemaRef);
+      if (!resolvedSchemaPath) {
+        return { ok: false, message: `Unable to resolve schema reference ${schemaRef} from ${rootSchemaPath}.` };
+      }
+      let referencedSchema = loadedSchemas.get(resolvedSchemaPath);
+      if (!referencedSchema) {
+        const fetchPath = `/${resolvedSchemaPath}`;
+        const schemaResponse = await this.fetchRef(fetchPath, { cache: "no-store" });
+        if (!schemaResponse.ok) {
+          return { ok: false, message: `Unable to load ${fetchPath}: ${schemaResponse.status}` };
+        }
+        referencedSchema = await schemaResponse.json();
+        if (!isPlainObject(referencedSchema)) {
+          return { ok: false, message: `${fetchPath} did not return a schema object.` };
+        }
+        loadedSchemas.set(resolvedSchemaPath, referencedSchema);
+        registerSchemaReference(schemaRegistry, resolvedSchemaPath, referencedSchema);
+        const nestedReferences = await this.loadSchemaReferences(referencedSchema, resolvedSchemaPath, schemaRegistry, loadedSchemas);
+        if (!nestedReferences.ok) {
+          return nestedReferences;
+        }
+      }
+      registerSchemaReference(schemaRegistry, schemaRef, referencedSchema, resolvedSchemaPath);
+    }
+    return { ok: true };
+  }
+
   async loadGameManifestSchema() {
     if (typeof this.fetchRef !== "function") {
       return { ok: false, message: "Fetch API is unavailable; Workspace Manager V2 cannot validate game manifests." };
@@ -1309,54 +1361,12 @@ export class WorkspaceManagerV2ContextService {
       if (!isPlainObject(schema)) {
         return { ok: false, message: `${GAME_MANIFEST_SCHEMA_PATH} did not return a schema object.` };
       }
-      const assetManagerSchemaPath = `/${TOOL_PAYLOAD_SCHEMA_REFS[ASSET_MANAGER_V2_TOOL_KEY]}`;
-      const assetManagerResponse = await this.fetchRef(assetManagerSchemaPath, { cache: "no-store" });
-      if (!assetManagerResponse.ok) {
-        return { ok: false, message: `Unable to load ${assetManagerSchemaPath}: ${assetManagerResponse.status}` };
-      }
-      const assetManagerSchema = await assetManagerResponse.json();
-      if (!isPlainObject(assetManagerSchema)) {
-        return { ok: false, message: `${assetManagerSchemaPath} did not return a schema object.` };
-      }
-      const paletteManagerSchemaPath = `/${TOOL_PAYLOAD_SCHEMA_REFS[PALETTE_MANAGER_V2_TOOL_KEY]}`;
-      const paletteManagerResponse = await this.fetchRef(paletteManagerSchemaPath, { cache: "no-store" });
-      if (!paletteManagerResponse.ok) {
-        return { ok: false, message: `Unable to load ${paletteManagerSchemaPath}: ${paletteManagerResponse.status}` };
-      }
-      const paletteManagerSchema = await paletteManagerResponse.json();
-      if (!isPlainObject(paletteManagerSchema)) {
-        return { ok: false, message: `${paletteManagerSchemaPath} did not return a schema object.` };
-      }
-      const objectVectorResponse = await this.fetchRef(OBJECT_VECTOR_STUDIO_V2_SCHEMA_PATH, { cache: "no-store" });
-      if (!objectVectorResponse.ok) {
-        return { ok: false, message: `Unable to load ${OBJECT_VECTOR_STUDIO_V2_SCHEMA_PATH}: ${objectVectorResponse.status}` };
-      }
-      const objectVectorSchema = await objectVectorResponse.json();
-      if (!isPlainObject(objectVectorSchema)) {
-        return { ok: false, message: `${OBJECT_VECTOR_STUDIO_V2_SCHEMA_PATH} did not return a schema object.` };
-      }
       const schemaRegistry = new Map();
-      registerSchemaReference(schemaRegistry, assetManagerSchemaPath, assetManagerSchema);
-      registerSchemaReference(schemaRegistry, TOOL_PAYLOAD_SCHEMA_REFS[ASSET_MANAGER_V2_TOOL_KEY], assetManagerSchema, assetManagerSchemaPath);
-      registerSchemaReference(schemaRegistry, "tools/asset-manager-v2.schema.json", assetManagerSchema, assetManagerSchemaPath);
-      registerSchemaReference(schemaRegistry, paletteManagerSchemaPath, paletteManagerSchema);
-      registerSchemaReference(schemaRegistry, TOOL_PAYLOAD_SCHEMA_REFS[PALETTE_MANAGER_V2_TOOL_KEY], paletteManagerSchema, paletteManagerSchemaPath);
-      registerSchemaReference(schemaRegistry, "tools/palette-manager-v2.schema.json", paletteManagerSchema, paletteManagerSchemaPath);
-      registerSchemaReference(schemaRegistry, OBJECT_VECTOR_STUDIO_V2_SCHEMA_PATH, objectVectorSchema);
-      registerSchemaReference(schemaRegistry, "tools/schemas/tools/object-vector-studio-v2.schema.json", objectVectorSchema, OBJECT_VECTOR_STUDIO_V2_SCHEMA_PATH);
-      registerSchemaReference(schemaRegistry, "tools/object-vector-studio-v2.schema.json", objectVectorSchema, OBJECT_VECTOR_STUDIO_V2_SCHEMA_PATH);
-      const text2SpeechSchemaPath = `/${TOOL_PAYLOAD_SCHEMA_REFS[TEXT2SPEECH_V2_TOOL_KEY]}`;
-      const text2SpeechResponse = await this.fetchRef(text2SpeechSchemaPath, { cache: "no-store" });
-      if (!text2SpeechResponse.ok) {
-        return { ok: false, message: `Unable to load ${text2SpeechSchemaPath}: ${text2SpeechResponse.status}` };
-      }
-      const text2SpeechSchema = await text2SpeechResponse.json();
-      if (!isPlainObject(text2SpeechSchema)) {
-        return { ok: false, message: `${text2SpeechSchemaPath} did not return a schema object.` };
+      registerSchemaReference(schemaRegistry, GAME_MANIFEST_SCHEMA_PATH, schema);
+      const referenceLoad = await this.loadSchemaReferences(schema, GAME_MANIFEST_SCHEMA_PATH, schemaRegistry);
+      if (!referenceLoad.ok) {
+        return referenceLoad;
       }
-      registerSchemaReference(schemaRegistry, text2SpeechSchemaPath, text2SpeechSchema);
-      registerSchemaReference(schemaRegistry, TOOL_PAYLOAD_SCHEMA_REFS[TEXT2SPEECH_V2_TOOL_KEY], text2SpeechSchema, text2SpeechSchemaPath);
-      registerSchemaReference(schemaRegistry, "tools/text2speech-V2.schema.json", text2SpeechSchema, text2SpeechSchemaPath);
       return { ok: true, schema, schemaPath: GAME_MANIFEST_SCHEMA_PATH, schemaRegistry };
     } catch (error) {
       return { ok: false, message: `Unable to load ${GAME_MANIFEST_SCHEMA_PATH}: ${error.message}` };
@@ -1387,83 +1397,12 @@ export class WorkspaceManagerV2ContextService {
       return schemaResult;
     }
     const workspaceContext = workspaceContextWithObjectVectorPayload(manifest);
-    const errors = this.validateManifestAgainstSchema(workspaceContext, schemaResult.schema);
-    if (!errors.length) {
-      const toolValidation = await this.validateToolPayloads(workspaceContext, schemaResult.schema);
-      errors.push(...toolValidation.errors);
-    }
+    const errors = validateSchemaValue(workspaceContext, schemaResult.schema, "root", schemaResult.schema, schemaResult.schemaRegistry, schemaResult.schemaPath);
     return errors.length
       ? { ok: false, message: `Generated Workspace Manager V2 manifest failed schema validation: ${errors.join(" | ")}` }
       : { ok: true };
   }
 
-  validateManifestAgainstSchema(manifest, schema) {
-    const errors = [];
-    if (!isPlainObject(manifest)) {
-      return ["root must be an object"];
-    }
-    missingRequiredFields(manifest, schema).forEach((key) => {
-      errors.push(`root.${key} is required`);
-    });
-    unsupportedFields(manifest, schema).forEach((key) => {
-      errors.push(`root.${key} is not allowed`);
-    });
-
-    if (!isPlainObject(manifest.tools)) {
-      errors.push("root.tools must be an object");
-      return errors;
-    }
-    const toolsSchema = schemaProperties(schema).tools || {};
-    const toolProperties = schemaProperties(toolsSchema);
-    missingRequiredFields(manifest.tools, toolsSchema).forEach((key) => {
-      errors.push(`root.tools.${key} is required`);
-    });
-    Object.keys(manifest.tools).forEach((key) => {
-      if (!Object.prototype.hasOwnProperty.call(toolProperties, key)) {
-        errors.push(`root.tools.${key} is not allowed`);
-      }
-    });
-    return errors;
-  }
-
-  async loadToolPayloadSchema(ref) {
-    if (typeof ref !== "string" || !ref.startsWith("./tools/")) {
-      return { ok: false, message: `Unsupported workspace manifest schema reference ${ref || "(empty)"}.` };
-    }
-    const schemaPath = `/tools/schemas/${ref.slice(2)}`;
-    try {
-      const response = await this.fetchRef(schemaPath, { cache: "no-store" });
-      if (!response.ok) {
-        return { ok: false, message: `Unable to load ${schemaPath}: ${response.status}` };
-      }
-      const schema = await response.json();
-      return isPlainObject(schema)
-        ? { ok: true, schema }
-        : { ok: false, message: `${schemaPath} did not return a schema object.` };
-    } catch (error) {
-      return { ok: false, message: `Unable to load ${schemaPath}: ${error.message}` };
-    }
-  }
-
-  async validateToolPayloads(manifest, workspaceSchema) {
-    const errors = [];
-    const toolsSchema = schemaProperties(workspaceSchema).tools || {};
-    const toolProperties = schemaProperties(toolsSchema);
-    for (const [toolKey, payload] of Object.entries(manifest.tools || {})) {
-      const toolSchemaRef = toolProperties[toolKey]?.$ref;
-      if (!toolSchemaRef) {
-        continue;
-      }
-      const toolSchemaResult = await this.loadToolPayloadSchema(toolSchemaRef);
-      if (!toolSchemaResult.ok) {
-        errors.push(toolSchemaResult.message);
-        continue;
-      }
-      errors.push(...validateSchemaValue(payload, toolSchemaResult.schema, `root.tools.${toolKey}`, toolSchemaResult.schema));
-    }
-    return { ok: errors.length === 0, errors };
-  }
-
   async fetchGameManifest(game) {
     const manifestResult = await this.fetchWorkspaceManifest(game.manifestPath);
     return manifestResult.ok