The Family Registry

"Compose what's declared. Overlay what's observed. Keep the two layers from ever pretending to be each other."

Two Layers, Two Jobs

With one owner per fact, Firelink needs a clean way to assemble those owners into something usable. It uses two layers with two distinct jobs. The FamilyRegistry composes declared truth: it takes the direct-project scope, the roster, the network ledger, and the operation-policy file, and produces the managed family model — who exists and what they're declared to be. The FamilyReconciler then overlays observed truth: it takes that declared model plus live disk, Git, GitHub, and runtime probes, and produces a census snapshot plus a drift report — what's actually true right now, and where reality disagrees with the declaration.

The composed FamilyRegistry is the one typed object everything else consumes: census, the APIs, the WebUI, the launcher's catalog export, and operation policy all read the same model. There is no second assembly, no parallel list for the frontend, no separate catalog for the launcher.

Drift Is an Explicit, Typed List

Because declared and observed are separate layers, the gaps between them become first-class data. Drift is not a vibe; it's an enumerated set: a managed repo missing from the roster; a network declaration absent or contradictory; an operational manifest missing or invalid; a declared service not installed; a GitHub repo absent; a version unknown; a launch target unavailable on the current client. Each drift is a named condition the hub can show, not a mystery you debug by hand.

The Reconciler Never Repairs on Its Own

This is the discipline that keeps the shrine from becoming the flame: the census never scans nested project trees, auto-deletes, retires, rewrites, or guesses product intent. It reports drift; it does not silently fix it. Repair is either an explicit, Add-owned step (birth flow) or a normal Dad-and-Pippa change made outside Firelink entirely. Observing and reconciling is the hub's job; deciding and repairing is a deliberate act, never an automatic one.

Split declared truth from observed truth into two composition layers, and make their disagreement an explicit typed drift — never an automatic repair. A system that silently 'fixes' drift is a system quietly editing reality to match its own assumptions; a system that reports drift lets a human decide which side was actually wrong.

Code

Compose declared, then overlay observed·text

  direct-project scope --+
  roster metadata -------+
  network ledger --------+--> FamilyRegistry --> managed family model
  operation policy ------+        (declared truth, one owner per fact)

  managed family model + disk / git / github / runtime probes
                         --> FamilyReconciler --> census snapshot + DRIFT
                                (observed truth overlaid on declared)

  DRIFT is a typed, enumerated set, e.g.:
    - managed repo missing from roster
    - network declaration absent or contradictory
    - operational manifest missing or invalid
    - declared service not installed
    - github repo absent / version unknown
    - launch target unavailable on THIS client

  The reconciler REPORTS drift. It never auto-deletes, retires,
  rewrites, or guesses intent. Repair is an explicit, separate act.

Exercise

Design the drift list for a small system you know (say, 'servers I declared in a config' vs 'servers actually reachable'). Enumerate at least four distinct drift conditions — not 'it's broken,' but named states like 'declared but unreachable,' 'reachable but undeclared,' 'declared twice,' 'version mismatch.' Then decide, for each, whether a machine should auto-repair it or report it to a human. Notice which ones you'd never let a machine fix silently.

Hint

The ones you'd never auto-fix are the ones where 'which side is wrong?' is a judgment call. 'Reachable but undeclared' might be a forgotten server or an intruder — a machine forcing either answer is a machine making a decision that wasn't its to make.

Two Layers, Two Jobs

Drift Is an Explicit, Typed List

The Reconciler Never Repairs on Its Own

Code

External links

Exercise

Progress

Comments 0