Audit legacy palette source swatches table - PR_26160_074-palette-db-legacy-table-audit

Author: ToolboxAid

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -8,9 +8,7 @@ Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 Changed runtime JS files considered:
 (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
+(86%) toolbox/colors/colors.js - executed lines 2289/2289; executed functions 193/224
 
 Guardrail warnings:
 (0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/palette-db-legacy-table-audit-report.md

@@ -0,0 +1,112 @@
+# PR_26160_074-palette-db-legacy-table-audit
+
+Generated: 2026-06-09
+
+## Branch Validation
+
+| Check | Result | 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` only. |
+
+## Requirement Checklist
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Audit `palette_source_swatches` reads | PASS | Reads are concentrated in `src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js`, `toolbox/colors/colors.js`, `toolbox/colors/palette-api-client.js`, `src/dev-runtime/server/mock-api-router.mjs`, `src/dev-runtime/persistence/mock-db-store.js`, and DB Viewer rendering through `src/engine/api/mock-db-viewer-ui.js`. |
+| Audit `palette_source_swatches` writes | PASS | Seed/write paths are `src/dev-runtime/guest-seeds/palette-source-mock-db.js`, `createPaletteToolMockDbTables()`, repository `getTables()`, and mock DB persistence/schema ownership in `src/dev-runtime/persistence/mock-db-store.js`. |
+| Determine Colors runtime effect | PASS | The table still affects source palette options, source swatch listing, source pin/unpin, harmony matching against current/all source swatches, table counts, diagnostics, and DB Viewer table visibility. |
+| Determine whether 838 records are legacy seed data | PASS | Probe confirmed `createPaletteSourceMockDbRows()` returns 838 rows and a fresh palette repository exposes 838 `palette_source_swatches` rows. They are seed-backed curated source rows, but not orphaned/unused legacy data. |
+| Decide remove/rename/archive/migrate | PASS | Do not remove or rename in this PR. Safe future migration would require first replacing source browser/harmony/source-row repository behavior with a new curated source catalog/service. |
+| Audit `palette_colors` | PASS | Active DB-owned Project Swatches table. Read/write via palette repository and visible in DB Viewer. |
+| Audit `palette_source_swatches` | PASS | Active DB-owned curated source/reference swatch table. Seeded by dev runtime and used by palette source/harmony paths. |
+| Audit `palette_swatch_usages` | PASS | Active DB-owned usage/dependency table. Used for swatch usage rows and DB Viewer relationship diagnostics to project swatches/assets. |
+| Audit `project_workspace_palette_globals` | PASS | Active DB-owned per-project palette settings/global table. Used for workspace palette records and palette table relationship diagnostics. |
+| Keep Colors grid behavior unchanged | PASS | Grid behavior was preserved. A narrow metadata repair in `toolbox/colors/colors.js` prevents generated swatches from storing the internal preview-layout sentinel `default` as user-facing sort metadata; the grid layout/order remains unchanged. |
+| Do not migrate unrelated Toolbox/Admin data | PASS | No Toolbox/Admin metadata migration was performed. |
+| No inline script/style/event handlers | PASS | No HTML/CSS changes were made. |
+
+## `palette_source_swatches` Usage Audit
+
+### Reads
+
+| File | Read behavior |
+| --- | --- |
+| `src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js` | Loads `loadedMockDbTables.palette_source_swatches`, normalizes rows with `normalizeSourcePaletteRows()`, exposes `sourcePaletteOptions()`, `listSourceSwatches()`, source counts, source row tables, and source-backed harmony matching. |
+| `toolbox/colors/palette-api-client.js` | Uses palette API repository constants/contracts that surface the palette repository snapshot and tables to the browser tool. |
+| `toolbox/colors/colors.js` | Reads `snapshot.sourcePaletteOptions`, `snapshot.sourcePaletteRecordCount`, `repository.listSourceSwatches()`, source diagnostics, and palette table counts. Source controls are currently hidden from the active UI, but the runtime code path remains present. |
+| `src/dev-runtime/server/mock-api-router.mjs` | Provides API-backed palette repository/test modes, including empty/invalid source table setup for palette route behavior. |
+| `src/dev-runtime/persistence/mock-db-store.js` | Declares `palette_source_swatches` schema and the Palette DB Viewer group. |
+| `src/engine/api/mock-db-viewer-ui.js` | Renders current adapter tables from the API snapshot; Palette filter shows `palette_source_swatches` with schema/records. |
+| `tests/playwright/tools/PaletteToolMockRepository.spec.mjs` | Asserts repository table ownership, source options, source swatch pin/unpin, hidden source controls in current UI, and symbol-free palette validation. |
+| `tests/playwright/tools/AdminDbViewer.spec.mjs` | Asserts Palette DB Viewer grouping includes `palette_source_swatches` and that raw Palette tables are DB-shaped. |
+
+### Writes / Ownership
+
+| File | Write/ownership behavior |
+| --- | --- |
+| `src/dev-runtime/guest-seeds/palette-source-mock-db.js` | `createPaletteSourceMockDbRows()` creates the curated source seed rows. |
+| `src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js` | `createPaletteToolMockDbTables()` seeds/clones source rows; `getTables()` returns normalized `palette_source_swatches` rows for persistence/snapshot output. |
+| `src/dev-runtime/persistence/mock-db-store.js` | Owns schema/table grouping and audit field normalization expectations for `palette_source_swatches`. |
+
+### Runtime Impact
+
+`palette_source_swatches` still affects active service behavior. The current Colors grid is the primary picker workflow, but the palette repository still uses source swatches for source palette options, source listing, source pinning, source-backed harmony suggestions, diagnostics, table counts, and DB Viewer visibility. Removing the table now would break those paths or force browser/server fallbacks, which would violate the current DB SSoT direction.
+
+### 838-Record Finding
+
+Targeted Node probe:
+
+```text
+seedRows: 838
+tableRows: 838
+sourceOptions: 11
+sourcePaletteRecordCount: 838
+tableCounts: palette_colors=0, palette_source_swatches=838, palette_swatch_usages=0, project_workspace_palette_globals=1
+```
+
+Conclusion: the 838 rows are dev/runtime seed-backed curated source swatches. They are legacy in the sense that they support the older source palette browser/harmony model, but they are not currently unused.
+
+## Palette Table Ownership Recommendation
+
+| Table | Current owner | Recommendation |
+| --- | --- | --- |
+| `palette_colors` | DB-backed Colors Project Swatches | Keep. It is the active project swatch table and is written/read by the Colors repository and DB Viewer. |
+| `palette_source_swatches` | DB-backed curated source/reference swatches | Keep for now. Do not delete until source browser/harmony matching is intentionally migrated to a new curated source catalog/service or retired. |
+| `palette_swatch_usages` | DB-backed swatch usage/dependency rows | Keep. It supports usage/dependency tracking and DB Viewer relationship diagnostics. |
+| `project_workspace_palette_globals` | DB-backed per-project palette settings/global records | Keep. It supports project palette settings and relationship checks for project swatches. |
+
+Future migration option: if the product direction is to remove source-browser behavior entirely, first remove or replace `sourcePaletteOptions()`, `listSourceSwatches()`, source pinning, and source-backed harmony matching. After that, migrate any still-useful curated swatches into a clearly named source catalog service/table or archive the seed file with a migration report.
+
+## Colors Metadata Repair
+
+During the requested Colors grid validation, the first run failed because generated picker swatches stored `sortField: "default"` when the preview grid was in default spatial order. That value is an internal layout sentinel, not a useful user-facing stored sort setting. `toolbox/colors/colors.js` now stores the active Project Swatches sort (`hue`, ascending by default) when the preview layout is `default`, while preserving the actual Picker Preview grid order and duplicate behavior.
+
+## Validation
+
+| Lane | Status | Command | Evidence |
+| --- | --- | --- | --- |
+| Branch guard | PASS | `git branch --show-current`; `git branch --list` | Current branch `main`; local branch list `main`. |
+| Palette DB audit probe | PASS | Inline Node import of palette seed and repository | Confirmed 838 seeded source rows, 838 repository table rows, 11 source options, and table counts. |
+| Changed JS syntax | PASS | `node --check toolbox/colors/colors.js` | Changed Colors JS parsed successfully. |
+| Colors grid/runtime Playwright | PASS | `npx playwright test tests/playwright/tools/PaletteToolMockRepository.spec.mjs --reporter=line` | 9 passed after metadata repair. Initial run exposed the `sortField: default` metadata drift. |
+| DB Viewer palette grouping Playwright | PASS | `npx playwright test tests/playwright/tools/AdminDbViewer.spec.mjs --reporter=line` | 7 passed. Covers Palette filter, `palette_source_swatches` visibility, raw DB-shaped Palette tables, Local Mem, and Local DB inspection. |
+| Static whitespace validation | PASS | `git diff --check` | No whitespace errors after report generation. |
+
+## Impacted Lane
+
+- Palette/Colors DB audit and runtime lane.
+- Admin DB Viewer Palette grouping lane.
+
+## Skipped Lanes
+
+| Lane | Status | Reason |
+| --- | --- | --- |
+| Full samples validation | SKIP | This PR does not touch sample loaders, game runtime, sample assets, or the shared sample framework. |
+| Broad Toolbox/Admin migration validation | SKIP | The request explicitly scoped this PR to Palette/Colors DB audit and DB Viewer palette grouping. |
+| Unrelated Toolbox/Admin data migration | SKIP | The request said not to migrate unrelated Toolbox/Admin data. |
+
+## Manual Test Notes
+
+No manual browser walkthrough was required beyond the targeted Playwright lanes. The audit found `palette_source_swatches` is still active and should not be deleted in this PR.

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -12,33 +12,23 @@ 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:
-(69%) Toolbox Index - exercised 9 runtime JS files
+(85%) Toolbox Index - exercised 3 runtime JS files
 (0%) Tool Template V2 - not exercised by this Playwright run
-(74%) Theme V2 Shared JS - exercised 2 runtime JS files
+(77%) Theme V2 Shared JS - exercised 3 runtime JS files
 
 Changed runtime JS files covered:
 (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
+(86%) toolbox/colors/colors.js - executed lines 2289/2289; executed functions 193/224
 
 Files with executed line/function counts where available:
-(38%) src/engine/api/session-api-client.js - executed lines 34/34; executed functions 3/8
-(55%) toolbox/project-journey/project-journey.js - executed lines 1003/1003; executed functions 54/99
-(57%) toolbox/colors/colors.js - executed lines 2289/2289; executed functions 123/216
 (58%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 11/19
 (64%) assets/theme-v2/js/tool-display-mode.js - executed lines 209/209; executed functions 9/14
-(71%) toolbox/assets/assets.js - executed lines 519/519; executed functions 42/59
+(75%) toolbox/tool-registry-api-client.js - executed lines 152/152; executed functions 21/28
 (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 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
+(86%) toolbox/colors/colors.js - executed lines 2289/2289; executed functions 193/224
+(92%) assets/theme-v2/js/account-controls.js - executed lines 47/47; executed functions 12/13
 (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
-(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/server/mock-api-router.mjs - WARNING: uncovered changed runtime JS file; advisory only
@@ -48,7 +38,4 @@ Changed JS files considered:
 (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
-(96%) toolbox/tools-page-accordions.js - changed JS file with browser V8 coverage
+(86%) toolbox/colors/colors.js - changed JS file with browser V8 coverage

docs_build/dev/reports/testing_lane_execution_report.md

@@ -1,40 +1,35 @@
 # Testing Lane Execution Report
 
-PR: PR_26160_073-db-migration-and-viewer-grouping
+PR: PR_26160_074-palette-db-legacy-table-audit
 Generated: 2026-06-09
 Full samples validation: SKIPPED
 
 ## Summary
 
-PASS: 9
-WARN: 1
+PASS: 6
+WARN: 0
 FAIL: 0
 SKIP: 3
 
 ## Executed Lanes
 
 | Lane | Status | Command | Evidence |
 | --- | --- | --- | --- |
-| Branch guard | PASS | `git branch --show-current` | Returned `main`. |
-| 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. |
-| 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. |
+| Branch guard | PASS | `git branch --show-current`; `git branch --list` | Current branch was `main`; local branch list contained `main`. |
+| Palette DB audit probe | PASS | Inline Node probe importing `createPaletteSourceMockDbRows()` and `createProjectWorkspacePaletteRepository()` | Confirmed `palette_source_swatches` seed count 838, repository table count 838, 11 source options, and palette table counts. |
+| Changed JS syntax | PASS | `node --check toolbox/colors/colors.js` | Changed Colors runtime file parsed successfully. |
+| Colors grid/runtime Playwright | PASS | `npx playwright test tests/playwright/tools/PaletteToolMockRepository.spec.mjs --reporter=line` | 9 passed after the metadata-only sort setting repair. |
+| Admin DB Viewer Playwright | PASS | `npx playwright test tests/playwright/tools/AdminDbViewer.spec.mjs --reporter=line` | 7 passed. Covers Palette grouping, `palette_source_swatches` visibility, DB-shaped Palette tables, Local Mem, Local DB readonly, and diagnostics. |
+| Static whitespace validation | PASS | `git diff --check` | No whitespace errors after final artifact generation. |
 
 ## 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 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. |
+| Full samples validation | SKIP | The PR does not touch sample loaders, playable game runtime, sample assets, or shared sample framework behavior. |
+| Broad Toolbox/Admin migration validation | SKIP | The request explicitly scoped validation to Palette/Colors DB audit and DB Viewer grouping. |
+| Unrelated game/sample DB migration validation | SKIP | The request explicitly said not to migrate unrelated Toolbox/Admin data. |
 
 ## Manual Test Notes
 
-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.
+The targeted Playwright lanes covered the requested browser behavior. The audit found `palette_source_swatches` is still active in service/repository behavior and DB Viewer grouping, so the table was not removed.