Enforce Toolbox DB service contract ownership - PR_26160_072-toolbox-db-contract-enforcement

Author: ToolboxAid

admin/tool-votes.js

@@ -3,6 +3,7 @@ import {
   reorderToolboxVoteRows,
   updateToolboxVoteMetadata,
 } from "../src/engine/api/toolbox-votes-api-client.js";
+import { getToolboxContract } from "../toolbox/tool-registry-api-client.js";
 
 const status = document.querySelector("[data-toolbox-votes-status]");
 const dragStatus = document.querySelector("[data-toolbox-votes-drag-status]");
@@ -14,22 +15,15 @@ const sortButtonLabels = new Map(sortButtons.map((button) => [
   button.textContent.trim(),
 ]));
 
-const RELEASE_CHANNEL_OPTIONS = Object.freeze([
-  ["planned", "Planned"],
-  ["wireframe", "Wireframe"],
-  ["beta", "Beta"],
-  ["complete", "Complete"],
-]);
+const toolboxContract = getToolboxContract();
+const releaseChannelLabels = toolboxContract.releaseChannelLabels || {};
+const RELEASE_CHANNEL_OPTIONS = Object.freeze((toolboxContract.releaseChannels || []).map((channel) => [
+  channel,
+  releaseChannelLabels[channel] || channel,
+]));
 const RELEASE_CHANNEL_LABELS = new Map(RELEASE_CHANNEL_OPTIONS);
-const GROUP_OPTIONS = Object.freeze([
-  "AI",
-  "Audio",
-  "Build/Create",
-  "Design",
-  "Marketplace",
-  "Platform",
-  "Play",
-]);
+const GROUP_OPTIONS = Object.freeze([...(toolboxContract.groups || [])]);
+const DEFAULT_RELEASE_CHANNEL = RELEASE_CHANNEL_OPTIONS[0]?.[0] || "planned";
 
 const SORT_TYPES = Object.freeze({
   down: "number",
@@ -125,7 +119,7 @@ function groupCell(voteRow) {
   const select = document.createElement("select");
   const currentGroup = String(voteRow.group || "").trim();
   const options = GROUP_OPTIONS.includes(currentGroup) || !currentGroup
-    ? GROUP_OPTIONS
+    ? [...GROUP_OPTIONS]
     : [...GROUP_OPTIONS, currentGroup];
   select.dataset.toolboxVotesGroup = voteRow.toolId;
   select.setAttribute("aria-label", `Group for ${voteRow.toolName}`);
@@ -135,7 +129,7 @@ function groupCell(voteRow) {
     option.textContent = group;
     select.append(option);
   });
-  select.value = currentGroup || GROUP_OPTIONS[0];
+  select.value = currentGroup || GROUP_OPTIONS[0] || "";
   select.addEventListener("click", (event) => {
     event.stopPropagation();
   });
@@ -169,12 +163,12 @@ function pathCell(voteRow) {
 }
 
 function releaseChannelLabel(value) {
-  return RELEASE_CHANNEL_LABELS.get(value) || RELEASE_CHANNEL_LABELS.get("planned");
+  return RELEASE_CHANNEL_LABELS.get(value) || RELEASE_CHANNEL_LABELS.get(DEFAULT_RELEASE_CHANNEL) || value || DEFAULT_RELEASE_CHANNEL;
 }
 
 function rowReleaseChannel(voteRow) {
   const value = String(voteRow.status || voteRow.releaseChannel || "").trim().toLowerCase();
-  return RELEASE_CHANNEL_LABELS.has(value) ? value : "planned";
+  return RELEASE_CHANNEL_LABELS.has(value) ? value : DEFAULT_RELEASE_CHANNEL;
 }
 
 function stateCell(voteRow) {
@@ -183,7 +177,8 @@ function stateCell(voteRow) {
   const currentState = rowReleaseChannel(voteRow);
   select.dataset.toolboxVotesState = voteRow.toolId;
   select.setAttribute("aria-label", `State for ${voteRow.toolName}`);
-  RELEASE_CHANNEL_OPTIONS.forEach(([value, label]) => {
+  const options = RELEASE_CHANNEL_OPTIONS.length ? RELEASE_CHANNEL_OPTIONS : [[currentState, currentState]];
+  options.forEach(([value, label]) => {
     const option = document.createElement("option");
     option.value = value;
     option.textContent = label;

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -9,6 +9,9 @@ Changed runtime JS files considered:
 (0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(89%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 25/28
+(92%) admin/tool-votes.js - executed lines 378/378; executed functions 47/51
+(96%) toolbox/tools-page-accordions.js - executed lines 954/954; executed functions 109/113
 
 Guardrail warnings:
 (0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -20,6 +20,9 @@ Changed runtime JS files covered:
 (0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(89%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 25/28
+(92%) admin/tool-votes.js - executed lines 378/378; executed functions 47/51
+(96%) toolbox/tools-page-accordions.js - executed lines 954/954; executed functions 109/113
 
 Files with executed line/function counts where available:
 (38%) src/engine/api/session-api-client.js - executed lines 34/34; executed functions 3/8
@@ -30,9 +33,9 @@ Files with executed line/function counts where available:
 (71%) toolbox/assets/assets.js - executed lines 519/519; executed functions 42/59
 (77%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 548/548; executed functions 37/48
 (83%) src/engine/api/toolbox-votes-api-client.js - executed lines 46/46; executed functions 5/6
-(89%) toolbox/tool-registry-api-client.js - executed lines 148/148; executed functions 24/27
-(92%) admin/tool-votes.js - executed lines 383/383; executed functions 46/50
-(96%) toolbox/tools-page-accordions.js - executed lines 997/997; executed functions 108/112
+(89%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 25/28
+(92%) admin/tool-votes.js - executed lines 378/378; executed functions 47/51
+(96%) toolbox/tools-page-accordions.js - executed lines 954/954; executed functions 109/113
 (100%) toolbox/assets/assets-api-client.js - executed lines 17/17; executed functions 3/3
 (100%) toolbox/colors/palette-api-client.js - executed lines 19/19; executed functions 4/4
 (100%) toolbox/project-journey/project-journey-api-client.js - executed lines 12/12; executed functions 2/2
@@ -48,3 +51,6 @@ Changed JS files considered:
 (0%) src/dev-runtime/persistence/mock-db-store.js - changed JS file not collected as browser runtime coverage
 (0%) src/dev-runtime/server/mock-api-router.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
+(89%) toolbox/tool-registry-api-client.js - changed JS file with browser V8 coverage
+(92%) admin/tool-votes.js - changed JS file with browser V8 coverage
+(96%) toolbox/tools-page-accordions.js - changed JS file with browser V8 coverage

docs_build/dev/reports/testing_lane_execution_report.md

@@ -1,12 +1,12 @@
 # Testing Lane Execution Report
 
-PR: PR_26160_068-db-ssot-governance-and-tool-audit
+PR: PR_26160_072-toolbox-db-contract-enforcement
 Generated: 2026-06-09
 Full samples validation: SKIPPED
 
 ## Summary
 
-PASS: 9
+PASS: 8
 WARN: 1
 FAIL: 0
 SKIP: 3
@@ -16,24 +16,23 @@ SKIP: 3
 | Lane | Status | Command | Evidence |
 | --- | --- | --- | --- |
 | Branch guard | PASS | `git branch --show-current` | Returned `main`. |
-| Changed JS syntax | PASS | `node --check admin/tool-votes.js src/dev-runtime/guest-seeds/tool-state-samples.js src/dev-runtime/persistence/mock-db-store.js src/dev-runtime/server/mock-api-router.mjs tests/playwright/tools/BuildPathProgressSimplification.spec.mjs tests/playwright/tools/ToolboxRoutePages.spec.mjs tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs toolbox/toolRegistry.js toolbox/tools-page-accordions.js` | All changed JS/test files parsed. |
-| Governance/static placement | PASS | `Select-String` for `DB-BACKED PRODUCT DATA SSOT GOVERNANCE` | Governance section exists in `docs_build/dev/PROJECT_INSTRUCTIONS.md`. |
-| API contract probe | PASS | Inline Node mock API probe against `/api/toolbox/votes/snapshot` | Snapshot returned 43 rows; counts planned 33, wireframe 4, beta 5, complete 1; required tools present. |
-| Toolbox/Admin SSoT Playwright | PASS | `npx playwright test tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs` | 3 passed. Verifies 43-tool metadata, Admin edit propagation, and no hardcoded Toolbox count text. |
-| Adjacent Toolbox/Admin Playwright | PASS | `npx playwright test tests/playwright/tools/BuildPathProgressSimplification.spec.mjs tests/playwright/tools/ToolboxRoutePages.spec.mjs tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs` | 17 passed. Verifies Build Path filters/counts, Admin Tool Votes, group matching, Admin wireframes/menu items. |
-| Hardcoded count/local metadata scan | PASS | `rg "Tool Count: [0-9]|Planned \\([0-9]+\\)|Wireframe \\([0-9]+\\)|Beta \\([0-9]+\\)|Complete \\([0-9]+\\)|buildPathGroups|sourceToolByTitle" toolbox admin src/dev-runtime` | No active source matches. |
-| Inline script/style/event scan | PASS | `rg --pcre2 "onclick=|onchange=|oninput=|<script(?![^>]+src)|<style[\\s>]" toolbox/index.html admin/tool-votes.html` | No matches. |
+| Changed JS syntax | PASS | `node --check admin/tool-votes.js`; `node --check toolbox/tool-registry-api-client.js`; `node --check toolbox/tools-page-accordions.js`; `node --check src/dev-runtime/server/mock-api-router.mjs`; `node --check tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs` | All changed JS/test files parsed. |
+| DB/API contract probe | PASS | Inline Node probe against `/api/toolbox/registry/snapshot`, `/api/toolbox/votes/snapshot`, and `/api/mock-db/snapshot` | Registry active tools 43; vote rows 43; metadata rows 43; planning rows 43; contract channels `planned,wireframe,beta,complete`. |
+| Toolbox/Admin SSoT Playwright | PASS | `npx playwright test tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs --reporter=line` | 4 passed. Verifies 43-tool DB-backed metadata/planning, Admin edit propagation, Toolbox reload behavior, no hardcoded count text, and no retired browser registry request. |
+| Toolbox route/display Playwright | PASS | `npx playwright test tests/playwright/tools/ToolboxRoutePages.spec.mjs --reporter=line` | 8 passed. Verifies Toolbox filters, voting controls, group colors/assignments, Build Path status rows, Colors route behavior, wireframe pages, and port guard. |
+| UI-owned product data audit | PASS | Static `rg` scans for old local arrays, hardcoded counts, storage SSoT, and contract endpoints | Active Toolbox/Admin local status/group arrays were replaced by API contract reads; no browser storage product SSoT found. |
+| Inline event/style constraint | PASS | Changed-file review plus static scan | No changed file adds inline script, inline style, or inline event handlers. |
 | Static whitespace validation | PASS | `git diff --check` | No whitespace errors; Git printed line-ending warnings only. |
-| V8 coverage artifact refresh | WARN | Playwright coverage reporter after targeted lanes | `docs_build/dev/reports/playwright_v8_coverage_report.txt` and `coverage_changed_js_guardrail.txt` were refreshed. Server/dev-runtime files are listed as advisory 0% browser coverage because they are not browser runtime files. |
+| V8 coverage artifact refresh | WARN | Playwright coverage reporter after targeted lanes | `playwright_v8_coverage_report.txt` and `coverage_changed_js_guardrail.txt` were refreshed. Server/dev-runtime files remain advisory 0% browser coverage because they are not browser runtime files. |
 
 ## Skipped Lanes
 
 | Lane | Status | Reason |
 | --- | --- | --- |
-| Full samples validation | SKIP | This PR does not touch sample loaders, sample assets, playable game runtime, or shared sample framework behavior. |
-| Broad all-Playwright suite | SKIP | Targeted Toolbox/Admin lanes cover the impacted UI/API contracts. |
-| Unrelated game/sample DB migration validation | SKIP | The request explicitly scoped migration to Toolbox/Admin tool metadata only. |
+| Full samples validation | SKIP | This PR does not touch samples, sample loaders, sample assets, playable runtime, or sample framework behavior. |
+| Broad all-Playwright suite | SKIP | Targeted Toolbox/Admin lanes cover the impacted API contract and UI surfaces. |
+| Unrelated game/sample DB migration validation | SKIP | The request explicitly scoped migration to Toolbox/Admin tool metadata, planning, voting, and order. |
 
 ## Manual Test Notes
 
-No additional manual browser walkthrough was needed. The targeted Playwright lanes directly exercise Toolbox Build Path, Admin Tool Votes, Admin menu/wireframes, 43-tool inventory parity, Admin metadata edits reflected in Toolbox after reload, and source scans for hardcoded counts/inline behavior.
+No additional manual walkthrough was needed. The targeted Playwright lanes exercised Toolbox Build Path, Admin Tool Votes, 43-tool inventory parity, tool planning load, votes, order/status/group metadata, Admin edits reflected in Toolbox after reload, and active-page guardrails against retired browser registry use.

docs_build/dev/reports/toolbox-db-contract-enforcement-report.md

@@ -0,0 +1,66 @@
+# PR_26160_072 Toolbox DB Contract Enforcement Report
+
+Generated: 2026-06-09
+
+## Branch Validation
+
+| Check | Status | Evidence |
+| --- | --- | --- |
+| Current branch | PASS | `git branch --show-current` returned `main`. |
+| Expected branch | PASS | Required branch is `main`. |
+| Local branches found | PASS | `git branch --list` returned `* main`. |
+
+## Requirement Checklist
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Audit active Toolbox/Admin pages for UI-owned product arrays, counts, maps, status/group/path/order duplication, and browser-storage SSoT use. | PASS | Static scans covered `toolbox/`, `admin/`, `src/engine/api`, and `src/dev-runtime/server/mock-api-router.mjs`. Active local status/group arrays were found in `toolbox/tools-page-accordions.js` and `admin/tool-votes.js`; no active `localStorage`/`sessionStorage` product SSoT matches were found. |
+| Move remaining Toolbox/Admin product data reads/writes behind API/service contract backed by DB adapter. | PASS | `src/dev-runtime/server/mock-api-router.mjs` now returns `toolboxContract` from `/api/toolbox/registry/snapshot`; `toolbox/tool-registry-api-client.js` exposes `getToolboxContract()`; `toolbox/tools-page-accordions.js` and `admin/tool-votes.js` consume that contract. |
+| Ensure Tool Metadata flows through Web UI -> API/Service Contract -> DB Adapter. | PASS | `/api/toolbox/registry/snapshot` and `/api/toolbox/votes/snapshot` read `toolbox_tool_metadata`; Playwright verified 43 metadata rows and Admin edits reflected in Toolbox after reload. |
+| Ensure Tool Planning flows through Web UI -> API/Service Contract -> DB Adapter. | PASS | `ToolboxAdminMetadataSsot.spec.mjs` verifies planning fields are absent from `toolbox_tool_metadata`, present in `toolbox_tool_planning`, and merged into registry tools as `planningSource: toolbox_tool_planning`. |
+| Ensure Tool Voting flows through Web UI -> API/Service Contract -> DB Adapter. | PASS | `admin/tool-votes.js` continues to call `readToolboxVoteSnapshot`, `updateToolboxVoteMetadata`, and `reorderToolboxVoteRows`; Playwright verified vote rows and Admin/Toolbox parity. |
+| Ensure Tool Order flows through Web UI -> API/Service Contract -> DB Adapter. | PASS | Admin reorder API remains `/api/toolbox/votes/order-list`; Playwright verified order changes propagate to Toolbox Build Path after reload. |
+| Keep Toolbox and Admin Tool Votes behavior unchanged. | PASS | `ToolboxAdminMetadataSsot.spec.mjs` passed 4/4; `ToolboxRoutePages.spec.mjs` passed 8/8. |
+| Do not migrate unrelated game/sample data. | PASS | Changes are limited to Toolbox/Admin contract wiring, one targeted Playwright spec, and generated reports. |
+| Do not use inline script/style/event handlers. | PASS | No changed file adds inline script, inline style, or inline event handlers. |
+
+## Remaining UI-Owned Data Audit
+
+| Area | Finding | Status | Action |
+| --- | --- | --- | --- |
+| Toolbox status/default filters | Page-local arrays previously owned release channels and defaults. | PASS | Moved to `toolboxContract.releaseChannels` and `toolboxContract.defaultReleaseChannels`. |
+| Toolbox status labels/help/swatches | Page-local maps previously duplicated release labels/help and state swatches. | PASS | Moved to `toolboxContract.releaseChannelLabels`, `releaseChannelHelpText`, and `releaseChannelSwatches`. |
+| Toolbox group order/swatches | Page-local group order and group swatch maps duplicated DB-backed metadata. | PASS | `toolboxContract.toolboxGroupOrder`, `groups`, and `groupSwatches` are derived from active registry tools. |
+| Toolbox role focus lists | Page-local role focus lists were UI-owned product display data. | PASS | Moved behind the registry API contract as `toolboxContract.roleFocusTools`. |
+| Admin Tool Votes state/group editors | Page-local status and group option arrays duplicated registry metadata. | PASS | Admin now uses `getToolboxContract()` for status labels and group options. |
+| Hardcoded counts | No active source hardcoded visible Toolbox counts. Test constants remain validation expectations only. | PASS | `Tool Count` is computed at runtime; Playwright verifies DB-backed counts. |
+| Browser storage SSoT | No active Toolbox/Admin product SSoT use of `localStorage` or `sessionStorage` found. | PASS | Session/storage test helpers are validation-only. |
+| `toolbox/toolRegistry.js` compatibility shell | Not loaded by active Toolbox/Admin pages; retained as a compatibility stub for older tests/scripts. | PASS | Existing Playwright test asserts active pages do not request `/toolbox/toolRegistry.js`. |
+
+## Validation
+
+| Lane | Status | Command | Evidence |
+| --- | --- | --- | --- |
+| Branch guard | PASS | `git branch --show-current` | Returned `main`. |
+| Changed JS syntax | PASS | `node --check` for changed JS/spec files | `admin/tool-votes.js`, `toolbox/tool-registry-api-client.js`, `toolbox/tools-page-accordions.js`, `src/dev-runtime/server/mock-api-router.mjs`, and `ToolboxAdminMetadataSsot.spec.mjs` all parsed. |
+| DB/API contract probe | PASS | Inline Node server probe | Registry returned 43 active tools, votes returned 43 rows, metadata/planning returned 43 rows each, and contract defaults were present. |
+| Toolbox/Admin Tool Votes Playwright | PASS | `npx playwright test tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs --reporter=line` | 4 passed. |
+| Toolbox route/UI Playwright | PASS | `npx playwright test tests/playwright/tools/ToolboxRoutePages.spec.mjs --reporter=line` | 8 passed. |
+| Static whitespace | PASS | `git diff --check` | No whitespace errors; Git printed line-ending warnings only. |
+| V8 coverage | PASS | Playwright reporter output | `playwright_v8_coverage_report.txt` updated; changed browser files covered at 89%, 92%, and 96%. |
+
+## Impacted Lane
+
+- Toolbox/Admin Tool Votes DB contract and UI behavior.
+
+## Skipped Lanes
+
+| Lane | Reason |
+| --- | --- |
+| Full samples validation | This PR does not touch sample loaders, game runtime, or shared sample framework behavior. |
+| Unrelated game/sample DB migration lanes | Request is scoped to Toolbox/Admin tool metadata, planning, voting, and order contracts. |
+| Broad all-Playwright suite | Targeted Toolbox/Admin lanes cover the changed service contract and active UI surfaces. |
+
+## Manual Test Notes
+
+No extra manual browser walkthrough was required. Targeted Playwright covered 43-tool inventory, planning load, votes, order, status/group metadata, filters, admin edits, and reload behavior.