PolicyEngine / PolicyEngine/microcosm
Migrate the US stacked driver onto microcosm.build.logbook_adoption
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 4
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 94
Description
Follow-up to #666 / PR #670, filed at review request: this is convergence work that prevents contract drift, not tidying.
The problem
PR #670 extracted the generic Logbook adoption helpers (attempt state, predecessor resolution, git code pins, exportable local:// references, role-pin digests, atomic JSON receipts, pipeline-error verdicts, the record-once terminal write) from tools/build_us_multispine_pool.py into microcosm.build.logbook_adoption, and wired the three UK drivers through the shared module. The US driver deliberately kept its private copies, because its ~4.7k-line contract suite pins those seams by monkeypatch and folding a US migration into the UK adoption diff would have doubled the review surface.
That leaves the same logic in two places, with the deep contract suite holding the unshared copy in place. A fix or hardening applied on the UK path does not reach the US path, and vice versa — and the drift runs toward the shared module, which three drivers now consume.
The drift is already real, not hypothetical
The extraction itself introduced one divergence: the shared _json_ready silently dropped None-valued keys from receipts, where the US original preserves them and rejects non-string keys. In an immutable audit receipt that made "explicitly null" indistinguishable from "never set". Caught in review of PR #670 and fixed by re-aligning the shared module to the US behavior — exactly the class of bug this migration exists to make structurally impossible.
Scope
- Replace the US driver's private helpers (
_StackedAttemptState,_append_phase,_git_code_pin,_local_artifact_reference,_logbook_predecessor,_input_pins_digest-adjacent digest helpers,_atomic_write_json/_json_ready,_sha256_argument, the terminal-record wrapper) with imports frommicrocosm.build.logbook_adoption, preserving the monkeypatch seams (from ... import git_code_pin as _git_code_pinkeepsbuilder._git_code_pinpatchable). - The US
_json_readyalso handles dataclasses and sets, which the shared module does not yet; fold those branches into the shared module rather than trimming US behavior. - Reconcile the
local_artifact_referencedocstring with the US original's: both must state the actual fallback ladder (checkout → home → absolute-minus-leading-slash) rather than claiming "never host-absolute" (see PR #670 review). test_us_multispine_pool_tool.pymust pass unchanged — it is the acceptance gate for this migration.
Out of scope
Behavior changes to either pipeline's rows, dispositions, or receipts.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in tools/build_us_multispine_pool.py and microcosm/build/logbook_adoption, comparing the US private helpers with the shared implementations. Run test_us_multispine_pool_tool.py first to establish the acceptance gate. Done means the US driver uses the shared helpers while preserving its monkeypatch seams, dataclass and set handling, receipt behavior, and the documented local-artifact fallback ladder; the test passes unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, testing-qa, tooling
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100