Replace JSON-backed Local DB with SQLite behind API boundary - PR_26158_027-sqlite-local-db

Author: qbytesdq-jpg

docs_build/dev/reports/browser_mock_remaining_audit.md

@@ -1,36 +1,38 @@
-# PR_26158_026 Browser Mock Remaining Audit
+# PR_26158_027 Browser Mock Remaining Audit
 
 ## Scope
 
-Focused audit for enabling Local DB read-only inspection through Admin DB Viewer:
+Focused audit for replacing Local DB JSON storage with SQLite behind the server API boundary:
 
-- `admin/db-viewer.html`
-- `admin/db-viewer.js`
-- `src/engine/api/mock-db-api-client.js`
-- `src/engine/api/mock-db-viewer-ui.js`
+- `src/dev-runtime/server/mock-api-router.mjs`
+- `src/dev-runtime/persistence/mock-db-store.js`
 - `tests/playwright/tools/AdminDbViewer.spec.mjs`
+- `tests/playwright/tools/LoginSessionMode.spec.mjs`
 
 ## Static Import Boundary
 
 | Check | Status | Evidence |
 | --- | --- | --- |
-| Browser files import `src/dev-runtime` directly. | PASS | `rg -n 'src/dev-runtime' admin assets toolbox src -g '*.js' -g '*.mjs' -g '!src/dev-runtime/**' -g '!**/*-mock-repository.js' ...` returned no matches. |
-| Browser files import mock repositories directly. | PASS | `rg -n 'mock-.*repository|LocalDbAdapter|DB implementation' ...` excluding repository implementation files returned no matches. |
-| Browser files import `LocalDbAdapter` or DB implementation modules directly. | PASS | Same focused `rg` returned no browser matches. |
+| Browser files import `node:sqlite` directly. | PASS | Focused `rg` for `node:sqlite` outside `src/dev-runtime/**` returned no matches. |
+| Browser files import `DatabaseSync` directly. | PASS | Focused `rg` for `DatabaseSync` outside `src/dev-runtime/**` returned no matches. |
+| Browser files import `LocalDbAdapter` directly. | PASS | Focused `rg` for `LocalDbAdapter` outside `src/dev-runtime/**` returned no matches. |
+| Browser files import `src/dev-runtime` directly. | PASS | Focused `rg` excluding dev-runtime and repository implementation files returned no matches. |
+| Browser files import mock repositories directly. | PASS | Focused `rg` excluding repository implementation files returned no matches. |
 
-## Local DB Viewer Boundary
+## SQLite Boundary
 
 | Check | Status | Evidence |
 | --- | --- | --- |
-| Browser flow remains Browser -> API client -> server API -> data source. | PASS | DB Viewer still uses `src/engine/api/mock-db-api-client.js` and `/api/mock-db/snapshot`; no browser Local DB imports were added. |
-| Local Mem behavior is preserved. | PASS | AdminDbViewer Playwright retained Local Mem clear/seed, filters, diagnostics, and live persisted tool-record coverage. |
-| Local DB behavior is read-only. | PASS | AdminDbViewer Playwright asserts no Local DB clear/seed/write controls are visible or available. |
-| Local DB renders live server-backed adapter state. | PASS | Playwright and API contract probe mutate/read server state through API routes and verify DB Viewer output. |
-| Local DB missing storage fails visibly. | PASS | Playwright and API contract probe assert `Local DB adapter not configured` diagnostics. |
-| UAT/Prod are not local login choices. | PASS | `/api/session/modes` probe returned exactly `Local Mem` and `Local DB`; UAT/Prod remain server-side deployment metadata only. |
+| Local DB remains behind the server API boundary only. | PASS | SQLite is imported only in `src/dev-runtime/server/mock-api-router.mjs`; browser callers continue through `/api/session/*` and `/api/mock-db/*`. |
+| Local Mem behavior is preserved. | PASS | AdminDbViewer Local Mem Playwright coverage passed. |
+| Admin DB Viewer Local DB read-only inspection is preserved. | PASS | AdminDbViewer Local DB Playwright coverage passed against SQLite-backed state. |
+| Local DB initializes required tables deterministically. | PASS | SQLite contract probe inspected physical SQLite tables and schema columns. |
+| Empty tables remain visible with headers. | PASS | SQLite contract probe and AdminDbViewer Playwright verified empty table schemas/headers. |
+| SQLite initialization/read/write/snapshot failures fail visibly. | PASS | Contract probe verified disabled snapshot and write diagnostics. |
+| UAT/Prod are not local login choices. | PASS | `/api/session/modes` probe in SQLite contract validation returned `Local Mem|Local DB`; UAT/Prod remain server-side deployment metadata only. |
 
 ## Remaining Internal Matches
 
 - UAT/Prod strings remain only in the server adapter contract as deployment-only metadata.
-- `toolbox/*/*-mock-repository.js` and `toolbox/colors/palette-workspace-repository.js` remain server/data-source implementation modules, not active browser entry imports.
+- `node:sqlite` currently emits a Node experimental warning during validation; no browser bundle or user-facing page imports it.
 - `/api/mock-db/*` route names and `mock-db-*` module filenames remain stable internal API contracts.

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -8,8 +8,8 @@ Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 Changed runtime JS files considered:
 (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
-(96%) src/engine/api/mock-db-viewer-ui.js - executed lines 510/510; executed functions 92/96
-(100%) src/engine/api/mock-db-api-client.js - executed lines 19/19; executed functions 5/5
+(60%) src/engine/api/mock-db-api-client.js - executed lines 19/19; executed functions 3/5
+(85%) src/engine/api/mock-db-viewer-ui.js - executed lines 510/510; executed functions 82/96
 
 Guardrail warnings:
 (0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -12,29 +12,27 @@ 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:
-(77%) Toolbox Index - exercised 7 runtime JS files
+(61%) Toolbox Index - exercised 3 runtime JS files
 (0%) Tool Template V2 - not exercised by this Playwright run
-(75%) Theme V2 Shared JS - exercised 2 runtime JS files
+(84%) Theme V2 Shared JS - exercised 3 runtime JS files
 
 Changed runtime JS files covered:
 (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
-(96%) src/engine/api/mock-db-viewer-ui.js - executed lines 510/510; executed functions 92/96
-(100%) src/engine/api/mock-db-api-client.js - executed lines 19/19; executed functions 5/5
+(60%) src/engine/api/mock-db-api-client.js - executed lines 19/19; executed functions 3/5
+(85%) src/engine/api/mock-db-viewer-ui.js - executed lines 510/510; executed functions 82/96
 
 Files with executed line/function counts where available:
+(55%) toolbox/project-journey/project-journey.js - executed lines 1003/1003; executed functions 54/99
+(56%) src/engine/api/server-api-client.js - executed lines 154/154; executed functions 10/18
+(60%) src/engine/api/mock-db-api-client.js - executed lines 19/19; executed functions 3/5
 (64%) assets/theme-v2/js/tool-display-mode.js - executed lines 201/201; executed functions 9/14
 (67%) admin/db-viewer.js - executed lines 53/53; executed functions 4/6
-(67%) src/engine/api/server-api-client.js - executed lines 154/154; executed functions 12/18
-(69%) toolbox/colors/colors.js - executed lines 877/877; executed functions 62/90
-(75%) toolbox/project-journey/project-journey.js - executed lines 1003/1003; executed functions 74/99
-(78%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 415/415; executed functions 29/37
 (81%) toolbox/tool-registry-api-client.js - executed lines 148/148; executed functions 22/27
-(88%) toolbox/assets/assets.js - executed lines 519/519; executed functions 53/60
-(96%) src/engine/api/mock-db-viewer-ui.js - executed lines 510/510; executed functions 92/96
-(100%) src/engine/api/mock-db-api-client.js - executed lines 19/19; executed functions 5/5
-(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
+(85%) src/engine/api/mock-db-viewer-ui.js - executed lines 510/510; executed functions 82/96
+(86%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 415/415; executed functions 32/37
+(88%) src/engine/api/session-api-client.js - executed lines 34/34; executed functions 7/8
+(94%) assets/theme-v2/js/login-session.js - executed lines 163/163; executed functions 15/16
 (100%) toolbox/project-journey/project-journey-api-client.js - executed lines 12/12; executed functions 2/2
 
 Uncovered or low-coverage changed JS files:
@@ -46,6 +44,6 @@ Changed JS files considered:
 (0%) src/dev-runtime/server/mock-api-router.mjs - 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/LoginSessionMode.spec.mjs - changed JS file not collected as browser runtime coverage
+(60%) src/engine/api/mock-db-api-client.js - changed JS file with browser V8 coverage
 (67%) admin/db-viewer.js - changed JS file with browser V8 coverage
-(96%) src/engine/api/mock-db-viewer-ui.js - changed JS file with browser V8 coverage
-(100%) src/engine/api/mock-db-api-client.js - changed JS file with browser V8 coverage
+(85%) src/engine/api/mock-db-viewer-ui.js - changed JS file with browser V8 coverage

docs_build/dev/reports/sqlite-local-db-report.md

@@ -0,0 +1,49 @@
+# PR_26158_027 SQLite Local DB Report
+
+## Executive Summary
+
+Replaced the server-side JSON-backed Local DB adapter with a real SQLite-backed Local DB adapter using Node's `node:sqlite` runtime. Browser code remains on the existing server API boundary, Local Mem behavior is unchanged, and Admin DB Viewer continues to inspect Local DB in read-only mode through `/api/mock-db/snapshot`.
+
+## Requirement Checklist
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Read `docs_build/dev/PROJECT_INSTRUCTIONS.md` first. | PASS | Instructions were read before implementation. |
+| Replace JSON-backed Local DB with real SQLite-backed Local DB. | PASS | `src/dev-runtime/server/mock-api-router.mjs` imports `node:sqlite` and persists Local DB state into physical SQLite tables. |
+| Keep Local DB behind server API boundary only. | PASS | SQLite implementation lives under `src/dev-runtime/server`; browser files continue to call server API clients/routes only. |
+| Browser code must not import SQLite, DB repositories, dev-runtime persistence, or DB implementation modules directly. | PASS | Static boundary checks returned no browser matches for `node:sqlite`, `DatabaseSync`, `LocalDbAdapter`, `src/dev-runtime`, or mock repositories. |
+| Preserve Local Mem behavior unchanged. | PASS | AdminDbViewer Local Mem Playwright coverage passed. |
+| Preserve Admin DB Viewer read-only Local DB inspection through API. | PASS | AdminDbViewer Local DB Playwright coverage passed with no write controls visible. |
+| Local DB initializes required tables/schemas deterministically. | PASS | SQLite contract probe verified physical SQLite tables and schema columns. |
+| Empty tables remain visible with headers in Admin DB Viewer. | PASS | SQLite contract probe and AdminDbViewer Playwright verified empty tables and headers. |
+| Initialization, read, write, and snapshot failures fail visibly with actionable diagnostics. | PASS | Contract probe verified disabled SQLite snapshot/write diagnostics with `Local DB adapter not configured`, `SQLite`, and `GAMEFOUNDRY_LOCAL_DB_DISABLE`. |
+| Do not add UAT/Prod API adapter behavior. | PASS | UAT/Prod remain deployment-only metadata; no UAT/Prod adapter implementation was added. |
+| Do not expose UAT or Prod as local login choices. | PASS | `/api/session/modes` validation returned only `Local Mem` and `Local DB`. |
+| Do not modify `start_of_day` folders. | PASS | No `start_of_day` files changed. |
+
+## Implementation Notes
+
+| Area | Evidence |
+| --- | --- |
+| SQLite adapter | `LocalDbAdapter` now opens `DatabaseSync`, initializes `__gf_metadata`, creates one SQLite table per known mock DB table, adds deterministic schema columns, and stores JSON-encoded cell values to preserve booleans/arrays/objects. |
+| Default storage | Local DB defaults to `tmp/local-db/local-db-state.sqlite`; `GAMEFOUNDRY_LOCAL_DB_PATH` still overrides it for tests and local diagnostics. |
+| Failure diagnostics | `GAMEFOUNDRY_LOCAL_DB_DISABLE=1` blocks initialization/read/write and returns visible server API diagnostics. |
+| Session mode copy | Local DB description now says `Uses LocalDbAdapter backed by server SQLite storage.` |
+| Tests | AdminDbViewer and LoginSessionMode test storage paths now use `.sqlite` files. |
+
+## Validation Evidence
+
+| Validation | Result |
+| --- | --- |
+| Changed-file syntax checks | PASS |
+| Local DB/API SQLite contract validation | PASS |
+| AdminDbViewer Playwright | PASS, 7/7 |
+| LoginSessionMode Playwright | PASS, 5/5 |
+| Static import boundary audit | PASS |
+| Active source/test JSON-backed wording check | PASS |
+| `git diff --check` | PASS, Git line-ending warnings only |
+
+## Remaining Migration Notes
+
+- Node emitted its standard experimental warning for `node:sqlite`; the implementation remains server/dev-runtime only and does not affect browser bundles.
+- UAT/Prod remain deployment-only adapter contract metadata and were not implemented in this PR.

docs_build/dev/reports/testing_lane_execution_report.md

@@ -1,47 +1,57 @@
-# PR_26158_026 Testing Lane Execution Report
+# PR_26158_027 Testing Lane Execution Report
 
 ## Lanes Run
 
 | Lane | Command | Result |
 | --- | --- | --- |
-| Changed-file syntax | `node --check admin/db-viewer.js`; `node --check src/engine/api/mock-db-api-client.js`; `node --check src/engine/api/mock-db-viewer-ui.js`; `node --check tests/playwright/tools/AdminDbViewer.spec.mjs` | PASS |
-| Local DB/API snapshot contract validation | Custom Node probe using `tests/helpers/playwrightRepoServer.mjs` with isolated `GAMEFOUNDRY_LOCAL_DB_PATH=tmp/local-db/pr_026_snapshot_contract.json` | PASS |
+| Changed-file syntax | `node --check src/dev-runtime/server/mock-api-router.mjs`; `node --check src/dev-runtime/persistence/mock-db-store.js`; `node --check tests/playwright/tools/AdminDbViewer.spec.mjs`; `node --check tests/playwright/tools/LoginSessionMode.spec.mjs` | PASS |
+| Local DB/API SQLite contract validation | Custom Node probe using `tests/helpers/playwrightRepoServer.mjs`, `node:sqlite`, and isolated `GAMEFOUNDRY_LOCAL_DB_PATH=tmp/local-db/pr_027_sqlite_contract.sqlite` | PASS |
 | AdminDbViewer Playwright | `npx playwright test tests/playwright/tools/AdminDbViewer.spec.mjs` | PASS, 7/7 |
-| Local login mode check | Custom Node probe of `/api/session/modes` | PASS |
-| Static import boundary | Focused `rg` checks for forbidden browser imports of `src/dev-runtime`, mock repositories, `LocalDbAdapter`, and DB implementation modules | PASS |
+| LoginSessionMode Playwright | `npx playwright test tests/playwright/tools/LoginSessionMode.spec.mjs` | PASS, 5/5 |
+| Static import boundary | Focused `rg` checks for forbidden browser imports of `node:sqlite`, `DatabaseSync`, `LocalDbAdapter`, `src/dev-runtime`, and mock repositories | PASS |
+| Active source/test JSON-backed Local DB wording check | Focused `rg` for `JSON storage`, `server local JSON`, `local JSON`, and `.json` in active Local DB source/tests | PASS; only normal `response.json()` calls matched |
 | Changed-file/static validation | `git diff --check` | PASS, with Git line-ending warnings only |
 
-## Local DB/API Snapshot Contract Probe
+## Local DB/API SQLite Contract Probe
 
 | Assertion | Result |
 | --- | --- |
-| Local Mem snapshot loads through `/api/mock-db/snapshot`. | PASS |
-| Local Mem empty tables expose schemas. | PASS |
-| Local DB mode selects through `/api/session/mode`. | PASS |
-| Local DB Admin resolves through users/roles/user_roles. | PASS |
-| Local DB snapshot loads through `/api/mock-db/snapshot`. | PASS |
-| Local DB renders live adapter state from the shared server API. | PASS |
-| Local DB empty tables expose schemas. | PASS |
-| Guest is not stored in Local DB `users`. | PASS |
-| Disabled Local DB snapshot fails visibly with `Local DB adapter not configured` and `GAMEFOUNDRY_LOCAL_DB_DISABLE`. | PASS |
+| Local login choices remain exactly `Local Mem` and `Local DB`. | PASS |
+| Local DB mode description names SQLite storage. | PASS |
+| Local DB mode initializes SQLite storage through `/api/session/mode`. | PASS |
+| Local DB resolves Admin through SQLite-backed users/roles/user_roles data. | PASS |
+| `/api/mock-db/snapshot` reads SQLite-backed Local DB state. | PASS |
+| Local DB snapshot includes schemas and empty tables. | PASS |
+| Guest is not stored in SQLite `users`. | PASS |
+| Physical SQLite tables are initialized for `users`, `roles`, `user_roles`, `palette_colors`, `asset_library_items`, and `project_journey_items`. | PASS |
+| SQLite table columns include deterministic schema fields such as `key`, `createdAt`, and `updatedBy`. | PASS |
+| SQLite-backed writes through `/api/dev/testing/mock-db-state` persist and appear in snapshots. | PASS |
+| SQLite-backed data persists across server restart with the same DB file. | PASS |
+| Disabled SQLite snapshot fails visibly with `Local DB adapter not configured`, `SQLite`, and `GAMEFOUNDRY_LOCAL_DB_DISABLE`. | PASS |
+| Disabled SQLite write fails visibly with actionable diagnostic text. | PASS |
 
 ## Playwright Coverage
 
-AdminDbViewer now covers:
+AdminDbViewer covers:
 
 - Existing Local Mem DB Viewer behavior.
-- Local DB read-only display with active mode text.
-- Local DB empty table schema/header rendering.
+- SQLite-backed Local DB read-only display.
+- Local DB empty-table schema/header rendering.
 - Local DB live adapter state rendering.
 - Local DB unavailable diagnostic rendering.
 - Absence of Local DB write controls.
 
-`docs_build/dev/reports/playwright_v8_coverage_report.txt` was regenerated by the targeted Playwright run.
+LoginSessionMode covers:
+
+- Local DB login mode copy updated to SQLite.
+- Local DB session user selection through server API.
+- Direct admin DB Viewer URL access in Local DB mode.
+
+`docs_build/dev/reports/playwright_v8_coverage_report.txt` was regenerated by the targeted Playwright runs. Node emitted the standard experimental warning for `node:sqlite`; validation passed.
 
 ## Skipped Lanes
 
 | Lane | Decision | Reason |
 | --- | --- | --- |
-| LoginSessionMode Playwright | SKIP | No login/session mode source files were changed. A focused `/api/session/modes` probe verified Local Mem and Local DB remain the only local choices. |
 | Full samples smoke | SKIP | No shared sample loader/framework or sample JSON changed. |
-| Full Playwright suite | SKIP | Targeted Admin DB Viewer, server snapshot contract, local mode check, and static import checks cover the changed surfaces. |
+| Full Playwright suite | SKIP | Targeted SQLite contract, Admin DB Viewer, LoginSessionMode, and static import checks cover the changed surfaces. |

src/dev-runtime/persistence/mock-db-store.js

@@ -58,7 +58,7 @@ export const MOCK_DB_SESSION_MODES = Object.freeze([
     adapterId: "local-db",
     adapterName: "LocalDbAdapter",
     configured: true,
-    description: "Uses LocalDbAdapter backed by server local JSON storage.",
+    description: "Uses LocalDbAdapter backed by server SQLite storage.",
     environment: "Local DB",
     id: "local-db",
     label: "Local DB",