ToolboxAid · ToolboxAid · Jun 21, 2026 · Jun 21, 2026
diff --git a/docs_build/database/dml/DML_INDEX.md b/docs_build/database/dml/DML_INDEX.md
@@ -14,7 +14,7 @@ Direct SQL setup is intentionally narrow. Account DEV users now require server-s
 | Game Design | `game-design.sql` | Server-seed-owned | Server-side seed API |
 | Game Journey | `game-journey.sql` | Server-seed-owned | Server-side seed API |
 | Game Hub | `game-workspace.sql` | Server-seed-owned | Server-side seed API |
-| Messages | `messages.sql` | Server-seed-owned | Messages Local API/server-side SQLite service |
+| Messages | `messages.sql` | Server-seed-owned | Messages Local API/server-side Postgres service |
 | Objects | `objects.sql` | Server-seed-owned | Server-side seed API |
 | Palette | `palette.sql` | Server-seed-owned | Server-side seed API |
 | Support Tickets | `support-tickets.sql` | Server-seed-owned | Admin Site Setup/server-side seed API |

diff --git a/docs_build/database/dml/messages.sql b/docs_build/database/dml/messages.sql
@@ -6,7 +6,7 @@
 -- Owned tables: messages_categories, messages_emotion_profiles, messages_tts_profiles, messages_records, messages_segments
 
 -- DML status: Server-seed-owned.
--- Setup is performed through the Messages Local API / server-side SQLite service for this PR.
+-- Setup is performed through the Messages Local API / server-side Postgres service for this PR.
 -- Browser pages must not seed authoritative records.
 -- The server/API layer generates all keys and audit fields.
 -- This SQL file intentionally has no direct INSERT statements because direct SQL would bypass key/audit ownership.

diff --git a/docs_build/database/seed/messages.json b/docs_build/database/seed/messages.json
@@ -31,5 +31,5 @@
     "messages_records": [],
     "messages_segments": []
   },
-  "note": "Seed names are applied by the server-side Messages SQLite service. Browser pages must not seed authoritative records."
+  "note": "Seed names are applied by the server-side Messages Postgres service. Browser pages must not seed authoritative records."
 }
diff --git a/..._BETA_022-messages-postgres-service-cutover-instruction-compliance-checklist.md b/..._BETA_022-messages-postgres-service-cutover-instruction-compliance-checklist.md
@@ -0,0 +1,16 @@
+# PR_26171_BETA_022 Instruction Compliance Checklist
+
+TEAM ownership: BETA.
+
+- PASS: Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
+- PASS: Read `docs_build/dev/PROJECT_MULTI_PC.txt`.
+- PASS: Verified Messages belongs to Team Beta ownership.
+- PASS: Started from latest `main` before creating `team/BETA/messages`.
+- PASS: Scope stayed within Messages Local API/service/tests and directly affected active database docs.
+- PASS: Removed active Messages SQLite runtime dependency without touching unrelated SQLite work.
+- PASS: Used targeted validation only.
+- PASS: Did not run samples.
+- PASS: Did not merge.
+- 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/`.
diff --git a/.../PR_26171_BETA_022-messages-postgres-service-cutover-manual-validation-notes.md b/.../PR_26171_BETA_022-messages-postgres-service-cutover-manual-validation-notes.md
@@ -0,0 +1,21 @@
+# PR_26171_BETA_022 Manual Validation Notes
+
+TEAM ownership: BETA.
+
+Manual validation performed:
+- Confirmed the Messages page loads through the repo Playwright server with the injected Postgres client stub.
+- Confirmed seeded Messages categories, emotion profiles, and TTS profiles are available from `/api/messages/*`.
+- Confirmed creating a message preserves `message`, `persistence`, `categoryName`, and `emotionProfileName` response shape fields.
+- Confirmed creating a message segment preserves `segment`, `messageName`, and `emotionProfileName` response shape fields.
+- Confirmed playback behavior remains covered by the Messages Playwright spec.
+- Confirmed active Messages SQLite runtime dependency strings are absent from scoped active paths.
+
+Expected outcome:
+- Messages Local API persists through the Postgres service contract.
+- Messages tool behavior remains unchanged from the browser user's perspective.
+- No `messages.sqlite` file is created or required by the Messages tool tests.
+
+Out of scope:
+- Full samples smoke.
+- Broad runtime regression suite.
+- Production database connectivity against a live Postgres instance.
diff --git a/docs_build/dev/reports/PR_26171_BETA_022-messages-postgres-service-cutover.md b/docs_build/dev/reports/PR_26171_BETA_022-messages-postgres-service-cutover.md
@@ -0,0 +1,39 @@
+# PR_26171_BETA_022-messages-postgres-service-cutover
+
+## Summary
+
+TEAM ownership: BETA.
+
+Branch: `team/BETA/messages`.
+
+Scope completed:
+- Replaced the active Messages Local API persistence service with a Postgres-backed implementation.
+- Routed `/api/messages/*` through `createMessagesPostgresService`.
+- Preserved the existing Local API response envelopes for Messages, categories, emotion profiles, TTS profiles, and segments.
+- Removed the active Messages `node:sqlite`, `DatabaseSync`, `messages.sqlite`, and `GAMEFOUNDRY_MESSAGES_SQLITE_PATH` runtime path.
+- Updated targeted Messages Playwright coverage to use an injected Postgres client stub.
+- Updated active Messages DML/seed documentation from SQLite service wording to Postgres service wording.
+
+Compatibility wrapper:
+- No wrapper was kept. Active imports were migrated to `messages-postgres-service.mjs`, and targeted text checks found no remaining active reference to `messages-sqlite-service`.
+
+Postgres authority:
+- The runtime service uses the existing `createPostgresConnectionClient` path, which reads `GAMEFOUNDRY_DATABASE_URL` for the server-side database connection.
+- Tests inject `createMessagesPostgresClientStub()` to preserve deterministic Local API and Playwright behavior without creating a local SQLite file.
+
+## Validation
+
+Passed:
+- `node --test --test-name-pattern "Messages Local API" tests/dev-runtime/DbSeedIntegrity.test.mjs`
+- `npx playwright test tests/playwright/tools/MessagesTool.spec.mjs --config=codex_playwright_system_chrome.config.cjs --project=playwright`
+- `git diff --check`
+- Targeted stale SQLite dependency check across Messages service, Local API router, affected tests, helper stubs, and active Messages docs.
+- Targeted Postgres wiring check for `GAMEFOUNDRY_DATABASE_URL`, `createPostgresConnectionClient`, and Postgres service references.
+
+Skipped:
+- Full samples smoke: out of scope for this Messages Local API cutover.
+- Broad runtime test suite: out of scope; validation was limited to the affected Messages and Local API surfaces.
+
+## Notes
+
+Playwright V8 coverage reports were refreshed by the targeted Messages Playwright run. Server-side runtime files are listed as advisory warnings because browser V8 coverage does not collect Node-side Local API modules.
diff --git a/docs_build/dev/reports/codex_changed_files.txt b/docs_build/dev/reports/codex_changed_files.txt
@@ -1,69 +1,36 @@
-# PR_26171_GAMMA_019-admin-workstream-mergeability-recovery changed files
+## 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
+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/server/local-api-router.mjs
+M  tests/dev-runtime/DbSeedIntegrity.test.mjs
+A  tests/helpers/messagesPostgresClientStub.mjs
+M  tests/helpers/playwrightRepoServer.mjs
+M  tests/playwright/tools/MessagesTool.spec.mjs
 
-Base: origin/main 35b04c02ea54da8b13c10354126f1ee8ddd14a89
-Head before recovery merge commit: 1806adbf5df787f7072c6579d23b99bb4257466b
+## 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(-)
 
-## Changed files against origin/main
-M	admin/system-health.html
-M	assets/theme-v2/js/admin-system-health.js
-A	docs_build/dev/reports/PR_26171_GAMMA_011-admin-system-health-foundation-instruction-compliance-checklist.md
-A	docs_build/dev/reports/PR_26171_GAMMA_011-admin-system-health-foundation-manual-validation-notes.md
-A	docs_build/dev/reports/PR_26171_GAMMA_011-admin-system-health-foundation.md
-A	docs_build/dev/reports/PR_26171_GAMMA_012-admin-system-health-status-reason-cleanup-instruction-compliance-checklist.md
-A	docs_build/dev/reports/PR_26171_GAMMA_012-admin-system-health-status-reason-cleanup-manual-validation-notes.md
-A	docs_build/dev/reports/PR_26171_GAMMA_012-admin-system-health-status-reason-cleanup.md
-A	docs_build/dev/reports/PR_26171_GAMMA_013-admin-system-health-diagnostics-plan-instruction-compliance-checklist.md
-A	docs_build/dev/reports/PR_26171_GAMMA_013-admin-system-health-diagnostics-plan-manual-validation-notes.md
-A	docs_build/dev/reports/PR_26171_GAMMA_013-admin-system-health-diagnostics-plan.md
-A	docs_build/dev/reports/PR_26171_GAMMA_014-admin-postgres-diagnostics-runtime-instruction-compliance-checklist.md
-A	docs_build/dev/reports/PR_26171_GAMMA_014-admin-postgres-diagnostics-runtime-manual-validation-notes.md
-A	docs_build/dev/reports/PR_26171_GAMMA_014-admin-postgres-diagnostics-runtime.md
-A	docs_build/dev/reports/PR_26171_GAMMA_015-admin-r2-diagnostics-runtime-instruction-compliance-checklist.md
-A	docs_build/dev/reports/PR_26171_GAMMA_015-admin-r2-diagnostics-runtime-manual-validation-notes.md
-A	docs_build/dev/reports/PR_26171_GAMMA_015-admin-r2-diagnostics-runtime.md
-A	docs_build/dev/reports/PR_26171_GAMMA_016-admin-runtime-environment-runtime-instruction-compliance-checklist.md
-A	docs_build/dev/reports/PR_26171_GAMMA_016-admin-runtime-environment-runtime-manual-validation-notes.md
-A	docs_build/dev/reports/PR_26171_GAMMA_016-admin-runtime-environment-runtime.md
-A	docs_build/dev/reports/PR_26171_GAMMA_019-admin-workstream-mergeability-recovery.md
-M	docs_build/dev/reports/codex_changed_files.txt
-M	docs_build/dev/reports/codex_review.diff
-M	docs_build/dev/reports/coverage_changed_js_guardrail.txt
-M	docs_build/dev/reports/playwright_v8_coverage_report.txt
-M	src/dev-runtime/server/local-api-router.mjs
-M	tests/playwright/tools/AdminHealthOperationsPage.spec.mjs
-
-## Diff stat against origin/main
- admin/system-health.html                           |  366 +--
- assets/theme-v2/js/admin-system-health.js          |  505 ++--
- ...-foundation-instruction-compliance-checklist.md |   32 +
- ...em-health-foundation-manual-validation-notes.md |   34 +
- ...171_GAMMA_011-admin-system-health-foundation.md |   65 +
- ...son-cleanup-instruction-compliance-checklist.md |   57 +
- ...tatus-reason-cleanup-manual-validation-notes.md |   26 +
- ...12-admin-system-health-status-reason-cleanup.md |   70 +
- ...ostics-plan-instruction-compliance-checklist.md |   64 +
- ...lth-diagnostics-plan-manual-validation-notes.md |   27 +
- ...MMA_013-admin-system-health-diagnostics-plan.md |   82 +
- ...ics-runtime-instruction-compliance-checklist.md |   64 +
- ...-diagnostics-runtime-manual-validation-notes.md |   27 +
- ...GAMMA_014-admin-postgres-diagnostics-runtime.md |   93 +
- ...ics-runtime-instruction-compliance-checklist.md |   62 +
- ...-diagnostics-runtime-manual-validation-notes.md |   26 +
- ...26171_GAMMA_015-admin-r2-diagnostics-runtime.md |   95 +
- ...ent-runtime-instruction-compliance-checklist.md |   66 +
- ...-environment-runtime-manual-validation-notes.md |   28 +
- ..._GAMMA_016-admin-runtime-environment-runtime.md |  102 +
- ...A_019-admin-workstream-mergeability-recovery.md |   50 +
- docs_build/dev/reports/codex_changed_files.txt     |   79 +-
- docs_build/dev/reports/codex_review.diff           | 2696 +++++++++++++++++---
- .../dev/reports/coverage_changed_js_guardrail.txt  |   28 +
- .../dev/reports/playwright_v8_coverage_report.txt  |   94 +-
- src/dev-runtime/server/local-api-router.mjs        |   46 +
- .../tools/AdminHealthOperationsPage.spec.mjs       |  151 +-
- 27 files changed, 4034 insertions(+), 1001 deletions(-)
-
-## Validation evidence
-- git diff --check: PASS
-- git diff --cached --check: PASS
-- npx playwright test tests/playwright/tools/AdminHealthOperationsPage.spec.mjs --config=codex_playwright_system_chrome.config.cjs --project=playwright: PASS (3 passed)
-- samples smoke: SKIPPED by request
+## git diff --stat
diff --git a/docs_build/dev/reports/codex_review.diff b/docs_build/dev/reports/codex_review.diff
diff --git a/docs_build/dev/reports/coverage_changed_js_guardrail.txt b/docs_build/dev/reports/coverage_changed_js_guardrail.txt
@@ -6,37 +6,9 @@ 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%) assets/theme-v2/js/account-achievements.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/messages/messages-sqlite-service.mjs - 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/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/seed/server-seed-loader.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(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/server/local-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/shared/toolbox/tool-metadata-inventory.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/controls/controls.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/game-hub/game-hub-api-client.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/game-hub/game-hub.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/game-journey/game-journey.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/idea-board/index.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/messages/messages.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/text-to-speech/text2speech.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/tools-page-accordions.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(74%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 977/977; executed functions 67/90
-(90%) assets/theme-v2/js/admin-system-health.js - executed lines 227/227; executed functions 28/31
 
 Guardrail warnings:
-(0%) assets/theme-v2/js/account-achievements.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/messages/messages-sqlite-service.mjs - 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/persistence/tool-repositories/game-journey-mock-repository.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/seed/server-seed-loader.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
+(0%) src/dev-runtime/messages/messages-postgres-service.mjs - 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
-(0%) src/shared/toolbox/tool-metadata-inventory.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/controls/controls.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/game-hub/game-hub-api-client.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/game-hub/game-hub.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/game-journey/game-journey.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/idea-board/index.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/messages/messages.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/text-to-speech/text2speech.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/tools-page-accordions.js - WARNING: changed runtime JS file missing from coverage; advisory only