PolicyEngine / PolicyEngine/chronicle

v2 surface migration plan: retire frozen ledger-named machine surfaces

Open
#143 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
0
Forks
1
Avg merge
11h 48m
Merged PRs (30d)
45

Description

The 2026-08-07 rename (PR #142) deliberately froze every machine surface at its v1 ledger-named form. This issue scopes the deliberate v2 migration:

  • Schema ids: ledger.bundle*.v1, ledger.build_artifact.v1, ledger.consumer_fact.v1, ledger.relational.v1, policyengine_ledger.{consumer_artifact,target_profile,resolved_target,approved_agents}.v1
  • Fact-identity hash domains (ledger.*.v2) — renaming changes every fact hash; needs an explicit identity-migration story (dual-hash window or v3 domains) coordinated with the witnessed journal
  • R2 buckets ledger-raw/ledger-derived and storage.r2 manifest keys; ledger.db artifact filename
  • Supabase schema "ledger", mirror tables/columns (ledger_builds, ledger_source_status)
  • Governance role ids (ledger-*) and concept authorities (ledger-us)
  • POLICYENGINE_LEDGER_* / LEDGER_* env names (dual-read fallback)
  • CLI ledger alias retirement after consumers migrate (María's publish flow, microcosm build scripts)
  • codex/thesis-ledger-facts branch + thesis witness machinery (Thesis session owns the canonical-URL PR)
  • thesisinstitute.org /ledger app dir + journal data paths (deferred with the witness machinery)

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 with PR #142 and inventory the listed schema ids, R2 buckets, Supabase ledger schema, environment names, CLI alias, branch, and thesis paths. Done requires an explicit fact-identity migration strategy, coordinated consumer migration, dual-read handling where noted, and retirement of the frozen ledger-named surfaces.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, supabase
Domain
backend, cli, cloud, databases, documentation
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.