---

title: 03 — Data Contract (node / list object) date: 2026-05-31

03 — Data Contract

The contract is the JSON object the PG→Directus/API layer returns for any node or list. Nuxt renders it verbatim — no derivation, no math, no thresholds, no label/pin arrays (Đ28 NT-D1/NT-D3, Đ26 §0-BA/§0-AU). Every numeric field is a pivot_count/pivot_query value or the literal token PIVOT_MISSING.

A. Identity & counts (OS-Agency reflection core)

• node_code — pivot code or filter-path identity
• layer · composition_level · species · group / label_ref
• total — pivot value or PIVOT_MISSING
• plus / minus — period delta vs baseline_count (pivot-backed; else PIVOT_MISSING)
• orphan_count — from meta_catalog.orphan_count / orphan pivot
• phantom_count — GREATEST(record_count − actual_count, 0) (needs meta_catalog.phantom_count; doc 05)
• verification_status — verified | unverified | failed (from last_scan_date + invariant)
• drift_status — none | drift (stored record_count ≠ live pivot / actual_count)
• count_integrity_status — ok | failed (doc 05)
• warning_flags[] — orphan | phantom | unmonitored | unregistered | ghost | pivot_missing | label_missing | drift
• next_action — register | onboard | recount | propose_pivot | propose_label | investigate | none
• source_ref — source_object + filter-path (provenance / Đ28 traceability / Đ31 contract)

B. Drill-down

• has_children (true iff total > 1 ∧ a next layer resolves)
• children_count
• next_layer_kind (species | composition_level | group | facet | collection | substrate)
• child_grouping_dimension
• next_pivot_code (or null → leaf)
• drilldown_query_ref (the pivot/query that expands this node)
• final_substrate_ref (set only at leaf: real rows / relationship edges / IU)
• group_size

C. Child-summary (per GPT addendum §C — shown on a parent before drilling)

• child_count
• child_species_count
• child_collection_count
• child_status_breakdown (e.g. {active, draft, deprecated, retired})
• child_orphan_count
• child_phantom_count
• child_drift_count
• child_missing_birth_count
• child_missing_pivot_count
• child_missing_iu_count
• child_missing_dot_count
• top_child_groups (the largest groups, for triage)
• warning_flags (rolled up from children)
• next_recommended_action Each of these is a pivot/aggregate over the child set, served from PG — never computed in Nuxt. Where a sub-metric has no pivot yet it is PIVOT_MISSING (e.g. child_missing_iu_count until an IU-coverage pivot exists).

D. Auto-label / grouping (doc 07; threshold addendum)

• requires_auto_label
• classification_status (classified | inspectable | classification_required | LABEL_MISSING)
• classification_dimension
• label_ref (→ taxonomy.code / label_rules.id)
• grouping_required
• grouping_reason
• max_ungrouped_threshold (per-species; default 50 = MAX ceiling, may be smaller; read from PG)
• suggested_next_grouping
• classification_workflow_trigger

E. Pin / ghim (doc 08)

• pin_state (pinned | unpinned | pinned-by-role | pinned-by-team) — from registry_pin, scoped to viewer

Contract invariants

1. Any numeric field is a pivot result or literally PIVOT_MISSING — never client arithmetic (Đ26, Đ28 Test-4).
2. max_ungrouped_threshold, labels, layers, pins all come from PG (no Nuxt constants/arrays).
3. has_children + depth are backend-decided; Nuxt renders next_layer_kind with no level logic.
4. A failed invariant is represented (warning_flags + count_integrity_status), never hidden (Đ28/Đ23/Đ31).
5. source_ref always present so any rendered cell is traceable to its PG origin (Đ31 contract / Đ28 Truth Check).

Serving path

pivot_* / views → meta_catalog & registry tables → Directus collection or /api/registries-pivot/* endpoint → Nuxt readItems → render via a registered Đ28 template. No direct PG-from-Nuxt; no business logic in the endpoint beyond shaping the contract from pivot outputs.