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

document_path: knowledge/dev/laws/dieu44-trien-khai/v0.2-design/dot-iu-cutter-v0.2-p0-2-manifest-unit-block-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-2. Logical design only.

---

§1 — Logical Object

cutter_governance.manifest_unit_block is one constituent unit of a proposal: a single piece that the envelope's topology change either consumes (origin) or produces (result). For a split envelope: 1 origin + N≥2 result blocks. For merge: M≥2 origin + 1 result. For first_cut: all result. Created empty (later, gated); zero writers/readers in v0.2.

§2 — Composite Identity

logical_primary_key: (envelope_id, unit_local_id)
envelope_id:   uuid; the owning manifest_envelope
unit_local_id: text or smallint; stable label UNIQUE WITHIN the envelope only
               (e.g. 'o1' for origin, 'r1','r2' for results)
in_schema_FK:  manifest_unit_block.envelope_id → manifest_envelope.envelope_id
               (THIS IS THE ONLY PG FK ALLOWED IN P0-2)
rationale: composite identity scopes a block to its proposal; unit_local_id keeps block
           references stable while the proposal is still a draft (no global id churn)

§3 — Logical Field Specification

#	Field	Logical type	Null	Semantics
1	envelope_id	uuid	NO	PK part 1; in-schema FK → manifest_envelope
2	unit_local_id	text	NO	PK part 2; unique within the envelope
3	block_role	text	NO	∈ {origin, result}; application-layer enum. The BR-6 pre-image/post-image discriminator
4	source_span	jsonb / range	NO	mandatory; the span this block covers in the source. Split partitions a parent span into non-overlapping, gap-free child spans; merge unions child spans (see §4)
5	render_order	numeric	NO	ordering of this block within its envelope/parent; value is carried, recompute algorithm is P1
6	target_unit_id	uuid	YES	soft uuid → public.tac_logical_unit.id (no PG FK). origin: the live unit being superseded (NOT NULL in practice). result: NULL until P1 enactment creates the row
7	proposed_canonical_address	text	YES	result: the address the block will be coined with at P1 (per GOV-1, unresolved). origin: NULL (predecessor keeps its live canonical; INV-1). Never written to the SSOT by the manifest
8	proposed_authority	text	YES	intended successor authority snapshot; bound by INV-2 + GOV-2 (unresolved). origin: NULL
9	payload_summary	jsonb	YES	per scope-backlog X-3 schema; summary of the block's content/intent
10	candidate_edges	jsonb	YES	per X-3; edge-redistribution intent only (which edges should follow which result). No edge tables; executor is P1
11	report_summary	jsonb	YES	per X-3; health/segmentation report context that motivated the proposal
12	decision_backlog_ref	uuid	YES	soft uuid → decision_backlog_entry (per scope-backlog v0.2-D-2 note); block-level escalation linkage
13	created_at	timestamptz	NO	now() at DDL time

Estimated row footprint in P0-2: 0.

§4 — source_span (mandatory)

purpose: a block IS a span; topology operations are span algebra
split_rule  (application-layer; not PG-enforced in P0-2):
  union(result.source_span) == origin.source_span
  result spans are pairwise non-overlapping and gap-free
merge_rule:
  result.source_span == union(origin[*].source_span)
representation: logical; concrete form (jsonb {start,end} vs PG range type) is a
  DDL-authoring decision, NOT frozen here (no DDL in P0-2)
note: span coverage/partition checks are application-layer/dry-run concerns at P1;
  P0-2 only guarantees the column exists and is mandatory so BR-6 is representable

§5 — block_role

origin: a pre-image unit consumed/superseded by the operation
        (split: exactly 1; merge: ≥2; first_cut: 0)
result: a post-image unit produced by the operation
        (split: ≥2; merge: exactly 1; first_cut: ≥1)
cardinality_enforcement: application-layer in P0-2 (no PG CHECK/trigger)
significance: block_role is what makes a row a split/merge participant rather than a
  plain first-cut piece; it is the single most BR-6-critical column

§6 — render_order

• Numeric ordering carried on the block so a proposal can express output order.
• The recompute algorithm on split/merge (re-deriving sibling order after a topology change) is P1 — P0-2 only guarantees the column exists. No trigger, no default ordering logic in P0-2.

§7 — target_unit_id (soft)

• Soft uuid → public.tac_logical_unit.id; no cross-schema PG FK (policy §10; Phase α soft-ref precedent).
• origin blocks: the existing live unit being superseded.
• result blocks: NULL in the proposal; the P1 executor creates the live row and the forward linkage at enactment (alias trail per INV-4).

§8 — proposed_canonical_address / proposed_authority / format_version relation

proposed_canonical_address:
  - result blocks only; the address P1 will coin (GOV-1 rule — UNRESOLVED, blocks DDL freeze)
  - manifest NEVER writes public.tac_logical_unit.canonical_address (INV-1)
  - origin block keeps its live canonical untouched; alias trail emitted at P1 (INV-4)
proposed_authority:
  - intended successor authority; bound by INV-2 (no escalation w/o re-enactment)
  - exact inheritance rule = GOV-2 (UNRESOLVED, blocks DDL freeze)
canonical_address_format_version (Phase α column on tac_logical_unit):
  - NOT a writable manifest column; relation only: successors INHERIT the predecessor's
    format_version and it is NEVER downgraded (INV-3)
  - if a future format bump is ever needed it is a separate governed path, not a manifest field

§9 — JSONB Payload Fields

payload_summary:  block content/intent summary (scope-backlog X-3 schema)
candidate_edges:  edge-redistribution INTENT only — no edge tables, no executor here (P1)
report_summary:   the segmentation/health-report context (Q21/Q22 detection signals)
posture: JSONB chosen so edge/report intent is representable WITHOUT building edge tables
  (BR-6 absorption: capture intent, defer executor). No JSON-schema PG enforcement in P0-2

§10 — Soft Reference Policy

in_schema_FK: manifest_unit_block.envelope_id → manifest_envelope.envelope_id  (ONLY one in P0-2)
soft_uuid_refs (NO PG FK in P0-2):
  - target_unit_id       → public.tac_logical_unit.id      (cross-schema)
  - decision_backlog_ref → cutter_governance.decision_backlog_entry
no_manifest_alias_coupling: TRUE  (GOV-3 lean = event-backed; INV-4 emits at P1)
no_PG_CHECK_trigger_DEFAULT_data_in_P0_2: TRUE
rollback_model_later: DROP empty tables (v0.1 cutter_governance precedent)

§11 — Hard Boundaries

no_DDL_written: TRUE
no_CREATE_TABLE_executed: TRUE
no_mutation: TRUE
no_dry_run: TRUE
no_edge_tables: TRUE
no_split_merge_execution: TRUE
output_form: p0_2_manifest_unit_block_logical_design

End of manifest_unit_block design.