---

title: 07 — Phantom Definition Decision Pack date: 2026-05-31 status: LAW_DEFINITION_GAP — decision pack only, NO enactment (Đ32 council)

07 — Phantom Definition Decision Pack

Phantom has no dedicated law article → LAW_DEFINITION_GAP. This pack gives the council the material to decide. Nothing is enacted here.

A. Candidate definitions

1. Naive: phantom = record_count > actual_count (surplus = phantom count). Rejected — unsafe (§B).
2. Source_model-aware (recommended): a phantom is a counted/registered unit whose substrate cannot be located by that source's own scanner, evaluated per source_model:
   • model B (file-backed): registered row with no backing file → phantom.
   • model A (DB/Directus-backed): reconcile the registered count against the live pivot; a record > actual surplus is stale-scan / live-write race, NOT phantom.
   • pg_table / unmeasured: cannot be phantom until measured (no scanner result yet).
3. Relationship-aware (Đ0/Đ19 alignment): phantom = registered unit failing the minimum relationship/birth set its species requires (overlaps "orphan"; keep phantom = substrate-absent, orphan = relationship/birth-absent to avoid collision).

B. Why record > actual alone is UNSAFE (from live drift)

The surplus direction is source_model-dependent, proven by today's rows:

row	model	record	actual	naive verdict	TRUE meaning
CAT-023 birth	A	985,472	985,471	"phantom +1"	live-write race, not phantom
CAT-006 dot_tools	B	309	163	"phantom +146"	genuine phantom (146 rows, no file)
CAT-007 ui_pages	B	37	52	"orphan −15" (record<actual)	15 unregistered files
Earlier today CAT-023 showed record 980,378 > actual 943,726 (+36,652) — the naive rule would
have called 36,652 real birth records "phantoms." A refresh scan erased the gap. **Blind
record−actual would have manufactured a 36k phantom incident.** Hence the def must be model-aware.

C. How it maps to system_issues / event_outbox (Đ45)

• Detection → system_issues (existing SoT). New: issue_type='count_integrity_phantom', source='registries-pivot-count-integrity', entity_code=<CAT code>, severity per magnitude, idempotent via coalesce_key (e.g. phantom:<cat>:<source_model>), occurrence_count/ reopen_count track recurrence. Pattern mirrors the existing dot-layer-integrity-audit source.
• Signal → event_outbox (Đ45: queue carries signal not data; MOT-not-executor). New event types (register before emit): count_integrity.phantom_detected, count_integrity.phantom_cleared. None of these event types exist in event_type_registry today (verified) → must be ratified first.

D. Cleanup workflow (proposed, gated)

1. fn_count_integrity_check() scans the leaf set; for each model-B row with record>actual and a missing-file signal, writes/updates a count_integrity_phantom issue (idempotent).
2. Council/owner triages: confirm phantom → soft-retire (Đ0 Atom: active=false, never hard delete) or re-onboard the missing file.
3. On reconciliation, emit phantom_cleared; issue → resolved with resolution.
4. Đ31 self-verification contract + watchdog ensures the check itself runs (silent-gap/heartbeat).

E. Proposed law-patch TEXT (DRAFT — for council, not enacted)

Điều [NN] — Phantom (Bóng ma đăng ký). A phantom is a counted or registered unit whose backing substrate cannot be located by the authoritative scanner of its source_model. Detection MUST be source_model-scoped: (a) model B (file/external): registered row with no resolvable backing artifact; (b) model A (DB/Directus): only after reconciling the registered count against the live pivot_count(); a positive record − actual that is explained by scan-lag or in-flight writes is NOT a phantom; (c) unmeasured sources: cannot be classified phantom until a scanner result exists. Blind record_count − actual_count MUST NOT be used as the phantom count. Phantom is distinct from orphan (orphan = missing birth/relationship per Đ19; phantom = missing substrate). Remediation is soft-retire (Đ0 Atom) or re-onboard; never silent hard-delete. Detection writes system_issues(issue_type='count_integrity_phantom') idempotently and emits signal-only event_outbox events (Đ45), both registered before first emit (Đ45 register-before-emit).

F. Acceptance criteria (for RG4)

• Phantom defined source_model-aware; blind record−actual explicitly rejected.
• Phantom vs orphan boundary stated (no collision with Đ19).
• count_integrity_phantom issue type + phantom_detected/cleared events registered before emit.
• Live test: CAT-006 classified phantom-candidate (model B); CAT-023 NOT phantom (model A race); CAT-007 classified unregistered, not phantom.
• Until ratified, the surface renders phantom as PIVOT_MISSING / warning_flag=phantom(unconfirmed) and emits nothing. No enactment by agent.