dot-iu-cutter v0.2 — P0-2 manifest_envelope Design

document_path: knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-p0-2-manifest-envelope-design-2026-05-16.md
revision: r1
date: 2026-05-16
author: Agent (Claude Code CLI, Opus 4.7 1M)
phase: v0.2 — P0-2 manifest DESIGN (LOGICAL ONLY; no DDL written here)
no_ddl_written: TRUE
no_mutation: TRUE

Companion to the P0-2 design master. Scope item v0.2-D-1. Logical design only — the table below is a logical field specification, not DDL.

---

§1 — Logical Object

cutter_governance.manifest_envelope is the proposal header: one row = one topology-change proposal that groups one or more manifest_unit_block rows. A proposal is a first cut, a split, or a merge. The envelope is the unit of review and the unit of P1 enactment. It is created empty (later, gated) and has zero writers/readers in v0.2 (proposal authoring is Phase β / P1).

§2 — Logical Field Specification

#	Field	Logical type	Null	Semantics
1	envelope_id	uuid	NO	PRIMARY KEY (logical); gen_random_uuid() at DDL time
2	operation_kind	text	NO	∈ {first_cut, split, merge}; application-layer enum in P0-2 (no PG CHECK). Distinguishes a plain cut from a BR-6 topology change
3	status	text	NO	proposal lifecycle (see §3); application-layer enum
4	source_doc_ref	text	NO	source document / parent-unit identifier the proposal derives from
5	escalation_ref	uuid	YES	soft reference to cutter_governance.decision_backlog_entry (no PG FK); review/escalation hook (INV-5)
6	cut_change_set_ref	uuid	YES	soft reference to cutter_governance.cut_change_set (no PG FK); the change-set that will enact this envelope at P1 (INV-6)
7	created_by	text	NO	actor that authored the proposal (owner metadata)
8	created_at	timestamptz	NO	now() at DDL time
9	reviewer	text	YES	actor that performed/holds the review (reviewer metadata; populated Phase β)
10	reviewed_at	timestamptz	YES	when review concluded (Phase β)
11	rationale	text	YES	free-text justification for the proposal
12	superseded_by_envelope_id	uuid	YES	soft self-reference (no PG FK); set if this proposal is replaced by a newer one

Estimated row footprint in P0-2: 0 (table created empty, later, gated).

§3 — Status Lifecycle

draft ──► under_review ──► accepted ──► enacted
  │            │                │
  │            └──► rejected     └──► superseded   (proposal replaced; see field 12)
  └──► withdrawn

application-layer enum (no PG CHECK in P0-2):
  draft        proposal being authored (Phase β)
  under_review submitted; awaiting review_decision (P0-6 future) via escalation_ref
  accepted     review passed; eligible for P1 enactment
  rejected     review failed; terminal
  withdrawn    author abandoned before review; terminal
  enacted      P1 executor applied the change-set (cut_change_set_ref); terminal-success
  superseded   replaced by a newer proposal (superseded_by_envelope_id set)
transition_enforcement: application-layer in P0-2; PG CHECK/trigger deferred (Phase β/P1)

INV-5 (review-gated): the only path from under_review to accepted is via a review decision recorded against escalation_ref (P0-6 supplies review_decision; not designed here). The manifest cannot self-accept.

§4 — operation_kind

first_cut: source document → initial pieces; no predecessor blocks (all blocks block_role=result)
split:     one origin unit → 2+ result units (1 origin block + N≥2 result blocks)
merge:     2+ origin units → 1 result unit (M≥2 origin blocks + 1 result block)
notes:
  - operation_kind is the BR-6 discriminator: without it a split/merge proposal is
    indistinguishable from a first cut
  - cardinality rules (1 origin / N result, etc.) are application-layer in P0-2;
    not PG-enforced (no CHECK/trigger constraint in P0-2)

§5 — escalation_ref (soft)

• Soft uuid to decision_backlog_entry; no PG FK (cross-table soft-ref policy, §8).
• Hook by which a proposal enters review/escalation (INV-5).
• review_decision (P0-6) is not designed here; when P0-6 lands it will reference the backlog/envelope — the manifest does not gain a reverse column now (dependency note).

§6 — cut_change_set_ref (soft)

• Soft uuid to cut_change_set; no PG FK.
• Records which change-set the P1 executor will apply to enact this envelope.
• INV-6: all metadata mutation flows through cut_change_set + verify_result; the manifest only names the change-set, it does not perform or verify it.
• NULL until a change-set is allocated (Phase β/P1).

§7 — Owner / Reviewer Metadata & Lifecycle Ownership

• created_by / created_at — provenance of the proposal.
• reviewer / reviewed_at — review provenance (populated when P0-6 review concludes).
• Ownership transfer (re-assignment) is not modeled in P0-2 (no owner-history table; that would be P0-5/P1). Single created_by + reviewer snapshot is sufficient for the proposal layer.

§8 — Soft Reference Policy

in_schema_FK: NONE on manifest_envelope itself
              (the ONLY in-schema FK in P0-2 is manifest_unit_block.envelope_id →
               manifest_envelope — see the unit_block design)
soft_uuid_refs (NO PG FK in P0-2):
  - escalation_ref            → cutter_governance.decision_backlog_entry
  - cut_change_set_ref        → cutter_governance.cut_change_set
  - superseded_by_envelope_id → cutter_governance.manifest_envelope (self)
rationale:
  - avoids coupling/ordering constraints before P1 write pathways stabilize
  - consistent with Phase α alias-design soft-ref precedent
  - referential integrity is an application-layer / P1 concern; P0-2 stays additive+empty
no_constraints_beyond_logical_PK_and_NOT_NULL: TRUE  (no UNIQUE/CHECK/trigger/DEFAULT-data)

§9 — Hard Boundaries

no_DDL_written: TRUE
no_CREATE_TABLE_executed: TRUE
no_mutation: TRUE
no_dry_run: TRUE
no_P0_6_design (escalation_ref is a hook only): TRUE
output_form: p0_2_manifest_envelope_logical_design

End of manifest_envelope design.