Add shared object-model contract for DB-backed tool migration - PR_26161_002-db-object-model-contract

Author: ToolboxAid

docs_build/dev/reports/codex_changed_files.txt

@@ -1,28 +1,25 @@
 # git status --short
-M docs_build/dev/reports/codex_changed_files.txt
- M docs_build/dev/reports/codex_review.diff
- M docs_build/dev/reports/coverage_changed_js_guardrail.txt
+M docs_build/dev/reports/coverage_changed_js_guardrail.txt
  M docs_build/dev/reports/playwright_v8_coverage_report.txt
- M src/dev-runtime/guest-seeds/tool-metadata-inventory.js
- M tests/playwright/tools/RootToolsFutureState.spec.mjs
- M tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs
+ M tests/playwright/tools/ObjectsTool.spec.mjs
  M toolbox/objects/index.html
-?? docs_build/dev/reports/objects-beta-rebuild-report.md
-?? tests/playwright/tools/ObjectsTool.spec.mjs
-?? toolbox/objects/objects.js
+ M toolbox/objects/objects.js
+?? docs_build/dev/reports/db-object-model-contract-report.md
+?? src/engine/object-model/
+?? tests/engine/ObjectModelContract.test.mjs
 
 # git ls-files --others --exclude-standard
-docs_build/dev/reports/objects-beta-rebuild-report.md
-tests/playwright/tools/ObjectsTool.spec.mjs
-toolbox/objects/objects.js
+docs_build/dev/reports/db-object-model-contract-report.md
+src/engine/object-model/index.js
+src/engine/object-model/objectDefinitionSchema.js
+src/engine/object-model/objectDefinitionValidator.js
+src/engine/object-model/objectModelRegistry.js
+tests/engine/ObjectModelContract.test.mjs
 
 # git diff --stat
-docs_build/dev/reports/codex_changed_files.txt     |  35 +++--
- docs_build/dev/reports/codex_review.diff           | Bin 101630 -> 49857 bytes
- .../dev/reports/coverage_changed_js_guardrail.txt  |   6 +-
- .../dev/reports/playwright_v8_coverage_report.txt  |  19 +--
- .../guest-seeds/tool-metadata-inventory.js         |  24 +--
- .../playwright/tools/RootToolsFutureState.spec.mjs |  14 +-
- .../tools/ToolboxAdminMetadataSsot.spec.mjs        |  10 +-
- toolbox/objects/index.html                         | 174 ++++++++++++++++++++-
- 8 files changed, 224 insertions(+), 58 deletions(-)
+.../dev/reports/coverage_changed_js_guardrail.txt  |   6 +-
+ .../dev/reports/playwright_v8_coverage_report.txt  |  34 ++--
+ tests/playwright/tools/ObjectsTool.spec.mjs        |   7 +
+ toolbox/objects/index.html                         |  15 +-
+ toolbox/objects/objects.js                         | 179 +++++++++++++++++----
+ 5 files changed, 185 insertions(+), 56 deletions(-)

docs_build/dev/reports/codex_review.diff

@@ -7,7 +7,11 @@ Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 
 Changed runtime JS files considered:
 (0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(95%) toolbox/objects/objects.js - executed lines 365/365; executed functions 38/40
+(67%) src/engine/object-model/objectModelRegistry.js - executed lines 146/146; executed functions 4/6
+(70%) src/engine/object-model/objectDefinitionValidator.js - executed lines 269/269; executed functions 14/20
+(75%) src/engine/object-model/objectDefinitionSchema.js - executed lines 44/44; executed functions 3/4
+(94%) toolbox/objects/objects.js - executed lines 466/466; executed functions 58/62
+(100%) src/engine/object-model/index.js - executed lines 29/29; executed functions 1/1
 
 Guardrail warnings:
 (0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -0,0 +1,73 @@
+# PR_26161_002-db-object-model-contract Report
+
+## Branch Guard
+
+- Current branch: `main`
+- Expected branch: `main`
+- Local branches found: `main`
+- Branch validation: PASS
+
+## Scope Checklist
+
+- PASS: Read `docs_build/dev/PROJECT_INSTRUCTIONS.md` before BUILD execution.
+- PASS: Added shared object-model contract files under `src/engine/object-model/`.
+- PASS: Added object body/type registry for `Static`, `Dynamic`, `Collectible`, `Hazard`, and `Goal`.
+- PASS: Added trait registry for `movable`, `damageable`, `killable`, `playerControlled`, `bounces`, `collides`, `scores`, `collectible`, `hazard`, and `goal`.
+- PASS: Added object definition schema and validator for manifest/config-driven object definitions.
+- PASS: Validator returns visible, actionable issue objects with `code`, `path`, `message`, and `action`.
+- PASS: Validator rejects legacy names such as `objectStatic`, `objectDynamic`, and `objectKillable`; no legacy class hierarchy was restored.
+- PASS: Wired `toolbox/objects` to consume the shared object-model registry and validator instead of page-local type metadata.
+- PASS: Objects remains focused on static/dynamic paddle + ball MVP setup and visible diagnostics.
+- PASS: Theme V2 restrictions preserved; no inline CSS, inline JS, script blocks, style blocks, or inline event handlers were added.
+- PASS: No persistence, auth, sample JSON alignment, DB write behavior, or new engine runtime behavior was added.
+- PASS: No Toolbox/Admin metadata was changed in this PR.
+
+## Implementation Evidence
+
+- `src/engine/object-model/objectModelRegistry.js` owns the shared object body/type registry and trait registry.
+- `src/engine/object-model/objectDefinitionSchema.js` owns the object definition schema metadata.
+- `src/engine/object-model/objectDefinitionValidator.js` validates definitions, rejects unknown fields/types/traits, rejects duplicate traits, and preserves incoming payloads without mutation.
+- `src/engine/object-model/index.js` exports the shared contract.
+- `toolbox/objects/objects.js` imports the shared registry/validator, renders object type and trait basics from the registry, derives MVP traits for draft rows, and validates draft/list definitions through the shared validator.
+- `tests/engine/ObjectModelContract.test.mjs` covers registry membership, schema enum alignment, valid payload cloning/no mutation, actionable invalid diagnostics, and legacy type rejection.
+- `tests/playwright/tools/ObjectsTool.spec.mjs` now verifies shared trait registry visibility and trait-backed MVP seeded output.
+
+## Validation
+
+- PASS: `node --check src\engine\object-model\objectModelRegistry.js`
+- PASS: `node --check src\engine\object-model\objectDefinitionSchema.js`
+- PASS: `node --check src\engine\object-model\objectDefinitionValidator.js`
+- PASS: `node --check src\engine\object-model\index.js`
+- PASS: `node --check toolbox\objects\objects.js`
+- PASS: `node --check tests\engine\ObjectModelContract.test.mjs`
+- PASS: `node --check tests\playwright\tools\ObjectsTool.spec.mjs`
+- PASS: `node .\scripts\run-node-test-files.mjs tests\engine\ObjectModelContract.test.mjs`
+- PASS: `npx playwright test tests/playwright/tools/ObjectsTool.spec.mjs`
+- PASS: `Select-String -Path toolbox\objects\index.html -Pattern '<style\b','\son[a-z]+\s*=','<script(?![^>]*\bsrc=)'` returned no matches.
+- PASS: `git diff --check`
+
+Note: an initial Playwright invocation used a Windows backslash path and returned `No tests found`; the corrected forward-slash path above matched and passed both targeted Objects tests.
+
+## Playwright V8 Coverage
+
+- PASS: `docs_build/dev/reports/playwright_v8_coverage_report.txt` was regenerated by the targeted Objects Playwright run.
+- PASS: Changed PR_002 runtime JS covered by Playwright V8:
+  - `src/engine/object-model/index.js`
+  - `src/engine/object-model/objectDefinitionSchema.js`
+  - `src/engine/object-model/objectDefinitionValidator.js`
+  - `src/engine/object-model/objectModelRegistry.js`
+  - `toolbox/objects/objects.js`
+- WARN: The coverage helper also reported `src/dev-runtime/guest-seeds/tool-metadata-inventory.js` from its HEAD-change detection path. That file is not modified in this PR working diff, and no Toolbox/Admin metadata behavior was changed here.
+
+## Skipped Lanes
+
+- SKIP: Full samples validation. Safe to skip because this PR does not touch sample JSON, sample launch flows, or sample runtime contracts.
+- SKIP: Toolbox/Admin metadata Playwright. Safe to skip because no tool metadata file changed in this PR.
+- SKIP: Broad engine/runtime suites. Safe to skip because the new object-model module is an authoring contract and validator only; runtime object instantiation and parser behavior were not changed.
+- SKIP: Auth, persistence, and DB adapter tests. Safe to skip because this PR adds no persistence/auth behavior and performs no DB writes.
+
+## Manual Notes
+
+- Objects still uses the First-Class Tool V2 surface and Theme V2 CSS.
+- Object type choices and visible type/trait registry lists are generated from `src/engine/object-model/`.
+- The MVP seeded path remains in-memory only and validates as ready with a Dynamic paddle, Dynamic ball, and Static boundary.

docs_build/dev/reports/db-object-model-contract-report.md

@@ -12,32 +12,40 @@ Note: entry percentages use function coverage when available, otherwise line cov
 Note: coverage entries are aggregated across every page/tool where coverageReporter.start(page) and coverageReporter.stop(page) ran.
 
 Exercised tool entry points detected:
-(88%) Toolbox Index - exercised 4 runtime JS files
+(88%) Toolbox Index - exercised 2 runtime JS files
 (0%) Tool Template V2 - not exercised by this Playwright run
-(74%) Theme V2 Shared JS - exercised 2 runtime JS files
+(59%) Theme V2 Shared JS - exercised 2 runtime JS files
 
 Changed runtime JS files covered:
 (0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(95%) toolbox/objects/objects.js - executed lines 365/365; executed functions 38/40
+(67%) src/engine/object-model/objectModelRegistry.js - executed lines 146/146; executed functions 4/6
+(70%) src/engine/object-model/objectDefinitionValidator.js - executed lines 269/269; executed functions 14/20
+(75%) src/engine/object-model/objectDefinitionSchema.js - executed lines 44/44; executed functions 3/4
+(94%) toolbox/objects/objects.js - executed lines 466/466; executed functions 58/62
+(100%) src/engine/object-model/index.js - executed lines 29/29; executed functions 1/1
 
 Files with executed line/function counts where available:
-(38%) src/engine/api/session-api-client.js - executed lines 34/34; executed functions 3/8
-(50%) src/engine/api/toolbox-votes-api-client.js - executed lines 46/46; executed functions 3/6
-(53%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 10/19
+(36%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 5/14
+(58%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 603/603; executed functions 30/52
 (64%) assets/theme-v2/js/tool-display-mode.js - executed lines 209/209; executed functions 9/14
-(77%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 603/603; executed functions 43/56
-(78%) admin/tool-votes.js - executed lines 406/406; executed functions 43/55
-(84%) toolbox/tools-page-accordions.js - executed lines 965/965; executed functions 92/109
-(89%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 25/28
-(95%) toolbox/objects/objects.js - executed lines 365/365; executed functions 38/40
-(100%) toolbox/project-workspace/project-workspace-api-client.js - executed lines 12/12; executed functions 2/2
+(67%) src/engine/object-model/objectModelRegistry.js - executed lines 146/146; executed functions 4/6
+(70%) src/engine/object-model/objectDefinitionValidator.js - executed lines 269/269; executed functions 14/20
+(75%) src/engine/object-model/objectDefinitionSchema.js - executed lines 44/44; executed functions 3/4
+(75%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 21/28
+(94%) toolbox/objects/objects.js - executed lines 466/466; executed functions 58/62
+(100%) src/engine/object-model/index.js - executed lines 29/29; executed functions 1/1
 
 Uncovered or low-coverage changed JS files:
 (0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: uncovered changed runtime JS file; advisory only
 
 Changed JS files considered:
 (0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - changed JS file not collected as browser runtime coverage
+(0%) tests/engine/ObjectModelContract.test.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/playwright/tools/ObjectsTool.spec.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/playwright/tools/RootToolsFutureState.spec.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs - changed JS file not collected as browser runtime coverage
-(95%) toolbox/objects/objects.js - changed JS file with browser V8 coverage
+(67%) src/engine/object-model/objectModelRegistry.js - changed JS file with browser V8 coverage
+(70%) src/engine/object-model/objectDefinitionValidator.js - changed JS file with browser V8 coverage
+(75%) src/engine/object-model/objectDefinitionSchema.js - changed JS file with browser V8 coverage
+(94%) toolbox/objects/objects.js - changed JS file with browser V8 coverage
+(100%) src/engine/object-model/index.js - changed JS file with browser V8 coverage

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -0,0 +1,32 @@
+/*
+Toolbox Aid
+David Quesenberry
+06/10/2026
+index.js
+*/
+
+export {
+  OBJECT_MODEL_TRAIT_IDS,
+  OBJECT_MODEL_TRAIT_LIST,
+  OBJECT_MODEL_TRAIT_REGISTRY,
+  OBJECT_MODEL_TYPE_IDS,
+  OBJECT_MODEL_TYPE_LIST,
+  OBJECT_MODEL_TYPE_REGISTRY,
+  getObjectModelTrait,
+  getObjectModelType,
+  isObjectModelTrait,
+  isObjectModelType,
+} from "./objectModelRegistry.js";
+
+export {
+  OBJECT_DEFINITION_SCHEMA,
+  OBJECT_DEFINITION_SCHEMA_ID,
+  OBJECT_DEFINITION_SCHEMA_VERSION,
+  getObjectDefinitionSchema,
+} from "./objectDefinitionSchema.js";
+
+export {
+  OBJECT_DEFINITION_VALIDATION_CODES,
+  validateObjectDefinition,
+  validateObjectDefinitionList,
+} from "./objectDefinitionValidator.js";

src/engine/object-model/index.js

@@ -0,0 +1,49 @@
+/*
+Toolbox Aid
+David Quesenberry
+06/10/2026
+objectDefinitionSchema.js
+*/
+
+import { OBJECT_MODEL_TRAIT_LIST, OBJECT_MODEL_TYPE_LIST } from "./objectModelRegistry.js";
+
+export const OBJECT_DEFINITION_SCHEMA_ID = "gamefoundrystudio.object-model.definition/1";
+export const OBJECT_DEFINITION_SCHEMA_VERSION = 1;
+
+const OBJECT_MODEL_TYPE_ENUM = Object.freeze(OBJECT_MODEL_TYPE_LIST.map((objectType) => objectType.id));
+const OBJECT_MODEL_TRAIT_ENUM = Object.freeze(OBJECT_MODEL_TRAIT_LIST.map((trait) => trait.id));
+const OBJECT_DEFINITION_STATE_ENUM = Object.freeze(["Active", "Idle", "Disabled"]);
+
+export const OBJECT_DEFINITION_SCHEMA = Object.freeze({
+  $id: OBJECT_DEFINITION_SCHEMA_ID,
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  additionalProperties: false,
+  properties: Object.freeze({
+    behavior: Object.freeze({ type: "string" }),
+    id: Object.freeze({ minLength: 1, type: "string" }),
+    interaction: Object.freeze({ type: "string" }),
+    name: Object.freeze({ minLength: 1, type: "string" }),
+    role: Object.freeze({ type: "string" }),
+    state: Object.freeze({ enum: OBJECT_DEFINITION_STATE_ENUM, type: "string" }),
+    traits: Object.freeze({
+      items: Object.freeze({
+        enum: OBJECT_MODEL_TRAIT_ENUM,
+        type: "string",
+      }),
+      type: "array",
+      uniqueItems: true,
+    }),
+    type: Object.freeze({
+      enum: OBJECT_MODEL_TYPE_ENUM,
+      type: "string",
+    }),
+  }),
+  required: Object.freeze(["name", "type", "traits"]),
+  title: "GameFoundryStudio Object Definition",
+  type: "object",
+  version: OBJECT_DEFINITION_SCHEMA_VERSION,
+});
+
+export function getObjectDefinitionSchema() {
+  return OBJECT_DEFINITION_SCHEMA;
+}