PolicyEngine / PolicyEngine/microcosm-dynamics

Package rename populace_dynamics → microcosm_dynamics requires a design-binding repin ceremony

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

Nobody has claimed this yet.

Dominant language
Python
Stars
1
Forks
1
Avg merge
1h 46m
Merged PRs (30d)
28

Description

The 2026-08-07 product rename (Populace→Microcosm, Ledger→Chronicle) renamed this repo to microcosm-dynamics but deliberately left the code untouched (#372 has the minimal prose change). A full mechanical sweep was authored and run against the suite; results (150 failed, 44 errors) established the constraints any real rename must satisfy:

  1. Never touch the registered evidence: docs/analysis/, docs/registrations/, runs/, data/external/, scripts/*_selector_config.json, benchmarks/registry.json — all byte-frozen with content hashes and fail-closed mutation tests.
  2. "ledger" is repo vocabulary, not the product: selection_ledger_sha256, relabel_ledger, full_scenario_ledger, ref_ledger, qstar_ledger_sha256, docs/forecasts/timeline_ledger.json, estimates/ledgers.py etc. are generic bookkeeping terms inside registered keys. They stay.
  3. Design bindings pin source paths and hashes: registered artifacts embed src/populace_dynamics/... module paths and tree shas. Renaming the package directory invalidates the bindings by construction — the rename must ship WITH a repin (the amendment-ratification repin flow, cf. #371) in the same change, plus updated schema-version/artifact-id constants only where the repin re-records them.
  4. Dist name policyengine-social-security-modelmicrocosm-dynamics should ride the same repin.
  5. Prose (README ✓, qmd chapters, ADR filenames) can rename freely where not hashed; the PDF at microcosm.institute/dynamics/paper regenerates from this repo afterward.

Owner: the dynamics lane (registered-analysis protocol), not a drive-by sweep.

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 by reviewing the amendment-ratification repin flow in #371 and the recorded mechanical-sweep results. Inspect the protected paths and design bindings listed in the issue, then run the suite and mutation checks; done means the package and distribution names are updated with the same-change repin while registered evidence remains byte-frozen.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, data, testing-qa
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.