Continue DB migration and improve DB Viewer grouping - PR_26160_073-db-migration-and-viewer-grouping

Author: ToolboxAid

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -6,14 +6,12 @@ Missing changed runtime JS files are WARN, not FAIL.
 Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 
 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
+(0%) src/engine/api/mock-db-viewer-ui.js - 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
-(0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file missing from coverage; advisory only
 (0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
+(0%) src/engine/api/mock-db-viewer-ui.js - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/db-migration-and-viewer-grouping-report.md

@@ -0,0 +1,67 @@
+# PR_26160_073 DB Migration And Viewer Grouping 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 |
+| --- | --- | --- |
+| Continue Web -> API/Service Contract -> DB Adapter migration for remaining Toolbox/Admin product data. | PASS | DB Viewer table grouping moved from `src/engine/api/mock-db-viewer-ui.js` browser constants to server-provided `viewerGroups` in `/api/mock-db/snapshot`. |
+| Audit and migrate remaining page-local product arrays, hardcoded counts, duplicated metadata ownership, and direct UI-owned tool data. | PASS | Removed DB Viewer browser-owned `TOOL_GROUP_ORDER`, `TOOL_GROUP_LABELS`, `STANDALONE_TABLE_LABELS`, and `IDENTITY_TABLE_GROUP`; Toolbox/Admin Tool Votes status/group contracts remain API-backed from PR_072. |
+| Ensure Tool Metadata, Tool Planning, Tool Voting, and Tool Order are DB-owned and accessed through service contract only. | PASS | Tool Metadata and Tool Order are in `toolbox_tool_metadata`; Tool Planning is in `toolbox_tool_planning`; Tool Voting is in `toolbox_votes`; all are read through server API snapshots. |
+| Group `toolbox_votes` and `toolbox_vote_order` under a single logical DB Viewer section named `Toolbox Votes`. | PASS | `dbViewerGroupsForSnapshot()` creates `Toolbox Votes` and includes `toolbox_votes`; it also includes `toolbox_vote_order` if that underlying table exists in the active adapter. |
+| Preserve underlying tables. | PASS | No table names, schemas, or owners were changed. Active adapter currently has `toolbox_votes`; it does not have `toolbox_vote_order`, so no duplicate order table was invented. |
+| Improve DB Viewer organization without changing table ownership. | PASS | DB Viewer filter organization is now server-owned via `viewerGroups`; table `owners` are unchanged. |
+| Verify DB Viewer shows all tables from active DB adapter, including empty tables with schema visibility. | PASS | `AdminDbViewer.spec.mjs` verifies all visible tables, empty `toolbox_votes`, empty table headers after clear, and Local DB readonly schema headers. |
+| Do not migrate unrelated game/sample data. | PASS | Changes are limited to DB Viewer grouping contract, server snapshot metadata, and targeted DB Viewer tests/reports. |
+| Do not use inline script/style/event handlers. | PASS | Static changed-file scan found no inline script/style/event handler additions. |
+
+## Remaining DB Migration Audit
+
+| Area | Finding | Status | Action |
+| --- | --- | --- | --- |
+| DB Viewer tool/table grouping | Browser previously owned tool group order and labels. | PASS | Moved to `viewerGroups` from the server snapshot. |
+| DB Viewer identity grouping | Browser previously owned `users`, `user_roles`, `roles` grouping. | PASS | Moved to server `viewerGroups` as `User Roles`. |
+| DB Viewer standalone labels | Browser previously owned labels for `tool_state_samples` and `user_roles`. | PASS | Moved to server label map and added Tool Metadata, Tool Planning, Toolbox Votes labels. |
+| Toolbox metadata/status/group/page contracts | Already API-backed from current base. | PASS | Static audit shows active page constants now copy from `toolboxContract`, not page-owned arrays. |
+| Hardcoded counts | No active UI-owned Toolbox/Admin hardcoded counts found. | PASS | Playwright and static scans verify runtime computed counts. |
+| Browser storage as product SSoT | No active Toolbox/Admin DB product SSoT use of `localStorage`/`sessionStorage` found. | PASS | Static scan returned no matches. |
+| `toolbox_vote_order` table | Not present in active DB adapter/schema. | PASS | Did not create a duplicate table because Tool Order is currently DB-owned by `toolbox_tool_metadata.order`; the viewer group includes `toolbox_vote_order` automatically if a future adapter exposes it. |
+
+## Validation
+
+| Lane | Status | Command | Evidence |
+| --- | --- | --- | --- |
+| Branch guard | PASS | `git branch --show-current` | Returned `main`. |
+| Changed JS syntax | PASS | `node --check` on changed server/UI/spec files | All parsed. |
+| DB adapter validation | PASS | `node --test tests/dev-runtime/DbSeedIntegrity.test.mjs` | 2 passed. |
+| DB Viewer Playwright | PASS | `npx playwright test tests/playwright/tools/AdminDbViewer.spec.mjs --reporter=line` | 7 passed. |
+| Toolbox/Admin Tool Votes Playwright | PASS | `npx playwright test tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs --reporter=line` | 4 passed. |
+| Toolbox route validation | PASS | `npx playwright test tests/playwright/tools/ToolboxRoutePages.spec.mjs --reporter=line` | 8 passed after rerun with longer timeout; first parallel attempt timed out before completion. |
+| API contract probe | PASS | Inline Node probe against `/api/mock-db/snapshot` | 27 tables; filter groups include All, tool groups, User Roles, Tool State Samples, Tool Metadata, Tool Planning, and Toolbox Votes. |
+| Static whitespace | PASS | `git diff --check` | No whitespace errors; Git printed line-ending warnings only. |
+| Inline/style/event scan | PASS | `rg --pcre2` on changed active files | No matches. |
+
+## Impacted Lane
+
+- DB adapter / DB Viewer / Toolbox / Admin Tool Votes.
+
+## Skipped Lanes
+
+| Lane | Reason |
+| --- | --- |
+| Full samples validation | This PR does not touch sample loaders, sample assets, playable game runtime, or sample framework behavior. |
+| Broad all-Playwright suite | Targeted DB Viewer, Toolbox, and Admin Tool Votes lanes cover the changed API contract and UI surfaces. |
+| Unrelated game/sample DB migration | Request explicitly excludes unrelated game/sample data migration. |
+
+## Manual Test Notes
+
+No extra manual browser walkthrough was required. Playwright directly covered DB Viewer table visibility, Toolbox Votes grouping, Local Mem/Local DB adapter behavior, 43-tool inventory, DB-backed metadata ownership, status/group/order reload behavior, and Toolbox route behavior.

docs_build/dev/reports/db-viewer-table-inventory-report.md

@@ -0,0 +1,67 @@
+# DB Viewer Table Inventory Report
+
+Generated: 2026-06-09
+Source: `/api/mock-db/snapshot` from the active Local Mem DB adapter.
+
+## Summary
+
+| Check | Status | Evidence |
+| --- | --- | --- |
+| Active DB adapter tables are rendered through API snapshot. | PASS | Snapshot returned 27 tables. |
+| Empty tables keep schema visibility. | PASS | `AdminDbViewer.spec.mjs` verifies empty `toolbox_votes`, cleared tables, and Local DB readonly empty tables still show headers. |
+| Toolbox Votes logical grouping exists. | PASS | `viewerGroups` includes `Toolbox Votes` with `toolbox_votes`. |
+| `toolbox_vote_order` grouping support. | PASS | The grouping contract includes `toolbox_vote_order` when present; active adapter does not currently expose that table. |
+
+## Viewer Groups
+
+| Group | Tables |
+| --- | --- |
+| All | all 27 active adapter tables |
+| Workspace | `workspace_projects`, `workspace_progress` |
+| Game Design | `game_design_documents`, `game_design_validation_items` |
+| Game Configuration | `game_configuration_records`, `game_configuration_validation_items` |
+| Project Journey | `project_journey_note_types`, `project_journey_notes`, `project_journey_templates`, `project_journey_items`, `project_journey_activity` |
+| Palette | `palette_colors`, `palette_source_swatches`, `palette_swatch_usages`, `project_workspace_palette_globals` |
+| Asset | `asset_role_definitions`, `asset_library_items`, `asset_storage_objects`, `asset_import_events`, `asset_validation_items` |
+| User Roles | `users`, `user_roles`, `roles` |
+| Tool State Samples | `tool_state_samples` |
+| Tool Metadata | `toolbox_tool_metadata` |
+| Tool Planning | `toolbox_tool_planning` |
+| Toolbox Votes | `toolbox_votes` |
+
+## Active Table Inventory
+
+| Table | Owner / Logical Group |
+| --- | --- |
+| `asset_import_events` | Asset |
+| `asset_library_items` | Asset |
+| `asset_role_definitions` | Asset |
+| `asset_storage_objects` | Asset |
+| `asset_validation_items` | Asset |
+| `game_configuration_records` | Game Configuration |
+| `game_configuration_validation_items` | Game Configuration |
+| `game_design_documents` | Game Design |
+| `game_design_validation_items` | Game Design |
+| `palette_colors` | Palette |
+| `palette_source_swatches` | Palette |
+| `palette_swatch_usages` | Palette |
+| `project_journey_activity` | Project Journey |
+| `project_journey_items` | Project Journey |
+| `project_journey_note_types` | Project Journey |
+| `project_journey_notes` | Project Journey |
+| `project_journey_templates` | Project Journey |
+| `project_workspace_palette_globals` | Palette |
+| `roles` | User Roles |
+| `tool_state_samples` | Tool State Samples |
+| `toolbox_tool_metadata` | Tool Metadata |
+| `toolbox_tool_planning` | Tool Planning |
+| `toolbox_votes` | Toolbox Votes |
+| `user_roles` | User Roles |
+| `users` | User Roles |
+| `workspace_progress` | Workspace |
+| `workspace_projects` | Workspace |
+
+## Notes
+
+- `toolbox_vote_order` is not an active adapter table today. Tool order is DB-owned as `toolbox_tool_metadata.order`.
+- No underlying table ownership changed in this PR.

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -17,9 +17,8 @@ Exercised tool entry points detected:
 (74%) Theme V2 Shared JS - exercised 2 runtime JS files
 
 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
+(0%) src/engine/api/mock-db-viewer-ui.js - 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
@@ -42,14 +41,13 @@ Files with executed line/function counts where available:
 (100%) toolbox/project-workspace/project-workspace-api-client.js - executed lines 12/12; executed functions 2/2
 
 Uncovered or low-coverage changed JS files:
-(0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: uncovered changed runtime JS file; advisory only
 (0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: uncovered changed runtime JS file; advisory only
+(0%) src/engine/api/mock-db-viewer-ui.js - WARNING: uncovered changed runtime JS file; advisory only
 
 Changed JS files considered:
-(0%) src/dev-runtime/guest-seeds/tool-state-samples.js - changed JS file not collected as browser runtime coverage
-(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%) src/engine/api/mock-db-viewer-ui.js - changed JS file not collected as browser runtime coverage
+(0%) tests/playwright/tools/AdminDbViewer.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
 (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

docs_build/dev/reports/testing_lane_execution_report.md

@@ -1,12 +1,12 @@
 # Testing Lane Execution Report
 
-PR: PR_26160_072-toolbox-db-contract-enforcement
+PR: PR_26160_073-db-migration-and-viewer-grouping
 Generated: 2026-06-09
 Full samples validation: SKIPPED
 
 ## Summary
 
-PASS: 8
+PASS: 9
 WARN: 1
 FAIL: 0
 SKIP: 3
@@ -16,23 +16,25 @@ 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`; `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. |
+| Changed JS syntax | PASS | `node --check src/dev-runtime/server/mock-api-router.mjs`; `node --check src/engine/api/mock-db-viewer-ui.js`; `node --check tests/playwright/tools/AdminDbViewer.spec.mjs`; plus current Toolbox/Admin contract files | All changed JS/test files parsed. |
+| DB adapter seed/reseed validation | PASS | `node --test tests/dev-runtime/DbSeedIntegrity.test.mjs` | 2 passed. |
+| DB Viewer API contract probe | PASS | Inline Node probe against `/api/mock-db/snapshot` | Snapshot returned 27 tables and `viewerGroups` containing `Toolbox Votes`. |
+| Admin DB Viewer Playwright | PASS | `npx playwright test tests/playwright/tools/AdminDbViewer.spec.mjs --reporter=line` | 7 passed. Covers table visibility, grouping, Local Mem, Local DB readonly, empty schema headers, and adapter diagnostics. |
+| Toolbox/Admin metadata SSoT Playwright | PASS | `npx playwright test tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs --reporter=line` | 4 passed. Covers 43-tool inventory, planning load, DB-backed metadata edits, order/status/group reload behavior. |
+| Toolbox route/page Playwright | PASS | `npx playwright test tests/playwright/tools/ToolboxRoutePages.spec.mjs --reporter=line` | 8 passed after rerun with longer timeout. |
+| Remaining UI-owned data audit | PASS | Static `rg` scans for old local DB Viewer groups, page-local status/group arrays, hardcoded counts, and browser storage SSoT | DB Viewer grouping is server-provided; active Toolbox/Admin copies are API-contract reads; no product SSoT browser storage found. |
 | 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 | `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. |
+| Inline script/style/event scan | PASS | `rg --pcre2` on changed active files | No inline script/style/event handler additions found. |
+| V8 coverage artifact refresh | WARN | Playwright coverage reporter after targeted lanes | `playwright_v8_coverage_report.txt` and `coverage_changed_js_guardrail.txt` 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 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. |
+| 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 DB Viewer, Toolbox, and Admin Tool Votes lanes cover the impacted UI/API contracts. |
+| Unrelated game/sample DB migration validation | SKIP | The request explicitly scoped migration to Toolbox/Admin product data and DB Viewer organization. |
 
 ## Manual Test Notes
 
-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.
+No extra manual browser walkthrough was needed. The targeted Playwright lanes exercised DB Viewer table visibility, Toolbox Votes grouping, 43-tool inventory, DB-backed metadata ownership, planning load, voting/order/status/group reload behavior, and active Toolbox routes.