Node graph implications for dynamics: registry, certification scopes, panel keying, and two interface amendments

[MaxGhenis]

Microcosm's node graph merged into main today (PolicyEngine/microcosm#836; charter in docs/graph-acceptance.md, 37/37 properties green including parity with the unchanged UK spine and the US post-transfer slice). This issue records what that changes for the dynamics design: what this repo no longer needs to build, what the graph forces us to decide, and two interface amendments the Dynamics operator needs before the panel schema can land.

Mechanism claims below are from the merged code, not the plan: a node declares the slices it reads, the cells it owns, its params, and a kernel; its key is a hash of the normative declaration, its input artifact keys, and the kernel's implementation hash; structural nodes (CREATE, FILTER, EXPAND, REWEIGHT) open population versions; gates are kernels with the gate role and a release tier is certified only if every gate on the ancestral path passed; decisions live in the run manifest and never in keys; seeds derive from node keys; artifacts live in a content-addressed store.

What this repo no longer needs to build

• Component registry and immutable candidate specs (External architecture review (Codex gpt-5.6-sol): 10 findings + pre-CPS refactor plan #106 findings 1, 2, 3, 5). A candidate is a Graph. ComponentRef(kind, implementation_id, params) is a Node with a kernel ref, params, and the kernel's implementation hash. A candidate composed of c1, c5, c6, c8 and c9 is a graph of those nodes, and the store reuses every artifact whose key is unchanged. "Unchanged" means the same key, never the same code object. The engineering replay the review asked for (port the c14 lineage, compare against the committed rate cube, record a compatibility certificate) is a parity property of the same kind as microcosm's H1 to H3.
• Certification scopes per tranche (External architecture review (Codex gpt-5.6-sol): 10 findings + pre-CPS refactor plan #106 finding 4; Roadmap: from incidence replication to a DYNASIM-class projection on one unified person-period panel #113's "inherit only the certification scopes their slice uses"). A cell is certified only if every gate on its ancestral path passed, so a product that prunes rows, columns, or years inherits exactly the gates its remaining cells descend from. No separate certification_scope machinery.
• Pre-registration mechanics. gates.yaml thresholds become gate-node params inside the frozen declaration: an amendment changes keys and is visible as a new revision. Decisions that may not affect keys live in the manifest, and a release that needs an unmade decision stays unreached.
• Seeds and the mean-over-N-draws protocol. Seeds derive from node keys, so a draw index is a param and every draw is reproducible and addressable.
• The alignment layer (Roadmap: from incidence replication to a DYNASIM-class projection on one unified person-period panel #113 hard part 2). Each projected year's alignment to Trustees assumptions is a REWEIGHT node that owns that year's weights and whose key includes the targets.

What the graph forces us to decide

• Keying. microcosm's DESIGN.md defers (person_id, period) to "before the Dynamics operator". In graph terms the choice is a person_period entity produced by an EXPAND node with lineage to the person, versus a composite key on the person entity. Recommendation: the EXPAND form. It reuses lineage, membership remapping, and the row-mask primitive (Slice.rows names a boolean column), so a year-slice is a row mask on the period column, the same move as geography.
• Weight-share. Households recompose across periods, so period-t group weights must be a declared function of member trajectory weights. That is a REWEIGHT node owning the period household's weights. Ownership makes the operator's absence a compile error rather than a silent member-constant collapse.
• Repo boundary. Kernels (transition models, generators, gates, the transport gate) live here; the population model and structural deltas live in microcosm-graph.

Two interface amendments the Dynamics operator needs (microcosm side)

1. Entry without lineage. EXPAND requires every new row to name an existing source id (population.py raises on unknown lineage). Births can trace to a parent; immigrant entry cohorts cannot enter at all. Proposal: either a union with a CREATE'd entry cohort, or an EXPAND form that admits sourceless rows carrying entry markers (birth, immigration), with exit markers as the FILTER side. decl.py is frozen, so this is an amendment ceremony.
2. Period residency in mass accounting. The mass ledger and the design-weight anchor are per population version. "A trajectory's weight contributes to a period only while resident" needs both to be period-aware.

Numeric claims

The H2 parity work found that the FRS root transform's household weights differ by one ulp between arm64 and x86 for two of 135 fixture households, and forest kernels are declared tolerance-bound. Gate verdicts here must compare in-process or against declared tolerances; the half-versus-half noise floor in gates.yaml is already the right shape.

Sequencing

Migrate the registry and candidate ladder onto graph declarations before M5, otherwise the #106 P1 refactor builds a second registry. Land the panel schema with M5 as #113 planned, but open the two amendments first. The transport gate itself is a gate node whose inputs are the PSID-fitted artifact and its deployment on the CPS frame.

Reconcile with in-flight design

• Family-transitions component registry + c16 compatibility certificate #121 already ported the family-transitions registry with a c16 compatibility certificate. The proposal here is that the next step expresses those components as graph nodes rather than growing that registry further.
• Immigration module design: new-entrant cohorts through the scheduled-entries seam (draft for referee) #218 (immigration: new-entrant cohorts through the scheduled-entries seam) is the design the entrants amendment must serve; whichever form the amendment takes, the scheduled-entries seam should be its consumer.
• Alignment machinery design: production-mode reconciliation with displacement disclosure (draft for referee) #217 (alignment machinery with displacement disclosure) maps onto per-year REWEIGHT nodes whose keys carry the targets; the displacement disclosure is that node's receipt.

Refs: #106, #113, #121, #217, #218, PolicyEngine/microcosm#836.

🤖 Generated with Claude Code

[MaxGhenis]

Folded into the microcosm-dynamics architecture review as a follow-ups section (artifact: https://claude.ai/code/artifact/77094123-ea65-4587-9e8e-9d6aaafa3c2a). Disposition recorded by the ceremony lane:

1. The graph's node and artifact keys are the natural answer to the review's revision-22 pin-manifest recommendation; Dynamics should adopt them rather than a parallel scheme.
2. The two forced decisions (person_period keying via EXPAND with lineage; period household weights as a REWEIGHT node) go to Max, with the note that whatever composes W1 transport into the M6 loop should itself be a Node.
3. The two interface amendments are recorded as prerequisites for any panel schema and route through microcosm's amendment ceremony (decl.py is frozen). Drafting waits on the two decisions.
4. The arm64/x86 one-ulp weight difference and tolerance-bound forest kernels go into the review's reproducibility pack.

Ownership boundary for the #121 / #217 / #218 conflicts, accepted by the ceremony lane with two additions (below): kernels (transition models, generators, gates, the W1 transport composition as a Node) live here; the population model and structural deltas (entrants delta, period-aware mass ledger and design anchor) live in microcosm-graph.

Additions from the review's findings, accepted into the boundary:

• Benefit-level gate-role kernels are dynamics-owned: AIME, PIA, claim-age, and benefit-level cells scored against SSA Supplement 6.A4 / 6.B3. The review's high finding is that no locked gate scores any benefit quantity today; naming the owner keeps that gate from falling between the repos when it is registered.
• Declared kernel tolerance on every Node, so gate verdicts compare against declared tolerances by construction (the arm64/x86 one-ulp weight difference; tolerance-bound forest kernels). On the microcosm side this is a third interface amendment: Capabilities.numeric already classifies a kernel as bitwise or tolerance-bound, and the magnitude (relative, absolute, or ulps) is the new field. It travels with the other two amendments through the ceremony.

[MaxGhenis]

Max ruled go (2026-09-02) on both decisions: person_period as an entity produced by an EXPAND node with lineage to the person, and period household weights as a REWEIGHT node that owns them. The three microcosm interface amendments (entrant rows without lineage; period-aware mass ledger and design-weight anchor; declared numeric tolerance on every kernel) are being drafted on the microcosm side, together with a charter clarification that conserve means weighted person mass per stratum and that composition-changing expansions declare their mass change with a receipt stating the invariant they do hold (PolicyEngine/microcosm#844). The draft text will be linked here for the dynamics side to review before the re-lock.