Repository navigation
Define rollback compatibility for world profile journal entries #227
Description
Problem
World resource profiles are stored as a new JournalEntry::ExecutionProfile variant. New binaries can read older journals, but an older binary cannot deserialize a journal after this entry has been written. The entry is currently appended under the journal's existing header version, so an old binary may fail while reading the entry rather than rejecting the file up front.
Follow-up
Define the world-journal upgrade/rollback contract for new entry variants. Options include a versioned journal migration that atomically upgrades the header when the first new entry is written, an explicit no-downgrade policy with a reliable early refusal, or an operator-managed migration/backup workflow. Preserve read support for existing journals and ensure a failed migration cannot leave a partially rewritten journal.
This is not a blocker for forward-only upgrades, but operators must not roll back to an older binary after writing profile entries until a migration path exists.
Acceptance criteria
- A written rollback/upgrade contract for new
JournalEntryvariants exists (versioned migration, explicit no-downgrade with early refusal, or operator-managed migration/backup) and is recorded in the journal code or docs it governs. - An older binary refuses an incompatible journal early and clearly (at header/version check), not mid-read on an entry it cannot deserialize.
- Existing journals remain readable by new binaries (forward compatibility preserved).
- A failed migration cannot leave a partially rewritten journal (atomicity demonstrated by a test or a documented atomic-rename procedure).
Activity
dezren39 commentedon Oct 17, 2026
Rollback finding, from the schedule and fixture work:
dezren39 commentedon Oct 24, 2026
id train triage (2026-10-24): too-big-needs-design — journal upgrade/rollback contract for new entry variants (this is F11.12).
docs(id): Phase 14 plan — close-out: finish, measure, verify, open th…
dezren39 commentedon Oct 25, 2026
Phase 13 gate note (from the F13.1–F13.3 slice, branch
id/phase-13-impl).The Phase 13 plan says F11.12 (journal format management) must land before the first new Phase 13 frame kind, because any new frame kind is forward-only for older binaries. I checked F11.12's state on
origin/main(ff7a009):JOURNAL_VERSION = 1inJournalEntry::Created, and open refuses a journal whose version is not equal to it (pkgs/id/src/world/core.rs:145-153). The fail-loud rollback check from fix(id): refuse a complete journal line this binary cannot read #244 is there too.id world journal check,id world journal backup, and a header bump or migration when a newer entry kind is first written. The case this issue describes (ExecutionProfileappended under the v1 header) is still open..opencode/plans/2026-10-20_phase-11-status.mdlists F11.12 as Planned. The Phase 12 plan's sequencing lists it among Phase 11 work as done. These two disagree; the status tracker is right.So the Phase 13 slice adds no new frame kind. Shell contract v1 (#783) writes down only frames that already exist on main. The SSH exec transport (#784) moves the existing frames over a new envelope. SSH-over-iroh (#785) is layer-1 tunnelling. Presentation tiers, focus, kitty keys and client providers are listed as
reservedin the contract and stay behind this issue.feat(id): versioned shell contract v1 with a conformance check (F13.1)
dezren39 commentedon Oct 27, 2026
Intake review
Design/contract follow-up:
JournalEntry::ExecutionProfileentries are appended under the existing journal header version, so an older binary fails mid-read instead of refusing up front. Still live — no versioned journal migration or header gate is in place. Related merged PR #244 ("refuse a complete journal line this binary cannot read") hardens per-line refusal and may be a building block, but it does not by itself define the upgrade/rollback contract this issue asks for, so this is not closed as solved.Risks: World journals are operator state; a non-atomic migration can corrupt the only copy. Any contract must be tested against a journal written by the previous binary.
Suggested approach: Pick the contract (the early-refusal variant is smallest and matches PR #244's direction), implement the header/version gate, and add a cross-version read test with a fixture journal.
Related: PR #244 (merged, per-line refusal); world profile journal entries in pkgs/id.
Enriched by the fleet monitor (intake pass): labels normalized and acceptance criteria appended to the body. This is triage only — no work has been started.
33 remaining items
dezren39 commentedon Oct 27, 2026
🤖 Agent note · picked up (resume) — queue task 1300
Resuming from the parked checkpoint: PR #1353 is open with all checks green on the current head (
79747635, branch updated with main). This shift verifies CI fresh and merges under the standing criteria, then completes the task.Merge pull request #1353 from developing-today/queue/1300-227-journal…
dezren39 commentedon Oct 27, 2026
🤖 Agent note · done — queue task 1300
PR #1353 merged (
452d69e6, 2026-10-27T10:58:06Z) after fresh verification: all 31 PR checks pass on head79747635(incl. clippy-lint, cargo-check, all test shards, crash gates), diff is the journal-contract change only (5 files, +280/−11). Issue #227 is closed by the merge. The bump-on-first-write contract is in code with its cross-version fixture tests; local world suite was 205 passed at implementation (per PR body) and CI test shards re-verified it on the merged head.