04 — Nuxt assembly contract

1. What this is

The PG -> Directus -> Nuxt boundary forbids new Nuxt business logic for IU Core. This macro therefore writes ZERO Nuxt code; it writes the deterministic assembly contract that pairs with the Directus registration package — telling a Nuxt developer which Directus collection name to read, which fields exist, how to filter per axis, and what the screen's tabs / sections look like. The contract is JSON-serialisable, derived from the same SSOT (v_ui_iu_directus_registration_envelope).

2. nuxt_assembly_contract.py — pure data

build_nuxt_contract(package) consumes a DirectusRegistrationPackage and projects:

• collection_name, source_view, primary_key_field — passthrough.
• field_names: tuple[str, ...] — every field, ordered by ordinal.
• axis_filters: tuple[NuxtAxisFilter, ...] — one filter per field with a discovered shape:
  • primary -> eq (filter by unit_id);
  • axis_a_* -> eq (sort_order is the linear key);
  • axis_b_* (jsonb tag aggregates) -> jsonb_contains;
  • axis_c_depth -> depth_eq; axis_c_ancestors -> in_array.
• tab_groups: Mapping[axis_group -> tuple[field, ...]] — for the three-axis tabs on the screen.
• sdk_example, rest_example — copy-paste starting points for the developer (existing Directus SDK pattern; no new server route).
• rules: tuple[str, ...] — MUST NOTs encoded as data:
  • Nuxt MUST NOT open a direct PG connection.
  • Nuxt MUST NOT bypass Directus permissions.
  • Nuxt MUST NOT add business logic on these fields; render only.
  • Nuxt MUST NOT mutate this collection.
  • Filters MUST come from this contract; new filters require a new registration package (deploy-gated).

The contract serialises deterministically via as_json() — diffable in git, easy to share with a Nuxt developer who is not running this repo.

3. CLI surface

NUXT_ASSEMBLY_COMMANDS registers one one-command (no IO):

• dot_iu_nuxt_three_axis_assembly_contract — prints the contract JSON.

4. Three-axis tabs (derived, not hardcoded)

• Identity (primary): eq filter, unit_id
• Metadata (meta): display only, canonical_address + unit_kind + section_type + lifecycle_status + created_at + updated_at
• Original-text reconstruction (axis_a): eq + sort, axis_a_doc_code + axis_a_sort_order + axis_a_section_code
• Semantic/content (axis_b): jsonb_contains, axis_b_tags + axis_b_tags_by_source
• Hierarchy (axis_c): eq/depth_eq/in_array, axis_c_parent_id + axis_c_depth + axis_c_ancestors + axis_c_ancestor_addresses

The tab list is the axis_group list discovered from the envelope. A future axis added to the three-axis view automatically shows up as a new tab without code change in Nuxt.

5. Example REST queries (from the contract)

GET /items/iu_core_three_axis_envelope?fields=*&sort=axis_a_doc_code,axis_a_sort_order&limit=200

GET /items/iu_core_three_axis_envelope
   ?filter[axis_b_tags][_contains]={"legal_document":["doc:DIEU-28"]}
   &sort=axis_a_sort_order

6. What is NOT in this macro

• Nuxt component code, route handler, build/restart/deploy.
• Directus collection registration call (deploy-gated; doc 03).

7. Reversibility

Removing this module from the codebase removes the assembly contract artifact only. It does not change any Nuxt behaviour (no Nuxt code imports from it). The Directus collection registration (doc 03) is the operational reverse path.