---

title: 09 — Consolidated Node / List Data Contract date: 2026-05-31

09 — Consolidated Node / List Data Contract

Every node returned by the backend to Registries-Pivot carries this contract. Nuxt renders fields verbatim — no derivation, no math, no thresholds. Fields are grouped by addendum source.

A. Identity & counts (reflection-screen core — addendum 1)

• node_code — pivot code or filter-path identity
• layer · composition_level · species · group / label_ref
• total — pivot value (pivot_count/pivot_query) 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 column; doc 02)
• verification_status — verified | unverified | failed (from last_scan_date + invariant)
• drift_status — none | drift (record ≠ actual)
• count_integrity_status — ok | failed (doc 02)
• 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)

B. Drill-down (addendum 1 §4)

• 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 to expand this node)
• final_substrate_ref (set only at leaf: real rows / relationship edges)
• group_size

C. Auto-label / grouping (addendum 1 §5 + threshold addendum)

• requires_auto_label (group_size > threshold ∧ no existing grouping)
• 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

D. Pin / ghim (addendum 1 §6)

• 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 computed in the client (T-COUNT-1/2).
2. max_ungrouped_threshold and all label/layer/pin data come from PG (T-LABEL-2, T-DRILL-2, T-PIN-1).
3. has_children and depth are backend-decided; the client renders next_layer_kind without level logic.
4. A failed invariant is represented (warning_flags + count_integrity_status), never hidden (Đ28/Đ23).