Skip to content

proposals: migrating stored IR across format versions - #171

Merged
Kinflou merged 4 commits into
mainfrom
proposals/ir-migrations
Nov 12, 2026
Merged

Kinflou merged 4 commits into
mainfrom
proposals/ir-migrations

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Accepted, decided 2026-11-13. A design for migrating the stored IR (.comline/) across format versions, so a format bump stops deleting every package's version history. Tracked in ComlineProject/core#268; relates to core#146 (reading older IR after 1.0) and core#222 (granular @unverified, which needs IR format 4).

The proposal is under docs/docs/proposals/ir-migrations/, linked from the proposals index and mkdocs.yml. Nothing is left open.

Scope: the migration system and a proof that it is sound, not migrating today's formats, which reset at 1.0 when the numbering restarts. Format 4 (core#222 chains) is the first real client.

The rule: nothing is deleted or changed without the user doing so. Migration and reset run only by comline store migrate and comline store reset; every other command stops and names them. Read commands may migrate in memory.

Pages:

  • The formats: what a store holds, a short history, the twenty additions to "format 3" made without a bump, and a written schema, frozen types, ledger and seal for every format. SCHEMA.md in core is the source.
  • Steps: a chain of total, deterministic N -> N+1 steps over frozen types, each with a down witness and an explicit, fail-closed unknown.
  • Running a migration: write beside, verify, swap, keep the backup; crash and resume; comline store migrate --check; reset; prune; a Git merge across formats is refused.
  • Proving it: the commuting square, fixtures and how they are produced, test-only formats, differential property tests, laws, and the CI gate.
  • Hashes, pins and history: old pins that verify through down are accepted with a notice; compat and the changelog recompute from stored inputs and list what is unseen.
  • Beyond the local store: other artifacts, the 1.0 refusal and reset, and the policy after 1.0.
  • Format 4 as the first client: an unpinned accept_unverified entry is re-asked via comline accept, never accepted.

Seven pages under proposals/ir-migrations: the formats and the additive
ledger, migration steps with explicit unknowns, running a migration
safely, the proof plan and CI gate, hashes, pins and history, artifacts
beyond the local store, and format 4 as the first client. Tracked in
core#268.
Kinflou added 3 commits November 13, 2026 03:52
…ts reset at 1.0

Today's formats are out of scope and reset to a backup before 1.0, with the
numbering restarting at format 0 at 1.0. Format 4 is the first real client;
test-only formats prove composition and lossy steps. Drops the per-format
fixture plans for formats 0 to 2 and the old-revs build job.
… decisions

Migration and reset run only by explicit user commands (comline store
migrate, comline store reset); other commands stop and name them. Every step
has a down witness checked at migration time. Old pins that verify are
accepted with a notice. Git merges across formats are refused. The 1.0
release refuses pre-1.0 stores, with an epoch stamp. Drops the older-binary
hazard discussion and most open questions.
@Kinflou
Kinflou marked this pull request as ready for review November 12, 2026 20:45
@Kinflou
Kinflou merged commit cb693fb into main Nov 12, 2026
8 checks passed
@Kinflou
Kinflou deleted the proposals/ir-migrations branch November 12, 2026 20:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant