Merge PR #45: PR_26171_ALPHA_023-game-journey-postgres-metrics-migration

PR_26171_ALPHA_023-game-journey-postgres-metrics-migration

Author: ToolboxAid

docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration-data-preservation-notes.md

@@ -0,0 +1,19 @@
+# PR_26171_ALPHA_023 Migration And Data Preservation Notes
+
+TEAM ownership: ALPHA.
+
+Migration behavior:
+- Active Game Journey completion metrics persistence now uses Postgres through `GAMEFOUNDRY_DATABASE_URL`.
+- The legacy SQLite file path is treated as a data-preservation guard only.
+- Existing legacy SQLite metrics data is preserved in place and is not deleted or overwritten.
+- If the legacy file exists, the metrics store stops with an actionable diagnostic instead of silently replacing data with Postgres seed rows.
+- No SQLite fallback is used after the Postgres path is active.
+
+Operator action when legacy data exists:
+- Export or migrate legacy metrics into Postgres.
+- Verify the Postgres `game_journey_completion_metrics` table contains the expected rows.
+- Move or archive the legacy SQLite file after verification.
+- Restart the Local API.
+
+Known local state:
+- This workspace had an ignored legacy metrics file under `tmp/local-api/`; tests used injected Postgres stubs and disabled the legacy-path guard only for isolated validation.

docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration-instruction-compliance-checklist.md

@@ -0,0 +1,16 @@
+# PR_26171_ALPHA_023 Instruction Compliance Checklist
+
+TEAM ownership: ALPHA.
+
+- PASS: Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
+- PASS: Read `docs_build/dev/PROJECT_MULTI_PC.txt`.
+- PASS: Verified Game Journey is Team Alpha owned.
+- PASS: Started from synced `main` before creating `team/ALPHA/game-journey`.
+- PASS: Scope stayed within Game Journey metrics persistence, Local API async pass-through, affected tests, and required reports.
+- PASS: Removed active Game Journey `node:sqlite` / `DatabaseSync` persistence.
+- PASS: Preserved data by blocking silent legacy SQLite replacement.
+- PASS: Used targeted validation only.
+- PASS: Did not run samples.
+- PASS: Required shared reports are generated under `docs_build/dev/reports/`.
+- PASS: Manual validation notes are present.
+- PASS: Repo-structured ZIP is required under `tmp/`.

docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration-manual-validation-notes.md

@@ -0,0 +1,20 @@
+# PR_26171_ALPHA_023 Manual Validation Notes
+
+TEAM ownership: ALPHA.
+
+Manual validation performed:
+- Confirmed Game Journey completion metrics dashboard renders through the Local API with a Postgres client stub.
+- Confirmed `/api/game-journey/completion-metrics` returns `databaseEngine: "Postgres"` and the existing 14 completion metric records.
+- Confirmed updating `001-idea` persists through the Postgres stub and returns `updatedMetric`.
+- Confirmed missing Postgres configuration reports `GAMEFOUNDRY_DATABASE_URL`.
+- Confirmed legacy SQLite data guard blocks startup without deleting the legacy file.
+
+Expected outcome:
+- Game Journey completion metrics preserve user-visible behavior and response shapes.
+- Active metrics persistence no longer depends on `node:sqlite` or `DatabaseSync`.
+- Legacy SQLite data cannot be silently dropped during cutover.
+
+Out of scope:
+- Full samples smoke.
+- Broad Game Journey editor/detail regression tests.
+- Live Postgres connectivity against an operator database.

docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration.md

@@ -0,0 +1,45 @@
+# PR_26171_ALPHA_023-game-journey-postgres-metrics-migration
+
+## Summary
+
+TEAM ownership: ALPHA.
+
+Branch: `team/ALPHA/game-journey`.
+
+Scope completed:
+- Migrated Game Journey completion metrics persistence from active SQLite usage to Postgres.
+- Replaced `node:sqlite` / `DatabaseSync` usage in `src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs`.
+- Reused the existing `createPostgresConnectionClient` dev-runtime pattern backed by `GAMEFOUNDRY_DATABASE_URL`.
+- Preserved the existing Game Journey completion metrics API response shape, including summary counts, `records`, `updatedMetric`, and compatibility metadata fields.
+- Updated Game Journey repository and Local API routes to await the Postgres-backed metrics store.
+- Updated affected Game Journey Playwright tests to use an injected Postgres client stub.
+
+## Validation
+
+Passed:
+- `git diff --check`
+- `node --check src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs`
+- `node --check src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js`
+- `node --check src/dev-runtime/server/local-api-router.mjs`
+- `node --check tests/playwright/tools/GameJourneyTool.spec.mjs`
+- `node --check tests/helpers/playwrightRepoServer.mjs`
+- `node --check tests/helpers/gameJourneyCompletionMetricsPostgresClientStub.mjs`
+- `npx playwright test tests/playwright/tools/GameJourneyTool.spec.mjs --config=codex_playwright_system_chrome.config.cjs --project=playwright -g "Game Journey progress dashboard|Game Journey mock data keeps system guidance template-owned|Game Journey Local API persists completion metrics to Postgres|Game Journey completion metrics fail visibly|Game Journey completion metrics protect legacy SQLite"`
+
+Targeted checks:
+- Verified changed Game Journey metrics paths no longer import `node:sqlite` or `DatabaseSync`.
+- Verified missing Postgres configuration fails with an actionable `GAMEFOUNDRY_DATABASE_URL` diagnostic.
+- Verified legacy SQLite metrics files are not deleted or silently ignored.
+- Verified no secret values are emitted by the metrics store.
+
+Skipped:
+- Full samples smoke: out of scope for this Game Journey metrics persistence migration.
+- Broad Game Journey editor/detail Playwright cases: out of scope for completion metrics persistence. A broader exploratory run surfaced editor/detail assertions outside the metrics path, so the completion gate used the affected metrics/API lane only.
+
+## Data Preservation
+
+The Postgres metrics store does not delete, overwrite, or fall back to legacy SQLite data.
+
+If a legacy Game Journey completion metrics SQLite file exists at the configured legacy path, the store fails visibly before seeding Postgres and reports that the operator must export or migrate the legacy data before moving the file. This prevents silent data loss while removing SQLite as the active persistence path.
+
+Tests inject `gameJourneyCompletionMetricsLegacyDbPath: null` with a Postgres client stub so the active Postgres path can be validated without touching ignored local runtime files.

docs_build/dev/reports/codex_changed_files.txt

@@ -1,36 +1,30 @@
 ## git status --short
-M  docs_build/database/dml/DML_INDEX.md
-M  docs_build/database/dml/messages.sql
-M  docs_build/database/seed/messages.json
-A  docs_build/dev/reports/PR_26171_BETA_022-messages-postgres-service-cutover-instruction-compliance-checklist.md
-A  docs_build/dev/reports/PR_26171_BETA_022-messages-postgres-service-cutover-manual-validation-notes.md
-A  docs_build/dev/reports/PR_26171_BETA_022-messages-postgres-service-cutover.md
+A  docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration-data-preservation-notes.md
+A  docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration-instruction-compliance-checklist.md
+A  docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration-manual-validation-notes.md
+A  docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration.md
 M  docs_build/dev/reports/coverage_changed_js_guardrail.txt
 M  docs_build/dev/reports/playwright_v8_coverage_report.txt
-A  src/dev-runtime/messages/messages-postgres-service.mjs
-D  src/dev-runtime/messages/messages-sqlite-service.mjs
+M  src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs
+M  src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js
 M  src/dev-runtime/server/local-api-router.mjs
-M  tests/dev-runtime/DbSeedIntegrity.test.mjs
-A  tests/helpers/messagesPostgresClientStub.mjs
+A  tests/helpers/gameJourneyCompletionMetricsPostgresClientStub.mjs
 M  tests/helpers/playwrightRepoServer.mjs
-M  tests/playwright/tools/MessagesTool.spec.mjs
+M  tests/playwright/tools/GameJourneyTool.spec.mjs
 
 ## git diff --cached --stat
- docs_build/database/dml/DML_INDEX.md               |    2 +-
- docs_build/database/dml/messages.sql               |    2 +-
- docs_build/database/seed/messages.json             |    2 +-
- ...ice-cutover-instruction-compliance-checklist.md |   16 +
- ...gres-service-cutover-manual-validation-notes.md |   21 +
- ...1_BETA_022-messages-postgres-service-cutover.md |   39 +
- .../dev/reports/coverage_changed_js_guardrail.txt  |   32 +-
- .../dev/reports/playwright_v8_coverage_report.txt  |   91 +-
- .../messages/messages-postgres-service.mjs         | 1117 +++++++++++++++++++
- .../messages/messages-sqlite-service.mjs           | 1118 --------------------
- src/dev-runtime/server/local-api-router.mjs        |   16 +-
- tests/dev-runtime/DbSeedIntegrity.test.mjs         |   61 +-
- tests/helpers/messagesPostgresClientStub.mjs       |   83 ++
- tests/helpers/playwrightRepoServer.mjs             |    6 +-
- tests/playwright/tools/MessagesTool.spec.mjs       |   39 +-
- 15 files changed, 1377 insertions(+), 1268 deletions(-)
+ ...es-metrics-migration-data-preservation-notes.md |  19 ++
+ ...s-migration-instruction-compliance-checklist.md |  16 +
+ ...es-metrics-migration-manual-validation-notes.md |  20 ++
+ ..._023-game-journey-postgres-metrics-migration.md |  45 +++
+ .../dev/reports/coverage_changed_js_guardrail.txt  |  30 +-
+ .../dev/reports/playwright_v8_coverage_report.txt  |  85 +----
+ .../game-journey-completion-metrics-store.mjs      | 369 ++++++++++++---------
+ .../game-journey-mock-repository.js                |   6 +-
+ src/dev-runtime/server/local-api-router.mjs        |  41 ++-
+ ...eJourneyCompletionMetricsPostgresClientStub.mjs |  87 +++++
+ tests/helpers/playwrightRepoServer.mjs             |  11 +-
+ tests/playwright/tools/GameJourneyTool.spec.mjs    | 108 ++++--
+ 12 files changed, 518 insertions(+), 319 deletions(-)
 
 ## git diff --stat

docs_build/dev/reports/codex_review.diff

@@ -6,9 +6,11 @@ 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/messages/messages-postgres-service.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(0%) src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/server/local-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 
 Guardrail warnings:
-(0%) src/dev-runtime/messages/messages-postgres-service.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
+(0%) src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
+(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: changed runtime JS file missing from coverage; advisory only
 (0%) src/dev-runtime/server/local-api-router.mjs - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -12,34 +12,34 @@ 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:
-(87%) Toolbox Index - exercised 4 runtime JS files
+(74%) Toolbox Index - exercised 3 runtime JS files
 (0%) Tool Template V2 - not exercised by this Playwright run
-(56%) Theme V2 Shared JS - exercised 2 runtime JS files
+(63%) Theme V2 Shared JS - exercised 2 runtime JS files
 
 Changed runtime JS files covered:
-(0%) src/dev-runtime/messages/messages-postgres-service.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(0%) src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/server/local-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 
 Files with executed line/function counts where available:
-(36%) src/api/server-api-client.js - executed lines 167/167; executed functions 5/14
-(36%) src/engine/audio/TextToSpeechEngine.js - executed lines 412/412; executed functions 16/44
-(38%) src/api/public-config-client.js - executed lines 209/209; executed functions 10/26
-(54%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 977/977; executed functions 46/85
-(58%) toolbox/messages/messages-api-client.js - executed lines 64/64; executed functions 11/19
+(53%) src/api/server-api-client.js - executed lines 167/167; executed functions 10/19
+(63%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 977/977; executed functions 54/86
 (64%) assets/theme-v2/js/tool-display-mode.js - executed lines 204/204; executed functions 9/14
+(65%) src/api/public-config-client.js - executed lines 209/209; executed functions 17/26
+(67%) src/api/game-journey-completion-api-client.js - executed lines 15/15; executed functions 2/3
+(74%) toolbox/game-journey/game-journey.js - executed lines 1652/1652; executed functions 110/149
 (76%) toolbox/tool-registry-api-client.js - executed lines 155/155; executed functions 22/29
-(95%) toolbox/messages/messages.js - executed lines 1019/1019; executed functions 98/103
-(100%) src/engine/audio/TextToSpeechDefaults.js - executed lines 108/108; executed functions 1/1
-(100%) toolbox/messages/message-tts-service-registry.js - executed lines 45/45; executed functions 7/7
+(100%) toolbox/game-journey/game-journey-api-client.js - executed lines 19/19; executed functions 2/2
 
 Uncovered or low-coverage changed JS files:
-(0%) src/dev-runtime/messages/messages-postgres-service.mjs - WARNING: uncovered changed runtime JS file; advisory only
+(0%) src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs - WARNING: uncovered changed runtime JS file; advisory only
+(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: uncovered changed runtime JS file; advisory only
 (0%) src/dev-runtime/server/local-api-router.mjs - WARNING: uncovered changed runtime JS file; advisory only
 
 Changed JS files considered:
-(0%) src/dev-runtime/messages/messages-postgres-service.mjs - changed JS file not collected as browser runtime coverage
+(0%) src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs - changed JS file not collected as browser runtime coverage
+(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - changed JS file not collected as browser runtime coverage
 (0%) src/dev-runtime/server/local-api-router.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/dev-runtime/DbSeedIntegrity.test.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/helpers/messagesPostgresClientStub.mjs - changed JS file not collected as browser runtime coverage
+(0%) tests/helpers/gameJourneyCompletionMetricsPostgresClientStub.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/helpers/playwrightRepoServer.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/MessagesTool.spec.mjs - changed JS file not collected as browser runtime coverage
+(0%) tests/playwright/tools/GameJourneyTool.spec.mjs - changed JS file not collected as browser runtime coverage