07 — UI / API Handoff

The contract is the live, read-only view v_rp_classification_governance_map (37 rows). RP UI/API can consume it today. No write endpoints — classification edits are DOT-mediated server-side (and currently held; see doc 04).

Field contract (per row)

field	type	meaning	UI use
pivot_code	text	PK (PIV-/MTX-)	row id
pivot_name	text	display name	label
source_object	text	backing table	tooltip
is_active	bool	active flag	dim/retired styling
raw_registry_group	text	raw token (VI domain or EN shape)	debug only
registry_group_kind	enum domain | pivot_shape | unknown	category-error #1 split	governed vs RP-local split
fac02_label_code	text | null	LBL-101..105	governed badge
fac02_label_name	text | null	VI role name	badge tooltip
pivot_kind	enum | null	default/cross_table/l2_drill/matrix/test	RP-local shape chip
raw_species	text | null	raw species token	debug
species_governed_code / _display_name	text | null	governed species	species badge
species_governed_composition	text | null	governed composition	expected-comp hint
species_status	enum clean|missing|ambiguous_meta|orphan	species health	status badge
raw_composition_level	text	current composition	value
composition_is_canonical	bool	in {atom,molecule,compound,meta}	validity hint
composition_status	enum match|mismatch|drill_overload|no_ref	comp health	badge
classification_lane	enum governance_home|rp_local|inactive_retire_candidate	top-level lane	section split

Cleanup status badges (derive from the row; no extra call)

badge	rule	color
✅ Governed	registry_group_kind='domain' AND fac02_label_code IS NOT NULL	green
🟡 Pending naming	registry_group_kind='domain' AND fac02_label_code IS NULL	amber
🔧 RP-local	registry_group_kind='pivot_shape'	blue
⚠️ Comp mismatch	composition_status='mismatch'	red
🪜 Drill-overload	composition_status='drill_overload'	grey (informational, NOT an error)
❓ Ambiguous meta	species_status='ambiguous_meta'	amber
🚫 Orphan	species_status='orphan'	red (currently never shown — 0)
🗄️ Retired	is_active=false	muted

L2 gate banner (MANDATORY, must read closed)

Render a persistent banner driven by the L2 counters (read-only):

ospa=0 ownership=0 gap=210 gov_emit=0  →  banner: "L2 Governance: GATED (not active)"

• Never render "governance gap=0" or "fully governed" while gap>0.
• The banner reflects L1 classification being live while L2 ownership is gated.
• Source: anti-drift AD-7 (ok_l2_gate_closed_no_false_claim).

Governed vs RP-local split (primary layout)

Two sections, driven by classification_lane then registry_group_kind:

1. Governance home (lane=governance_home, 15 rows) — show FAC-02 badge; amber where fac02_label_code is null (pending naming).
2. RP-local (lane=rp_local, 20 rows) — show pivot_kind chip; drill_overload is normal, render as informational, not an error.
3. Retired (lane=inactive_retire_candidate, 2 rows) — muted/collapsed.

JSON examples

Governed, healthy:

{ "pivot_code":"PIV-003","pivot_name":"...","registry_group_kind":"domain",
  "fac02_label_code":"LBL-104","fac02_label_name":"Công cụ",
  "species_status":"clean","composition_status":"match",
  "classification_lane":"governance_home" }

Governance-home with a real composition bug (Action A target):

{ "pivot_code":"PIV-001","registry_group_kind":"domain","fac02_label_code":"LBL-101",
  "raw_composition_level":"molecule","species_governed_composition":"atom",
  "composition_status":"mismatch","classification_lane":"governance_home" }

RP-local drill pivot (NOT a bug):

{ "pivot_code":"PIV-204","registry_group_kind":"pivot_shape","pivot_kind":"l2_drill",
  "raw_composition_level":"material","composition_status":"drill_overload",
  "classification_lane":"rp_local" }

Forbidden UI assumptions

• ❌ Do not treat drill_overload as an error — it is law-valid RP-local drill metadata.
• ❌ Do not claim governance coverage / gap=0 — gap=210 (real); show the GATED banner.
• ❌ Do not offer an inline "edit classification" write — there is no write endpoint; edits are DOT-mediated server-side and currently held.
• ❌ Do not treat species='species' (ambiguous_meta) as an orphan/error — it is the governed meta-species (SPE-SPE).
• ❌ Do not read clone/test data as production truth.
• ❌ Do not assume fac02_label_code exists for all domain rows — 6 are pending naming.