Skip to content

Commit 2d863fd

Browse files
ToolboxAidToolboxAid
committed
Audit SQLite deprecation backlog - PR_26171_GAMMA_006-sqlite-deprecation-audit
1 parent eaee83f commit 2d863fd

5 files changed

Lines changed: 433 additions & 978 deletions

‎docs_build/dev/reports/PR_26171_GAMMA_006-sqlite-deprecation-audit-instruction-compliance-checklist.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# PR_26171_GAMMA_006 Instruction Compliance Checklist
2+
3+
- Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`: PASS.
4+
- Read `docs_build/dev/PROJECT_MULTI_PC.txt`: PASS.
5+
- Checkout `main` before starting: PASS.
6+
- Pull latest `main`: PASS.
7+
- Verify branch is `main`: PASS.
8+
- Verify clean status before branch creation: PASS.
9+
- Verify PR 005 artifacts do not leave unstaged report changes: PASS.
10+
- Verify PR name includes TEAM token: PASS.
11+
- Verify TEAM owner matches Team Gamma governance/diagnostics ownership: PASS.
12+
- Create requested branch `pr/26171-GAMMA-006-sqlite-deprecation-audit`: PASS.
13+
- Audit SQLite references across active repo paths: PASS.
14+
- Classify references as active runtime, local API, test, docs, or archive/reference: PASS.
15+
- Do not remove SQLite code in this PR: PASS.
16+
- Create removal backlog with recommended follow-up PRs: PASS.
17+
- Confirm Postgres remains authoritative: PASS.
18+
- Run `git diff --check`: PASS.
19+
- Run targeted SQLite/Postgres text checks: PASS.
20+
- Do not run Playwright: PASS.
21+
- Do not run samples: PASS.
22+
- Create required PR-specific audit report: PASS.
23+
- Create manual validation notes: PASS.
24+
- Create instruction compliance checklist: PASS.
25+
- Create `codex_review.diff`: PASS.
26+
- Create `codex_changed_files.txt`: PASS.
27+
- Create repo-structured ZIP under `tmp/`: PASS.
28+
- Do not merge before explicit EOD approval: PASS.

‎docs_build/dev/reports/PR_26171_GAMMA_006-sqlite-deprecation-audit-manual-validation-notes.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# PR_26171_GAMMA_006 Manual Validation Notes
2+
3+
Manual validation status: PASS.
4+
5+
Manual checks performed:
6+
- Confirmed `main` was checked out and pulled before branch creation.
7+
- Confirmed `git status --short docs_build/dev/reports` returned no unstaged PR 005 report changes before branch creation.
8+
- Reviewed the SQLite audit classification for active runtime, Local API, test, docs, and archive/reference categories.
9+
- Confirmed the PR does not remove SQLite code.
10+
- Confirmed the removal backlog assigns follow-up work to the appropriate team ownership areas.
11+
- Confirmed Postgres remains documented as authoritative.
12+
- Confirmed Playwright and samples are skipped because this PR changes audit reports only.
13+
14+
Expected outcome:
15+
- The repo has an explicit SQLite deprecation inventory and follow-up backlog.
16+
- Existing SQLite code remains unchanged until owner-scoped removal/cutover PRs.
17+
- Postgres remains the authoritative direction for new database work.
18+
19+
Out of scope:
20+
- Removing SQLite services.
21+
- Replacing Local API persistence.
22+
- Updating tests to Postgres fixtures.
23+
- Editing archive/reference material.
24+
- Running Playwright.
25+
- Running samples.

‎docs_build/dev/reports/PR_26171_GAMMA_006-sqlite-deprecation-audit.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# PR_26171_GAMMA_006-sqlite-deprecation-audit
2+
3+
## Summary
4+
5+
Team ownership: GAMMA.
6+
7+
Purpose: audit SQLite references across active repo paths, classify the remaining references, create a removal backlog, and confirm Postgres remains authoritative.
8+
9+
No SQLite code was removed in this PR.
10+
11+
## Start Gate
12+
13+
- Checkout `main`: PASS.
14+
- Pull latest `main`: PASS.
15+
- Verify branch is `main`: PASS.
16+
- Verify clean status before branch creation: PASS.
17+
- Verify PR 005 artifacts do not leave unstaged report changes: PASS.
18+
- Created branch: `pr/26171-GAMMA-006-sqlite-deprecation-audit`.
19+
- Base main commit before branch: `eaee83f93`.
20+
21+
## Audit Method
22+
23+
Commands:
24+
- `rg -l -i "sqlite|better-sqlite3|sqlite3|\.sqlite|\.db\b|node:sqlite|DatabaseSync" -g "!tmp/**" -g "!node_modules/**" -g "!.git/**"`
25+
- `rg --count-matches -i "sqlite|better-sqlite3|sqlite3|\.sqlite|\.db\b|node:sqlite|DatabaseSync" -g "!tmp/**" -g "!node_modules/**" -g "!.git/**"`
26+
- `rg -n -i "SQLite is deprecated|Postgres is authoritative|New database work must target Postgres|Local API -> Postgres|Database Direction|Postgres target|GAMEFOUNDRY_DATABASE_URL must use postgres"`
27+
28+
Excluded generated/dependency paths:
29+
- `tmp/**`
30+
- `node_modules/**`
31+
- `.git/**`
32+
33+
## Classification Summary
34+
35+
| Classification | References | Files | Status |
36+
| --- | ---: | ---: | --- |
37+
| active runtime | 43 | 3 | Legacy SQLite runtime debt remains under `src/dev-runtime/`. |
38+
| local API | 6 | 1 | Local API still exposes or reports SQLite-backed legacy paths. |
39+
| test | 42 | 7 | Targeted tests still create temporary SQLite files or guard against SQLite exposure. |
40+
| docs | 298 | 96 | Historical reports, BUILD docs, database docs, and governance text. |
41+
| archive/reference | 5 | 1 | Deprecated V1/V2 reference material only. |
42+
43+
## Active Runtime References
44+
45+
| File | Count | Classification | Notes |
46+
| --- | ---: | --- | --- |
47+
| `src/dev-runtime/messages/messages-sqlite-service.mjs` | 37 | active runtime | Main remaining server-side SQLite service. Uses `node:sqlite`, `DatabaseSync`, `GAMEFOUNDRY_MESSAGES_SQLITE_PATH`, `messages.sqlite`, and reports `SQLite`. |
48+
| `src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs` | 5 | active runtime | Uses `node:sqlite`, `DatabaseSync`, `game-journey-completion-metrics.sqlite`, and reports `SQLite`. |
49+
| `src/dev-runtime/persistence/mock-db-store.js` | 1 | active runtime | Describes Local DB as SQLite-backed server storage. |
50+
51+
## Local API References
52+
53+
| File | Count | Classification | Notes |
54+
| --- | ---: | --- | --- |
55+
| `src/dev-runtime/server/local-api-router.mjs` | 6 | local API | Imports and creates `MessagesSqliteService`, reports `databaseEngine: "SQLite"` for legacy routes, and includes Local DB/SQLite export text. |
56+
57+
## Test References
58+
59+
| File | Count | Classification | Notes |
60+
| --- | ---: | --- | --- |
61+
| `scripts/validate-browser-env-agnostic.mjs` | 10 | test | Static guard rejects browser/provider leakage and documents deprecated SQLite/Local DB technical debt. |
62+
| `tests/dev-runtime/DbSeedIntegrity.test.mjs` | 2 | test | Creates temporary `.sqlite` files under `tmp/local-db`. |
63+
| `tests/playwright/tools/AdminDbViewer.spec.mjs` | 1 | test | Creates temporary Admin DB Viewer `.sqlite` fixture. |
64+
| `tests/playwright/tools/BrowserApiUrlConfig.spec.mjs` | 1 | test | Creates temporary browser API URL config `.sqlite` fixture. |
65+
| `tests/playwright/tools/GameJourneyTool.spec.mjs` | 7 | test | Includes Game Journey Local API SQLite persistence test and direct `node:sqlite` inspection. |
66+
| `tests/playwright/tools/LoginSessionMode.spec.mjs` | 1 | test | Creates temporary login-session `.sqlite` fixture. |
67+
| `tests/playwright/tools/MessagesTool.spec.mjs` | 20 | test | Uses `GAMEFOUNDRY_MESSAGES_SQLITE_PATH` and temporary messages `.sqlite` fixtures for legacy Messages coverage. |
68+
69+
## Docs References
70+
71+
| Group | References | Files | Classification |
72+
| --- | ---: | ---: | --- |
73+
| `docs_build/dev/PROJECT_INSTRUCTIONS.md` | 7 | 1 | docs |
74+
| `docs_build/dev/reports/` | 270 | 83 | docs |
75+
| `docs_build/pr/` | 18 | 9 | docs |
76+
| `docs_build/database/` | 3 | 3 | docs |
77+
78+
Docs references are historical reports, active governance, or prior BUILD/validation records. They should remain as traceability unless a dedicated docs cleanup PR rewrites obsolete guidance.
79+
80+
## Archive/Reference
81+
82+
| Group | References | Files | Classification |
83+
| --- | ---: | ---: | --- |
84+
| `archive/v1-v2/` | 5 | 1 | archive/reference |
85+
86+
Archive references are retained as deprecated V1/V2 reference material and are not active implementation ownership.
87+
88+
## Postgres Authoritative Confirmation
89+
90+
Postgres remains authoritative.
91+
92+
Evidence:
93+
- `docs_build/dev/PROJECT_INSTRUCTIONS.md` states `SQLite is deprecated.` and `Postgres is authoritative.`
94+
- `docs_build/dev/PROJECT_INSTRUCTIONS.md` requires new database work to target Postgres and requires `Local API -> Postgres`.
95+
- `src/dev-runtime/persistence/postgres-connection-client.mjs` rejects non-`postgres://` and non-`postgresql://` database URLs.
96+
- `toolbox/messages/index.html` surfaces `Database Direction: Postgres`.
97+
- `toolbox/messages/messages.js` sets the Messages persistence label to `Postgres target`.
98+
99+
## Removal Backlog
100+
101+
Recommended follow-up PRs:
102+
103+
1. `PR_26171_BETA_0XX-messages-postgres-service-cutover`
104+
- Owner: Team Beta.
105+
- Scope: replace `src/dev-runtime/messages/messages-sqlite-service.mjs` with a Postgres-backed Messages service contract.
106+
- Include migration of Messages categories, emotion profiles, TTS profiles, messages, segments, and playback payload reads.
107+
- Update `src/dev-runtime/server/local-api-router.mjs` to create the Postgres-backed service instead of `createMessagesSqliteService`.
108+
109+
2. `PR_26171_ALPHA_0XX-game-journey-postgres-metrics-cutover`
110+
- Owner: Team Alpha.
111+
- Scope: replace `src/dev-runtime/persistence/game-journey-completion-metrics-store.mjs` SQLite storage with Local API -> Postgres persistence.
112+
- Update Game Journey tests to avoid direct `node:sqlite` inspection.
113+
114+
3. `PR_26171_GAMMA_0XX-local-api-sqlite-diagnostic-cleanup`
115+
- Owner: Team Gamma.
116+
- Scope: after Alpha/Beta cutovers, remove Local API `databaseEngine: "SQLite"` reporting and Local DB/SQLite operator wording that no longer reflects active behavior.
117+
118+
4. `PR_26171_GAMMA_0XX-sqlite-test-fixture-retirement`
119+
- Owner: Team Gamma with Alpha/Beta follow-through where tool ownership applies.
120+
- Scope: retire temp SQLite fixtures once the owning runtime paths are Postgres-backed.
121+
- Preserve browser boundary guard checks that ensure no browser code imports database implementation details.
122+
123+
5. `PR_26171_GAMMA_0XX-sqlite-docs-traceability-cleanup`
124+
- Owner: Team Gamma.
125+
- Scope: clean obsolete active docs after runtime/test cutovers while preserving historical reports and archive/reference material.
126+
127+
## Validation
128+
129+
Lanes executed:
130+
- docs/static - audit/report-only PR.
131+
132+
Commands run:
133+
- `git diff --check` - PASS.
134+
- Targeted SQLite reference scan - PASS.
135+
- Targeted Postgres authoritative text scan - PASS.
136+
137+
Skipped lanes:
138+
- Playwright: SKIP. Audit/report-only PR with no runtime, UI, toolState, or workspace behavior changes.
139+
- Samples: SKIP. Audit/report-only PR with no sample loader, sample JSON, or sample runtime changes.
140+
- Runtime, integration, and engine: SKIP. No runtime, handoff, shared parser, or engine behavior changed.
141+
142+
## Required Reports
143+
144+
- `docs_build/dev/reports/codex_review.diff`
145+
- `docs_build/dev/reports/codex_changed_files.txt`
146+
- `docs_build/dev/reports/PR_26171_GAMMA_006-sqlite-deprecation-audit.md`
147+
- `docs_build/dev/reports/PR_26171_GAMMA_006-sqlite-deprecation-audit-manual-validation-notes.md`
148+
- `docs_build/dev/reports/PR_26171_GAMMA_006-sqlite-deprecation-audit-instruction-compliance-checklist.md`
149+
150+
## Git Workflow
151+
152+
- Current branch: `pr/26171-GAMMA-006-sqlite-deprecation-audit`.
153+
- Created branch: `pr/26171-GAMMA-006-sqlite-deprecation-audit`.
154+
- Push result: PASS. Pushed `pr/26171-GAMMA-006-sqlite-deprecation-audit` to `origin`.
155+
- PR URL: `https://github.com/ToolboxAid/HTML-JavaScript-Gaming/pull/30`.
156+
- Merge result: not merged; EOD approval required.

‎docs_build/dev/reports/codex_changed_files.txt‎

Lines changed: 6 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,6 @@
1-
docs_build/dev/reports/PR_26171_BETA_071-tts-profile-emotion-table-manual-validation-notes.md
2-
docs_build/dev/reports/PR_26171_BETA_071-tts-profile-emotion-table-validation.md
3-
docs_build/dev/reports/PR_26171_BETA_071-tts-profile-emotion-table.md
4-
docs_build/dev/reports/codex_changed_files.txt
5-
docs_build/dev/reports/codex_review.diff
6-
docs_build/dev/reports/coverage_changed_js_guardrail.txt
7-
docs_build/dev/reports/dependency_gating_report.md
8-
docs_build/dev/reports/dependency_hydration_reuse_report.md
9-
docs_build/dev/reports/execution_graph_reuse_report.md
10-
docs_build/dev/reports/failure_fingerprint_report.md
11-
docs_build/dev/reports/filesystem_scan_reduction_report.md
12-
docs_build/dev/reports/incremental_validation_report.md
13-
docs_build/dev/reports/lane_compilation_report.md
14-
docs_build/dev/reports/lane_deduplication_report.md
15-
docs_build/dev/reports/lane_input_validation_report.md
16-
docs_build/dev/reports/lane_runtime_optimization_report.md
17-
docs_build/dev/reports/lane_snapshot_report.md
18-
docs_build/dev/reports/lane_warm_start_report.md
19-
docs_build/dev/reports/monolith_trigger_removal_report.md
20-
docs_build/dev/reports/persistent_lane_manifest_report.md
21-
docs_build/dev/reports/playwright_discovery_ownership_report.md
22-
docs_build/dev/reports/playwright_discovery_scope_report.md
23-
docs_build/dev/reports/playwright_structure_audit.md
24-
docs_build/dev/reports/playwright_v8_coverage_report.txt
25-
docs_build/dev/reports/retry_suppression_report.md
26-
docs_build/dev/reports/slow_path_pruning_report.md
27-
docs_build/dev/reports/static_validation_report.md
28-
docs_build/dev/reports/targeted_file_manifest_report.md
29-
docs_build/dev/reports/test_cleanup_performance_report.md
30-
docs_build/dev/reports/test_cleanup_routing_report.md
31-
docs_build/dev/reports/testing_lane_execution_report.md
32-
docs_build/dev/reports/validation_cache_report.md
33-
docs_build/dev/reports/zero_browser_preflight_report.md
34-
tests/playwright/tools/TextToSpeechFunctional.spec.mjs
35-
toolbox/text-to-speech/text2speech.js
1+
M docs_build/dev/reports/PR_26171_GAMMA_006-sqlite-deprecation-audit.md
2+
3+
...ation-audit-instruction-compliance-checklist.md | 28 ++++
4+
...te-deprecation-audit-manual-validation-notes.md | 25 ++++
5+
.../PR_26171_GAMMA_006-sqlite-deprecation-audit.md | 156 +++++++++++++++++++++
6+
3 files changed, 209 insertions(+)

0 commit comments

Comments
 (0)