Skip to content

feat: compact the checkpoint ledger in place and raise its bounds (A5) - #39

Open
James-Chapman wants to merge 2 commits into
codex/plan-baseline-refreshfrom
codex/checkpoint-ledger-compaction
Open

James-Chapman wants to merge 2 commits into
codex/plan-baseline-refreshfrom
codex/checkpoint-ledger-compaction

Conversation

@James-Chapman

Copy link
Copy Markdown
Contributor

Summary

Phase A5: compact the checkpoint ledger in place and raise its bounds (ADR-0053). Version 0.35.0.

Stacked on codex/plan-baseline-refresh.

What changed

  • The ledger bounds rise to 65,536 records and 64 MiB. The store's total quota rises to 128 MiB.
  • New compacted and checkpoint_carried records. Replay rebuilds each carried entry through the normal transitions and requires it to be resolved. A revision floor is kept for later starts.
  • Compaction runs from the trusted file compact-checkpoints --discard-history, and automatically before an apply, restore or deletion that would not fit.
    • It is refused while any work is unresolved.
    • It writes nothing when nothing would be dropped.
  • Publishing goes through a synced ledger.compact candidate and one handle-relative rename, using the new PrivateDirectory::replace_file.
    • Linux uses renameat.
    • Windows uses a replace-if-exists rename with POSIX semantics.
    • A failure after the candidate exists is reported as uncertain, poisons the writer, and is not retried.
  • Appends are validated incrementally, and operation IDs are indexed, so replaying a full ledger takes linear time.
  • docs/filesystem-qualification.md adds a filesystem and power-loss qualification plan. The plan has not been run.
  • The file-access contract, testing standards, platform support, plan, README and CHANGELOG are updated.

Why it changed

The ledger held at most 4,096 records and 8 MiB for the lifetime of an installation. About 580 applies with deletion used up checkpoints permanently.

Tests

  • Windows: fmt and clippy are clean, and the workspace tests pass.
  • Linux (WSL, clean clone): fmt and clippy are clean, and the workspace tests pass.
  • Not run:
    • power-loss testing;
    • the filesystem qualification matrix.

Updated

  • crates/omgcode-core/src/files/replacement/tests.rs: the full-ledger padding helper now counts records incrementally, and the full-ledger test expects the trailing failed operation to be carried.
  • crates/omgcode-core/tests/replacement_records.rs, crates/omgcode-core/tests/checkpoint_storage.rs: the new bounds and record kinds.
  • crates/omgcode-cli/tests/checkpoint_lifecycle.rs: the CLI compaction workflow.
  • crates/omgcode-platform/src/broker/windows/replacement/tests.rs: replace_file on Windows.

New

  • Compaction behaviour:
    • compaction_carries_retained_state_and_drops_deleted_history
    • compaction_is_refused_while_an_operation_or_deletion_is_unresolved
    • compaction_faults_keep_a_valid_ledger_and_are_not_retried
    • a_full_ledger_is_compacted_before_apply_and_before_deletion
  • Replay and record validation:
    • a_compacted_ledger_replays_carried_state_and_keeps_the_revision_floor
    • compaction_and_carried_records_have_fixed_positions
    • carried_state_must_be_resolved_and_reachable
    • compaction_claims_have_strict_bounds
  • Storage and CLI:
    • aggregate_checkpoint_storage_refuses_before_exceeding_one_hundred_twenty_eight_mib
    • compacting_unused_storage_creates_nothing
    • compaction_drops_deleted_history_through_the_cli

🤖 Generated with Claude Code

The replacement ledger held at most 4,096 records and 8 MiB for an
installation's lifetime, so about 580 applies with deletion exhausted
checkpoints for good (Phase A5, ADR-0053).

- Raise the ledger bounds to 65,536 records and 64 MiB and the store's
  aggregate quota to 128 MiB.
- Add `compacted` and `checkpoint_carried` records. Replay rebuilds each
  carried entry through the ordinary transitions, requires it resolved,
  and keeps a revision floor for later starts.
- Compact by trusted `file compact-checkpoints --discard-history`, and
  before an apply, restore, or deletion that would not fit. Refuse while
  work is unresolved; write nothing when nothing would be dropped.
- Publish through a synced `ledger.compact` candidate and one
  handle-relative rename (`renameat` on Linux, a POSIX-semantics
  replace-if-exists rename on Windows) via a new
  `PrivateDirectory::replace_file`. Failures after the candidate exists
  are uncertain, poison the writer, and are not retried.
- Validate appends incrementally and index operation IDs so replay of a
  full ledger is linear.
- Add a filesystem and power-loss qualification plan; it has not run.
- Bump the version to 0.35.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 43 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 981f216 and ec2ebd7.

Files ignored due to path filters: 1

  • Cargo.lock is excluded by !**/*.lock
Files selected for processing: 28

  • AGENTS.md
  • CHANGELOG.md
  • Cargo.toml
  • IMPLEMENTATION_PLAN.md
  • README.md
  • crates/omgcode-cli/src/file_cli.rs
  • crates/omgcode-cli/tests/checkpoint_lifecycle.rs
  • crates/omgcode-core/src/files/checkpoint.rs
  • crates/omgcode-core/src/files/replacement/tests.rs
  • crates/omgcode-core/src/replacement.rs
  • crates/omgcode-core/src/replacement/replay.rs
  • crates/omgcode-core/src/replacement/store.rs
  • crates/omgcode-core/tests/checkpoint_storage.rs
  • crates/omgcode-core/tests/replacement_records.rs
  • crates/omgcode-platform/src/broker/windows.rs
  • crates/omgcode-platform/src/broker/windows/replacement.rs
  • crates/omgcode-platform/src/broker/windows/replacement/tests.rs
  • crates/omgcode-platform/src/private_store.rs
  • crates/omgcode-platform/src/private_store/linux.rs
  • crates/omgcode-platform/src/private_store/windows.rs
  • docs/README.md
  • docs/adr/0053-compact-the-checkpoint-ledger-in-place.md
  • docs/adr/index.md
  • docs/development.md
  • docs/file-access.md
  • docs/filesystem-qualification.md
  • docs/platform-support.md
  • docs/testing-standards.md
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@James-Chapman
James-Chapman added this pull request to stack #41 November 17, 2026 22:28
@sonarqubecloud

Copy link
Copy Markdown

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