dot-iu-cutter v0.5 — Pre-Scale Index-Only DDL Draft

Date: 2026-05-17 · Status: AUTHORING ONLY — NOT executed. No index created, no dry-run, no production write. Authored for GPT review. Parent: GPT PASS of v0.5 pre-scale foundation (sequencing step 1 = pre-scale index-only DDL authoring). Accepted code commit: e93424b5ff7fa5e4b8406131977ce4339cd0856a (branch main, iu-cutter clean). Grounded read-only against the deployed cutter_governance schema (column nullability verified; no proposed index name collides with an existing index).

1. Scope (mandated)

Index-only · additive · no table/column/constraint/trigger/function/RLS/default-privilege/data change · no label registry · no vector/NoSQL. Exactly the 7 GPT-specified hot-path indexes. Deterministic, schema-qualified names. IF NOT EXISTS for idempotency.

2. Column-nullability grounding (drives partial-vs-full, decision D-2)

Target	Nullable?	Index form
decision_backlog_entry (status, emitted_at, entry_id)	all NOT NULL	FULL composite btree
manifest_envelope (source_doc_ref)	NOT NULL	FULL btree
review_decision (manifest_id)	NOT NULL	FULL btree
verify_result (change_set_id)	NOT NULL	FULL btree
cut_change_set (decision_backlog_entry_id)	NULLABLE	PARTIAL WHERE … IS NOT NULL
dot_pair_signature (cross_reference_change_set_id)	NULLABLE (XOR)	PARTIAL WHERE … IS NOT NULL
dot_pair_signature (cross_reference_verify_result_id)	NULLABLE (XOR)	PARTIAL WHERE … IS NOT NULL

D-2 decision (made; recommended, escalatable): partial WHERE col IS NOT NULL for the 3 nullable refs. Justification: the runtime predicate is equality col = $1 with a non-null bound value; the planner treats col = $1 as implying col IS NOT NULL, so the partial index is used; the partial excludes the large NULL fraction (XOR ⇒ ~50% NULL per signature xref column; decision_backlog_entry_id NULL until/unless linked) → smaller, faster, predicate-exact. Conservative alternative if GPT prefers uniformity = full btree on those three (identical correctness, marginally larger). FULL btree for the 3 NOT-NULL columns + the all-NOT-NULL composite (no partial benefit).

3. PRODUCTION DDL artefact (CREATE INDEX CONCURRENTLY — PROPOSED, NOT executed)

Each statement is standalone and must NOT run inside a transaction block (CIC restriction, §5). No BEGIN/COMMIT. Order independent. Run one-by-one; on failure of any one, that index may be left INVALID → drop it by name and retry only that one (handled by the future execution cycle).

-- 1. SWEEP cursor: WHERE status = $1 ORDER BY emitted_at, entry_id  (all NOT NULL)
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_dbe_status_emitted_keyset
  ON cutter_governance.decision_backlog_entry USING btree (status, emitted_at, entry_id);

-- 2. lineage: manifest_envelope WHERE source_doc_ref = $1  (NOT NULL)
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_me_source_doc_ref
  ON cutter_governance.manifest_envelope USING btree (source_doc_ref);

-- 3. lineage/review lookup: review_decision WHERE manifest_id = $1  (NOT NULL)
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_rd_manifest_id
  ON cutter_governance.review_decision USING btree (manifest_id);

-- 4. cut-once guard: cut_change_set WHERE decision_backlog_entry_id = $1  (NULLABLE -> partial)
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_ccs_dbe_id
  ON cutter_governance.cut_change_set USING btree (decision_backlog_entry_id)
  WHERE decision_backlog_entry_id IS NOT NULL;

-- 5. verify lookup: verify_result WHERE change_set_id = $1  (NOT NULL)
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_vr_change_set_id
  ON cutter_governance.verify_result USING btree (change_set_id);

-- 6. DOT executor xref: dot_pair_signature WHERE cross_reference_change_set_id = $1  (NULLABLE/XOR -> partial)
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_dps_xref_cs
  ON cutter_governance.dot_pair_signature USING btree (cross_reference_change_set_id)
  WHERE cross_reference_change_set_id IS NOT NULL;

-- 7. DOT verifier xref: dot_pair_signature WHERE cross_reference_verify_result_id = $1  (NULLABLE/XOR -> partial)
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_dps_xref_vr
  ON cutter_governance.dot_pair_signature USING btree (cross_reference_verify_result_id)
  WHERE cross_reference_verify_result_id IS NOT NULL;

4. ISOLATED DRY-RUN variant (reference; for the later, separately-authorized dry-run env only)

In an isolated restored env (not production), the same 7 indexes may be created without CONCURRENTLY (plain CREATE INDEX IF NOT EXISTS …), which can run inside a transaction and is faster — acceptable because an isolated env tolerates the brief ACCESS EXCLUSIVE lock. The canonical production artefact remains §3 (CONCURRENTLY). Names/columns/partial-predicates identical so structural verification is variant-invariant.

5. Transaction / concurrency limitations (documented, mandated)

• CREATE INDEX CONCURRENTLY cannot run inside a transaction block and cannot be combined with other statements in one txn; each is its own implicit-commit statement. The execution harness must issue them individually with autocommit (no BEGIN).
• CIC takes SHARE UPDATE EXCLUSIVE on the table: concurrent SELECT/INSERT/UPDATE/DELETE continue; it blocks other DDL and does two table scans (slower wall time; safe online).
• On interruption/failure CIC can leave an INVALID index (pg_index.indisvalid = false) that still consumes writes — must be DROP INDEX CONCURRENTLY by name and recreated; never left in place.
• Tables are tiny now (1–2 rows) so build is instant today; CONCURRENTLY is specified for the production model so the same artefact remains correct when tables are large.
• Not runnable via a single multi-statement psql -f inside one txn; the future command-review will run them as discrete sha-gated steps.

6. Decisions made / escalated

• D-1 exact index set: the 7 above (= GPT's list), 1:1 with the hot paths. Made.
• D-2 partial vs full for nullable refs: partial for the 3 nullable (recommended, §2) — escalated for GPT confirm vs full.
• D-3 CIC transaction model: standalone, no txn, autocommit, per-statement (§5). Made.
• D-4 rollback: DROP INDEX CONCURRENTLY IF EXISTS by exact name (see rollback-plan). Made.
• D-5 production command model: a later, separate dry-run → command-review → sovereign cycle (not here). Escalated/deferred.

Boundaries / Git

Authoring only — NOT executed; no index/dry-run/write/code/commit. Git: main · e93424b5ff7fa5e4b8406131977ce4339cd0856a · git status --short -- iu-cutter clean (0 lines). No fixed IP/DSN/password/container/vector-collection; no runtime label/key hardcoding; no new columns; SQL = SSOT. Next = GPT review; index execution stays forbidden until a separate authorized cycle.