dot-iu-cutter v0.5 Schema Q5 — Verification & Rollback / Compensation Master Plan

Phase: v0_5_schema_Q5_and_evidenced_by_command_review_planning · Nature: design_only / command_review_preparation · Date: 2026-05-18 Authority (consumed, NOT reopened — QG1): evidenced_by verification-and-rollback-plan (SV-1..SV-10, NT-1..NT-12, §4.1–§4.4); pre-scale index verification-plan (V-1..V-8 / A-1..A-5, catalog-level, no rendered-string compare) + rollback-plan (DROP INDEX CONCURRENTLY, no CASCADE); WS-2 D1–D6; project rollback doctrine (deactivate/retire/forward-compensation, no hard-delete default).

⚠️ GATING BANNER

phase: design_only
verification_executed: false     # this is the PLAN, not the run
rollback_executed: false
checks_run: 0
executable_sql: none             # QG2 — assertions described logically only
execution_authorized: false
self_advance: PROHIBITED

This is the unified acceptance + rollback contract for a FUTURE command-review across schema-Q5, vocab amend, Cap-4 checker, and indexes. Nothing is executed. Hard delete is NOT the default rollback (QG6 doctrine): prefer deactivate / retire / forward-compensation when data exists.

---

1. Verification master plan (design of the checks — NOT run)

1.1 Registry structural checks (WS-Q5 — OBJ-01..06 + sub-objects)

RSV-1  each registry object exists EXACTLY ONCE; PK present; no shadow/dup object.
RSV-2  expected logical columns present with expected nullability/policy columns
        (catalog-level introspection — NOT pg_get_*def() string equality;
         carry the false-negative lesson from index verification).
RSV-3  declared FKs resolve schema-qualified & exact:
         source_family_registry.grammar_profile_ref -> grammar_profile;
         entity_reference_registry.entity_kind -> entity_kind_registry;
         grammar_profile.matcher_ref -> matcher_config_registry;
         grammar_profile.address_template_ref -> address_template_registry.
RSV-4  seed presence: source_family_registry ≥9 families; grammar_profile ≥2
        concrete profiles; entity_kind_registry seed set; each seed lifecycle
        in {proposed,active} only (no orphan state).
RSV-5  ownership/grants follow cutter_governance pattern (cutter_ro read;
        cutter_exec/cutter_verify write) — no broader grant introduced.
RSV-6  zero data rows beyond the authorized seed (registries are config, not corpus).

1.2 Uniqueness checks

USV-1  every registry PK unique; no duplicate canonical key
        (metadata_key, source_family, grammar_profile_ref, entity_kind,
         entity_ref_id, override_id).
USV-2  address_docprefix UNIQUE within source_document registry (1 doc -> 1 prefix)
        — collision-prevention (WS-2 D6); NOTE: gated on OD-SEQ1/source_document.
USV-3  no two seed families share a (source_family) key; no two grammar profiles
        share grammar_profile_ref.

1.3 No-hardcode checks

NHV-1  metadata_key / source_family / entity_kind / edge_type are resolvable
        ONLY via their registry — assert NO runtime literal path is required
        (design assertion: the resolution contract reads the registry).
NHV-2  grammar matcher = matcher_config row reference, never inline regex
        (WS-2 D3).
NHV-3  evidenced_by edge_type read from vocab framework, never hardcoded
        (≡ Cap-4 R-AD3 / SV-3 / NT4).

1.4 Canonical-address separator checks (BR-A1 dependent)

CAV-1  canonical_address shape conforms to the FINAL ratified scheme
        `<DOCPREFIX><SEP1><L1><SEP2>...<Lk>` — BLOCKED until BR-A1 locks
        slash-vs-hyphen (WS-2 D6 self-flagged canon contradiction).
CAV-2  docprefix derived from source_document_ref, never a literal (WS-2 D6 / canon §4).
CAV-3  address encodes NO volatile state (no ✅/📋 status in address; status is metadata).
CAV-4  re-ingest of identical content_checksum -> identical addresses (canon §4/§5).
status: CAV-* are DESIGNED but NOT runnable until BR-A1 + source_document
        registry resolved (flag, do not self-resolve — QG1).

1.5 evidenced_by vocab checks (carried verbatim from authority — SV-1..SV-10)

reuse: SV-1..SV-10 from evidenced-by-verification-and-rollback-plan §2
  (vocab entry exactly once; attributes reverse=evidences /
   owner_law_code=NRM-LAW-44 / relation Cap-4 / default proposed /
   provenance_required true; checker reads from vocab; 8 Core + 3 Candidate
   + 1 Extension, no Core/Candidate altered; reverse via §6 index;
   endpoint/provenance/lifecycle/anti-drift live; idempotent re-amend).
NOT reopened (QG1) — referenced as the WS-VA acceptance contract.

1.6 Cap-4 checker logical checks + negative matrix integration

reuse: NT-1..NT-12 from evidenced-by-verification-and-rollback-plan §3
  (raw evidence path -> iu_entity_binding; weak mention -> references;
   provenance -> derived_from; build-to-spec -> implements; governance ->
   governed_by; authority-role mismatch; provenance missing; illegal
   lifecycle; cross-layer; redundant duplicate; NT-12 positive control).
integration_note: WS-CK acceptance = full NT matrix PASS AND SV-3/SV-6..SV-9
  PASS; checker MUST be deployed behind a reversible/versioned rule set
  (OD-VC3) so a mismatch is revertable without data.

1.7 Index structural checks (WS-IX — later phase)

reuse: V-1..V-8 + A-1..A-5 from pre-scale-index-verification-plan
  (catalog-level: index exists, correct table/columns/partial-predicate,
   valid not INVALID, additive-only, no table/constraint/trigger change).
applies only if/when WS-IX enters its own D-5 dry-run/command-review cycle.

2. Rollback / compensation master plan (QG5/QG6)

Failure-mode-driven. No hard delete as default. Pre-state snapshot is mandatory at command-review before any mutation.

2.1 Schema object created wrong (RSV-* / USV-* fail)

detect: missing/extra column, wrong FK, dup object, wrong seed, bad grants
compensation:
  - registries are EMPTY config objects at creation (RSV-6) -> blast radius
    is schema-only, no corpus rows -> clean inverse is safe
  - rollback = exact-inverse DROP of the just-created object(s), no CASCADE,
    no touch to the 12 existing cutter_governance tables / 19 FKs
  - if a wrong FK was added to an EXISTING object -> drop only that FK
    (named, no CASCADE); never drop the existing object
reversibility: HIGH (additive, pre-data); all steps command-review-gated

2.2 Vocab amend wrong (SV-1/2/4/10 fail)

reuse: evidenced-by-verification-and-rollback-plan §4.1 (snapshot vocab
  framework pre-amend; restore to snapshot; exact inverse; no Core/Candidate
  touched; vocab precedes any edge row -> no row blast radius)
reversibility: HIGH

2.3 Checker extension wrong (SV-3/6..9 or any NT-* mismatch)

reuse: evidenced-by-verification-and-rollback-plan §4.2 (checker behind
  reversible toggle / versioned rule set; revert to prior rule version;
  no evidenced_by rows created until full NT matrix passes)
reversibility: HIGH (stateless validation; revert = redeploy prior rules)

2.4 Partial apply (a workstream aborts mid-sequence)

detect: G4 interrupted; some WS-Q5 objects created, others not; or vocab
  amended but checker not yet deployed
compensation:
  - WS boundaries are independent lanes (sequencing §2) -> a partial WS-Q5
    is rolled back by exact-inverse DROP of only the objects created in that
    run (idempotent, named, no CASCADE)
  - vocab-without-checker state: SAFE transient — vocab entry default
    `proposed`; with no checker, NO evidenced_by row is accepted -> no bad
    data can form; do NOT rush WS-CK to "complete" — re-enter WS-CK G2
  - never leave a half-FK: FK additions are the last sub-step of each object
reversibility: HIGH; rule: roll back most-reversible first
  (checker -> vocab -> schema objects), per evidenced_by §4.4 ordering

2.5 Bad rows discovered later (post go-live data defect)

detect: periodic audit (Cap-4 R-AD7/R-AD8/R-LC5) or registry drift audit
compensation (NO hard delete first — QG6 doctrine):
  - registry config row wrong  -> set lifecycle=deprecated (append-only audit
    trail), supersede with corrected row; never silent UPDATE-in-place of an
    authority row
  - evidenced_by edge wrong    -> status -> deprecated, then retired after
    grace; reroute true relation to correct mechanism (iu_entity_binding /
    references / derived_from / implements / governed_by) — reuse
    evidenced_by §4.3
  - quarantine: stop further writes on the affected key/edge until root-caused
  - full vocab/checker/schema rollback (2.1–2.3) ONLY if defect is systemic
escalation: any ambiguous case -> STOP, route GPT/User; Agent does NOT self-decide
reversibility: MEDIUM (data exists -> lifecycle demotion + reroute, append-only)

2.6 Guardrails (all workstreams)

- command-review MUST capture pre-state snapshots before ANY mutation
- no destructive DELETE/CASCADE in rollback; demote-then-retire + restore-from-snapshot
- verification = catalog-level assertions, NEVER pg_get_*def() string equality
  (carry the documented false-negative lesson)
- every rollback step is itself command-review-gated (NOT auto-run)
- production sysid / existing 12 tables / 19 FKs / corpus must be re-confirmed
  UNCHANGED before and after any WS-Q5 apply

3. Statements

• QG1: SV/NT/V/A check sets and §4.x rollbacks are reused from authority, not reopened. QG2: no executable SQL — assertions are logical. QG5: rollback/compensation present for schema-wrong / vocab-wrong / checker-wrong / partial-apply / bad-rows. QG6: deactivate/retire/forward-compensation preferred over hard delete throughout.
• BR-A1 / OD-SEQ1 dependencies on CAV-* explicitly flagged, not self-resolved.
• No repo/VPS access in this session. code_changed: false, commit_made: false.
• Self-advance PROHIBITED — doc 3 of 5; STOP after package complete → route GPT/User.

Companion files: scope-and-object-inventory, command-sequencing-and-gates, open-decisions-and-risk-register, command-review-planning-report.