Skip to content

Registration 7: the first estimates report (forecast ledger entry 8) #307

Description

@MaxGhenis

REGISTRATION 7 — the first estimates report (forecast ledger entry 8)

Registration

Class: registered estimates report — the class chartered by
docs/design/first_estimates_report.md, ratified at 6586b92,
amendment 1 at ee1221d, the §11 sealed-invocation restatement at
070cbb7, amendment 2 at 4104d3d with corrective revision 10.1 at
f771b49
(the current design identity), implemented at 1c7f354.
The design is at revision 10.1.

Output artifact: runs/first_estimates_v1.json with its paired
.env.json sidecar, integrity-bound by the primary's recorded sidecar
hash, written append-only by artifacts.write_new.

The canonical execution rule (§11, restated verbatim as the sole
normative wording):
one registered run; publishes_regardless;
no_self_rescue; at most one coordinator-adjudicated, report-first
retry solely for an external pre-output failure yielding no
estimate-bearing information
. A published v1, any changed
configuration byte, or a second failure of any kind requires fresh
registration
— there is no same-ceremony v2 path. Preparation,
invariant, compute, or publication aborts publish an append-only
incident record (first_estimates_incident.v1, the frozen nine-key
schema) before any further step. The durable attempt claim and the
retry-consumption marker enforce these terms across crashes.

The sealed invocation (unchanged): before any populace_dynamics
import the runner self-re-executes the same interpreter as python -I -B -X pycache_prefix=<fresh-empty-sentinel-directory> scripts/run_first_estimates.py <registered-arguments>; the launcher is
the launchd user-domain topology of the candidate-3 record (one-shot
LaunchAgent, RunAtLoad, AbandonProcessGroup,
ProcessType=Interactive, no KeepAlive, launcher spawns-and-exits,
runner-held caffeinate -sim, bootstrap → health check → bootout,
runner ending as a pid-1 orphan in no application coalition);
publication performed by the coordinator after exit.

Registered arguments: --registration-reference populace-dynamics#<this issue> and --registered-configuration docs/registrations/first_estimates_registration_7_configuration.json.

What changed since registration 5

Registration 5's incident opened a chain that is now closed, every
link referee-gated and on the record (#299):

Rehearsal evidence (new; a precondition of this registration)

A full out-of-ceremony rehearsal of the coordinator's compute and
invariant phases — projection of all twenty draws, per-draw preparation,
batch preparation, and artifact assembly, stopping before publication —
completed on this code before this registration was created. Its log
and the assembled artifact's canonical byte count are recorded in the
launch comment. Registrations 3, 4, and 5 each died on a failure a
rehearsal would have surfaced in minutes; rehearsing before spending a
registration is now standing practice for this class.

The rehearsal is not a substitute for the ceremony and confers no
authority: it publishes nothing, its artifact is discarded, and the
registered run recomputes everything under the sealed interpreter.

Frozen configuration (the coordinator hard-asserts or records)

  • Source: master 1c7f354 — a clean checkout; the
    guards refuse ANY tracked or untracked drift, ignored executable
    artifacts under the code roots, assume-unchanged/skip-worktree
    entries, redirected git routing, and an unsealed interpreter.
  • Candidate-3 binding: the gate runner's normative
    fit/preflight/materialization sequence with both CandidateSpec
    sha256s asserted against the registration-12 pins — family
    734a5b04f347c5d4904bbc6d5ab9a1c2876272d35284eedd2f450518acf1cec5,
    engine
    c9be28a28d6fcc3911723872386906af559f6d0e0d5c89a87f741a5b2c3eacd6
    (a mismatch aborts); unsplit population; draw indices 0-19 (root
    seeds 5200+k per the RNG registry law).
  • Statutory parameters: policyengine-us 1.752.2; rate legs from
    gov/irs/payroll/social_security/rate/{employee,employer}.yaml with
    the 6.2%/6.2%/12.4% fail-closed assertions and no fallback; the
    committed SSA COLA history data/external/ssa_cola_history.json
    (sha256 12da7f0e…a38b, determination-year keyed, coverage asserted
    for 1979-2022 exactly).
  • The staged inclusion law as ratified at revision 10.1: Stage A
    DI screen over all persons; Stage B any-slice candidate universe;
    Stage C origin classification (birth-free) for every candidate;
    Stage C.5 birth-year resolvability with the frozen
    excluded_birth_year_unresolved key (published even when empty;
    origins = C.5 + Stage-D + included); Stage C completed — the
    strict-< truncated-renormalized 6.B5.1 imputation under the
    code-frozen stock-imputation namespace — for C.5 survivors; Stage
    D's five ordered predicates with the frozen excluded_* keys;
    eligibility era ≥ 1979; the 0.80 coverage rule;
    cutoff-before-imputation. Birth years resolve under §3.1's four
    clauses with the five frozen source classes and the per-draw §10
    birth-timing sensitivity published alongside.
  • Ledgers: as-of AIME; eligibility-year PIA; months-based
    benefit_factor; stepwise COLA with dime flooring; no recomputation
    (affected count published); the payment-window triple intersection;
    nominal in-window revenue with wage-base capping and no expectation
    layers.
  • PSID staging: ~/PolicyEngine/psid-data.

Candid expectations (house rule)

Every dollar is frame-relative, pre-alignment, labor-income-proxy.
No level anchor exists in-repo; no comparison to any administrative
total is made (the context ratio is deferred_to_anchor_extraction by
amendment 1). What would look pathological: an empty or near-empty
modeled_award universe, an exclusion class absorbing the overwhelming
majority of candidates, a coverage-ratio distribution collapsing at the
0.80 boundary, or across-draw SDs rivaling means. The odd-year earnings
carry law and its affected-share diagnostics accompany every annual
table, with biennial companions.

Measured before this registration (the committed evidence artifact),
and stated so the run cannot be credited with a surprise: the report
population is 30,482 persons; birth sources 13,727 inferred + 9,673
exact + 4,077 derived + 690 synthetic + 2,315 unresolved; canonical
candidates 3,083 (2,784 domain-resident; origins 1,495 modeled /
1,588 backfill); excluded_birth_year_unresolved expected empty;
included claimants 1,514 by source 0 derived / 74 exact / 1,440
inferred. The rehearsal's full Stage A-D funnel is recorded in the
launch comment, and the registered run is expected to reproduce it
exactly
; any divergence is itself a finding about determinism and
will be disclosed as one.

Runtime and publication

Twenty draws of a 2014→2022 unsplit projection plus the statutory
pipeline; the sealed registration-5 run reached the invariant phase in
~40 minutes at the pinned eight-thread topology, so the compute is
hours-scale at most. On completion (any verdictless outcome — this class
has no verdict), the coordinator commits the artifact pair on a branch
and opens the publication PR; forecast ledger entry 8 resolves at that
PR's merge
(p50 2026-08-02). Incidents 1-4 are committed; incident 5's
record publishes in the records PR that carries this registration's
configuration document (the append-only debt named on #299); any
further incident publishes to runs/first_estimates_incident_6.json.

Lineage from registration 6

Registration 6 (#305) was consumed by incident 6 — a
refusal-to-start on registration 5's stale durable attempt claim,
raised before any claim was bound to #305 and before any input was
loaded. The claim was adjudicated and removed with disclosure on #299;
the incident record commits with this registration's document. Nothing
about the code, the design, the document construction, or the
rehearsal evidence changed between the two registrations. The
pre-launch checklist now verifies: attempt claim absent, retry marker
absent, artifact pair absent, worktree pristine at the registered
commit.

Rehearsal evidence (the precondition, met)

Full out-of-ceremony rehearsal at 1c7f354 (worktree fresh, pristine;
launchd vehicle, nice 0, pinned eight-thread topology), completed
2026-07-26 02:19 ET, REHEARSAL PASSED:

  • fit + preflights + materialization + twenty draws: 3,096.9 s
    (draws 104-136 s each after the first);
  • batch preparation, including the per-draw §10 birth-timing
    sensitivity: 539.4 s;
  • artifact assembly: 0.9 s; canonical artifact 19,513,372 bytes,
    schema first_estimates.v1, all thirteen top-level keys present
    (tables: modeled_award_flow / opening_stock / revenue; diagnostics
    include birth_timing_sensitivity and common_support_agreement).

Funnel spot-checks against the committed evidence artifact: the four
real birth-source classes draw-invariant at exactly
13,727/9,673/4,077/2,315 (sample SD 0.0 across all twenty draws);
draw-0 synthetic natives 690; excluded_birth_year_unresolved = 0 in
every draw (published, as the law requires); draw-0 included claimants
1,514 with included_birth_source__derived_projection_age = 0.0 in
all twenty draws — the ratified nil-contribution expectation is now
a measured fact across the whole batch, not only draw 0. Across draws:
included 1,518.1 ± 16.8.

The rehearsal publishes nothing and confers no authority; the
registered run recomputes everything under the sealed interpreter and
is expected to reproduce the draw-0 funnel exactly.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions