From 52a2cdfe9c4968e805080906e868f219a1c37b77 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Tue, 18 Aug 2026 15:18:18 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs(db):=20board=20=E2=80=94=20Phase=202?= =?UTF-8?q?=20and=20reconcile=20#2098=20landed;=20record=20staging=20traps?= =?UTF-8?q?=20and=20the=20#183=20rider=20(#316)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- docs/database-remediation-coordination.md | 37 ++++++++++++----------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/database-remediation-coordination.md b/docs/database-remediation-coordination.md index 1fb94ae0dc..0e0b7347ff 100644 --- a/docs/database-remediation-coordination.md +++ b/docs/database-remediation-coordination.md @@ -79,20 +79,20 @@ _Board re-baselined 2026-08-17 from `main` `f5b093291`; **updated 2026-08-18 fro forensics file, and the PR list — worker self-reports were checked against merged content, not trusted as-is._ -| Phase | Status | PR / evidence | Notes | -| ----------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Prereq: docs on `main` | ☑ done | #1906 (plan/playbook), #2027 (traps), #2044 (this board, `e663203ce`) | — | -| Prereq: `SUPABASE_ACCESS_TOKEN` secret (`#183`) | ☐ pending — not blocking | repo-level secret names checked 2026-08-17: not present | Owner chose the Supabase MCP connector for all windows (2026-08-17). Token gates CLI repair paths only. | -| 0 — Enablement | ☑ COMPLETE 2026-08-14 | #1938, #1939, #1951 (proof run `31813064485`, auto-issue #1963), #1978 | Issue #1963 stays open until Phases 3–4 land; now that Phase 6.1 is on `main` repo-side, weekly live-drift will _additionally_ report `schema_drift_snapshot()` as repo-ahead plus an info line "migration-history probe not present" — expected, not a regression. | -| 1.1 — History fingerprint | ☑ done (owner action open) | #1960 §1.1 | `20260705180000` NOT mark-applied (14 stmts). Drop window 2026-07-05→08-02; Phase 2 narrowed it: staging **kept** the four indexes production lost, so an out-of-band drop on production is the leading explanation. Dashboard audit-history pairing = owner. `#248` open. | -| 1.2 — RPC divergence dossier | ☑ COMPLETE 2026-08-18 | **#2087** merged `173ea9f28` → forensics §1.2; `#316` update queued (inbox `1591ee4a`) | Read-only connector window, 4 SELECTs, zero writes. **All 10 mismatches are attribute-only `SET work_mem`** present on live, absent from `schema.sql`; strip it → manifest hash 10/10. 4 mirror-stale (64 MB = `20260724000000`), 6 live-ahead attribute-only (128 MB ×4 hybrids; live-only 64 MB on `chunks_text_v2` and on `table_facts_text` after its `20260724120000` recreate). Zero body divergences, zero repo-ahead, zero UNCLASSIFIED. | -| 1.3 — Inventory / EXPLAIN | ◐ whole-schema done; sizing pending | #1970 §1.3 | 20 absent, 2 orphaned, zero invalid. Remaining index sizing + `rag_retrieval_logs` miss-scan baseline pending — fold into Phase 5. | -| 2 — Staging parity (`#056`) | ☑ COMPLETE — PR OPEN | **#2093** (tip `a6daac6c6`; BEHIND but merge-tree clean; `PR policy` red because `scripts/check-drift.ts` is a clinical-risk path and the body lacks the Clinical Governance Preflight) | Gap was **28**, not 26. Staging `ikoiolksxqxfxgiyqpnu` at 194/194 parity, zero `statements IS NULL`, all 28 rows md5-identical, corpus untouched, production never targeted. **`check:drift` vs staging RED, 19 items** — the migration chain does not reproduce `schema.sql`: `work_mem` 0× in `schema.sql` (7 fn mismatches; the 8th absent for exactly 1.2's recreate reason), **8 objects `schema.sql` declares that no migration creates** (five `document_embedding_fields` indexes, `documents_status_idx`, `documents_updated_at` / `ingestion_jobs_updated_at` triggers), 3 table column-set mismatches, 1 index-def mismatch. **Owed:** re-measure at `main` ≥ 195 migrations (apply `20260818090000` to staging, re-run `check:drift`). | -| 3 — Reconciliation (reframed) | ☐ NEXT — repo-side; D2 canary decision pending | needs owner decisions D1/D2 below | Fable. Not a production deploy: (a) add `SET work_mem` to the 10 `schema.sql` definitions + one migration `ALTER FUNCTION … SET work_mem = ` per function, ordered after every recreate (idempotent on prod); (b) codify the 8 never-created objects; (c) triage the 3 column-set + 1 index-def staging mismatches; regenerate `drift-manifest.json` (Docker); `RAG impact: no retrieval behaviour change — codifying already-live attribute`; governance preflight. Applying the migration to production is a trivial window (state already matches); the staging apply proves it first. | -| 4 — Index restoration | ◐ PARTIAL (incident) | #1960 §Phase 4 | 2 trgm restored; **20** still missing, 2 unexpected undispositioned; guard migration for the repaired pair owed (4.4); Phase 6.3 named 8 monitor-candidates for `required_indexes` — decide in 4.4. Blocked on Phase 3 landing. | -| 5 — Measure | ◐ PARTIAL (incident) | #1960 §Phase 5 | Text fast path 31,610 → 1,535 ms; hybrid 8,519 ms residual. Full EXPLAIN set, `work_mem` before/after (only if D1 changes values), `check:production-readiness` pending. | -| 6 — Future-proofing | ◐ REPO-SIDE COMPLETE 2026-08-18 | **#2058** merged `9c660af1f` (14 paths verified on `main`); follow-up #2090 open (comment pointers only) | 6.1 migration `20260818090000_schema_drift_snapshot_history_probe.sql` built + mirrored + manifest regenerated, **NOT deployed** — needs a production migration window after Phase 4. 6.2 contract + `supabase/drift-allowlist.json` (5 seeded superseded guards; ~18 §1.1 versions deliberately NOT allowlisted → first post-deploy run reports them; fix = fail-fast guard migrations, never bare allowlisting). 6.3 `tests/search-health-index-coverage.test.ts` + unmonitored list (44 entries, 8 monitor-candidates). New P2 row queued (inbox `d6ce8a1d`). Stale branch `claude/database-drift-allowlist-48839e` (tip `3fe1deafe`) was recreated after merge — redundant, owner may delete. | -| 7 — Deferred | ☐ not started | — | Each its own session, per playbook. | +| Phase | Status | PR / evidence | Notes | +| ----------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Prereq: docs on `main` | ☑ done | #1906 (plan/playbook), #2027 (traps), #2044 (this board, `e663203ce`) | — | +| Prereq: `SUPABASE_ACCESS_TOKEN` secret (`#183`) | ☐ pending — not blocking | repo-level secret names checked 2026-08-17: not present | Owner chose the Supabase MCP connector for all windows (2026-08-17). Token gates CLI repair paths only. | +| 0 — Enablement | ☑ COMPLETE 2026-08-14 | #1938, #1939, #1951 (proof run `31813064485`, auto-issue #1963), #1978 | Issue #1963 stays open until Phases 3–4 land; now that Phase 6.1 is on `main` repo-side, weekly live-drift will _additionally_ report `schema_drift_snapshot()` as repo-ahead plus an info line "migration-history probe not present" — expected, not a regression. | +| 1.1 — History fingerprint | ☑ done (owner action open) | #1960 §1.1 | `20260705180000` NOT mark-applied (14 stmts). Drop window 2026-07-05→08-02; Phase 2 narrowed it: staging **kept** the four indexes production lost, so an out-of-band drop on production is the leading explanation. Dashboard audit-history pairing = owner. `#248` open. | +| 1.2 — RPC divergence dossier | ☑ COMPLETE 2026-08-18 | **#2087** merged `173ea9f28` → forensics §1.2; `#316` row updated by reconcile #2098 (`d113396b0`) | Read-only connector window, 4 SELECTs, zero writes. **All 10 mismatches are attribute-only `SET work_mem`** present on live, absent from `schema.sql`; strip it → manifest hash 10/10. 4 mirror-stale (64 MB = `20260724000000`), 6 live-ahead attribute-only (128 MB ×4 hybrids; live-only 64 MB on `chunks_text_v2` and on `table_facts_text` after its `20260724120000` recreate). Zero body divergences, zero repo-ahead, zero UNCLASSIFIED. | +| 1.3 — Inventory / EXPLAIN | ◐ whole-schema done; sizing pending | #1970 §1.3 | 20 absent, 2 orphaned, zero invalid. Remaining index sizing + `rag_retrieval_logs` miss-scan baseline pending — fold into Phase 5. | +| 2 — Staging parity (`#056`) | ☑ COMPLETE 2026-08-18 — re-measure owed | **#2093** merged `e546840a1` → forensics §2.0–2.4; `#056` row updated by reconcile #2098 | Gap was **28**, not 26. Staging `ikoiolksxqxfxgiyqpnu` at 194/194 parity, zero `statements IS NULL`, all 28 rows md5-identical, corpus untouched, production never targeted; `check:drift` can now target staging (`scripts/check-drift.ts` fix). **`check:drift` vs staging RED, 19 items** — the migration chain does not reproduce `schema.sql`: (a) 7 `work_mem` fn mismatches (8th absent for exactly 1.2's recreate reason); (b) **8 objects `schema.sql` declares that no migration creates** (five `document_embedding_fields` indexes, `documents_status_idx`, `documents_updated_at` / `ingestion_jobs_updated_at` triggers); (c) 3 table column-set mismatches (`document_chunks`, `rag_visual_eval_cases`, `rag_visual_eval_runs`); (d) 1 index-def mismatch `document_chunks_content_trgm_idx` (manifest `8499c3d3…` vs staging `c3db2960…` — one of the two restored on production 2026-08-14; confirm which definition production actually carries). §2.4: staging KEPT the indexes production lost; four duplicate migration version pairs (`20260717161000`/`173000`/`20260719053532`/`053533` vs `20260719055541`/`055555`/`055609`/`055623`) — a plain `db push --include-all` applies older bodies over newer; `20260725000000` points staging's `app.ingestion_worker_base_url` at production — inert, **never seed `cron_ingestion_jwt` / `indexing_v3_agent_secret` / `ingestion_webhook_secret` into staging's vault**. **Owed:** re-measure at `main` ≥ 195 migrations (apply `20260818090000` to staging, re-run `check:drift`). | +| 3 — Reconciliation (reframed) | ☐ NEXT — repo-side, no canary | needs owner decisions D1/D2 below | Fable. Not a production deploy: (a) add `SET work_mem` to the 10 `schema.sql` definitions + one migration `ALTER FUNCTION … SET work_mem = ` per function, ordered after every recreate (idempotent on prod); (b) codify the 8 never-created objects; (c) triage the 3 column-set + 1 index-def staging mismatches; regenerate `drift-manifest.json` (Docker); `RAG impact: no retrieval behaviour change — codifying already-live attribute`; governance preflight. Applying the migration to production is a trivial window (state already matches); the staging apply proves it first. | +| 4 — Index restoration | ◐ PARTIAL (incident) | #1960 §Phase 4 | 2 trgm restored; **20** still missing, 2 unexpected undispositioned; guard migration for the repaired pair owed (4.4); Phase 6.3 named 8 monitor-candidates for `required_indexes` — decide in 4.4. Blocked on Phase 3 landing. | +| 5 — Measure | ◐ PARTIAL (incident) | #1960 §Phase 5 | Text fast path 31,610 → 1,535 ms; hybrid 8,519 ms residual. Full EXPLAIN set, `work_mem` before/after (only if D1 changes values), `check:production-readiness` pending. | +| 6 — Future-proofing | ◐ REPO-SIDE COMPLETE 2026-08-18 | **#2058** merged `9c660af1f` (14 paths verified on `main`); follow-up #2090 merged `79e5d2a68` | 6.1 migration `20260818090000_schema_drift_snapshot_history_probe.sql` built + mirrored + manifest regenerated, **NOT deployed** — needs a production migration window after Phase 4. 6.2 contract + `supabase/drift-allowlist.json` (5 seeded superseded guards; ~18 §1.1 versions deliberately NOT allowlisted → first post-deploy run reports them; fix = fail-fast guard migrations, never bare allowlisting). 6.3 `tests/search-health-index-coverage.test.ts` + unmonitored list (44 entries, 8 monitor-candidates). New P2 row queued (inbox `d6ce8a1d`). Stale branch `claude/database-drift-allowlist-48839e` (tip `3fe1deafe`) was recreated after merge — redundant, owner may delete. | +| 7 — Deferred | ☐ not started | — | Each its own session, per playbook. | **Owner decisions outstanding (2026-08-18):** @@ -106,10 +106,11 @@ trusted as-is._ verified by Phase 5 EXPLAIN, not a canary. The RAG-surface flag and `RAG impact:` line still apply. - **D3 — 6.1 deploy window** timing (after Phase 4). -**Ledger state note (2026-08-18):** pending inbox on `main`: `1591ee4a` (`#316`, Phase 1.2) plus six -unrelated requests; #2093 carries the `#056` update (`d958d671`, replacing cancelled `a1c319d6`). -One serialized `issues:reconcile` after #2093 lands. Never merge `main` into a PR carrying a -reconciliation. +**Ledger state note (2026-08-18, later):** reconcile PR #2098 (`d113396b0`) applied 16 requests +including `1591ee4a` (`#316` Phase 1.2), `d958d671` (`#056` Phase 2) and `d6ce8a1d` (Phase 6 row); +inbox is empty on `main`. `#183` rider: the Supabase CLI is now authenticated and the repo linked +to staging (owner, 2026-08-18) — queue that `#183` update on the next product PR (Phase 3), not a +ledger-only branch. Never merge `main` into a PR carrying a reconciliation; re-cut from `main`. ## Coordination rules From 9652db1dc0bd2259f4d508d58e18e5a3e5ef4c53 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Tue, 18 Aug 2026 15:20:02 +0800 Subject: [PATCH 2/2] chore(ledger): record review of the board refresh PR Co-Authored-By: Claude Fable 5 --- ...dd146e61f664ae30c068ebd46d97eb56a209e5e8f56adc175eb.record.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/branch-review-records/26601359b89b2dd146e61f664ae30c068ebd46d97eb56a209e5e8f56adc175eb.record.md diff --git a/docs/branch-review-records/26601359b89b2dd146e61f664ae30c068ebd46d97eb56a209e5e8f56adc175eb.record.md b/docs/branch-review-records/26601359b89b2dd146e61f664ae30c068ebd46d97eb56a209e5e8f56adc175eb.record.md new file mode 100644 index 0000000000..16855e7faa --- /dev/null +++ b/docs/branch-review-records/26601359b89b2dd146e61f664ae30c068ebd46d97eb56a209e5e8f56adc175eb.record.md @@ -0,0 +1 @@ +| 2026-08-18 | claude/db-remediation-board-refresh-2026-08-18b | 52a2cdfe9c4968e805080906e868f219a1c37b77 | docs/database-remediation-coordination.md board refresh after #2093/#2098 (#316) | coordinator self-review: docs-only, verified against main 2c311c7ed | prettier --check pass; docs:check-links 1881 refs resolve |