Skip to content

Commit 4bf6db2

Browse files
ToolboxAidToolboxAid
authored
Merge PR #45: PR_26171_ALPHA_023-game-journey-postgres-metrics-migration
PR_26171_ALPHA_023-game-journey-postgres-metrics-migration
2 parents ca72ead + 6f3c4d0 commit 4bf6db2

14 files changed

Lines changed: 545 additions & 263 deletions

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# PR_26171_ALPHA_023 Migration And Data Preservation Notes
2+
3+
TEAM ownership: ALPHA.
4+
5+
Migration behavior:
6+
- Active Game Journey completion metrics persistence now uses Postgres through `GAMEFOUNDRY_DATABASE_URL`.
7+
- The legacy SQLite file path is treated as a data-preservation guard only.
8+
- Existing legacy SQLite metrics data is preserved in place and is not deleted or overwritten.
9+
- If the legacy file exists, the metrics store stops with an actionable diagnostic instead of silently replacing data with Postgres seed rows.
10+
- No SQLite fallback is used after the Postgres path is active.
11+
12+
Operator action when legacy data exists:
13+
- Export or migrate legacy metrics into Postgres.
14+
- Verify the Postgres `game_journey_completion_metrics` table contains the expected rows.
15+
- Move or archive the legacy SQLite file after verification.
16+
- Restart the Local API.
17+
18+
Known local state:
19+
- 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‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# PR_26171_ALPHA_023 Instruction Compliance Checklist
2+
3+
TEAM ownership: ALPHA.
4+
5+
- PASS: Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
6+
- PASS: Read `docs_build/dev/PROJECT_MULTI_PC.txt`.
7+
- PASS: Verified Game Journey is Team Alpha owned.
8+
- PASS: Started from synced `main` before creating `team/ALPHA/game-journey`.
9+
- PASS: Scope stayed within Game Journey metrics persistence, Local API async pass-through, affected tests, and required reports.
10+
- PASS: Removed active Game Journey `node:sqlite` / `DatabaseSync` persistence.
11+
- PASS: Preserved data by blocking silent legacy SQLite replacement.
12+
- PASS: Used targeted validation only.
13+
- PASS: Did not run samples.
14+
- PASS: Required shared reports are generated under `docs_build/dev/reports/`.
15+
- PASS: Manual validation notes are present.
16+
- 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‎

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

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

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# PR_26171_ALPHA_023-game-journey-postgres-metrics-migration
2+
3+
## Summary
4+
5+
TEAM ownership: ALPHA.
6+
7+
Branch: `team/ALPHA/game-journey`.
8+
9+
Scope completed:
10+
- Migrated Game Journey completion metrics persistence from active SQLite usage to Postgres.
11+
- Replaced `node:sqlite` / `DatabaseSync` usage in `src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs`.
12+
- Reused the existing `createPostgresConnectionClient` dev-runtime pattern backed by `GAMEFOUNDRY_DATABASE_URL`.
13+
- Preserved the existing Game Journey completion metrics API response shape, including summary counts, `records`, `updatedMetric`, and compatibility metadata fields.
14+
- Updated Game Journey repository and Local API routes to await the Postgres-backed metrics store.
15+
- Updated affected Game Journey Playwright tests to use an injected Postgres client stub.
16+
17+
## Validation
18+
19+
Passed:
20+
- `git diff --check`
21+
- `node --check src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs`
22+
- `node --check src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js`
23+
- `node --check src/dev-runtime/server/local-api-router.mjs`
24+
- `node --check tests/playwright/tools/GameJourneyTool.spec.mjs`
25+
- `node --check tests/helpers/playwrightRepoServer.mjs`
26+
- `node --check tests/helpers/gameJourneyCompletionMetricsPostgresClientStub.mjs`
27+
- `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"`
28+
29+
Targeted checks:
30+
- Verified changed Game Journey metrics paths no longer import `node:sqlite` or `DatabaseSync`.
31+
- Verified missing Postgres configuration fails with an actionable `GAMEFOUNDRY_DATABASE_URL` diagnostic.
32+
- Verified legacy SQLite metrics files are not deleted or silently ignored.
33+
- Verified no secret values are emitted by the metrics store.
34+
35+
Skipped:
36+
- Full samples smoke: out of scope for this Game Journey metrics persistence migration.
37+
- 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.
38+
39+
## Data Preservation
40+
41+
The Postgres metrics store does not delete, overwrite, or fall back to legacy SQLite data.
42+
43+
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.
44+
45+
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‎

Lines changed: 21 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,30 @@
11
## git status --short
2-
M docs_build/database/dml/DML_INDEX.md
3-
M docs_build/database/dml/messages.sql
4-
M docs_build/database/seed/messages.json
5-
A docs_build/dev/reports/PR_26171_BETA_022-messages-postgres-service-cutover-instruction-compliance-checklist.md
6-
A docs_build/dev/reports/PR_26171_BETA_022-messages-postgres-service-cutover-manual-validation-notes.md
7-
A docs_build/dev/reports/PR_26171_BETA_022-messages-postgres-service-cutover.md
2+
A docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration-data-preservation-notes.md
3+
A docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration-instruction-compliance-checklist.md
4+
A docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration-manual-validation-notes.md
5+
A docs_build/dev/reports/PR_26171_ALPHA_023-game-journey-postgres-metrics-migration.md
86
M docs_build/dev/reports/coverage_changed_js_guardrail.txt
97
M docs_build/dev/reports/playwright_v8_coverage_report.txt
10-
A src/dev-runtime/messages/messages-postgres-service.mjs
11-
D src/dev-runtime/messages/messages-sqlite-service.mjs
8+
M src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs
9+
M src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js
1210
M src/dev-runtime/server/local-api-router.mjs
13-
M tests/dev-runtime/DbSeedIntegrity.test.mjs
14-
A tests/helpers/messagesPostgresClientStub.mjs
11+
A tests/helpers/gameJourneyCompletionMetricsPostgresClientStub.mjs
1512
M tests/helpers/playwrightRepoServer.mjs
16-
M tests/playwright/tools/MessagesTool.spec.mjs
13+
M tests/playwright/tools/GameJourneyTool.spec.mjs
1714

1815
## git diff --cached --stat
19-
docs_build/database/dml/DML_INDEX.md | 2 +-
20-
docs_build/database/dml/messages.sql | 2 +-
21-
docs_build/database/seed/messages.json | 2 +-
22-
...ice-cutover-instruction-compliance-checklist.md | 16 +
23-
...gres-service-cutover-manual-validation-notes.md | 21 +
24-
...1_BETA_022-messages-postgres-service-cutover.md | 39 +
25-
.../dev/reports/coverage_changed_js_guardrail.txt | 32 +-
26-
.../dev/reports/playwright_v8_coverage_report.txt | 91 +-
27-
.../messages/messages-postgres-service.mjs | 1117 +++++++++++++++++++
28-
.../messages/messages-sqlite-service.mjs | 1118 --------------------
29-
src/dev-runtime/server/local-api-router.mjs | 16 +-
30-
tests/dev-runtime/DbSeedIntegrity.test.mjs | 61 +-
31-
tests/helpers/messagesPostgresClientStub.mjs | 83 ++
32-
tests/helpers/playwrightRepoServer.mjs | 6 +-
33-
tests/playwright/tools/MessagesTool.spec.mjs | 39 +-
34-
15 files changed, 1377 insertions(+), 1268 deletions(-)
16+
...es-metrics-migration-data-preservation-notes.md | 19 ++
17+
...s-migration-instruction-compliance-checklist.md | 16 +
18+
...es-metrics-migration-manual-validation-notes.md | 20 ++
19+
..._023-game-journey-postgres-metrics-migration.md | 45 +++
20+
.../dev/reports/coverage_changed_js_guardrail.txt | 30 +-
21+
.../dev/reports/playwright_v8_coverage_report.txt | 85 +----
22+
.../game-journey-completion-metrics-store.mjs | 369 ++++++++++++---------
23+
.../game-journey-mock-repository.js | 6 +-
24+
src/dev-runtime/server/local-api-router.mjs | 41 ++-
25+
...eJourneyCompletionMetricsPostgresClientStub.mjs | 87 +++++
26+
tests/helpers/playwrightRepoServer.mjs | 11 +-
27+
tests/playwright/tools/GameJourneyTool.spec.mjs | 108 ++++--
28+
12 files changed, 518 insertions(+), 319 deletions(-)
3529

3630
## git diff --stat

‎docs_build/dev/reports/codex_review.diff‎

-120 KB
Binary file not shown.

‎docs_build/dev/reports/coverage_changed_js_guardrail.txt‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,11 @@ Missing changed runtime JS files are WARN, not FAIL.
66
Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
77

88
Changed runtime JS files considered:
9-
(0%) src/dev-runtime/messages/messages-postgres-service.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
9+
(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
10+
(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
1011
(0%) src/dev-runtime/server/local-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
1112

1213
Guardrail warnings:
13-
(0%) src/dev-runtime/messages/messages-postgres-service.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
14+
(0%) src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
15+
(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: changed runtime JS file missing from coverage; advisory only
1416
(0%) src/dev-runtime/server/local-api-router.mjs - WARNING: changed runtime JS file missing from coverage; advisory only

‎docs_build/dev/reports/playwright_v8_coverage_report.txt‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -12,34 +12,34 @@ Note: entry percentages use function coverage when available, otherwise line cov
1212
Note: coverage entries are aggregated across every page/tool where coverageReporter.start(page) and coverageReporter.stop(page) ran.
1313

1414
Exercised tool entry points detected:
15-
(87%) Toolbox Index - exercised 4 runtime JS files
15+
(74%) Toolbox Index - exercised 3 runtime JS files
1616
(0%) Tool Template V2 - not exercised by this Playwright run
17-
(56%) Theme V2 Shared JS - exercised 2 runtime JS files
17+
(63%) Theme V2 Shared JS - exercised 2 runtime JS files
1818

1919
Changed runtime JS files covered:
20-
(0%) src/dev-runtime/messages/messages-postgres-service.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
20+
(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
21+
(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
2122
(0%) src/dev-runtime/server/local-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
2223

2324
Files with executed line/function counts where available:
24-
(36%) src/api/server-api-client.js - executed lines 167/167; executed functions 5/14
25-
(36%) src/engine/audio/TextToSpeechEngine.js - executed lines 412/412; executed functions 16/44
26-
(38%) src/api/public-config-client.js - executed lines 209/209; executed functions 10/26
27-
(54%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 977/977; executed functions 46/85
28-
(58%) toolbox/messages/messages-api-client.js - executed lines 64/64; executed functions 11/19
25+
(53%) src/api/server-api-client.js - executed lines 167/167; executed functions 10/19
26+
(63%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 977/977; executed functions 54/86
2927
(64%) assets/theme-v2/js/tool-display-mode.js - executed lines 204/204; executed functions 9/14
28+
(65%) src/api/public-config-client.js - executed lines 209/209; executed functions 17/26
29+
(67%) src/api/game-journey-completion-api-client.js - executed lines 15/15; executed functions 2/3
30+
(74%) toolbox/game-journey/game-journey.js - executed lines 1652/1652; executed functions 110/149
3031
(76%) toolbox/tool-registry-api-client.js - executed lines 155/155; executed functions 22/29
31-
(95%) toolbox/messages/messages.js - executed lines 1019/1019; executed functions 98/103
32-
(100%) src/engine/audio/TextToSpeechDefaults.js - executed lines 108/108; executed functions 1/1
33-
(100%) toolbox/messages/message-tts-service-registry.js - executed lines 45/45; executed functions 7/7
32+
(100%) toolbox/game-journey/game-journey-api-client.js - executed lines 19/19; executed functions 2/2
3433

3534
Uncovered or low-coverage changed JS files:
36-
(0%) src/dev-runtime/messages/messages-postgres-service.mjs - WARNING: uncovered changed runtime JS file; advisory only
35+
(0%) src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs - WARNING: uncovered changed runtime JS file; advisory only
36+
(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: uncovered changed runtime JS file; advisory only
3737
(0%) src/dev-runtime/server/local-api-router.mjs - WARNING: uncovered changed runtime JS file; advisory only
3838

3939
Changed JS files considered:
40-
(0%) src/dev-runtime/messages/messages-postgres-service.mjs - changed JS file not collected as browser runtime coverage
40+
(0%) src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs - changed JS file not collected as browser runtime coverage
41+
(0%) src/dev-runtime/persistence/tool-repositories/game-journey-mock-repository.js - changed JS file not collected as browser runtime coverage
4142
(0%) src/dev-runtime/server/local-api-router.mjs - changed JS file not collected as browser runtime coverage
42-
(0%) tests/dev-runtime/DbSeedIntegrity.test.mjs - changed JS file not collected as browser runtime coverage
43-
(0%) tests/helpers/messagesPostgresClientStub.mjs - changed JS file not collected as browser runtime coverage
43+
(0%) tests/helpers/gameJourneyCompletionMetricsPostgresClientStub.mjs - changed JS file not collected as browser runtime coverage
4444
(0%) tests/helpers/playwrightRepoServer.mjs - changed JS file not collected as browser runtime coverage
45-
(0%) tests/playwright/tools/MessagesTool.spec.mjs - changed JS file not collected as browser runtime coverage
45+
(0%) tests/playwright/tools/GameJourneyTool.spec.mjs - changed JS file not collected as browser runtime coverage

0 commit comments

Comments
 (0)