03 — cut_manifest_piece_schema_v1

Required per-piece schema enforced by public.fn_cut_mark_staged_file BEFORE the cut_request transitions to status='marked'. Enforced as of mig 054 (2026-05-27).

Required fields

field	type	rule	enforced where
local_piece_id	string	non-empty (after btrim); MUST be unique within the manifest	fn_cut_mark_staged_file
content_text	string	non-empty (after btrim)	fn_cut_mark_staged_file (mig 053)
canonical_address	string	non-empty (after btrim)	fn_cut_mark_staged_file (mig 053)
source_position	integer-like string	matches ^[0-9]+$, value >= 1	fn_cut_mark_staged_file (new)
piece_role	string	non-empty (after btrim). Vocab not yet defined → no membership check today.	fn_cut_mark_staged_file (new)
section_type	string	non-empty; MUST be in public.dot_config under key vocab.section_type.<value> (18-key vocab as of 2026-05-27)	fn_cut_mark_staged_file (new)

Optional fields

field	type	rule	enforced where
parent_local_id	string or null	null OR must reference a local_piece_id present in the same manifest	fn_iu_verify_mark Axis C

Manifest-level rules

field	rule	enforced where
pieces	non-empty array	fn_iu_op_mark_file + fn_cut_mark_staged_file
source_position density	min=1, no holes between min and max	fn_iu_verify_mark Axis A
manifest_digest	matches ^[0-9a-f]{32}$	fn_iu_verify_mark
coverage_proof.covered_bytes	equals manifest.source_bytes	fn_iu_verify_mark

Boundary placement (why MARK, not verify)

• fn_iu_op_mark_file (the alias) is a pass-through and its body md5 is governance-pinned across packs (Phase 3 / Phase 3B / 052 / 053). Adding validation there would mutate the alias contract.
• fn_cut_mark_staged_file is the operational wrapper above the alias — it already gates on cut_request.status, performs the state-machine transitions, and built-in to it as of mig 053 was the first per-piece check (content_text, canonical_address). Extending it to the full v1 schema preserves the alias boundary and puts the gate at the right architectural layer.
• Result: bad pieces are refused with an indexed message (piece[N].<field> is required (cut_manifest_piece_schema_v1)) and cut_request never reaches mark_in_progress, let alone marked. The prior mid-flight jsonb_set recovery pattern (see [[feedback-mark-pieces-live-in-iu-staging-payload-cut-manifest-not-in-iu-staging-record-metadata]]) is no longer needed as production behavior.

Example valid piece

{
  "local_piece_id":    "P1",
  "source_position":   1,
  "piece_role":        "section_body",
  "section_type":      "section",
  "content_text":      "# ĐIỀU 39 — LUẬT KNOWLEDGE GRAPH v2.3 ...",
  "canonical_address": "DIEU-39-v2.3#preamble",
  "parent_local_id":   null,
  "title":             "Preamble + enactment header",
  "unit_kind":         "law_section",
  "source_ref":        "knowledge/dev/laws/dieu39-knowledge-graph-law.md",
  "piece_index":       1
}

Caller may add additional informational fields (e.g. title, unit_kind, source_ref, piece_index) — they are preserved verbatim in the manifest but not validated.