02 — The piece-native authoring / composer model (migration 015)

The idea

Before this macro a file/document existed in IU Core only as a cut source document: a blob of text decomposed into pieces wired into the iu_tree_path parent-child tree. There was no way to author content directly from pieces.

Migration 015 adds that. A composition is a first-class, named, ordered collection of IU pieces — a file, a document, or a workflow — orthogonal to the cut-source tree:

• the document tree records how a cut source decomposes into pieces;
• a composition records how an arbitrary file/workflow is assembled from pieces — pieces from any document, or authored from scratch.

Both paths converge: a composition's pieces are the same information_unit rows with the same three-axis metadata. Complex content can still be written then cut; simple content can now be authored directly as pieces.

No second source of truth

iu_piece_membership stores order + role only. The piece is an FK to information_unit(id) — never copied content. A composition is pure metadata: an ordered index over existing IU rows.

Objects authored — 2 tables, 3 views, 10 functions, 1 gate

Tables

• iu_piece_collection — collection_key (unique), collection_kind ∈ {file,document,workflow}, title, lifecycle_status ∈ {draft,active, deprecated,retired}, source_axis_kind ∈ {composed,cut,imported} (the axis-A generated-source provenance), manifest_digest, created_by.
• iu_piece_membership — piece_order (NULL iff removed), piece_role ∈ {title,intro,body,step,clause,appendix,reference}. UNIQUE(collection_id, iu_id) + UNIQUE(collection_id,piece_order).

Views

v_iu_collection_manifest (ordered three-axis render), v_iu_collection_envelope (per-collection summary), v_iu_collection_health (observability flags).

Functions

fn_iu_composer_enabled (fail-closed gate); fn_iu_collection_create; fn_iu_collection_add_piece; fn_iu_collection_remove_piece (renumbers remaining contiguous); fn_iu_collection_reorder_piece (two collision-free passes); fn_iu_compose (create a file/workflow from N pieces — each existing {"iu_id":…} or from-scratch {"new_piece":{…}}); fn_iu_collection_manifest _refresh; fn_iu_collection_render; fn_iu_collection_validate; fn_iu_collection_healthcheck.

Fail-closed + governed birth

The gate dot_config 'iu_core.composer_enabled' is registered by the migration (default false). Every mutating function RAISE … insufficient_privilege while it is shut. fn_iu_compose mints from-scratch pieces ONLY through public.fn_iu_create — the IU Gateway birth gate. No-ungoverned-IU guarantee.

DOT

+2 tables / +3 views / +10 functions / +1 config. runtime/110 SSOT bumped table 12→14, view 9→12, function 24→34, config 5→6 (total 68→84) in the same commit; D8 drift guard gained iu\_piece%.