PolicyEngine / PolicyEngine/microcosm

Migrate the US stacked driver onto microcosm.build.logbook_adoption

Open
#689 0 comments 0 reactions 0 assignees View on GitHub

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 from microcosm.build.logbook_adoption, preserving the monkeypatch seams (from ... import git_code_pin as _git_code_pin keeps builder._git_code_pin patchable).
  • The US _json_ready also 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_reference docstring 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.py must 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.