docs(homesonspec): O3 partition + add-disk plan (Steve-chosen path) — disk-first ordering, pg_partman raw-SQL migration, size canary (TK-10878)

019ab4e82a0b4e49274bc8b3c88f8e115f769f03 · 2026-08-26 10:23:08 -0700 · Steve

Files touched

A ops/o3-partition-and-disk-plan.md

Diff

commit 019ab4e82a0b4e49274bc8b3c88f8e115f769f03
Author: Steve <steve@designerwallcoverings.com>
Date:   Wed Aug 26 10:23:08 2026 -0700

    docs(homesonspec): O3 partition + add-disk plan (Steve-chosen path) — disk-first ordering, pg_partman raw-SQL migration, size canary (TK-10878)
---
 ops/o3-partition-and-disk-plan.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/ops/o3-partition-and-disk-plan.md b/ops/o3-partition-and-disk-plan.md
new file mode 100644
index 00000000..e77e0d1f
--- /dev/null
+++ b/ops/o3-partition-and-disk-plan.md
@@ -0,0 +1,32 @@
+# TK-10878 — O3 partition + add-disk plan (Steve-chosen path, 2026-08-26)
+
+**Goal:** bound homesonspec growth (~16 GB/wk) so it never silently returns to an 80 GB crisis, while keeping the full 122 M-row provenance (it's real, unique, live-read — not prunable). This is the "accept the data, make it manageable" path, NOT the 25 GB pruning fantasy.
+
+**Every prod step below is `PROD_DELETE_REQUIRED` / infra-spend → hard-gated. Drafts here; Steve executes on the box.**
+
+## ⚠️ Hard ordering: DISK FIRST, then partition
+pg_partman's conversion of an **existing** large table (`partition_data_proc`) rewrites rows into their partitions and needs ~table-sized scratch **during** conversion. `SourceEvidence` is ~55 GB; the box is ~90 % full (~67 GB free). Converting before adding disk would stall/fill the box. So:
+
+### PHASE 1 — add disk (gated: infra + spend)
+- Box `45.61.58.125` ~90 % full. Grow the Postgres volume.
+- **Recommended target: +100 GB minimum** → clears the 90 % pressure, gives headroom for the 55 GB `SourceEvidence` conversion rewrite, and buffers ~months of the 16 GB/wk growth. Exact size = Steve's Kamatera-plan call.
+- Verify after grow: `df -h /` shows ≥75 GB free before any conversion (also unblocks the pg_repack gate if ever needed).
+
+### PHASE 2 — pg_partman monthly range partitions (gated: prod DDL, maintenance window)
+Targets: `SourceEvidence` on `createdAt`, `ValidationEvent` on `runAt` (monthly RANGE).
+- Install/confirm `pg_partman` extension on prod.
+- These are the two firehose tables; `StagedRecord`/`InventoryHome` stay unpartitioned.
+- **Conversion approach (online, existing data):** create the partitioned parent + `create_parent(...)`, then background `partition_data_proc` in batches (throttled) to move existing rows — NOT a single blocking rewrite. Verify row counts parent-vs-source before cutover.
+- **Prisma caveat:** Prisma has no declarative partitioning — this is a **raw-SQL migration** (a `migration.sql` with the partman calls), and `schema.prisma` keeps the models as-is (Prisma treats the partitioned parent as a normal table for reads/writes). Do NOT let a later `prisma migrate dev` try to "fix" drift — mark it a manual/raw migration.
+- **Payoff:** future reclaim = `DROP PARTITION` (instant, zero WAL); growth becomes bounded + operationally trivial.
+
+### PHASE 3 — STEP 5 size canary (gated on Steve provisioning prod-read connectivity)
+homesonspec DB-size canary → fleet-health-rollup (PASS/WARN/FAIL, `data/latest.json`), WARN on regrowth past a threshold. Mac2 is classifier-blocked from prod, so it must either run on Kamatera or use a Steve-provisioned read-only conn. Author when connectivity exists.
+
+## Sequencing summary
+1. **Now (gated, ready):** apply STEP 1 index-drop (~508 MB) — `pending-approval/2026-08-26-TK-10878-step1-index-drop-APPLY.md`.
+2. **Next (gated):** PHASE 1 add disk (+≥100 GB).
+3. **Then (gated, maintenance window):** PHASE 2 pg_partman conversion.
+4. **After connectivity:** PHASE 3 size canary.
+
+Unused-PKEY drop (~10.4 GB, @id data-model change) is explicitly NOT on this path (Steve chose partition+disk over the higher-risk pkey change).

← 26657d75 docs(homesonspec): runbook reflects measured reality — index · back to Homesonspec · docs(homesonspec): STEP 1 APPLIED on prod — record actual me 7312ce4b →