KB-4176

RP Aggregate Pivots — 03 Candidate Pivots 301/302/303/312

4 min read Revision 1
registries-pivotcandidate-pivotsorphanphantomdriftkg2026-06-03

03 — Candidate Pivots PIV-301 / 302 / 303 / 312 (Workstream B)

No candidate is left vague. Each has a defined source, meaning, live count, parent, classification, and a UI render decision. None was added to pivot_definitions canon — instead they are surfaced through the additive read-only register v_rp_aggregate_candidate_register (doc 06), so they are clearly marked candidate/non-final in metadata, never asserted as FINAL pivots and never birthing a row. This satisfies §5 ("may be added only if clearly marked candidate"). Adding them as canon pivots was rejected because (a) the RP-grain law is unratified and (b) each would birth an unretirable row.

Why a register row, not a canon pivot

The engine could count each (all are single views; pivot_query supports FROM <view>). The blocker is not engineering — it is law ratification + the irreversible birth side-effect. The register gives the UI a live count + explicit status today without faking law.

Per-candidate decision

pivot concept source live count grain note classification parent UI
PIV-301 orphan v_birth_orphan 59 birth-grain (unborn/missing-birth). Differs from per-collection orphan_count in v_count_integrity. CANDIDATE_REPORT_ONLY n/a (cross-cut, not under a registry total) CANDIDATE_BADGE
PIV-302 phantom v_birth_phantom 289 birth-grain (registered-but-absent). Differs from per-collection record_surplus (e.g. dot_tools=146). CANDIDATE_REPORT_ONLY n/a CANDIDATE_BADGE
PIV-303 count_drift v_count_drift 3 rows row-count drift flag (counted≠actual). Distinct from surplus-object equation drift (net surplus 21,197). CANDIDATE_REPORT_ONLY n/a CANDIDATE_BADGE
PIV-312 kg_edges v_kg_edges_all 2,259 graph edges. NEEDS_LAW_DEFINITION n/a PROPOSE_PIVOT

Rationale / guardrails honored

  • orphan / phantom must not conflict with the birth/orphan safety-net. They don't: the register explicitly labels them birth-grain and notes they differ from the per-collection count-integrity grain. We do not redefine the safety-net's numbers; we point at them.
  • Phantom can't be remediated to 0 — there is no birth-retire mechanism (documented in prior macros). So PIV-302 stays REPORT_ONLY, not a target.
  • KG edge count must not fake relationship completeness. PIV-312 is NEEDS_LAW_DEFINITION precisely because "is a graph edge a registry object?" and "does counting edges imply the graph is complete?" are unanswered. We surface the raw count with the caveat, nothing more.
  • Drift count distinguishes row-count drift vs surplus-object equation drift. PIV-303 = 3 drift-flagged rows (a quality flag). The surplus-object equation drift (Σcounted − Σactual = 21,197) is a separate number reported in doc 06, not conflated.

Promotion path (owner-gated, future)

A candidate becomes a FINAL canon pivot only when: (1) its RP-grain law is ratified; (2) the owner accepts the birth row; (3) it is rehearsed BEGIN..ROLLBACK like PIV-311/313. Until then it lives in the register. No candidate remains undefined.

Back to Knowledge Hub knowledge/dev/reports/architecture/registries-pivot-aggregate-pivots-ratify-add-dot-drill-fix-2026-06-03/03-candidate-pivots-301-302-303-312.md