Flatten Object Vector Studio roles into object tags and restore Asteroids game discovery - PR_26133_121-object-vector-role-flatten-and-game-discovery

Author: DavidQ

docs/dev/reports/PR_26133_121-object-vector-role-flatten-and-game-discovery_report.md

@@ -0,0 +1,44 @@
+# PR_26133_121-object-vector-role-flatten-and-game-discovery
+
+## Summary
+- Flattened Asteroids Object Vector role ownership out of `vectorMaps.objectVectorRoles`.
+- Kept `objects[].shapes[]` as the Object Vector Studio V2 geometry SSoT.
+- Fixed Workspace Manager V2 game manifest validation so Asteroids is discovered in the Active Game dropdown.
+
+## Cleanup Decisions
+- Removed `object-vector-studio-v2.vectorMaps.objectVectorRoles` from `games/Asteroids/game.manifest.json`.
+- Kept the existing role tags on `objects[]` as the manifest-owned runtime role source.
+- Updated Asteroids role resolution to derive required runtime roles from `objects[].tags`.
+- Kept concrete object IDs for direct object identity checks such as `object.asteroids.bullet`, `object.asteroids.ship`, and attract object IDs.
+- Updated the Asteroids manifest loader to reject legacy `vectorMaps.objectVectorRoles` with an actionable error.
+- Removed Object Vector Studio V2 schema definitions for `objectVectorRoles` and role bindings.
+- Updated Object Vector Studio V2 delete cleanup so it no longer edits a removed role map.
+- Updated Workspace Manager V2's game manifest schema reference from the removed `vectorMapDocument` definition to `objectVectorShapeDocument`.
+- Updated Workspace Manager V2 summary fallback wording from old vector-map `vectors` to current `vectorMaps.shapes`.
+
+## Validation
+- Playwright impacted: Yes. This PR changes Workspace Manager V2 game discovery and Object Vector manifest loading.
+- PASS targeted Workspace Manager V2 game dropdown validation:
+  `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list -g "discovers Active Game options from selected repo manifests"`
+- PASS direct Workspace Manager V2 Asteroids manifest validation.
+- PASS direct Workspace Manager V2 game discovery includes Asteroids.
+- PASS targeted Asteroids tag-flatten manifest-load validation.
+- PASS targeted Object Vector Studio V2 tag-flatten manifest-load validation.
+- PASS `node -e "import('./tests/tools/ObjectVectorStudioV2DeleteCleanup.test.mjs').then(async (m) => { await m.run(); console.log('PASS ObjectVectorStudioV2DeleteCleanup'); })"`
+- PASS `node -e "import('./tests/games/AsteroidsValidation.test.mjs').then(async (m) => { await m.run(); console.log('PASS AsteroidsValidation'); })"`
+- PASS `node -e "import('./tests/games/AsteroidsVectorTransforms.test.mjs').then(async (m) => { await m.run(); console.log('PASS AsteroidsVectorTransforms'); })"`
+- PASS `node -e "import('./tests/games/AsteroidsAssetReferenceAdoption.test.mjs').then(async (m) => { await m.run(); console.log('PASS AsteroidsAssetReferenceAdoption'); })"`
+- PASS `node -e "import('./tests/games/AsteroidsPlatformDemo.test.mjs').then(async (m) => { await m.run(); console.log('PASS AsteroidsPlatformDemo'); })"`
+- PASS `node -e "import('./tests/games/AsteroidsPresentation.test.mjs').then(async (m) => { await m.run(); console.log('PASS AsteroidsPresentation'); })"`
+- PASS `node --check` for changed runtime, tool, schema-service, targeted test, and targeted Playwright files.
+- PASS JSON parse for changed manifest/schema JSON files.
+- PASS `git diff --check`.
+
+## Skipped
+- Full Workspace Manager V2 suite via `npm run test:workspace-v2` skipped in favor of the PR-requested targeted dropdown validation.
+- Full regression/full samples smoke test skipped per PR instructions.
+
+## Artifacts
+- Review diff: `docs/dev/reports/codex_review.diff`
+- Changed files report: `docs/dev/reports/codex_changed_files.txt`
+- Delta ZIP: `tmp/PR_26133_121-object-vector-role-flatten-and-game-discovery_delta.zip`

games/Asteroids/game.manifest.json

@@ -217,57 +217,6 @@
         "version": 1,
         "name": "Asteroids Object Vector Shape Roles",
         "source": "object-vector-studio-v2",
-        "objectVectorRoles": {
-          "bullet": {
-            "objectId": "object.asteroids.bullet",
-            "tags": [
-              "projectile",
-              "bullet"
-            ]
-          },
-          "ship": {
-            "objectId": "object.asteroids.ship",
-            "tags": [
-              "player",
-              "ship"
-            ]
-          },
-          "asteroidLarge": {
-            "objectId": "object.asteroids.large-asteroid",
-            "tags": [
-              "asteroid",
-              "large"
-            ]
-          },
-          "asteroidMedium": {
-            "objectId": "object.asteroids.medium-asteroid",
-            "tags": [
-              "asteroid",
-              "medium"
-            ]
-          },
-          "asteroidSmall": {
-            "objectId": "object.asteroids.small-asteroid",
-            "tags": [
-              "asteroid",
-              "small"
-            ]
-          },
-          "ufoLarge": {
-            "objectId": "object.asteroids.large-ufo",
-            "tags": [
-              "ufo",
-              "large"
-            ]
-          },
-          "ufoSmall": {
-            "objectId": "object.asteroids.small-ufo",
-            "tags": [
-              "ufo",
-              "small"
-            ]
-          }
-        },
         "shapes": []
       },
       "objects": [

games/Asteroids/game/AsteroidsGameScene.js

@@ -89,14 +89,13 @@ export default class AsteroidsGameScene extends Scene {
     this.objectVectorAssets = options.objectVectorAssets || null;
     this.objectVectorRuntime = options.objectVectorRuntime || null;
     this.vectorMaps = options.vectorMaps || null;
-    if (!this.vectorMaps?.objectVectorMapsById || !this.vectorMaps?.objectVectorRoles) {
+    if (!this.vectorMaps?.objectVectorMapsById || !this.vectorMaps?.objectsByRole) {
       const message = 'Asteroids Object Vector manifest validation failed: object geometry was not loaded from game.manifest.json.';
       console.error(message);
       throw new Error(message);
     }
     this.objectVectorRuntimeObjectValidation = this.objectVectorAssets
       ? validateAsteroidsRuntimeObjectRoles([...this.objectVectorAssets.objectsById.values()], {
-        roleBindings: this.vectorMaps.objectVectorRoles,
         logger: this.objectVectorRuntime,
       })
       : { errors: [], objectsByRole: {}, ok: false, warnings: [] };
@@ -110,7 +109,6 @@ export default class AsteroidsGameScene extends Scene {
     }
     this.asteroidGeometryProfiles = options.asteroidGeometryProfiles
       || createAsteroidGeometryProfilesFromObjectVectorAssets(this.objectVectorAssets, {
-        roleBindings: this.vectorMaps.objectVectorRoles,
         logger: this.objectVectorRuntime,
       });
     this.objectVectorPlaybackMs = 0;
@@ -860,7 +858,7 @@ export default class AsteroidsGameScene extends Scene {
   }
 
   objectVectorRoleOptions(roleId) {
-    return runtimeObjectRoleOptions(roleId, this.vectorMaps.objectVectorRoles);
+    return runtimeObjectRoleOptions(roleId);
   }
 
   drawLives(renderer, centerX, y, lives) {

games/Asteroids/game/asteroidsObjectVectorRoles.js

@@ -1,27 +1,34 @@
 export const ASTEROIDS_RUNTIME_OBJECT_ROLES = Object.freeze({
   bullet: Object.freeze({
     label: 'Bullet',
+    tags: Object.freeze(['projectile', 'bullet']),
   }),
   ship: Object.freeze({
     label: 'Ship',
+    tags: Object.freeze(['player', 'ship']),
   }),
   asteroidLarge: Object.freeze({
     label: 'Large Asteroid',
     size: 3,
+    tags: Object.freeze(['asteroid', 'large']),
   }),
   asteroidMedium: Object.freeze({
     label: 'Medium Asteroid',
     size: 2,
+    tags: Object.freeze(['asteroid', 'medium']),
   }),
   asteroidSmall: Object.freeze({
     label: 'Small Asteroid',
     size: 1,
+    tags: Object.freeze(['asteroid', 'small']),
   }),
   ufoLarge: Object.freeze({
     label: 'Large UFO',
+    tags: Object.freeze(['ufo', 'large']),
   }),
   ufoSmall: Object.freeze({
     label: 'Small UFO',
+    tags: Object.freeze(['ufo', 'small']),
   }),
 });
 
@@ -83,33 +90,29 @@ function logResolution(logger, level, message, details = {}) {
   logger[method]?.(message, details);
 }
 
-function roleBindingFor(roleBindings, roleId) {
-  return roleBindings && typeof roleBindings === 'object' && !Array.isArray(roleBindings)
-    ? roleBindings[roleId] || null
-    : null;
+function roleTags(roleId) {
+  return normalizeTags(ASTEROIDS_RUNTIME_OBJECT_ROLES[roleId]?.tags);
 }
 
-export function runtimeObjectRoleOptions(roleId, roleBindings = {}) {
+export function runtimeObjectRoleOptions(roleId) {
   const role = ASTEROIDS_RUNTIME_OBJECT_ROLES[roleId] || null;
-  const binding = roleBindingFor(roleBindings, roleId);
   if (!role) {
     return {
       objectId: '',
-      requireManifestBinding: true,
+      requireManifestBinding: false,
       runtimeRole: roleId,
       tags: [],
     };
   }
   return {
-    objectId: normalizeString(binding?.objectId),
-    requireManifestBinding: true,
+    objectId: '',
+    requireManifestBinding: false,
     runtimeRole: roleId,
-    tags: normalizeTags(binding?.tags),
+    tags: roleTags(roleId),
   };
 }
 
 export function resolveAsteroidsObjectVectorRole(objects, roleId, {
-  roleBindings = {},
   logger = null,
 } = {}) {
   const role = ASTEROIDS_RUNTIME_OBJECT_ROLES[roleId] || null;
@@ -119,93 +122,74 @@ export function resolveAsteroidsObjectVectorRole(objects, roleId, {
     return null;
   }
 
-  const binding = roleBindingFor(roleBindings, roleId);
-  const targetObjectId = normalizeString(binding?.objectId);
-  const targetTags = normalizeTags(binding?.tags);
-  const targetObject = targetObjectId
-    ? objectList.find((object) => object?.id === targetObjectId) || null
-    : null;
+  const targetTags = roleTags(roleId);
   const candidates = objectList
     .map((object, index) => ({
       index,
       object,
       oldSignal: oldObjectSignal(object),
     }))
     .filter((candidate) => candidate.object && (!targetTags.length || objectHasTags(candidate.object, targetTags)));
+  const oldCandidates = candidates.filter((candidate) => candidate.oldSignal);
+  const activeCandidates = candidates.filter((candidate) => !candidate.oldSignal);
 
-  if (!binding) {
+  if (!targetTags.length) {
     logResolution(
       logger,
       'FAIL',
-      `Asteroids Object Vector runtime role ${roleId} requires a manifest objectVectorRoles.${roleId} binding.`,
+      `Asteroids Object Vector runtime role ${roleId} does not define required object tags.`,
       {
-        candidates: candidates.map(candidateLabel),
         objectCount: objectList.length,
       }
     );
     return null;
   }
 
-  if (!targetObjectId) {
+  if (!candidates.length) {
     logResolution(
       logger,
       'FAIL',
-      `Asteroids Object Vector runtime role ${roleId} manifest binding is missing objectId.`,
+      `Asteroids Object Vector runtime role ${roleId} could not resolve an object from objects[].tags [${targetTags.join(', ')}].`,
       {
-        candidates: candidates.map(candidateLabel),
         objectCount: objectList.length,
+        targetTags,
       }
     );
     return null;
   }
 
-  if (!targetObject) {
+  if (oldCandidates.length) {
     logResolution(
       logger,
       'FAIL',
-      `Asteroids Object Vector runtime role ${roleId} manifest binding requires object ${targetObjectId} in root.tools.object-vector-studio-v2.objects.`,
+      `Asteroids Object Vector runtime role ${roleId} matches old/legacy object tag candidates [${targetTags.join(', ')}]; remove deprecated duplicates or retag them outside the active role.`,
       {
-        candidates: candidates.map(candidateLabel),
+        candidates: oldCandidates.map(candidateLabel),
         objectCount: objectList.length,
-        targetObjectId,
-      }
-    );
-    return null;
-  }
-
-  if (targetTags.length && !objectHasTags(targetObject, targetTags)) {
-    logResolution(
-      logger,
-      'FAIL',
-      `Asteroids Object Vector runtime role ${roleId} manifest binding ${targetObjectId} is missing required tags [${targetTags.join(', ')}].`,
-      {
-        candidates: candidates.map(candidateLabel),
-        objectTags: normalizeTags(targetObject.tags),
-        targetObjectId,
         targetTags,
       }
     );
     return null;
   }
 
-  if (oldObjectSignal(targetObject)) {
+  if (activeCandidates.length > 1) {
     logResolution(
       logger,
       'FAIL',
-      `Asteroids Object Vector runtime role ${roleId} manifest binding ${targetObjectId} is marked old/legacy; keep runtime object IDs on active Object Vector objects.`,
+      `Asteroids Object Vector runtime role ${roleId} matched multiple active objects from objects[].tags [${targetTags.join(', ')}].`,
       {
-        candidates: candidates.map(candidateLabel),
-        targetObjectId,
+        candidates: activeCandidates.map(candidateLabel),
+        objectCount: objectList.length,
+        targetTags,
       }
     );
     return null;
   }
 
-  return targetObject;
+  return activeCandidates[0].object;
 }
 
 export function validateAsteroidsRuntimeObjectRoles(objects, {
-  roleBindings = {},
   logger = null,
 } = {}) {
   const errors = [];
@@ -225,7 +209,6 @@ export function validateAsteroidsRuntimeObjectRoles(objects, {
 
   ASTEROIDS_REQUIRED_RUNTIME_OBJECT_ROLE_IDS.forEach((roleId) => {
     const object = resolveAsteroidsObjectVectorRole(objects, roleId, {
-      roleBindings,
       logger: collectingLogger,
     });
     if (object) {