From 1fee38b3bb8b2b1195d025deaa3fd9919b902beb Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 19:41:01 +0000 Subject: [PATCH] feat: compact the checkpoint ledger in place and raise its bounds 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 --- AGENTS.md | 5 +- CHANGELOG.md | 43 ++ Cargo.lock | 10 +- Cargo.toml | 2 +- IMPLEMENTATION_PLAN.md | 18 +- README.md | 4 +- crates/omgcode-cli/src/file_cli.rs | 15 + .../omgcode-cli/tests/checkpoint_lifecycle.rs | 67 +++ crates/omgcode-core/src/files/checkpoint.rs | 21 +- .../src/files/replacement/tests.rs | 329 ++++++++++++- crates/omgcode-core/src/replacement.rs | 51 +- crates/omgcode-core/src/replacement/replay.rs | 460 +++++++++++++++--- crates/omgcode-core/src/replacement/store.rs | 392 +++++++++++++-- .../omgcode-core/tests/checkpoint_storage.rs | 20 +- .../omgcode-core/tests/replacement_records.rs | 261 +++++++++- crates/omgcode-platform/src/broker/windows.rs | 61 ++- .../src/broker/windows/replacement.rs | 63 +-- .../src/broker/windows/replacement/tests.rs | 1 + crates/omgcode-platform/src/private_store.rs | 4 + .../src/private_store/linux.rs | 122 ++++- .../src/private_store/windows.rs | 160 +++++- docs/README.md | 1 + ...-compact-the-checkpoint-ledger-in-place.md | 97 ++++ docs/adr/index.md | 1 + docs/development.md | 15 +- docs/file-access.md | 107 +++- docs/filesystem-qualification.md | 146 ++++++ docs/platform-support.md | 4 +- docs/testing-standards.md | 2 +- 29 files changed, 2228 insertions(+), 254 deletions(-) create mode 100644 docs/adr/0053-compact-the-checkpoint-ledger-in-place.md create mode 100644 docs/filesystem-qualification.md diff --git a/AGENTS.md b/AGENTS.md index cf5eac1..5f13932 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,7 +76,10 @@ under the file-access contract. It requires the operator to stop other writers. Windows makes no power-loss claim. Trusted CLI restore writes a retained original back through the same apply path and a new checkpoint. Trusted CLI checkpoint deletion removes one resolved checkpoint and keeps its history. -Neither is power-loss qualified. +Neither is power-loss qualified. The ledger is compacted in place, by a trusted +CLI command or before an operation that would not fit, and that discards +deleted checkpoints' history ([ADR-0053](docs/adr/0053-compact-the-checkpoint-ledger-in-place.md)). +A [filesystem qualification plan](docs/filesystem-qualification.md) has not run. Repository review and analysis are defined in [docs/repository-checks.md](docs/repository-checks.md). Do not describe planned features or security controls as implemented. Do not diff --git a/CHANGELOG.md b/CHANGELOG.md index 49262e7..8c6bf50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,49 @@ Changes are recorded here before a release version is assigned. ### Added +- Version 0.35.0 compacts the checkpoint ledger in place and raises its bounds + (Phase A5). See ADR-0053 and + [ledger compaction](docs/file-access.md#implemented-ledger-compaction-phase-a5). + Until now the ledger held at most 4,096 records and 8 MiB for an + installation's lifetime, so about 580 applies with deletion exhausted it. + It is on branch `codex/checkpoint-ledger-compaction`, stacked on + `codex/plan-baseline-refresh`; it is not merged. It adds no dependency. + - **Bounds:** the ledger may hold 65,536 records and 64 MiB, and the store's + aggregate quota grows from 64 MiB to 128 MiB. The 64-entry bound and the + 64 KiB record bound are unchanged. + - **Format:** a compacted ledger is the original `created` record, one + `compacted` record with the replaced ledger's size, SHA-256, record count, + and revision floor, and one `checkpoint_carried` record per retained entry. + Replay rebuilds each carried entry through the ordinary transitions and + requires it to be resolved. `file checkpoints` reports `compacted_from`. + Readers older than 0.35.0 refuse both new record types. + - **Triggers:** the trusted `file compact-checkpoints --discard-history` + command, and apply, restore, and deletion when the ledger lacks room for + their records. Both refuse while an operation is unresolved or a deletion + is unfinished, and write nothing when nothing would be dropped. + - **Publication:** the store replays the candidate, writes and syncs + `ledger.compact`, reads it back, checks the live ledger is unchanged, and + replaces `ledger.jsonl` with one handle-relative rename: `renameat` on + Linux and a POSIX-semantics replace-if-exists `NtSetInformationFile` + rename on Windows. It flushes the directory and reopens and compares the + ledger. A failure after the candidate exists is uncertain, poisons the + writer, and is not retried. The new `PrivateDirectory::replace_file` + performs the rename and checks that the name then refers to the source. + Neither the rename nor the flush is power-loss qualified. + - **Replay:** an append validates only its own record, and operation IDs are + indexed, so a full replay is linear in its records. + - **Deleted history:** compaction discards every record of deleted entries. + Only the replaced ledger's digest, size, and record count remain. + - **Tests:** new core tests cover carried state, refusal of unresolved work, + each compaction fault, and compaction at the record cap before apply and + before deletion. New replay tests cover the record positions, carried + state reachability, and claim bounds. New CLI tests cover the command, and + new platform tests cover the native rename on both platforms. The replay + cap tests and the aggregate quota test use the new bounds. +- A [filesystem and power-loss qualification plan](docs/filesystem-qualification.md) + defines the release filesystem matrix and the block-level and physical + power-cut campaigns for the checkpoint store and trusted publication. None of + it has run, and it changes no support claim. - A Testing build workflow (`.github/workflows/testing-build.yml`) runs on every push to `main`. It calls the Rust and Frontend workflows, builds release binaries of `omgcode` and `omgcode-desktop`, and packages them without an diff --git a/Cargo.lock b/Cargo.lock index 7eb4467..bd0bb0d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2522,7 +2522,7 @@ dependencies = [ [[package]] name = "omgcode-app" -version = "0.34.0" +version = "0.35.0" dependencies = [ "directories", "omgcode-core", @@ -2537,7 +2537,7 @@ dependencies = [ [[package]] name = "omgcode-cli" -version = "0.34.0" +version = "0.35.0" dependencies = [ "clap", "omgcode-app", @@ -2550,7 +2550,7 @@ dependencies = [ [[package]] name = "omgcode-core" -version = "0.34.0" +version = "0.35.0" dependencies = [ "libc", "omgcode-platform", @@ -2568,7 +2568,7 @@ dependencies = [ [[package]] name = "omgcode-desktop" -version = "0.34.0" +version = "0.35.0" dependencies = [ "omgcode-app", "serde", @@ -2580,7 +2580,7 @@ dependencies = [ [[package]] name = "omgcode-platform" -version = "0.34.0" +version = "0.35.0" dependencies = [ "libc", "rustix", diff --git a/Cargo.toml b/Cargo.toml index b578690..25e53e6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/omgcode-core", "crates/omgcode-cli", "crates/omgcode-platform", "crates/omgcode-app", "crates/omgcode-desktop"] [workspace.package] -version = "0.34.0" +version = "0.35.0" edition = "2024" rust-version = "1.99.1" license = "Apache-2.0" diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index 45f7cf0..e4f5f80 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -235,6 +235,13 @@ Implemented today: `file delete-checkpoint --permanent` for one resolved checkpoint, on the same filesystems as apply. Neither is power-loss qualified. See [ADR-0025](docs/adr/0025-restore-and-delete-checkpoints-explicitly.md). +- In-place checkpoint ledger compaction (0.35.0, on branch + `codex/checkpoint-ledger-compaction`, not merged): 65,536 records and + 64 MiB for the ledger, 128 MiB for the store, trusted + `file compact-checkpoints --discard-history`, and automatic compaction + before an apply, restore, or deletion that would not fit. Deleted entries' + history is discarded. Not power-loss qualified. See + [ADR-0053](docs/adr/0053-compact-the-checkpoint-ledger-in-place.md). Not implemented: @@ -763,8 +770,15 @@ at that review boundary: keeps history and frees a retained slot. Inspection and acknowledgement stay read-only. See [ADR-0025](docs/adr/0025-restore-and-delete-checkpoints-explicitly.md). - Ledger compaction, release qualification, and power-loss evidence remain - open. + Ledger compaction was left to A5; release qualification and power-loss + evidence remain open. + - **A5 (branch `codex/checkpoint-ledger-compaction`, not merged):** raise + the ledger bounds to 65,536 records and 64 MiB and the store quota to + 128 MiB, and compact the ledger in place by trusted command or before an + operation that would not fit. See + [ADR-0053](docs/adr/0053-compact-the-checkpoint-ledger-in-place.md). + The [filesystem qualification plan](docs/filesystem-qualification.md) + defines the release matrix and power-loss campaign; it has not run. Contract decisions accepted in A1: diff --git a/README.md b/README.md index 75685f1..9ddc3a5 100644 --- a/README.md +++ b/README.md @@ -159,7 +159,9 @@ Windows NTFS. Stop independent writers first: a content check and rename cannot guarantee no lost updates. Windows makes no power-loss claim. Trusted `file restore` writes a retained original back through a new checkpoint after an explicit current-content check. Trusted `file delete-checkpoint --permanent` -removes one resolved checkpoint's files and keeps its ledger history. Neither +removes one resolved checkpoint's files and keeps its ledger history until +trusted `file compact-checkpoints --discard-history`, or an apply, restore, or +deletion that would not fit, compacts the ledger. Neither command is power-loss qualified. The model edit tool uses the same checkpointed apply after an approved, writers-stopped decision; it cannot create, delete, or rename files and does not detect a concurrent writer. diff --git a/crates/omgcode-cli/src/file_cli.rs b/crates/omgcode-cli/src/file_cli.rs index f33796a..3e156c9 100644 --- a/crates/omgcode-cli/src/file_cli.rs +++ b/crates/omgcode-cli/src/file_cli.rs @@ -145,6 +145,16 @@ pub(crate) enum FileCommand { #[arg(long, required = true, action = clap::ArgAction::SetTrue)] permanent: bool, }, + /// Rewrite the checkpoint ledger in place, keeping only retained entries. + /// + /// Deleted checkpoints' history is dropped; only the replaced ledger's + /// size, digest, and record count remain. No checkpoint entry or + /// workspace file is opened or changed. + CompactCheckpoints { + /// Acknowledge that deleted checkpoints' history is discarded. + #[arg(long, required = true, action = clap::ArgAction::SetTrue)] + discard_history: bool, + }, } /// Restore output: the new operation's receipt and the checkpoint it read. @@ -353,6 +363,11 @@ pub(crate) fn run(command: FileCommand, data_root: &Path) -> Result<(), CliError .checkpoint_delete(operation_id) .map_err(file_error)?, ), + FileCommand::CompactCheckpoints { discard_history: _ } => print_json( + &FileBroker::new(&mut control) + .checkpoint_compact() + .map_err(file_error)?, + ), } } diff --git a/crates/omgcode-cli/tests/checkpoint_lifecycle.rs b/crates/omgcode-cli/tests/checkpoint_lifecycle.rs index e747e36..61de838 100644 --- a/crates/omgcode-cli/tests/checkpoint_lifecycle.rs +++ b/crates/omgcode-cli/tests/checkpoint_lifecycle.rs @@ -195,3 +195,70 @@ fn deleting_from_unused_storage_creates_nothing() { ORIGINAL ); } + +#[cfg(any(target_os = "linux", windows))] +#[test] +fn compaction_drops_deleted_history_through_the_cli() { + let fixture = Fixture::new(ORIGINAL); + let deleted = fixture.apply_bytes(PROPOSED); + let retained = fixture.apply_bytes(ORIGINAL); + assert_success(&run_cli( + &fixture.data, + &["file", "delete-checkpoint", &deleted, "--permanent"], + )); + let ledger = fixture.data.join("replacement-v1").join("ledger.jsonl"); + let before = fs::read(&ledger).expect("ledger"); + + let output = run_cli(&fixture.data, &["file", "compact-checkpoints"]); + assert!(!output.status.success(), "missing acknowledgement accepted"); + assert!(String::from_utf8_lossy(&output.stderr).contains("--discard-history")); + assert_eq!(fs::read(&ledger).expect("unchanged ledger"), before); + + let output = run_cli( + &fixture.data, + &["file", "compact-checkpoints", "--discard-history"], + ); + assert_success(&output); + let result = json_output(&output); + assert_eq!(result["compacted"], true); + assert_eq!(result["carried"], 1); + assert_eq!(result["dropped"], 1); + assert_eq!(result["previous_bytes"], before.len()); + assert_eq!(result["records"], 3); + + let output = run_cli(&fixture.data, &["file", "checkpoints"]); + assert_success(&output); + let view = json_output(&output); + let operations = view["operations"].as_array().expect("operations"); + assert_eq!(operations.len(), 1); + assert_eq!(operations[0]["operation_id"], retained.as_str()); + assert_eq!(operations[0]["retention"], "retained"); + assert_eq!( + view["compacted_from"]["records"], + result["previous_records"] + ); + assert_eq!(view["compacted_from"]["ledger"]["bytes"], before.len()); + + let output = run_cli( + &fixture.data, + &["file", "compact-checkpoints", "--discard-history"], + ); + assert_success(&output); + assert_eq!(json_output(&output)["compacted"], false); + assert_eq!( + fs::read(fixture.workspace.join("note.txt")).expect("target untouched"), + ORIGINAL + ); +} + +#[test] +fn compacting_unused_storage_creates_nothing() { + let fixture = Fixture::new(ORIGINAL); + let output = run_cli( + &fixture.data, + &["file", "compact-checkpoints", "--discard-history"], + ); + assert_error_code(&output, "checkpoint_unavailable"); + assert!(!fixture.data.join("replacement-v1").exists()); + assert!(!fixture.data.join("replacement-init-v1.jsonl").exists()); +} diff --git a/crates/omgcode-core/src/files/checkpoint.rs b/crates/omgcode-core/src/files/checkpoint.rs index 158bf5a..553141e 100644 --- a/crates/omgcode-core/src/files/checkpoint.rs +++ b/crates/omgcode-core/src/files/checkpoint.rs @@ -7,7 +7,8 @@ use super::{FileBroker, FileError, FileOperation, FileOutcome, FileTarget, valid use crate::policy::{Operation, PolicyRequest, SessionBinding}; use crate::replacement::store::{self, Store}; use crate::replacement::{ - CheckpointDeletion, CheckpointError, CheckpointInspection, CheckpointReceipt, RecordedArtifact, + CheckpointCompaction, CheckpointDeletion, CheckpointError, CheckpointInspection, + CheckpointReceipt, RecordedArtifact, }; use crate::session::sha256_hex; @@ -21,7 +22,9 @@ impl FileBroker<'_> { /// not an apply token. No payload bytes appear in the returned receipt. /// /// Each payload is at most 1 MiB. Storage retains at most 64 intents and - /// 64 MiB of managed file bytes, with capacity reserved before artifacts. + /// 128 MiB of managed file bytes, with capacity reserved before artifacts. + /// A ledger without room for the operation is compacted in place first, + /// which drops deleted entries' history (ADR-0053). /// A write or sync error can leave uncertain private evidence. Reopen for /// inspection; do not automatically retry or remove that evidence. pub fn checkpoint_prepare( @@ -98,6 +101,20 @@ impl FileBroker<'_> { ) -> Result { Ok(store::delete(self.control, operation_id)?) } + + /// Rewrite the checkpoint ledger in place, dropping deleted entries' history. + /// + /// This is a trusted operator action, not a model tool route. It needs no + /// workspace binding and opens no workspace file or checkpoint entry. + /// Retained entries keep their recorded state as one carried record each; + /// only the replaced ledger's size, digest, and record count remain of the + /// rest. It is refused while an operation is unresolved or a deletion is + /// unfinished, and writes nothing when the ledger would not shrink. A + /// failure during the rewrite is uncertain; reopen to inspect, and do not + /// retry automatically. + pub fn checkpoint_compact(&mut self) -> Result { + Ok(store::compact(self.control)?) + } } /// Require both permissions from the same live binding while control is locked. diff --git a/crates/omgcode-core/src/files/replacement/tests.rs b/crates/omgcode-core/src/files/replacement/tests.rs index f16cd13..ccbe768 100644 --- a/crates/omgcode-core/src/files/replacement/tests.rs +++ b/crates/omgcode-core/src/files/replacement/tests.rs @@ -7,8 +7,9 @@ use super::*; use crate::control::ControlStore; use crate::policy::{PermissionSet, SessionBinding, WorkspaceId}; use crate::replacement::{ - CheckpointDeletion, CheckpointError, CheckpointInspection, CheckpointRetention, - RecordedArtifact, ReplacementOutcome, ReplacementProgress, + CheckpointCompaction, CheckpointDeletion, CheckpointError, CheckpointInspection, + CheckpointRetention, RecordedArtifact, RecordedReplacement, ReplacementOutcome, + ReplacementProgress, }; use sha2::{Digest, Sha256}; use tempfile::TempDir; @@ -1018,3 +1019,327 @@ fn deletion_never_removes_an_unknown_name() { assert_eq!(fs::read(&unexpected).unwrap(), b"operator data"); assert!(fixture.inspect().is_err()); } + +fn compact(fixture: &mut Fixture) -> Result { + FileBroker::new(&mut fixture.control).checkpoint_compact() +} + +fn ledger_path(fixture: &Fixture) -> PathBuf { + fixture.data.join("replacement-v1").join("ledger.jsonl") +} + +fn candidate_path(fixture: &Fixture) -> PathBuf { + fixture.data.join("replacement-v1").join("ledger.compact") +} + +fn record_count(bytes: &[u8]) -> usize { + bytes.iter().filter(|byte| **byte == b'\n').count() +} + +fn retained_operations(inspection: &CheckpointInspection) -> Vec { + inspection + .operations + .iter() + .filter(|operation| operation.retention == CheckpointRetention::Retained) + .cloned() + .collect() +} + +/// Leave one retained entry and one deleted entry's history. The source ends +/// with its original bytes. +fn retained_and_deleted(fixture: &mut Fixture) -> (Uuid, Uuid) { + let retained = applied_id(fixture, ORIGINAL, PROPOSED); + let deleted = applied_id(fixture, PROPOSED, ORIGINAL); + delete(fixture, deleted).expect("delete one entry"); + (retained, deleted) +} + +/// Writes synthesized ledger records with the store's scope and sequence. +struct Padding { + header: serde_json::Value, + revision: u64, + workspace_id: Uuid, + bytes: Vec, + /// Records in `bytes`, counted as they are pushed. + records: usize, +} + +impl Padding { + fn push(&mut self, kind: &str, payload: serde_json::Value) { + let record = serde_json::json!({ + "schema_version": 1, + "control_store_id": self.header["control_store_id"], + "replacement_store_id": self.header["replacement_store_id"], + "event_id": Uuid::new_v4(), + "sequence": self.records, + "timestamp": "2026-11-17T12:00:00Z", + "action": {"type": kind, "payload": payload}, + }); + serde_json::to_writer(&mut self.bytes, &record).expect("record JSON"); + self.bytes.push(b'\n'); + self.records += 1; + } + + /// Record one operation that failed before preparing an entry. + fn failed(&mut self) -> Uuid { + let operation_id = Uuid::new_v4(); + self.push( + "replacement_started", + serde_json::json!({ + "operation_id": operation_id, + "session_id": Uuid::new_v4(), + "workspace_id": self.workspace_id, + "revision": self.revision, + "target": crate::session::NativePath::from_path(Path::new("padding.txt")) + .expect("native target"), + "expected": {"bytes": 1, "sha256": "a".repeat(64)}, + "proposed": {"bytes": 1, "sha256": "b".repeat(64)}, + "artifacts": { + "original": "original", "proposed": "proposed", + "manifest": "manifest.json", "stage": "stage" + } + }), + ); + self.push( + "replacement_finished", + serde_json::json!({ + "operation_id": operation_id, "outcome": "failed", "code": "padding" + }), + ); + operation_id + } +} + +/// Append deleted operations, four records each, then at most one failed +/// operation without an entry, until the ledger holds at least `minimum` +/// records. Real failures and deletions write these same records. Returns the +/// failed operation, which stays retained and is carried by compaction. +fn pad_ledger(fixture: &Fixture, minimum: usize) -> Option { + let path = ledger_path(fixture); + let bytes = fs::read(&path).expect("ledger"); + let header = serde_json::from_slice( + bytes + .split_inclusive(|byte| *byte == b'\n') + .next() + .expect("header record"), + ) + .expect("header JSON"); + let mut padding = Padding { + header, + revision: fixture.control.revision(), + workspace_id: *fixture.workspace_id.as_uuid(), + records: record_count(&bytes), + bytes, + }; + while padding.records + 4 <= minimum { + let operation_id = padding.failed(); + padding.push( + "checkpoint_deletion_started", + serde_json::json!({"operation_id": operation_id}), + ); + padding.push( + "checkpoint_deleted", + serde_json::json!({"operation_id": operation_id}), + ); + } + let failed = (padding.records < minimum).then(|| padding.failed()); + fs::write(&path, padding.bytes).expect("write padded ledger"); + failed +} + +#[test] +fn compaction_carries_retained_state_and_drops_deleted_history() { + let mut fixture = Fixture::new(); + let (retained, deleted) = retained_and_deleted(&mut fixture); + let before = fixture.inspect().expect("inspect"); + let old = fs::read(ledger_path(&fixture)).expect("ledger"); + let header = old + .split_inclusive(|byte| *byte == b'\n') + .next() + .expect("header") + .to_vec(); + + let result = compact(&mut fixture).expect("compact"); + assert!(result.compacted); + assert_eq!((result.carried, result.dropped), (1, 1)); + assert_eq!(result.previous_records, record_count(&old)); + assert_eq!(result.previous_bytes, old.len()); + let new = fs::read(ledger_path(&fixture)).expect("compacted ledger"); + assert_eq!(result.records, 3); + assert_eq!(record_count(&new), 3); + assert_eq!(result.bytes, new.len()); + assert!(new.len() < old.len()); + assert!( + new.starts_with(&header), + "the header record is kept exactly" + ); + assert!(!candidate_path(&fixture).exists()); + + let after = fixture.inspect().expect("inspect compacted ledger"); + assert_eq!(after.operations, retained_operations(&before)); + assert!( + after + .operations + .iter() + .all(|entry| entry.operation_id != deleted) + ); + let compacted_from = after.compacted_from.clone().expect("compaction recorded"); + assert_eq!(compacted_from.ledger, artifact(&old)); + assert_eq!( + compacted_from.records, + u64::try_from(record_count(&old)).unwrap() + ); + assert_eq!(after.managed_bytes, result.managed_bytes); + assert_payloads(&fixture, retained); + + // Nothing is left to drop, so a second request writes nothing. + let again = compact(&mut fixture).expect("compact again"); + assert!(!again.compacted); + assert_eq!(fs::read(ledger_path(&fixture)).unwrap(), new); + + // New work appends after the carried record, and a carried entry + // restores and deletes like any other. + let target = fixture.workspace.join("source.txt"); + let applied = applied_id(&mut fixture, ORIGINAL, PROPOSED); + restore(&mut fixture, retained, PROPOSED).expect("restore a carried entry"); + assert_eq!(fs::read(&target).unwrap(), ORIGINAL); + delete(&mut fixture, retained).expect("delete a carried entry"); + let chained_from = fs::read(ledger_path(&fixture)).expect("ledger"); + let chained = compact(&mut fixture).expect("compact a compacted ledger"); + assert!(chained.compacted); + assert_eq!(chained.dropped, 1); + let inspection = fixture.inspect().expect("inspect"); + assert_eq!( + inspection.compacted_from.clone().expect("chained").ledger, + artifact(&chained_from) + ); + assert_eq!( + operation(&inspection, applied).retention, + CheckpointRetention::Retained + ); + assert_eq!(inspection.operations.len(), 2); +} + +#[test] +fn compaction_is_refused_while_an_operation_or_deletion_is_unresolved() { + let mut fixture = Fixture::new(); + let binding = fixture.binding(); + let pending = uncertain_id(fixture.apply(&binding, |store| { + store.inject_publication_fault("commit_intent_sync"); + })); + let ledger = fs::read(ledger_path(&fixture)).expect("ledger"); + assert_eq!( + checkpoint_error(compact(&mut fixture)).code(), + "checkpoint_pending" + ); + assert_eq!(fs::read(ledger_path(&fixture)).unwrap(), ledger); + FileBroker::new(&mut fixture.control) + .checkpoint_acknowledge(pending) + .expect("acknowledge"); + + let id = applied_id(&mut fixture, ORIGINAL, PROPOSED); + crate::replacement::store::delete_with_fault(&fixture.control, id, "deletion_artifact") + .expect_err("interrupted deletion"); + let ledger = fs::read(ledger_path(&fixture)).expect("ledger"); + assert_eq!( + checkpoint_error(compact(&mut fixture)).code(), + "checkpoint_deletion_pending" + ); + assert_eq!(fs::read(ledger_path(&fixture)).unwrap(), ledger); + assert!(!candidate_path(&fixture).exists()); +} + +#[test] +fn compaction_faults_keep_a_valid_ledger_and_are_not_retried() { + for (fault, replaced) in [ + ("compaction_partial_write", false), + ("compaction_sync", false), + ("compaction_rename", false), + ("compaction_directory_sync", true), + ] { + let mut fixture = Fixture::new(); + let (retained, _) = retained_and_deleted(&mut fixture); + let before = fixture.inspect().expect("inspect"); + let old = fs::read(ledger_path(&fixture)).expect("ledger"); + + let error = crate::replacement::store::compact_with_fault(&fixture.control, fault) + .expect_err(fault); + assert_eq!(error.code(), "checkpoint_uncertain", "{fault}"); + // Either ledger reopens with the same retained state. + let after = fixture.inspect().expect(fault); + assert_eq!( + retained_operations(&after), + retained_operations(&before), + "{fault}" + ); + assert_eq!(after.compacted_from.is_some(), replaced, "{fault}"); + assert_eq!( + fs::read(ledger_path(&fixture)).unwrap() == old, + !replaced, + "{fault}" + ); + assert_eq!(candidate_path(&fixture).exists(), !replaced, "{fault}"); + + // Ordinary work continues beside a stale candidate, which only a + // later explicit compaction removes. + applied_id(&mut fixture, ORIGINAL, PROPOSED); + assert_eq!(candidate_path(&fixture).exists(), !replaced, "{fault}"); + let result = compact(&mut fixture).expect(fault); + assert!(result.compacted, "{fault}"); + assert!(!candidate_path(&fixture).exists(), "{fault}"); + assert_payloads(&fixture, retained); + } +} + +#[test] +fn a_full_ledger_is_compacted_before_apply_and_before_deletion() { + // The record bound in `replacement::replay`. + const MAX_RECORDS: usize = 65_536; + let mut fixture = Fixture::new(); + let (retained, _) = retained_and_deleted(&mut fixture); + + // Apply needs six more records and deletion two. + let failed = pad_ledger(&fixture, MAX_RECORDS - 5); + let padded = fs::read(ledger_path(&fixture)).expect("padded ledger"); + assert!((MAX_RECORDS - 5..=MAX_RECORDS).contains(&record_count(&padded))); + let inspection = fixture.inspect().expect("a padded ledger is valid"); + assert!(inspection.operations.len() > 16_000); + + let applied = applied_id(&mut fixture, ORIGINAL, PROPOSED); + let inspection = fixture.inspect().expect("inspect"); + let compacted_from = inspection.compacted_from.clone().expect("compacted first"); + assert_eq!(compacted_from.ledger, artifact(&padded)); + let mut kept = inspection + .operations + .iter() + .map(|entry| entry.operation_id) + .collect::>(); + kept.sort(); + let mut expected = vec![retained, applied]; + expected.extend(failed); + expected.sort(); + assert_eq!(kept, expected); + assert!(record_count(&fs::read(ledger_path(&fixture)).unwrap()) < 16); + + pad_ledger(&fixture, MAX_RECORDS - 1); + let padded = fs::read(ledger_path(&fixture)).expect("padded ledger"); + delete(&mut fixture, retained).expect("deletion compacts first"); + let inspection = fixture.inspect().expect("inspect"); + assert_eq!( + inspection + .compacted_from + .clone() + .expect("compacted again") + .ledger, + artifact(&padded) + ); + assert_eq!( + operation(&inspection, retained).retention, + CheckpointRetention::Deleted + ); + assert_eq!( + operation(&inspection, applied).retention, + CheckpointRetention::Retained + ); + assert!(!fixture.operation_dir(retained).exists()); +} diff --git a/crates/omgcode-core/src/replacement.rs b/crates/omgcode-core/src/replacement.rs index 4e6c157..1c608e4 100644 --- a/crates/omgcode-core/src/replacement.rs +++ b/crates/omgcode-core/src/replacement.rs @@ -10,10 +10,12 @@ mod manifest; mod replay; pub(crate) mod store; pub use store::{ - CheckpointDeletion, CheckpointError, CheckpointInspection, CheckpointReceipt, CheckpointState, - ReplacementReceipt, + CheckpointCompaction, CheckpointDeletion, CheckpointError, CheckpointInspection, + CheckpointReceipt, CheckpointState, ReplacementReceipt, }; +use std::collections::{HashMap, HashSet}; + use serde::{Deserialize, Serialize}; use thiserror::Error; use uuid::Uuid; @@ -90,7 +92,7 @@ pub struct InitializationSnapshot { } /// Furthest recorded preparation/commit step. This is historical evidence only. -#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)] +#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)] #[serde(rename_all = "snake_case")] pub enum ReplacementProgress { /// Intent exists; no prepared checkpoint has been recorded. @@ -185,20 +187,47 @@ pub struct RecordedReplacement { pub retention: CheckpointRetention, } +/// The ledger that an in-place compaction replaced. Its records are gone; +/// this claim alone cannot reproduce or verify them. +#[derive(Clone, Debug, Eq, PartialEq, Serialize)] +pub struct RecordedCompaction { + /// Claimed exact size and SHA-256 of the replaced ledger. + pub ledger: RecordedArtifact, + /// Claimed number of records in the replaced ledger. + pub records: u64, +} + /// Fully validated in-memory ledger evidence. No filesystem work is performed. #[derive(Clone, Debug, Eq, PartialEq)] pub struct ReplacementSnapshot { /// Expected store identities, matched by every record. pub scope: ReplacementScope, - /// All recorded operations in order, including deleted entries' history. - /// No history is evicted; at most 64 operations are not yet deleted. + /// Recorded operations in order, including deleted entries' history since + /// the last compaction. Compaction keeps only retained entries, as one + /// carried record each; at most 64 operations are not yet deleted. pub operations: Vec, + /// The replaced ledger, when this ledger was compacted in place. + pub compaction: Option, /// Number of complete accepted records, including the header. pub event_count: usize, /// Exact supplied byte count, including record delimiters. pub encoded_bytes: usize, pending_operation_id: Option, pending_deletion_id: Option, + /// Revision of the last started operation, or the floor a compaction + /// carried. A later start must not record a lower revision. + revision_floor: Option, + /// Revision of the last carried operation, for their own order. + carried_revision: Option, + /// Whether the previous record was a compaction or carried record. + carrying: bool, + /// Every accepted event ID, so one appended record validates alone. + event_ids: HashSet, + /// Index of each recorded operation ID in `operations`. Replay of a + /// 65,536-record ledger must not scan the history for every record. + positions: HashMap, + /// Operations whose entries are not deleted, at most 64. + not_deleted: usize, } impl ReplacementSnapshot { @@ -214,9 +243,11 @@ impl ReplacementSnapshot { } fn find(&self, id: Uuid) -> Option<&RecordedReplacement> { - self.operations - .iter() - .find(|operation| operation.operation_id == id) + self.operations.get(self.position(id)?) + } + + fn position(&self, id: Uuid) -> Option { + self.positions.get(&id).copied() } } @@ -256,8 +287,8 @@ pub fn inspect_initialization( /// Validate a complete bounded ledger and preserve every unfinished operation. /// -/// Limits are 8 MiB, 4,096 records, 64 KiB per record including its delimiter, -/// and 64 operation IDs whose entries are not deleted. Duplicate JSON keys and unknown fields fail. +/// Limits are 64 MiB, 65,536 records, 64 KiB per record including its +/// delimiter, and 64 operation IDs whose entries are not deleted. Duplicate JSON keys and unknown fields fail. /// Targets must use this OS's native encoding and broker-relative path syntax. /// This function validates only recorded claims, not checkpoint files, native /// identities, current policy, aggregate disk quota, durability, or authority. diff --git a/crates/omgcode-core/src/replacement/replay.rs b/crates/omgcode-core/src/replacement/replay.rs index 84f72eb..ee597e0 100644 --- a/crates/omgcode-core/src/replacement/replay.rs +++ b/crates/omgcode-core/src/replacement/replay.rs @@ -1,6 +1,6 @@ //! Strict bounded decoding and historical state transitions; no filesystem I/O. -use std::collections::HashSet; +use std::collections::{HashMap, HashSet}; use omgcode_platform::broker::RelativePath; use serde::de::DeserializeOwned; @@ -11,17 +11,19 @@ use uuid::{Uuid, Variant, Version}; use super::{ CheckpointRetention, InitializationPhase, InitializationSnapshot, RecordedArtifact, - RecordedFileIdentity, RecordedReplacement, ReplacementError, ReplacementOutcome, - ReplacementProgress, ReplacementScope, ReplacementSnapshot, + RecordedCompaction, RecordedFileIdentity, RecordedReplacement, ReplacementError, + ReplacementOutcome, ReplacementProgress, ReplacementScope, ReplacementSnapshot, }; use crate::policy::WorkspaceId; use crate::session::NativePath; use crate::storage::parse_strict_json; -const MAX_LEDGER_BYTES: usize = 8 * 1024 * 1024; -const MAX_RECORD_BYTES: usize = 64 * 1024; -const MAX_LEDGER_RECORDS: usize = 4096; -const MAX_OPERATIONS: usize = 64; +/// Whole-ledger byte bound. Raised from 8 MiB in 0.35.0 (ADR-0053). +pub(super) const MAX_LEDGER_BYTES: usize = 64 * 1024 * 1024; +pub(super) const MAX_RECORD_BYTES: usize = 64 * 1024; +/// Whole-ledger record bound. Raised from 4,096 in 0.35.0 (ADR-0053). +pub(super) const MAX_LEDGER_RECORDS: usize = 65_536; +pub(super) const MAX_OPERATIONS: usize = 64; const MAX_PAYLOAD_BYTES: u64 = 1024 * 1024; const MAX_MANIFEST_BYTES: u64 = 64 * 1024; @@ -105,6 +107,41 @@ pub(super) enum LedgerAction { CheckpointDeleted { operation_id: Uuid, }, + /// The ledger was rewritten in place. Only the second record may be one. + /// Older readers refuse it. + Compacted { + previous: RecordedArtifact, + previous_records: u64, + revision_floor: Option, + }, + /// One retained, resolved operation's whole recorded state, carried by a + /// compaction. It follows the compaction record or another carried record. + CheckpointCarried { + operation_id: Uuid, + session_id: Uuid, + workspace_id: Uuid, + revision: u64, + target: NativePath, + expected: RecordedArtifact, + proposed: RecordedArtifact, + manifest: Option, + stage_identity: Option, + progress: ReplacementProgress, + outcome: Option, + code: Option, + acknowledged: bool, + }, +} + +/// The recorded fields that start an operation, whether new or carried. +struct Started { + operation_id: Uuid, + session_id: Uuid, + workspace_id: Uuid, + revision: u64, + target: NativePath, + expected: RecordedArtifact, + proposed: RecordedArtifact, } /// Check framing and all byte/count bounds before parsing or allocating JSON. @@ -225,34 +262,101 @@ pub(super) fn ledger( let mut snapshot = ReplacementSnapshot { scope, operations: Vec::new(), + compaction: None, event_count: 0, - encoded_bytes: bytes.len(), + encoded_bytes: 0, pending_operation_id: None, pending_deletion_id: None, + revision_floor: None, + carried_revision: None, + carrying: false, + event_ids: HashSet::new(), + positions: HashMap::new(), + not_deleted: 0, }; - let mut event_ids = HashSet::new(); - for (index, line) in records( + for line in records( bytes, MAX_LEDGER_BYTES, MAX_LEDGER_RECORDS, MAX_RECORD_BYTES, - )? - .enumerate() + )? { + push(&mut snapshot, line)?; + } + Ok(snapshot) +} + +/// Validate one more record against a validated ledger, leaving it unchanged. +/// +/// The result equals replaying the whole ledger with `line` appended: the +/// same framing, bounds, and transitions apply, without parsing earlier +/// records again. +pub(super) fn extend( + snapshot: &ReplacementSnapshot, + line: &[u8], +) -> Result { + if snapshot + .encoded_bytes + .checked_add(line.len()) + .is_none_or(|total| total > MAX_LEDGER_BYTES) { - let entry: Envelope = decode(line)?; - validate_envelope(&entry, index, scope)?; - if !event_ids.insert(entry.event_id) { - return Err(ReplacementError::Invalid("duplicate event ID")); + return Err(ReplacementError::Limit("total bytes")); + } + if snapshot.event_count >= MAX_LEDGER_RECORDS { + return Err(ReplacementError::Limit("record count")); + } + if line.len() > MAX_RECORD_BYTES { + return Err(ReplacementError::Limit("record bytes")); + } + match line.split_last() { + Some((b'\n', body)) if !body.contains(&b'\n') => {} + _ => { + return Err(ReplacementError::Invalid( + "record is not one complete JSONL line", + )); } - if (index == 0) != matches!(entry.action, LedgerAction::Created) { + } + if line.iter().all(u8::is_ascii_whitespace) { + return Err(ReplacementError::Invalid("blank JSONL record")); + } + let mut next = snapshot.clone(); + push(&mut next, line)?; + Ok(next) +} + +/// Decode one framed record and apply it at the next sequence number. +fn push(snapshot: &mut ReplacementSnapshot, line: &[u8]) -> Result<(), ReplacementError> { + let index = snapshot.event_count; + let entry: Envelope = decode(line)?; + validate_envelope(&entry, index, snapshot.scope)?; + if !snapshot.event_ids.insert(entry.event_id) { + return Err(ReplacementError::Invalid("duplicate event ID")); + } + if (index == 0) != matches!(entry.action, LedgerAction::Created) { + return Err(ReplacementError::Invalid( + "created record must occur exactly first", + )); + } + if index != 1 && matches!(entry.action, LedgerAction::Compacted { .. }) { + return Err(ReplacementError::Invalid( + "a compaction record must be the second record", + )); + } + if matches!(entry.action, LedgerAction::CheckpointCarried { .. }) { + if !snapshot.carrying { return Err(ReplacementError::Invalid( - "created record must occur exactly first", + "a carried operation must follow the compaction record", )); } - apply(&mut snapshot, entry.action)?; - snapshot.event_count = index + 1; + } else { + snapshot.carrying = false; } - Ok(snapshot) + apply(snapshot, entry.action)?; + snapshot.event_count = index + 1; + snapshot.encoded_bytes = snapshot + .encoded_bytes + .checked_add(line.len()) + .ok_or(ReplacementError::Limit("total bytes"))?; + Ok(()) } fn validate_artifact( @@ -321,37 +425,6 @@ fn apply(snapshot: &mut ReplacementSnapshot, action: LedgerAction) -> Result<(), proposed, artifacts, } => { - validate_uuid(operation_id)?; - validate_uuid(session_id)?; - validate_uuid(workspace_id)?; - if snapshot.pending_operation_id.is_some() - || snapshot.pending_deletion_id.is_some() - || snapshot - .operations - .iter() - .any(|operation| operation.operation_id == operation_id) - { - return Err(ReplacementError::Invalid("parallel or reused operation ID")); - } - if snapshot - .operations - .iter() - .filter(|operation| operation.retention != CheckpointRetention::Deleted) - .count() - >= MAX_OPERATIONS - { - return Err(ReplacementError::Limit("retained operations")); - } - if snapshot - .operations - .last() - .is_some_and(|operation| revision < operation.revision) - { - return Err(ReplacementError::Invalid("policy revision moved backwards")); - } - validate_target(&target)?; - validate_artifact(&expected, MAX_PAYLOAD_BYTES, true)?; - validate_artifact(&proposed, MAX_PAYLOAD_BYTES, true)?; if artifacts.original != "original" || artifacts.proposed != "proposed" || artifacts.manifest != "manifest.json" @@ -361,25 +434,19 @@ fn apply(snapshot: &mut ReplacementSnapshot, action: LedgerAction) -> Result<(), "artifact names do not match the fixed private layout", )); } - let workspace_id = WorkspaceId::from_uuid(workspace_id) - .map_err(|_| ReplacementError::Invalid("invalid workspace ID"))?; - snapshot.operations.push(RecordedReplacement { - operation_id, - session_id, - workspace_id, - revision, - target, - expected, - proposed, - manifest: None, - stage_identity: None, - progress: ReplacementProgress::Intent, - outcome: None, - code: None, - acknowledged: false, - retention: CheckpointRetention::Retained, - }); - snapshot.pending_operation_id = Some(operation_id); + start( + snapshot, + Started { + operation_id, + session_id, + workspace_id, + revision, + target, + expected, + proposed, + }, + false, + )?; } LedgerAction::CheckpointPrepared { operation_id, @@ -474,9 +541,8 @@ fn apply(snapshot: &mut ReplacementSnapshot, action: LedgerAction) -> Result<(), )); } let operation = snapshot - .operations - .iter_mut() - .find(|operation| operation.operation_id == operation_id) + .position(operation_id) + .and_then(|index| snapshot.operations.get_mut(index)) .ok_or(ReplacementError::Invalid( "deletion names no recorded operation", ))?; @@ -495,13 +561,253 @@ fn apply(snapshot: &mut ReplacementSnapshot, action: LedgerAction) -> Result<(), )); } let operation = snapshot - .operations - .iter_mut() - .find(|operation| operation.operation_id == operation_id) + .position(operation_id) + .and_then(|index| snapshot.operations.get_mut(index)) .ok_or(ReplacementError::Invalid("missing deleted operation"))?; operation.retention = CheckpointRetention::Deleted; snapshot.pending_deletion_id = None; + snapshot.not_deleted = snapshot + .not_deleted + .checked_sub(1) + .ok_or(ReplacementError::Invalid("deleted count exceeds history"))?; + } + LedgerAction::Compacted { + previous, + previous_records, + revision_floor, + } => { + let maximum = u64::try_from(MAX_LEDGER_BYTES) + .map_err(|_| ReplacementError::Limit("total bytes"))?; + validate_artifact(&previous, maximum, false)?; + if previous_records == 0 + || usize::try_from(previous_records) + .map_or(true, |count| count > MAX_LEDGER_RECORDS) + { + return Err(ReplacementError::Invalid( + "compacted record count is outside its bound", + )); + } + snapshot.compaction = Some(RecordedCompaction { + ledger: previous, + records: previous_records, + }); + snapshot.revision_floor = revision_floor; + snapshot.carrying = true; + } + LedgerAction::CheckpointCarried { + operation_id, + session_id, + workspace_id, + revision, + target, + expected, + proposed, + manifest, + stage_identity, + progress, + outcome, + code, + acknowledged, + } => carry( + snapshot, + Started { + operation_id, + session_id, + workspace_id, + revision, + target, + expected, + proposed, + }, + Carried { + manifest, + stage_identity, + progress, + outcome, + code, + acknowledged, + }, + )?, + } + Ok(()) +} + +/// The recorded state a carried operation reached after it started. +struct Carried { + manifest: Option, + stage_identity: Option, + progress: ReplacementProgress, + outcome: Option, + code: Option, + acknowledged: bool, +} + +/// Rebuild one carried operation through the same transitions that its +/// original records made, so a carried state can only be one those records +/// could reach. The result must be resolved. Carried revisions keep their +/// recorded order and never exceed the compaction's floor. +fn carry( + snapshot: &mut ReplacementSnapshot, + started: Started, + carried: Carried, +) -> Result<(), ReplacementError> { + let operation_id = started.operation_id; + let revision = started.revision; + if snapshot.revision_floor.is_none_or(|floor| revision > floor) + || snapshot + .carried_revision + .is_some_and(|last| revision < last) + { + return Err(ReplacementError::Invalid( + "carried revision is out of order or above the floor", + )); + } + let content = started.proposed.clone(); + start(snapshot, started, true)?; + let Carried { + manifest, + stage_identity, + progress, + outcome, + code, + acknowledged, + } = carried; + let prepared = progress != ReplacementProgress::Intent; + let staged = matches!( + progress, + ReplacementProgress::StagePrepared | ReplacementProgress::CommitIntended + ); + match (prepared, manifest) { + (true, Some(manifest)) => apply( + snapshot, + LedgerAction::CheckpointPrepared { + operation_id, + manifest, + }, + )?, + (false, None) => {} + _ => { + return Err(ReplacementError::Invalid( + "carried manifest does not match its progress", + )); + } + } + match (staged, stage_identity) { + (true, Some(identity)) => apply( + snapshot, + LedgerAction::StagePrepared { + operation_id, + identity, + content, + }, + )?, + (false, None) => {} + _ => { + return Err(ReplacementError::Invalid( + "carried stage does not match its progress", + )); } } + if progress == ReplacementProgress::CommitIntended { + apply(snapshot, LedgerAction::CommitIntended { operation_id })?; + } + match outcome { + Some(outcome) => apply( + snapshot, + LedgerAction::ReplacementFinished { + operation_id, + outcome, + code, + }, + )?, + None if code.is_none() => {} + None => { + return Err(ReplacementError::Invalid( + "carried machine code has no outcome", + )); + } + } + if acknowledged { + apply( + snapshot, + LedgerAction::ReplacementAcknowledged { operation_id }, + )?; + } + if snapshot.pending_operation_id.is_some() { + return Err(ReplacementError::Invalid( + "a carried operation must be resolved", + )); + } + snapshot.carried_revision = Some(revision); + Ok(()) +} + +/// Record a new or carried operation. A new start must not lower the +/// revision floor and raises it; carried revisions follow their own rule. +fn start( + snapshot: &mut ReplacementSnapshot, + started: Started, + carried: bool, +) -> Result<(), ReplacementError> { + let Started { + operation_id, + session_id, + workspace_id, + revision, + target, + expected, + proposed, + } = started; + validate_uuid(operation_id)?; + validate_uuid(session_id)?; + validate_uuid(workspace_id)?; + if snapshot.pending_operation_id.is_some() + || snapshot.pending_deletion_id.is_some() + || snapshot.positions.contains_key(&operation_id) + { + return Err(ReplacementError::Invalid("parallel or reused operation ID")); + } + if snapshot.not_deleted >= MAX_OPERATIONS { + return Err(ReplacementError::Limit("retained operations")); + } + if !carried + && snapshot + .revision_floor + .is_some_and(|floor| revision < floor) + { + return Err(ReplacementError::Invalid("policy revision moved backwards")); + } + validate_target(&target)?; + validate_artifact(&expected, MAX_PAYLOAD_BYTES, true)?; + validate_artifact(&proposed, MAX_PAYLOAD_BYTES, true)?; + let workspace_id = WorkspaceId::from_uuid(workspace_id) + .map_err(|_| ReplacementError::Invalid("invalid workspace ID"))?; + snapshot + .positions + .insert(operation_id, snapshot.operations.len()); + snapshot.not_deleted = snapshot + .not_deleted + .checked_add(1) + .ok_or(ReplacementError::Limit("retained operations"))?; + snapshot.operations.push(RecordedReplacement { + operation_id, + session_id, + workspace_id, + revision, + target, + expected, + proposed, + manifest: None, + stage_identity: None, + progress: ReplacementProgress::Intent, + outcome: None, + code: None, + acknowledged: false, + retention: CheckpointRetention::Retained, + }); + snapshot.pending_operation_id = Some(operation_id); + if !carried { + snapshot.revision_floor = Some(revision); + } Ok(()) } diff --git a/crates/omgcode-core/src/replacement/store.rs b/crates/omgcode-core/src/replacement/store.rs index b69b52d..ade1b83 100644 --- a/crates/omgcode-core/src/replacement/store.rs +++ b/crates/omgcode-core/src/replacement/store.rs @@ -18,11 +18,14 @@ use time::format_description::well_known::Rfc3339; use uuid::Uuid; use super::manifest::{MAX_MANIFEST, Manifest, SecurityMetadata, descriptor}; -use super::replay::{ArtifactNames, Envelope, InitializationAction, LedgerAction}; +use super::replay::{ + self, ArtifactNames, Envelope, InitializationAction, LedgerAction, MAX_LEDGER_BYTES, + MAX_LEDGER_RECORDS, MAX_OPERATIONS, MAX_RECORD_BYTES, +}; use super::{ - CheckpointRetention, InitializationPhase, RecordedArtifact, RecordedReplacement, - ReplacementProgress, ReplacementScope, ReplacementSnapshot, inspect_initialization, - inspect_ledger, + CheckpointRetention, InitializationPhase, RecordedArtifact, RecordedCompaction, + RecordedReplacement, ReplacementProgress, ReplacementScope, ReplacementSnapshot, + inspect_initialization, inspect_ledger, }; use crate::control::{ControlError, ControlStore}; use crate::files::FileTarget; @@ -35,16 +38,21 @@ pub use publication::ReplacementReceipt; const ANCHOR: &str = "replacement-init-v1.jsonl"; const DIRECTORY: &str = "replacement-v1"; const LEDGER: &str = "ledger.jsonl"; -const MAX_LEDGER: usize = 8 * 1024 * 1024; -const MAX_RECORD: usize = 64 * 1024; -const MAX_EVENTS: usize = 4096; +/// A compacted ledger before it replaces `LEDGER`. Left behind only by an +/// interrupted compaction; it is a derived copy, never evidence. +const COMPACTION: &str = "ledger.compact"; +const MAX_LEDGER: usize = MAX_LEDGER_BYTES; +const MAX_RECORD: usize = MAX_RECORD_BYTES; +const MAX_EVENTS: usize = MAX_LEDGER_RECORDS; const MAX_PAYLOAD: usize = 1024 * 1024; -const MAX_STORAGE: u64 = 64 * 1024 * 1024; +/// The 64 MiB ledger bound plus the 64 MiB that the whole store had before +/// 0.35.0, so a full ledger leaves checkpoint files their earlier room. +const MAX_STORAGE: u64 = 128 * 1024 * 1024; // Each remaining v1 stage, commit, finish, or acknowledgement record fits 1 KiB. const TAIL_RECORD_BYTES: usize = 1024; const RECOVERY_BYTES: usize = 4 * TAIL_RECORD_BYTES; const FUTURE_STAGE_BYTES: u64 = 1024 * 1024; -const MAX_RETAINED: usize = 64; +const MAX_RETAINED: usize = MAX_OPERATIONS; /// Fixed entry artifact names, in deletion order: unpublished and private /// bytes first, then the manifest that describes them. const ENTRY_ARTIFACTS: [&str; 4] = ["stage", "proposed", "original", "manifest.json"]; @@ -104,7 +112,8 @@ pub enum CheckpointError { /// Private evidence may exist. Reopen for inspection; do not retry or delete. #[error("checkpoint operation is uncertain for operation {operation_id:?}: {source}")] Uncertain { - /// None denotes initialization, before an operation was admitted. + /// None denotes initialization or a ledger compaction, neither of + /// which belongs to one operation. operation_id: Option, /// The original failure, retained without automatic recovery. #[source] @@ -162,6 +171,29 @@ pub struct CheckpointDeletion { pub managed_bytes: u64, } +/// Outcome of one ledger compaction. No checkpoint entry or workspace file is +/// opened, changed, or removed. +#[derive(Debug, Serialize)] +pub struct CheckpointCompaction { + /// Whether the ledger was rewritten. False when compaction would not + /// shrink it; nothing is written then. + pub compacted: bool, + /// Records in the ledger before this request. + pub previous_records: usize, + /// Bytes in the ledger before this request. + pub previous_bytes: usize, + /// Records in the ledger after this request. + pub records: usize, + /// Bytes in the ledger after this request. + pub bytes: usize, + /// Retained operations carried into the ledger, one record each. + pub carried: usize, + /// Deleted operations whose history the rewrite dropped. + pub dropped: usize, + /// Observed managed file bytes after the request. + pub managed_bytes: u64, +} + /// Observed protected-storage phase. No variant grants authority. #[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)] #[serde(rename_all = "snake_case")] @@ -187,9 +219,11 @@ pub struct CheckpointInspection { pub pending: Option, /// One recorded, unfinished deletion, if any. pub pending_deletion: Option, - /// All recorded operation metadata, including deleted entries' history. - /// At most 64 operations are not deleted. + /// Recorded operation metadata, including deleted entries' history since + /// the last compaction. At most 64 operations are not deleted. pub operations: Vec, + /// The ledger that the last compaction replaced, if there was one. + pub compacted_from: Option, /// Observed managed file bytes including anchor, ledger, and partial files. pub managed_bytes: u64, } @@ -256,6 +290,7 @@ pub(crate) fn inspect(control: &ControlStore) -> Result Result Result { + compact_with(control, Faults::default()) +} + +/// Compact with one instance-local test fault at a named persistence boundary. +#[cfg(test)] +pub(crate) fn compact_with_fault( + control: &ControlStore, + point: &'static str, +) -> Result { + compact_with(control, Faults { at: Some(point) }) +} + +fn compact_with( + control: &ControlStore, + faults: Faults, +) -> Result { + let (expected, control_id) = context(control)?; + if !state_present(&expected.live_path()?)? { + return Err(CheckpointError::Unavailable); + } + let mut store = Store::open_ready(open_root(&expected)?, control_id, true)?; + store.faults = faults; + store.compact_ledger() +} + /// Return one retained checkpoint's original bytes for an explicit restore. /// /// The entry must be prepared and recorded for the same workspace and native @@ -426,7 +494,9 @@ fn record_acknowledgement(store: &mut Store, operation_id: Uuid) -> Result<(), C pub(crate) struct Store { root: PrivateDirectory, directory: PrivateDirectory, - ledger: File, + /// Absent only while a compaction replaces the ledger name, which Windows + /// refuses while this handle is open; the writer is poisoned until reopen. + ledger: Option, bytes: Vec, snapshot: ReplacementSnapshot, used: u64, @@ -472,6 +542,7 @@ impl Faults { "ack_sync" => "ack_partial_write", "deletion_intent_sync" => "deletion_intent_partial_write", "deletion_outcome_sync" => "deletion_outcome_partial_write", + "compaction_sync" => "compaction_partial_write", _ => "unselected_partial_write", }; if self.at == Some(partial) { @@ -570,7 +641,7 @@ impl Store { root, _anchor: anchor, directory, - ledger, + ledger: Some(ledger), bytes, snapshot, used, @@ -616,7 +687,7 @@ impl Store { root, _anchor: anchor, directory, - ledger, + ledger: Some(ledger), bytes, snapshot, used, @@ -639,10 +710,24 @@ impl Store { .pending_deletion() .map(|operation| operation.operation_id), operations: self.snapshot.operations.clone(), + compacted_from: self.snapshot.compaction.clone(), managed_bytes: self.used, } } + /// Whether `events` more records and `bytes` more ledger bytes fit. + fn ledger_fits(&self, events: usize, bytes: usize) -> bool { + self.snapshot + .event_count + .checked_add(events) + .is_some_and(|count| count <= MAX_EVENTS) + && self + .bytes + .len() + .checked_add(bytes) + .is_some_and(|size| size <= MAX_LEDGER) + } + /// Reserve the full future storage tail before recording intent and artifacts. /// Stop unresolved after verified preparation; any error after intent starts /// poisons this writer and reports uncertainty without workspace publication. @@ -699,7 +784,17 @@ impl Store { stage: "stage".to_owned(), }, }; - let intent = encode(self.snapshot.scope, self.snapshot.event_count, &start)?; + let mut intent = encode(self.snapshot.scope, self.snapshot.event_count, &start)?; + // A full ledger is compacted in place first. Only a rewrite that + // keeps every retained entry's state can make this room. + let tail = intent + .len() + .checked_add(RECOVERY_BYTES + 1024) + .ok_or(CheckpointError::Limit)?; + if !self.ledger_fits(6, tail) { + self.compact_ledger()?; + intent = encode(self.snapshot.scope, self.snapshot.event_count, &start)?; + } // Reserve maximum originals/proposal/stage, manifest, and all journal tail // capacity before making any artifact. No eviction makes capacity appear. let reserve = 3u64 @@ -710,18 +805,11 @@ impl Store { .and_then(|size| size.checked_add(u64::try_from(intent.len()).ok()?)) .ok_or(CheckpointError::Limit)?; ensure_budget(self.used, reserve)?; - if self - .snapshot - .event_count - .checked_add(6) - .is_none_or(|size| size > MAX_EVENTS) - || self - .bytes - .len() - .checked_add(intent.len()) - .and_then(|size| size.checked_add(RECOVERY_BYTES + 1024)) - .is_none_or(|size| size > MAX_LEDGER) - { + let tail = intent + .len() + .checked_add(RECOVERY_BYTES + 1024) + .ok_or(CheckpointError::Limit)?; + if !self.ledger_fits(6, tail) { return Err(CheckpointError::Limit); } let result = (|| { @@ -804,6 +892,11 @@ impl Store { }) { return Err(CheckpointError::Unavailable); } + // The intent and its completion need two records. A full + // ledger is compacted first; the entry stays retained. + if !self.ledger_fits(2, 2 * TAIL_RECORD_BYTES) { + self.compact_ledger()?; + } false } }; @@ -875,6 +968,191 @@ impl Store { Ok(()) } + /// Rewrite the ledger as its original header, one compaction record, and + /// one carried record per retained entry, then replace it by name. + /// + /// The candidate is replayed and must hold exactly the retained entries' + /// state before anything is written. It is written to `COMPACTION`, + /// synced, read back, and renamed over the ledger, so a crash leaves + /// either ledger and both describe the same retained state. A candidate + /// left by an interrupted compaction is removed first; it is a derived + /// copy, never evidence. Any failure after that poisons this writer and is + /// uncertain; reopen to inspect. Nothing is retried. + fn compact_ledger(&mut self) -> Result { + if self.poisoned { + return Err(CheckpointError::Poisoned); + } + if let Some(operation) = self.snapshot.pending() { + return Err(CheckpointError::Pending(operation.operation_id)); + } + if let Some(operation) = self.snapshot.pending_deletion() { + return Err(CheckpointError::DeletionPending(operation.operation_id)); + } + let retained = |snapshot: &ReplacementSnapshot| { + snapshot + .operations + .iter() + .filter(|operation| operation.retention == CheckpointRetention::Retained) + .cloned() + .collect::>() + }; + let current = retained(&self.snapshot); + let previous_records = self.snapshot.event_count; + let previous_bytes = self.bytes.len(); + let unchanged = CheckpointCompaction { + compacted: false, + previous_records, + previous_bytes, + records: previous_records, + bytes: previous_bytes, + carried: current.len(), + dropped: 0, + managed_bytes: self.used, + }; + // A ledger that is already its header, one compaction record, and one + // record per retained entry has nothing to drop. + let minimal = current.len().checked_add(2).ok_or(CheckpointError::Limit)?; + if previous_records <= minimal { + return Ok(unchanged); + } + let candidate = self.compacted_bytes()?; + let snapshot = inspect_ledger(&candidate, self.snapshot.scope)?; + let carried = retained(&snapshot); + if carried != current || snapshot.operations.len() != carried.len() { + return Err(CheckpointError::Invalid( + "compaction would change retained checkpoint state", + )); + } + if candidate.len() > previous_bytes { + return Ok(unchanged); + } + let dropped = self + .snapshot + .operations + .len() + .checked_sub(carried.len()) + .ok_or(CheckpointError::Invalid("retained count exceeds history"))?; + let result = (|| { + if self.directory.exists(OsStr::new(COMPACTION))? { + self.directory.remove_file(OsStr::new(COMPACTION))?; + self.directory.sync()?; + self.refresh_usage()?; + } + ensure_budget( + self.used, + u64::try_from(candidate.len()).map_err(|_| CheckpointError::Limit)?, + )?; + { + let mut file = self.directory.create_file(OsStr::new(COMPACTION))?; + self.faults + .write(&mut file, &candidate, "compaction_sync")?; + self.faults.check("compaction_sync")?; + file.sync_all()?; + } + let mut written = self.directory.open_file(OsStr::new(COMPACTION), false)?; + if read_bounded(&mut written, MAX_LEDGER)? != candidate { + return Err(CheckpointError::Invalid( + "compacted ledger differs from its candidate", + )); + } + drop(written); + let mut ledger = self.ledger.take().ok_or(CheckpointError::Poisoned)?; + self.require_unchanged(&mut ledger)?; + // Windows refuses to replace a name while this handle, which + // denies delete sharing, is open. The anchor lock stays held. + drop(ledger); + self.faults.check("compaction_rename")?; + self.directory + .replace_file(OsStr::new(COMPACTION), OsStr::new(LEDGER))?; + self.faults.check("compaction_directory_sync")?; + self.directory.sync()?; + let mut ledger = self.directory.open_file(OsStr::new(LEDGER), true)?; + if read_bounded(&mut ledger, MAX_LEDGER)? != candidate { + return Err(CheckpointError::Invalid( + "replaced ledger differs from its candidate", + )); + } + self.ledger = Some(ledger); + self.bytes = candidate; + self.snapshot = snapshot; + self.refresh_usage()?; + Ok(CheckpointCompaction { + compacted: true, + previous_records, + previous_bytes, + records: self.snapshot.event_count, + bytes: self.bytes.len(), + carried: carried.len(), + dropped, + managed_bytes: self.used, + }) + })(); + result.map_err(|source: CheckpointError| { + self.poisoned = true; + CheckpointError::Uncertain { + operation_id: None, + source: Box::new(source), + } + }) + } + + /// Encode the compacted form of the current ledger without writing it. + /// The original header record is kept byte for byte. + fn compacted_bytes(&self) -> Result, CheckpointError> { + let header = self + .bytes + .split_inclusive(|byte| *byte == b'\n') + .next() + .ok_or(CheckpointError::Invalid("ledger has no header record"))?; + let mut bytes = header.to_vec(); + let previous = descriptor(&self.bytes)?; + let compacted = LedgerAction::Compacted { + previous, + previous_records: u64::try_from(self.snapshot.event_count) + .map_err(|_| CheckpointError::Limit)?, + revision_floor: self.snapshot.revision_floor, + }; + bytes.extend_from_slice(&encode(self.snapshot.scope, 1, compacted)?); + let retained = self + .snapshot + .operations + .iter() + .filter(|operation| operation.retention == CheckpointRetention::Retained); + for (offset, operation) in retained.enumerate() { + let carried = LedgerAction::CheckpointCarried { + operation_id: operation.operation_id, + session_id: operation.session_id, + workspace_id: *operation.workspace_id.as_uuid(), + revision: operation.revision, + target: operation.target.clone(), + expected: operation.expected.clone(), + proposed: operation.proposed.clone(), + manifest: operation.manifest.clone(), + stage_identity: operation.stage_identity.clone(), + progress: operation.progress, + outcome: operation.outcome, + code: operation.code.clone(), + acknowledged: operation.acknowledged, + }; + let sequence = offset.checked_add(2).ok_or(CheckpointError::Limit)?; + bytes.extend_from_slice(&encode(self.snapshot.scope, sequence, carried)?); + } + Ok(bytes) + } + + /// Require the open ledger to still hold exactly the validated bytes. + fn require_unchanged(&self, ledger: &mut File) -> Result<(), CheckpointError> { + let expected_length = + u64::try_from(self.bytes.len()).map_err(|_| CheckpointError::Limit)?; + if ledger.metadata()?.len() != expected_length { + return Err(CheckpointError::Invalid("ledger changed while open")); + } + if read_bounded(ledger, MAX_LEDGER)? != self.bytes { + return Err(CheckpointError::Invalid("ledger bytes changed while open")); + } + Ok(()) + } + fn refresh_usage(&mut self) -> Result<(), CheckpointError> { let anchor_bytes = usize::try_from(self._anchor.metadata()?.len()).map_err(|_| CheckpointError::Limit)?; @@ -942,34 +1220,30 @@ impl Store { ) .map_err(|_| CheckpointError::Limit)?; ensure_budget(self.used, growth)?; - let mut candidate = Vec::with_capacity(size); - candidate.extend_from_slice(&self.bytes); - candidate.extend_from_slice(&encoded); - let snapshot = inspect_ledger(&candidate, self.snapshot.scope)?; - let expected_length = - u64::try_from(self.bytes.len()).map_err(|_| CheckpointError::Limit)?; - if self.ledger.metadata()?.len() != expected_length { - return Err(CheckpointError::Invalid("ledger changed while open")); - } - if read_bounded(&mut self.ledger, MAX_LEDGER)? != self.bytes { - return Err(CheckpointError::Invalid("ledger bytes changed while open")); - } - let result = (|| { - self.ledger.seek(SeekFrom::End(0))?; - self.faults.write(&mut self.ledger, &encoded, sync_point)?; - // Publication of memory follows acknowledged sync, never write alone. - self.faults.check(sync_point)?; - self.ledger.sync_all() - })(); - if let Err(error) = result { - self.poisoned = true; - return Err(error.into()); - } + // Validating the one new record against the replayed state equals + // replaying the whole candidate ledger, without parsing it again. + let snapshot = replay::extend(&self.snapshot, &encoded)?; + let mut ledger = self.ledger.take().ok_or(CheckpointError::Poisoned)?; + let result = self.require_unchanged(&mut ledger).and_then(|()| { + let written = (|| { + ledger.seek(SeekFrom::End(0))?; + self.faults.write(&mut ledger, &encoded, sync_point)?; + // Publication of memory follows acknowledged sync, never write alone. + self.faults.check(sync_point)?; + ledger.sync_all() + })(); + written.map_err(|error| { + self.poisoned = true; + CheckpointError::from(error) + }) + }); + self.ledger = Some(ledger); + result?; self.used = self .used .checked_add(u64::try_from(encoded.len()).map_err(|_| CheckpointError::Limit)?) .ok_or(CheckpointError::Limit)?; - self.bytes = candidate; + self.bytes.extend_from_slice(&encoded); self.snapshot = snapshot; Ok(()) } @@ -1053,7 +1327,8 @@ fn inventory( &mut used, u64::try_from(snapshot.encoded_bytes).map_err(|_| CheckpointError::Limit)?, )?; - let names = directory.names(65)?; + // The ledger, one possible compaction candidate, and 64 entries. + let names = directory.names(66)?; let mut saw_ledger = false; let mut seen = Vec::new(); for name in names { @@ -1061,6 +1336,17 @@ fn inventory( saw_ledger = true; continue; } + if name == OsStr::new(COMPACTION) { + // An interrupted compaction's candidate. The ledger stays + // authoritative; count the bytes until a compaction removes it. + let file = directory.open_file(&name, false)?; + let length = file.metadata()?.len(); + if length > u64::try_from(MAX_LEDGER).map_err(|_| CheckpointError::Limit)? { + return Err(CheckpointError::Limit); + } + add_usage(&mut used, length)?; + continue; + } let id = name .to_str() .and_then(|name| Uuid::parse_str(name).ok()) diff --git a/crates/omgcode-core/tests/checkpoint_storage.rs b/crates/omgcode-core/tests/checkpoint_storage.rs index 4307dba..c5ed56d 100644 --- a/crates/omgcode-core/tests/checkpoint_storage.rs +++ b/crates/omgcode-core/tests/checkpoint_storage.rs @@ -805,8 +805,8 @@ fn sixty_four_acknowledged_checkpoints_are_retained_and_refuse_the_sixty_fifth() #[cfg(target_os = "linux")] #[test] /// Fills storage with full payload pairs, then compares reported bytes with -/// every actual managed file length at the quota boundary. -fn aggregate_checkpoint_storage_refuses_before_exceeding_sixty_four_mib() { +/// every actual managed file length at the 128 MiB quota boundary. +fn aggregate_checkpoint_storage_refuses_before_exceeding_one_hundred_twenty_eight_mib() { const PAYLOAD_BYTES: usize = 1024 * 1024; const MEBIBYTE: u64 = 1024 * 1024; @@ -825,7 +825,7 @@ fn aggregate_checkpoint_storage_refuses_before_exceeding_sixty_four_mib() { let mut successes = 0; let mut refused = false; - for _ in 0..34 { + for _ in 0..66 { let ledger_before = ledger_path .exists() .then(|| fs::read(&ledger_path).expect("snapshot existing ledger before attempt")); @@ -858,12 +858,14 @@ fn aggregate_checkpoint_storage_refuses_before_exceeding_sixty_four_mib() { } } - assert!(refused, "quota did not refuse within 34 attempts"); + // Each pair is 2 MiB and the next reservation about 3 MiB, so the quota, + // not the 64-entry bound, refuses first. + assert!(refused, "quota did not refuse within 66 attempts"); assert!( - successes >= 30, - "expected at least 30 whole checkpoints, got {successes}" + successes >= 62, + "expected at least 62 whole checkpoints, got {successes}" ); - assert!(successes < 32, "32 full checkpoint pairs must exceed quota"); + assert!(successes < 64, "64 full checkpoint pairs must exceed quota"); assert_eq!(entry_paths(&store_path).len(), successes + 1); let inspection = FileBroker::new(&mut fixture.control) @@ -871,8 +873,8 @@ fn aggregate_checkpoint_storage_refuses_before_exceeding_sixty_four_mib() { .expect("inspect full retained checkpoint store"); assert_eq!(inspection.operations.len(), successes); assert_eq!(inspection.pending, None); - assert!(inspection.managed_bytes >= 60 * MEBIBYTE); - assert!(inspection.managed_bytes <= 64 * MEBIBYTE); + assert!(inspection.managed_bytes >= 124 * MEBIBYTE); + assert!(inspection.managed_bytes <= 128 * MEBIBYTE); assert_eq!( inspection.managed_bytes, managed_file_bytes(&fixture, successes), diff --git a/crates/omgcode-core/tests/replacement_records.rs b/crates/omgcode-core/tests/replacement_records.rs index 473b662..62737bd 100644 --- a/crates/omgcode-core/tests/replacement_records.rs +++ b/crates/omgcode-core/tests/replacement_records.rs @@ -11,7 +11,8 @@ use serde_json::{Value, json}; use uuid::Uuid; const MAX_RECORD: usize = 64 * 1024; -const MAX_LEDGER: usize = 8 * 1024 * 1024; +const MAX_LEDGER: usize = 64 * 1024 * 1024; +const MAX_LEDGER_RECORDS: usize = 65_536; struct Fixture { control: Uuid, @@ -126,6 +127,40 @@ impl Fixture { ); } + fn compacted(&mut self, floor: Option) { + self.push( + "compacted", + Some(json!({ + "previous": {"bytes": 4096, "sha256": "d".repeat(64)}, + "previous_records": 12, + "revision_floor": floor + })), + ); + } + + /// One carried operation that succeeded, the state a full apply reaches. + fn carried_payload(&self) -> Value { + json!({ + "operation_id": self.operation, + "session_id": Uuid::new_v4(), + "workspace_id": Uuid::new_v4(), + "revision": 3, + "target": NativePath::from_path(Path::new("src/file.txt")).expect("native target"), + "expected": {"bytes": 4, "sha256": "a".repeat(64)}, + "proposed": {"bytes": 5, "sha256": "b".repeat(64)}, + "manifest": {"bytes": 512, "sha256": "c".repeat(64)}, + "stage_identity": {"volume": 7, "file_id": vec![9; 16]}, + "progress": "commit_intended", + "outcome": "succeeded", + "code": null, + "acknowledged": false + }) + } + + fn carried(&mut self, payload: Value) { + self.push("checkpoint_carried", Some(payload)); + } + fn bytes(&self) -> Vec { encode(&self.events) } @@ -562,7 +597,7 @@ fn ledger_record_and_retained_operation_caps_do_not_evict_history() { Err(ReplacementError::Limit(_)) )); let header = ledger(); - let many_records = header.bytes().repeat(4097); + let many_records = header.bytes().repeat(MAX_LEDGER_RECORDS + 1); assert!(matches!( inspect_ledger(&many_records, header.scope()), Err(ReplacementError::Limit(_)) @@ -731,11 +766,15 @@ fn native_encoding_policy_preserves_local_units_and_rejects_foreign_encoding() { #[test] fn exact_ledger_byte_cap_is_accepted_and_one_more_byte_is_refused() { + // Deleted operations do not count toward the 64 retained entries, so + // enough records exist to pad each to 64 KiB and reach 64 MiB. let mut fixture = ledger(); - for _ in 0..64 { + for _ in 0..300 { fixture.operation = Uuid::new_v4(); fixture.start(); fixture.finish("failed"); + fixture.delete_started(); + fixture.deleted(); } let raw = fixture.bytes(); let mut remaining = MAX_LEDGER - raw.len(); @@ -754,7 +793,7 @@ fn exact_ledger_byte_cap_is_accepted_and_one_more_byte_is_refused() { .expect("exact total bound") .operations .len(), - 64 + 300 ); padded.insert(padded.len() - 1, b' '); assert!(matches!( @@ -948,3 +987,217 @@ fn unit_actions_reject_object_payloads_and_stage_identity_rejects_duplicate_keys let duplicate = original.replacen("\"volume\":7", "\"volume\":7,\"volume\":7", 1); assert!(inspect_ledger(duplicate.as_bytes(), fixture.scope()).is_err()); } + +#[test] +fn a_compacted_ledger_replays_carried_state_and_keeps_the_revision_floor() { + let mut fixture = ledger(); + fixture.compacted(Some(5)); + let carried = fixture.operation; + fixture.carried(fixture.carried_payload()); + let snapshot = inspect_ledger(&fixture.bytes(), fixture.scope()).expect("compacted ledger"); + assert_eq!(snapshot.event_count, 3); + assert_eq!(snapshot.pending(), None); + let compaction = snapshot.compaction.as_ref().expect("compaction claim"); + assert_eq!(compaction.records, 12); + assert_eq!(compaction.ledger.bytes, 4096); + let operation = &snapshot.operations[0]; + assert_eq!(operation.operation_id, carried); + assert_eq!(operation.progress, ReplacementProgress::CommitIntended); + assert_eq!(operation.outcome, Some(ReplacementOutcome::Succeeded)); + assert_eq!(operation.retention, CheckpointRetention::Retained); + assert!(operation.manifest.is_some() && operation.stage_identity.is_some()); + + // A later start may not fall below the carried floor of 5. + fixture.operation = Uuid::new_v4(); + fixture.start(); + fixture.events[3]["action"]["payload"]["revision"] = json!(4); + assert!(inspect_ledger(&fixture.bytes(), fixture.scope()).is_err()); + fixture.events[3]["action"]["payload"]["revision"] = json!(5); + assert_eq!( + inspect_ledger(&fixture.bytes(), fixture.scope()) + .expect("start at the floor") + .pending() + .map(|operation| operation.operation_id), + Some(fixture.operation) + ); + + // The carried entry can be deleted, and a compaction with no entries is valid. + fixture.events.truncate(3); + fixture.operation = carried; + fixture.delete_started(); + fixture.deleted(); + let snapshot = inspect_ledger(&fixture.bytes(), fixture.scope()).expect("deleted carried"); + assert_eq!( + snapshot.operations[0].retention, + CheckpointRetention::Deleted + ); + let mut empty = ledger(); + empty.compacted(None); + assert!(inspect_ledger(&empty.bytes(), empty.scope()).is_ok()); +} + +#[test] +fn compaction_and_carried_records_have_fixed_positions() { + // A compaction record anywhere but second is refused. + let mut fixture = ledger(); + fixture.start(); + fixture.finish("failed"); + fixture.compacted(Some(3)); + assert!(inspect_ledger(&fixture.bytes(), fixture.scope()).is_err()); + + // A carried record needs a directly preceding compaction or carried record. + let mut fixture = ledger(); + fixture.carried(fixture.carried_payload()); + assert!(inspect_ledger(&fixture.bytes(), fixture.scope()).is_err()); + let mut fixture = ledger(); + fixture.compacted(Some(3)); + fixture.operation = Uuid::new_v4(); + fixture.start(); + fixture.finish("failed"); + fixture.operation = Uuid::new_v4(); + fixture.carried(fixture.carried_payload()); + assert!(inspect_ledger(&fixture.bytes(), fixture.scope()).is_err()); + + // Two compaction records, or a carried ID used twice, are refused. + let mut fixture = ledger(); + fixture.compacted(Some(3)); + fixture.compacted(Some(3)); + assert!(inspect_ledger(&fixture.bytes(), fixture.scope()).is_err()); + let mut fixture = ledger(); + fixture.compacted(Some(3)); + fixture.carried(fixture.carried_payload()); + fixture.carried(fixture.carried_payload()); + assert!(inspect_ledger(&fixture.bytes(), fixture.scope()).is_err()); +} + +#[test] +fn carried_state_must_be_resolved_and_reachable() { + let check = |change: &dyn Fn(&mut Value), valid: bool| { + let mut fixture = ledger(); + fixture.compacted(Some(3)); + let mut payload = fixture.carried_payload(); + change(&mut payload); + fixture.carried(payload); + assert_eq!( + inspect_ledger(&fixture.bytes(), fixture.scope()).is_ok(), + valid, + "{}", + fixture.events[2]["action"]["payload"] + ); + }; + check(&|_| {}, true); + // Unresolved: no outcome and no acknowledgement, or uncertain without one. + check(&|payload| payload["outcome"] = Value::Null, false); + check( + &|payload| { + payload["outcome"] = json!("uncertain"); + payload["code"] = json!("sync_failed"); + }, + false, + ); + check( + &|payload| { + payload["outcome"] = json!("uncertain"); + payload["code"] = json!("sync_failed"); + payload["acknowledged"] = json!(true); + }, + true, + ); + check( + &|payload| { + payload["outcome"] = Value::Null; + payload["acknowledged"] = json!(true); + }, + true, + ); + // Acknowledgement of an operation that finished cleanly never happens. + check(&|payload| payload["acknowledged"] = json!(true), false); + // Success requires commit intent, and failure forbids it. + check( + &|payload| payload["progress"] = json!("stage_prepared"), + false, + ); + check( + &|payload| { + payload["outcome"] = json!("failed"); + payload["code"] = json!("conflict"); + }, + false, + ); + // Manifest and stage must match the recorded progress. + check( + &|payload| { + payload["progress"] = json!("intent"); + payload["outcome"] = json!("failed"); + payload["code"] = json!("conflict"); + payload["manifest"] = Value::Null; + payload["stage_identity"] = Value::Null; + }, + true, + ); + check( + &|payload| { + payload["progress"] = json!("intent"); + payload["outcome"] = json!("failed"); + payload["code"] = json!("conflict"); + payload["stage_identity"] = Value::Null; + }, + false, + ); + check(&|payload| payload["stage_identity"] = Value::Null, false); + check(&|payload| payload["manifest"] = Value::Null, false); + // A code without an outcome, a revision above the floor, and unknown + // fields are refused. + check( + &|payload| { + payload["outcome"] = Value::Null; + payload["acknowledged"] = json!(true); + payload["code"] = json!("orphan"); + }, + false, + ); + check(&|payload| payload["revision"] = json!(4), false); + check(&|payload| payload["retention"] = json!("retained"), false); + + // Carried revisions keep their order and need a floor. + let mut fixture = ledger(); + fixture.compacted(None); + fixture.carried(fixture.carried_payload()); + assert!(inspect_ledger(&fixture.bytes(), fixture.scope()).is_err()); + let mut fixture = ledger(); + fixture.compacted(Some(3)); + let mut first = fixture.carried_payload(); + first["revision"] = json!(3); + fixture.carried(first); + fixture.operation = Uuid::new_v4(); + let mut second = fixture.carried_payload(); + second["revision"] = json!(2); + fixture.carried(second); + assert!(inspect_ledger(&fixture.bytes(), fixture.scope()).is_err()); +} + +#[test] +fn compaction_claims_have_strict_bounds() { + for (field, value) in [ + ("previous_records", json!(0)), + ("previous_records", json!(MAX_LEDGER_RECORDS + 1)), + ("previous", json!({"bytes": 0, "sha256": "d".repeat(64)})), + ( + "previous", + json!({"bytes": MAX_LEDGER + 1, "sha256": "d".repeat(64)}), + ), + ("previous", json!({"bytes": 4096, "sha256": "D".repeat(64)})), + ] { + let mut fixture = ledger(); + fixture.compacted(Some(3)); + fixture.events[1]["action"]["payload"][field] = value; + assert!( + inspect_ledger(&fixture.bytes(), fixture.scope()).is_err(), + "{field}" + ); + } + let mut fixture = ledger(); + fixture.compacted(Some(3)); + fixture.events[1]["action"]["payload"]["extra"] = json!(true); + assert!(inspect_ledger(&fixture.bytes(), fixture.scope()).is_err()); +} diff --git a/crates/omgcode-platform/src/broker/windows.rs b/crates/omgcode-platform/src/broker/windows.rs index a364800..4bfbd60 100644 --- a/crates/omgcode-platform/src/broker/windows.rs +++ b/crates/omgcode-platform/src/broker/windows.rs @@ -19,8 +19,9 @@ use std::time::{Duration, SystemTime}; use windows_sys::Wdk::Foundation::OBJECT_ATTRIBUTES; use windows_sys::Wdk::Storage::FileSystem::{ FILE_CREATE, FILE_DIRECTORY_FILE, FILE_ID_BOTH_DIR_INFORMATION, FILE_NON_DIRECTORY_FILE, - FILE_OPEN, FILE_OPEN_REPARSE_POINT, FILE_SYNCHRONOUS_IO_NONALERT, - FileIdBothDirectoryInformation, NtCreateFile, NtQueryDirectoryFile, + FILE_OPEN, FILE_OPEN_REPARSE_POINT, FILE_RENAME_INFORMATION, FILE_RENAME_POSIX_SEMANTICS, + FILE_RENAME_REPLACE_IF_EXISTS, FILE_SYNCHRONOUS_IO_NONALERT, FileIdBothDirectoryInformation, + FileRenameInformationEx, NtCreateFile, NtQueryDirectoryFile, NtSetInformationFile, }; use windows_sys::Win32::Foundation::{ HANDLE, NTSTATUS, OBJ_CASE_INSENSITIVE, OBJ_DONT_REPARSE, STATUS_NO_MORE_FILES, @@ -582,6 +583,62 @@ fn encode_component(name: &OsStr) -> io::Result> { Ok(units) } +/// Atomically replace `name` beneath `parent` with the object behind `source`. +/// +/// The rename is by handle, with POSIX semantics and replace-if-exists. The +/// source handle needs DELETE access, and every open handle to the replaced +/// object must permit delete sharing or the call fails. One attempt is made; +/// an error is never retried here. The caller flushes the parent. +#[allow(unsafe_code)] +pub(crate) fn rename_onto(source: &File, parent: &File, name: &OsStr) -> io::Result<()> { + let units = encode_component(name)?; + if units.is_empty() { + return Err(invalid_input("replacement requires a target name")); + } + let name_bytes = units + .len() + .checked_mul(size_of::()) + .ok_or_else(|| invalid_input("replacement name is too long"))?; + let name_offset = offset_of!(FILE_RENAME_INFORMATION, FileName); + // Windows refuses a buffer smaller than the structure with a length mismatch. + let total = name_offset + .checked_add(name_bytes) + .ok_or_else(|| invalid_input("replacement name is too long"))? + .max(size_of::()); + let length = u32::try_from(total).map_err(|_| invalid_input("rename buffer is too large"))?; + let file_name_length = + u32::try_from(name_bytes).map_err(|_| invalid_input("replacement name is too long"))?; + let mut storage = vec![0u64; total.div_ceil(size_of::())]; + let base = storage.as_mut_ptr().cast::(); + let information = base.cast::(); + let mut status_block = IO_STATUS_BLOCK::default(); + // SAFETY: `storage` is zeroed, aligned for the structure, and holds at least + // `total` bytes, so every field and all of `name_bytes` at `name_offset` are + // in bounds. `parent` outlives the synchronous call that reads its handle. + let status = unsafe { + (*information).Anonymous.Flags = + FILE_RENAME_REPLACE_IF_EXISTS | FILE_RENAME_POSIX_SEMANTICS; + (*information).RootDirectory = parent.as_raw_handle() as HANDLE; + (*information).FileNameLength = file_name_length; + std::ptr::copy_nonoverlapping( + units.as_ptr().cast::(), + base.add(name_offset), + name_bytes, + ); + NtSetInformationFile( + source.as_raw_handle() as HANDLE, + &mut status_block, + information.cast(), + length, + FileRenameInformationEx, + ) + }; + if status != 0 { + return Err(native_error(status)); + } + Ok(()) +} + fn require_directory_identity( file: &File, expected: DirectoryIdentity, diff --git a/crates/omgcode-platform/src/broker/windows/replacement.rs b/crates/omgcode-platform/src/broker/windows/replacement.rs index 01055cc..16f12c1 100644 --- a/crates/omgcode-platform/src/broker/windows/replacement.rs +++ b/crates/omgcode-platform/src/broker/windows/replacement.rs @@ -18,10 +18,7 @@ use std::os::windows::ffi::OsStrExt; use std::os::windows::io::AsRawHandle; use std::time::SystemTime; -use windows_sys::Wdk::Storage::FileSystem::{ - FILE_OPEN, FILE_RENAME_INFORMATION, FILE_RENAME_POSIX_SEMANTICS, FILE_RENAME_REPLACE_IF_EXISTS, - FileRenameInformationEx, NtSetInformationFile, -}; +use windows_sys::Wdk::Storage::FileSystem::FILE_OPEN; use windows_sys::Win32::Foundation::{ HANDLE, NTSTATUS, STATUS_DELETE_PENDING, STATUS_FILE_IS_A_DIRECTORY, STATUS_NOT_A_DIRECTORY, STATUS_OBJECT_NAME_NOT_FOUND, STATUS_REPARSE_POINT_ENCOUNTERED, STATUS_SHARING_VIOLATION, @@ -30,13 +27,12 @@ use windows_sys::Win32::Storage::FileSystem::{ DELETE, FILE_ADD_FILE, FILE_NAME_INFO, FILE_SHARE_DELETE, FILE_SHARE_READ, FileNormalizedNameInfo, GetFileInformationByHandleEx, SYNCHRONIZE, }; -use windows_sys::Win32::System::IO::IO_STATUS_BLOCK; use super::{ DIRECTORY_ACCESS, NativeStatus, NativeWorkspace, RelativePath, SHARE_READ_WRITE, creation_time, - encode_component, invalid_data, invalid_input, last_directory, native_error, open_relative, - query_attributes, query_basic, query_identity, query_standard, read_bounded, - validate_component, validate_directory, validate_regular_file, + invalid_data, invalid_input, last_directory, open_relative, query_attributes, query_basic, + query_identity, query_standard, read_bounded, rename_onto, validate_component, + validate_directory, validate_regular_file, }; use crate::broker::{FileCapture, MAX_FILE_BYTES}; use crate::directory_identity; @@ -504,57 +500,6 @@ fn published_matches(target: &ReplacementTarget<'_>, stage: &ReplacementStage) - && stage_metadata(&published)? == stage.metadata) } -/// Replace `name` beneath `parent` with the file behind `stage`, by handle. -#[allow(unsafe_code)] -fn rename_onto(stage: &File, parent: &File, name: &OsStr) -> io::Result<()> { - let units = encode_component(name)?; - if units.is_empty() { - return Err(invalid_input("replacement requires a target name")); - } - let name_bytes = units - .len() - .checked_mul(size_of::()) - .ok_or_else(|| invalid_input("replacement name is too long"))?; - let name_offset = offset_of!(FILE_RENAME_INFORMATION, FileName); - // Windows refuses a buffer smaller than the structure with a length mismatch. - let total = name_offset - .checked_add(name_bytes) - .ok_or_else(|| invalid_input("replacement name is too long"))? - .max(size_of::()); - let length = u32::try_from(total).map_err(|_| invalid_input("rename buffer is too large"))?; - let file_name_length = - u32::try_from(name_bytes).map_err(|_| invalid_input("replacement name is too long"))?; - let mut storage = vec![0u64; total.div_ceil(size_of::())]; - let base = storage.as_mut_ptr().cast::(); - let information = base.cast::(); - let mut status_block = IO_STATUS_BLOCK::default(); - // SAFETY: `storage` is zeroed, aligned for the structure, and holds at least - // `total` bytes, so every field and all of `name_bytes` at `name_offset` are - // in bounds. `parent` outlives the synchronous call that reads its handle. - let status = unsafe { - (*information).Anonymous.Flags = - FILE_RENAME_REPLACE_IF_EXISTS | FILE_RENAME_POSIX_SEMANTICS; - (*information).RootDirectory = parent.as_raw_handle() as HANDLE; - (*information).FileNameLength = file_name_length; - std::ptr::copy_nonoverlapping( - units.as_ptr().cast::(), - base.add(name_offset), - name_bytes, - ); - NtSetInformationFile( - stage.as_raw_handle() as HANDLE, - &mut status_block, - information.cast(), - length, - FileRenameInformationEx, - ) - }; - if status != 0 { - return Err(native_error(status)); - } - Ok(()) -} - fn file_snapshot(file: &File) -> io::Result { let identity = query_identity(file)?; validate_regular_file(file, identity.VolumeSerialNumber)?; diff --git a/crates/omgcode-platform/src/broker/windows/replacement/tests.rs b/crates/omgcode-platform/src/broker/windows/replacement/tests.rs index e258337..9dac219 100644 --- a/crates/omgcode-platform/src/broker/windows/replacement/tests.rs +++ b/crates/omgcode-platform/src/broker/windows/replacement/tests.rs @@ -11,6 +11,7 @@ use windows_sys::Win32::Storage::FileSystem::{ FILE_WRITE_ATTRIBUTES, FileBasicInfo, READ_CONTROL, SetFileInformationByHandle, WRITE_DAC, WRITE_OWNER, }; +use windows_sys::Win32::System::IO::IO_STATUS_BLOCK; struct Fixture { workspace: NativeWorkspace, diff --git a/crates/omgcode-platform/src/private_store.rs b/crates/omgcode-platform/src/private_store.rs index 738efcb..df64278 100644 --- a/crates/omgcode-platform/src/private_store.rs +++ b/crates/omgcode-platform/src/private_store.rs @@ -170,6 +170,10 @@ impl PrivateDirectory { pub fn remove_dir(&self, _name: &OsStr) -> io::Result<()> { Err(unsupported()) } + /// Refuse unsupported private file replacement. + pub fn replace_file(&self, _source: &OsStr, _target: &OsStr) -> io::Result<()> { + Err(unsupported()) + } } #[cfg(not(any(target_os = "linux", windows)))] diff --git a/crates/omgcode-platform/src/private_store/linux.rs b/crates/omgcode-platform/src/private_store/linux.rs index 3789806..4356ee1 100644 --- a/crates/omgcode-platform/src/private_store/linux.rs +++ b/crates/omgcode-platform/src/private_store/linux.rs @@ -9,7 +9,7 @@ use std::time::SystemTime; use rustix::fs::{ AtFlags, Dir, Mode, OFlags, ResolveFlags, StatxAttributes, StatxFlags, mkdirat, open, openat2, - statat, statx, unlinkat, + renameat, statat, statx, unlinkat, }; use rustix::io::Errno; @@ -314,6 +314,48 @@ impl PrivateDirectory { Ok(()) } + /// Atomically replace one existing private file with another in this + /// directory without following a link. + /// + /// Both names are pinned and must be private regular single-link files on + /// this filesystem. One `renameat` replaces `target`. Afterwards `target` + /// must name the pinned source inode and the pinned old target must have + /// no link. A same-user substitution between the checks and the rename is + /// reported as an error, not prevented. Nothing is retried; the caller + /// syncs this directory afterwards. + pub fn replace_file(&self, source: &OsStr, target: &OsStr) -> io::Result<()> { + validate_name(source)?; + validate_name(target)?; + if source == target { + return Err(invalid("replacement needs two different names")); + } + let parent = self.validate()?; + let pinned_source = self.pin(source)?; + let expected = validate_file(&pinned_source, parent.dev())?; + let pinned_target = self.pin(target)?; + validate_file(&pinned_target, parent.dev())?; + renameat(&self.file, source, &self.file, target)?; + let published = self.pin(target)?.metadata()?; + if published.dev() != expected.dev() + || published.ino() != expected.ino() + || pinned_target.metadata()?.nlink() != 0 + { + return Err(invalid("replaced name does not refer to the source")); + } + Ok(()) + } + + /// Pin one child name with `O_PATH` without following a link or mount. + fn pin(&self, name: &OsStr) -> io::Result { + native_open( + &self.file, + Path::new(name), + OFlags::PATH | OFlags::CLOEXEC, + Mode::empty(), + child_flags(), + ) + } + /// Remove one empty private child directory. A nonempty directory fails; /// this never removes contents. The caller syncs this directory afterwards. pub fn remove_dir(&self, name: &OsStr) -> io::Result<()> { @@ -583,6 +625,84 @@ mod tests { assert!(directory.remove_file(OsStr::new("../escape")).is_err()); } + #[test] + fn replacement_swaps_one_private_file_and_refuses_links() { + let root = private_root(); + let directory = PrivateDirectory::open(root.path()).expect("private root"); + private_file(&root.path().join("ledger"), b"old"); + private_file(&root.path().join("candidate"), b"new"); + let source = fs::symlink_metadata(root.path().join("candidate")).expect("source"); + let held = directory + .open_file(OsStr::new("ledger"), true) + .expect("held target"); + + directory + .replace_file(OsStr::new("candidate"), OsStr::new("ledger")) + .expect("replace"); + assert_eq!(fs::read(root.path().join("ledger")).expect("new"), b"new"); + assert!(!root.path().join("candidate").exists()); + assert_eq!( + fs::symlink_metadata(root.path().join("ledger")) + .expect("published") + .ino(), + source.ino() + ); + // A retained handle keeps the replaced inode, now with no link. + assert_eq!(held.metadata().expect("held").nlink(), 0); + + for (source, target) in [("missing", "ledger"), ("ledger", "missing")] { + assert_eq!( + directory + .replace_file(OsStr::new(source), OsStr::new(target)) + .expect_err("missing name") + .kind(), + io::ErrorKind::NotFound + ); + } + assert!( + directory + .replace_file(OsStr::new("ledger"), OsStr::new("ledger")) + .is_err() + ); + private_file(&root.path().join("linked"), b"linked"); + fs::hard_link(root.path().join("linked"), root.path().join("alias")).expect("hard link"); + assert!( + directory + .replace_file(OsStr::new("linked"), OsStr::new("ledger")) + .is_err() + ); + symlink("ledger", root.path().join("link")).expect("symlink"); + assert!( + directory + .replace_file(OsStr::new("link"), OsStr::new("ledger")) + .is_err() + ); + assert!( + directory + .replace_file(OsStr::new("ledger"), OsStr::new("link")) + .is_err() + ); + private_file(&root.path().join("shared"), b"shared"); + fs::set_permissions( + root.path().join("shared"), + fs::Permissions::from_mode(0o644), + ) + .expect("shared mode"); + assert!( + directory + .replace_file(OsStr::new("shared"), OsStr::new("ledger")) + .is_err() + ); + assert!( + directory + .replace_file(OsStr::new("../escape"), OsStr::new("ledger")) + .is_err() + ); + assert_eq!(fs::read(root.path().join("ledger")).expect("kept"), b"new"); + assert!(fs::symlink_metadata(root.path().join("link")).is_ok()); + assert!(root.path().join("linked").exists()); + } + #[test] fn pinned_reopen_does_not_read_a_substituted_path() { let root = private_root(); diff --git a/crates/omgcode-platform/src/private_store/windows.rs b/crates/omgcode-platform/src/private_store/windows.rs index 56da861..ddad501 100644 --- a/crates/omgcode-platform/src/private_store/windows.rs +++ b/crates/omgcode-platform/src/private_store/windows.rs @@ -66,8 +66,8 @@ use super::PrivateFileIdentity; use crate::broker::invalid_windows_name; use crate::broker::windows::{ DIRECTORY_ACCESS, SHARE_READ_WRITE, create_relative_secured, creation_time, is_dot_entry, - is_name_not_found, open_relative, query_directory_batch, query_identity, validate_directory, - validate_regular_file, + is_name_not_found, open_relative, query_directory_batch, query_identity, rename_onto, + validate_directory, validate_regular_file, }; use crate::{DirectoryIdentity, directory_identity}; @@ -840,6 +840,64 @@ impl WindowsPrivateDirectory { self.require_removed(name) } + /// Atomically replaces one existing private file with another in this + /// directory, by handle and without following a reparse point. + /// + /// Both names must be regular single-link private files on this volume. + /// The source handle is renamed over `target` with POSIX semantics, so the + /// replaced object leaves the namespace in the same native operation. An + /// open handle to `target` that denies delete sharing makes the rename + /// fail; callers close their own handles first. Afterwards `target` must + /// name the checked source object and `source` must be absent. One attempt + /// is made and nothing is retried. The caller flushes this directory, and + /// that flush carries no power-loss guarantee (ADR-0023). + pub fn replace_file(&self, source: &OsStr, target: &OsStr) -> io::Result<()> { + validate_name(source)?; + validate_name(target)?; + if source == target { + return Err(invalid_input("replacement needs two different names")); + } + self.validate()?; + let file = open_relative( + &self.file, + source, + REMOVE_ACCESS, + FILE_OPEN, + FILE_OPTIONS, + SHARE_READ_WRITE | FILE_SHARE_DELETE, + 0, + ) + .map_err(map_missing)?; + self.validate_child_file(&file)?; + let expected = query_identity(&file)?; + // The replaced name must already be one of this store's private files. + // This handle closes before the rename so it cannot block it. + self.validate_child_file(&self.open_checked(target)?)?; + rename_onto(&file, &self.file, target)?; + let published = query_identity(&self.open_checked(target)?)?; + if published.VolumeSerialNumber != expected.VolumeSerialNumber + || published.FileId.Identifier != expected.FileId.Identifier + { + return Err(invalid_data("replaced name does not refer to the source")); + } + self.require_removed(source) + } + + /// Opens one name for attribute and security queries only, permitting + /// every sharing mode so the handle never blocks a later rename. + fn open_checked(&self, name: &OsStr) -> io::Result { + open_relative( + &self.file, + name, + FILE_READ_ATTRIBUTES | READ_CONTROL | SYNCHRONIZE, + FILE_OPEN, + FILE_OPTIONS, + SHARE_READ_WRITE | FILE_SHARE_DELETE, + 0, + ) + .map_err(map_missing) + } + /// POSIX-semantics deletion unlinks the name when the marked handle closes. fn require_removed(&self, name: &OsStr) -> io::Result<()> { if self.exists(name)? { @@ -1374,6 +1432,104 @@ pub(crate) mod tests { assert!(outside.path().exists()); } + fn private_bytes(fixture: &Fixture, name: &str, bytes: &[u8]) { + let mut file = fixture.root.create_file(OsStr::new(name)).expect("file"); + file.write_all(bytes).expect("contents"); + file.sync_all().expect("sync"); + } + + #[test] + fn replacement_swaps_one_private_file_by_handle_and_refuses_others() { + let fixture = fixture(); + private_bytes(&fixture, "ledger", b"old"); + private_bytes(&fixture, "candidate", b"new"); + let source = fixture + .root + .open_file(OsStr::new("candidate"), false) + .expect("source"); + let expected = query_identity(&source).expect("source identity"); + drop(source); + + // An open handle without delete sharing blocks the replacement, and + // the failed attempt leaves both names unchanged. + let held = fixture + .root + .open_file(OsStr::new("ledger"), true) + .expect("held target"); + assert!( + fixture + .root + .replace_file(OsStr::new("candidate"), OsStr::new("ledger")) + .is_err() + ); + assert_eq!(fs::read(fixture.path.join("ledger")).expect("kept"), b"old"); + assert!(fixture.path.join("candidate").exists()); + drop(held); + + fixture + .root + .replace_file(OsStr::new("candidate"), OsStr::new("ledger")) + .expect("replace"); + assert_eq!(fs::read(fixture.path.join("ledger")).expect("new"), b"new"); + assert!(!fixture.path.join("candidate").exists()); + let published = fixture + .root + .open_file(OsStr::new("ledger"), false) + .expect("published"); + assert_eq!( + query_identity(&published) + .expect("identity") + .FileId + .Identifier, + expected.FileId.Identifier + ); + drop(published); + + // A missing source or target, the same name twice, a hard-linked + // source, and a junction are all refused without a rename. + for (source, target) in [("missing", "ledger"), ("ledger", "missing")] { + assert_eq!( + fixture + .root + .replace_file(OsStr::new(source), OsStr::new(target)) + .expect_err("missing name") + .kind(), + io::ErrorKind::NotFound + ); + } + assert!( + fixture + .root + .replace_file(OsStr::new("ledger"), OsStr::new("ledger")) + .is_err() + ); + private_bytes(&fixture, "linked", b"linked"); + fs::hard_link(fixture.path.join("linked"), fixture.path.join("alias")).expect("hard link"); + assert!( + fixture + .root + .replace_file(OsStr::new("linked"), OsStr::new("ledger")) + .is_err() + ); + let outside = tempfile::tempdir().expect("outside"); + create_junction_bounded(&fixture.path.join("junction"), outside.path()).expect("junction"); + assert!( + fixture + .root + .replace_file(OsStr::new("junction"), OsStr::new("ledger")) + .is_err() + ); + assert!( + fixture + .root + .replace_file(OsStr::new("ledger"), OsStr::new("junction")) + .is_err() + ); + assert_eq!(fs::read(fixture.path.join("ledger")).expect("kept"), b"new"); + assert!(fixture.path.join("linked").exists()); + assert!(fixture.path.join("junction").exists()); + } + #[test] fn hard_linked_private_files_never_supply_data() { let fixture = fixture(); diff --git a/docs/README.md b/docs/README.md index c8c13b1..2c06464 100644 --- a/docs/README.md +++ b/docs/README.md @@ -38,6 +38,7 @@ remaining product contracts. | [Provider authentication](provider-authentication.md) | Required subscription/API profiles, provider evidence, and readiness gates | | [Workspace settings](workspace-permissions.md) | Implemented workspace IDs, configuration-only permissions, revisions, audit, and remaining gates | | [Workspace file access](file-access.md) | Native broker, previews, Linux ext4 apply, checkpoint storage, and existing-only recovery | +| [Filesystem qualification plan](filesystem-qualification.md) | Release filesystem matrix and power-loss campaign for checkpoints and apply; plan only, not run | | [Development tools](development-tools.md) | Installed/managed toolchains, runtime grants, outputs, caches, and qualification | | [Command execution](execution.md) | Process-tree runner contract, confinement, trusted runs, toolchain profiles, the run journal, limits, and next increments | | [Agent instructions](agent-instructions.md) | Product priorities, visible SYSTEM prompt, user additions, and request manifests | diff --git a/docs/adr/0053-compact-the-checkpoint-ledger-in-place.md b/docs/adr/0053-compact-the-checkpoint-ledger-in-place.md new file mode 100644 index 0000000..c540b1f --- /dev/null +++ b/docs/adr/0053-compact-the-checkpoint-ledger-in-place.md @@ -0,0 +1,97 @@ +# 0053: Compact the checkpoint ledger in place + +- Status: Accepted +- Date: 2026-11-17 + +## Context + +The replacement ledger (`replacement-v1/ledger.jsonl`) records every checkpoint +operation, deletion, and acknowledgement. Through 0.34.0 it was bounded at +4,096 records and 8 MiB, and no record was ever removed. A successful apply +writes five records and its deletion two, so an installation could perform +about 580 applies with deletion in its lifetime. After that every apply, +restore, and deletion was refused, and the only recovery was to remove the +store by hand. [ADR-0025](0025-restore-and-delete-checkpoints-explicitly.md) +recorded compaction or rotation as future work. + +The ledger is the store's only evidence. Replay must rebuild every retained +entry's state from it. The store accepts only a ledger that a strict replay +validates. An operator can stop other writers to the store's private directory, +but no claim about power-loss behaviour is qualified for either platform, and +Windows directory flushes keep the ADR-0023 limitation. + +## Decision + +The [workspace file access contract](../file-access.md#implemented-ledger-compaction-phase-a5) +owns the details. + +- **Bounds.** The ledger may hold 65,536 records and 64 MiB, with 64 KiB per + record. The store's aggregate quota grows from 64 MiB to 128 MiB so that a + full ledger does not consume the payload budget. The 64-entry bound is + unchanged. +- **Format.** A compacted ledger keeps the original `created` record byte for + byte. A `compacted` record follows as the second record. It holds the + replaced ledger's size and SHA-256, its record count, and the revision of the + last started operation. One `checkpoint_carried` record follows for each + retained entry in recorded order. Each carries that entry's whole recorded + state. Replay rebuilds a carried entry through the ordinary transitions, so a + state that a real ledger cannot reach is refused. A carried entry must be + resolved. Later starts may not go below the recorded revision floor. +- **Triggers.** The trusted `file compact-checkpoints --discard-history` command + compacts on request. Apply, restore, and deletion compact first when the + ledger lacks room for their records. Neither path runs while an operation is + unresolved or a deletion is unfinished. Neither writes anything when nothing + would be dropped or when the rewrite would be larger. +- **Publication.** The store replays the candidate in memory and requires the + retained entries to match exactly. It writes `ledger.compact` with an + exclusive private create, syncs it, and reads it back. It checks that the + live ledger is unchanged and closes its handle. One handle-relative native + rename then replaces `ledger.jsonl`: `renameat` on Linux and a POSIX-semantics + replace-if-exists rename on Windows. The store flushes the directory, reopens + the ledger, and compares its bytes. A failure after the candidate exists + poisons the writer and is reported as uncertain. Nothing is retried. A stale + candidate counts against the quota until the next compaction removes it. +- **Replay cost.** An append validates only its own record against the replayed + state. Operation IDs are indexed, so a full replay is linear in its records. + +## Alternatives considered + +- **Raise the caps only.** This postpones the failure. A higher fixed cap + still ends an installation's use of checkpoints, and replay cost grows with + lifetime use. +- **Rotate to numbered ledgers.** Keeping every replaced ledger preserves the + history but makes the store unbounded, or needs a second eviction rule. The + store would also have to validate a chain of files on every open. +- **Compact only on operator request.** An installation that reaches the cap + would fail an apply without warning. The automatic trigger runs only where + the operation would otherwise be refused, and it uses the same path. +- **Compact into a second store and switch an anchor.** This needs a new + pointer record and its own recovery rules. A single atomic rename within the + existing directory keeps one ledger name and one anchor. +- **Drop retained history too and keep only a summary.** A carried record + already holds everything replay needs. A free-form summary could not be + checked against the ordinary transitions. + +## Consequences + +- An installation can apply, restore, and delete without a lifetime limit, + provided at most 64 entries are retained. +- Deleted entries' history is discarded. Only the replaced ledger's digest, + size, and record count remain. The digest cannot reproduce or verify the + history. Each compaction replaces the previous claim, so the digests form a + chain only if an operator keeps each replaced ledger. +- Operation-ID reuse is detected only against the history the ledger still + holds. The store creates random version-4 IDs. +- Readers older than 0.35.0 refuse a ledger with either new record type. + Downgrading after compaction needs the store to be removed by hand. +- A full open still reads and parses up to 64 MiB, and every admission still + rereads and digests managed files within the 128 MiB quota. +- Neither the rename nor the directory flush is power-loss qualified. The + [filesystem qualification plan](../filesystem-qualification.md) describes + the campaign that has not run. + +## References + +- [Workspace file access](../file-access.md) +- [ADR-0023](0023-store-windows-checkpoints-with-verified-acls.md) +- [ADR-0025](0025-restore-and-delete-checkpoints-explicitly.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index f5b1fde..8f6c7ba 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -67,3 +67,4 @@ meaningful alternative does not need an ADR. | [0050: Interrupt a streamed model request when a turn is cancelled](0050-interrupt-a-streamed-model-request-on-cancellation.md) | Accepted; amended by ADR-0051 | 2026-11-16 | | [0051: Cancel every model request and let an interrupt cancel a CLI turn](0051-cancel-every-model-request-and-interrupt-cli-turns.md) | Accepted | 2026-11-17 | | [0052: Publish rolling testing builds from main](0052-publish-rolling-testing-builds-from-main.md) | Accepted | 2026-11-17 | +| [0053: Compact the checkpoint ledger in place](0053-compact-the-checkpoint-ledger-in-place.md) | Accepted | 2026-11-17 | diff --git a/docs/development.md b/docs/development.md index ab648d3..51cbedf 100644 --- a/docs/development.md +++ b/docs/development.md @@ -88,6 +88,17 @@ ledger keeps its history. If deletion is interrupted, every file operation is refused until the same command is repeated. See the [restore and deletion contract](file-access.md#implemented-restore-and-checkpoint-deletion-phase-a4). +Deletion keeps the deleted entry's ledger records until the ledger is +compacted. Apply, restore, and deletion compact it first when it lacks room. +To compact it on request, discarding every deleted entry's history: + +```text +omgcode --data-dir /private/omgcode-data file compact-checkpoints --discard-history +``` + +Copy `replacement-v1/ledger.jsonl` first if that history is needed. See +[ledger compaction](file-access.md#implemented-ledger-compaction-phase-a5). + ## Build Install Rust through rustup and use a native Windows or Linux development @@ -397,8 +408,8 @@ infer a root, or treat a journal's workspace metadata as a grant. `read`, `list` and `diff` require the read preference. `create` and `mkdir` require the write preference. `apply` and `restore` require both preferences and a supported native mount. Execute remains disabled. The `audit`, `acknowledge`, -`checkpoints`, `acknowledge-checkpoint`, and `delete-checkpoint` commands require -existing workspace settings. +`checkpoints`, `acknowledge-checkpoint`, `delete-checkpoint`, and +`compact-checkpoints` commands require existing workspace settings. They do not require a configured root, workspace registration, or session selection. Chat advertises the read/list tools when the session's workspace enables `model_tools`, the edit tool when `read` and `write` are also enabled, diff --git a/docs/file-access.md b/docs/file-access.md index e836f6c..d83384e 100644 --- a/docs/file-access.md +++ b/docs/file-access.md @@ -198,7 +198,8 @@ optionally by `ready`, with unchanged identities. The first record alone returns an incomplete initialization snapshot. A `ready` record is a recorded claim, not evidence that files or directory entries are durable. -Ledger input has the 8 MiB, 4,096-record, and 64 KiB-per-record bounds below. +Ledger input has the 64 MiB, 65,536-record, and 64 KiB-per-record bounds +below; 0.34.0 and earlier used 8 MiB and 4,096 records. It retains at most 64 operation intents, including failed and acknowledged intents that might have no artifact directory yet. This conservative count does not infer freed capacity from absent files. The first record is `created`. @@ -212,6 +213,9 @@ The remaining action sequence is: | `commit_intended` | Matching `operation_id`. Requires stage preparation. | | `replacement_finished` | Matching `operation_id`, `outcome`, and bounded non-success `code`. Success requires commit intent. Clean failure/conflict is accepted only before commit intent. Uncertainty remains unresolved. | | `replacement_acknowledged` | Matching unresolved `operation_id`. Clears only the recorded blocker; retains progress and outcome and never creates a success result. | +| `checkpoint_deletion_started`, `checkpoint_deleted` | One resolved retained entry's deletion; see [Phase A4](#implemented-restore-and-checkpoint-deletion-phase-a4). | +| `compacted` | Only as the second record. The replaced ledger's `previous` descriptor (nonempty, at most 64 MiB), `previous_records` (1 to 65,536), and the optional `revision_floor` that later starts must not go below. | +| `checkpoint_carried` | Only directly after `compacted` or another carried record. One retained entry's whole recorded state. Replay rebuilds it through the ordinary transitions above, so only a reachable state is accepted, and it must be resolved. Carried revisions are nondecreasing and at most the floor. See [ledger compaction](#implemented-ledger-compaction-phase-a5). | Artifact descriptors have `bytes` and lowercase hexadecimal `sha256`. File payload claims are at most 1 MiB; a manifest claim is nonempty and at most @@ -277,7 +281,7 @@ capacity before creating operation artifacts. It counts every retained intent, including acknowledged attempts, and all managed file lengths. A bounded inventory rejects unknown entries, unsafe objects, missing required files, changed manifests, and corrupt payloads. It revalidates existing payload bytes -on every ready-store admission and inspection. This can read up to the 64 MiB +on every ready-store admission and inspection. This can read up to the 128 MiB store bound per request; this deliberate cost avoids trusting cached evidence. Standalone preparation stops at `checkpoint_prepared`. It returns @@ -503,11 +507,12 @@ objects, and unavailable controls. Native parent/entry checks must protect both creation and reopening. Existing journal helpers alone do not establish that protection. -Replacement storage has at most 64 operation entries and 64 MiB of managed file -bytes, including manifests, the replacement ledger, and the initialization -journal described below. Each manifest is at most 64 KiB. Reserve the worst-case -original, proposed, and staging payloads -(1 MiB each), manifest, and terminal ledger space before preparation. Count +Replacement storage has at most 64 operation entries and 128 MiB of managed +file bytes, including manifests, the replacement ledger, and the initialization +journal described below. The bound was 64 MiB before 0.35.0; it grew by the +64 MiB that the ledger may now use. Each manifest is at most 64 KiB. Reserve +the worst-case original, proposed, and staging payloads (1 MiB each), manifest, +and terminal ledger space before preparation. Count incomplete entries and staging data inside this store against the limits. Bound enumeration and refuse an unknown layout; do not recursively scan an arbitrary tree or ignore unknown files to make capacity available. Only one @@ -520,11 +525,13 @@ is durable only when the backend's reviewed persistence requirements succeed. Any preparation, quota, validation, or sync failure must prevent replacement. Partial preparation remains evidence and can require explicit acknowledgement. -Keep completed, conflicted, and uncertain entries. There is no automatic -expiration, eviction, export, or pruning. At the quota, refuse further -replacements while preserving inspection and permission changes. Only an +Keep completed, conflicted, and uncertain entries. No checkpoint entry is +expired, evicted, exported, or pruned automatically. At the quota, refuse +further replacements while preserving inspection and permission changes. Only an explicit trusted deletion of one resolved entry frees capacity; see -[Phase A4](#implemented-restore-and-checkpoint-deletion-phase-a4). Export needs a +[Phase A4](#implemented-restore-and-checkpoint-deletion-phase-a4). Ledger +compaction drops the history of deleted entries only; see +[Phase A5](#implemented-ledger-compaction-phase-a5). Export needs a later reviewed lifecycle; journal rotation must not discard referenced checkpoints. Checkpoints contain source bytes and can contain secrets. They are private recovery data, never ordinary model context, @@ -569,8 +576,8 @@ Use a separate versioned replacement ledger in the private store. Do not add replacement variants to strict `file-operations-v1.jsonl` or rewrite control-v1 settings or session journals. The new ledger must strictly validate bounded records, store identity, unique operation IDs, contiguous sequence numbers, -state transitions, and exact manifest references. Limit it to 4,096 events, -8 MiB total, and 64 KiB per event, also within the store's aggregate quota. +state transitions, and exact manifest references. Limit it to 65,536 events, +64 MiB total, and 64 KiB per event, also within the store's aggregate quota. Reserve terminal outcome and acknowledgement capacity before admission. Required ordering: @@ -751,7 +758,7 @@ directory, and flushes the store directory. Last, it appends `checkpoint_deleted`. The intent reserves space for that completion record. The ledger keeps the operation's progress, outcome, and acknowledgement, and marks its `retention` as `deleted`. A deleted entry no longer counts toward the -64-entry or 64 MiB caps. +64-entry or 128 MiB caps. Removal never recurses. Linux pins each name with `openat2`, checks a local regular single-link file, calls `unlinkat`, and then requires the pinned inode @@ -773,11 +780,73 @@ an explicit operator request, not an automatic retry. A partial deletion record fails inspection closed, as other partial ledger records do. New deletion records make a ledger unreadable to 0.10.0, which refuses it as an -unknown record. History is never evicted, so the 4,096-record ledger cap still -bounds an installation's lifetime operation count. A successful apply uses five -records and its deletion two. Ledger compaction or rotation is future work. -Deletion is not power-loss qualified on either platform. Windows directory -flushes keep the ADR-0023 limitation. +unknown record. A successful apply uses five records and its deletion two. +Before 0.35.0 history was never evicted, so the 4,096-record cap bounded an +installation's lifetime operation count. Deletion is not power-loss qualified on +either platform. Windows directory flushes keep the ADR-0023 limitation. + +## Implemented ledger compaction (Phase A5) + +Version 0.35.0 raises the ledger bounds to 65,536 records and 64 MiB, raises the +store's aggregate bound to 128 MiB, and compacts the ledger in place. See +[ADR-0053](adr/0053-compact-the-checkpoint-ledger-in-place.md). + +A compacted ledger is the original `created` record byte for byte, one +`compacted` record, and one `checkpoint_carried` record for each retained entry, +in their recorded order. The `compacted` record holds the replaced ledger's size, +SHA-256, and record count, and the revision of the last started operation. Every +record of deleted entries' history is dropped; nothing else keeps it, and the +digest alone cannot reproduce or verify it. `file checkpoints` reports the claim +as `compacted_from`. A later compaction replaces the claim with one for the +ledger it replaced, so the digests form a chain only if an operator kept each +replaced ledger. + +Compaction runs in two ways: + +- `file compact-checkpoints --discard-history` is a trusted operator command. It + needs no workspace binding and opens no workspace file or checkpoint entry. +- Apply, restore, and deletion compact first when the ledger lacks room for + their records: six for an apply or restore and two for a deletion. They do + not compact for the aggregate byte quota. + +Both refuse while an operation is unresolved or a deletion is unfinished; there +is nothing to carry for those states. Both write nothing when the ledger is +already its header, one compaction record, and one record per retained entry, +or when the rewrite would be larger. + +The store builds the candidate in memory and replays it. It must hold exactly +the retained entries' recorded state before anything is written. It writes the +candidate to `replacement-v1/ledger.compact` with an exclusive private create, +syncs it, reads it back, checks that the open ledger still holds the validated +bytes, and closes that handle. Windows refuses to replace a name while a handle +that denies delete sharing is open. One native rename then replaces +`ledger.jsonl`: `renameat` on Linux, and a handle-relative POSIX-semantics +replace-if-exists rename on Windows. Both check that the name refers to the +source afterwards. The store flushes the directory, reopens the ledger, and +compares its bytes with the candidate. The anchor lock is held throughout. + +A failure after the candidate is created poisons the writer and is uncertain. +Either ledger reopens with the same retained state, because the rename is +atomic and both ledgers describe the same entries. A left `ledger.compact` is a +derived copy, never evidence. Inventory counts its bytes against the quota and +otherwise ignores it; ordinary work continues. Only the next compaction removes +it, before writing a new candidate. Nothing is retried automatically. + +Replay is incremental. An append validates its one record against the replayed +state instead of parsing the whole ledger again, and the result equals a full +replay. Operation IDs are indexed, so replay of a full ledger is linear in its +records. A full open still reads and parses the whole ledger, which can be +64 MiB. + +Limits: + +- Deleted entries' history is gone after compaction. An operator who needs it + must copy `ledger.jsonl` before compacting. +- Operation-ID reuse is checked only against the history the ledger still holds. + IDs are random version-4 UUIDs created by the store. +- Readers older than 0.35.0 refuse a compacted ledger as an unknown record. +- Neither the rename nor the directory flush is power-loss qualified. On + Windows the flush keeps the ADR-0023 limitation. ## Private operation journal and recovery diff --git a/docs/filesystem-qualification.md b/docs/filesystem-qualification.md new file mode 100644 index 0000000..f0142d5 --- /dev/null +++ b/docs/filesystem-qualification.md @@ -0,0 +1,146 @@ +# Filesystem and power-loss qualification plan + +Status: plan only. None of this campaign has run. No result in this document +is evidence, and nothing here changes what the +[workspace file access contract](file-access.md) or +[platform support](platform-support.md) claims today. + +## Purpose + +Trusted apply, restore, checkpoint deletion, and ledger compaction run on Linux +ext4 and Windows NTFS. Their native tests show one rename and the ordered syncs +on one tested mount. They do not show which filesystems, kernels, and Windows +builds a release can support, or what the store and workspace hold after a +power loss. This plan defines the campaign that would answer both questions +before any release claim. + +The campaign qualifies the private checkpoint store and trusted publication. It +does not qualify process confinement, the run journal, session journals, or the +derived session index. + +## Operations under test + +Each cell of the matrix exercises the same operations through the trusted CLI: + +| Operation | Native steps that matter | +| --- | --- | +| Store initialization | Private directory creation, initialization journal, ledger creation, directory syncs | +| Apply | Payload and manifest writes, stage creation, commit-intent record, one rename onto the target, file and parent syncs, outcome record | +| Restore | The apply steps with the retained original as the proposed content | +| Checkpoint deletion | Deletion-intent record, removal of each fixed artifact name, entry directory removal, outcome record | +| Ledger compaction | Candidate create and sync, one rename onto `ledger.jsonl`, directory sync, reopen and compare | +| Acknowledgement | One appended record and its sync | + +## Release filesystem matrix + +A cell passes only when every functional case below passes on it. A cell that +the store or apply must refuse passes only when every refusal is the documented +error and nothing is written to the workspace or the store. + +| Platform | Filesystem and mount | Expected result | +| --- | --- | --- | +| Ubuntu LTS (current and previous), Fedora (current) | ext4, default options, local block device | Supported candidate | +| Same distributions | ext4 with `data=journal`, and with `nodelalloc` | Supported candidate; record any difference | +| Same distributions | ext4 on LVM and on dm-crypt | Supported candidate | +| Same distributions | XFS, Btrfs, tmpfs, overlayfs | Apply refuses; store behaviour recorded | +| Same distributions | NFS, SMB/CIFS, FUSE | Apply and store refuse | +| WSL 2 | ext4 virtual disk | Supported candidate; WSL results do not qualify a native Linux host | +| WSL 2 | drvfs (`/mnt/`) | Apply and store refuse | +| Windows 11 (current and previous feature update), Windows Server 2025 | NTFS on a fixed local disk | Supported candidate | +| Same builds | NTFS on BitLocker | Supported candidate | +| Same builds | ReFS (including a Dev Drive), FAT32, exFAT, removable media | Apply and store refuse | +| Same builds | SMB share, mapped drive, OneDrive placeholder | Apply and store refuse | + +Each run records the exact OS build, kernel, filesystem tools version, mount +options or volume flags, storage device model and write-cache setting, and the +`omgcode --version` output with the commit. + +### Functional cases per cell + +- The existing native suites for the platform crate, `checkpoint_storage`, + `checkpoint_lifecycle`, and the replacement tests pass unchanged on that + mount, with the data root and workspace both on it. +- Data root and workspace on different volumes: the store works, and apply + refuses cross-volume staging as documented. +- Security metadata: owner, group, mode, ACLs, and the refused attribute set + match the contract on both sides of an apply and a restore. +- Ledger compaction at the record cap, at the byte cap, and on request leaves + the retained entries' replayed state unchanged. +- A store reaching the 128 MiB aggregate quota refuses further work without + losing inspection. + +## Power-loss campaign + +### Method + +Two methods are needed because neither alone is enough. + +1. **Block-level replay (Linux).** Record each operation's writes with + `dm-log-writes`, then replay every prefix that ends at a flush or FUA + boundary onto a fresh device, and also a sample of prefixes between them. + Mount each replayed image and run the checks below. This shows behaviour + at every ordering point the kernel can expose. It does not show device + cache behaviour. +2. **Physical power cut (Linux and Windows).** Use real machines with the + operation running in a loop and a controllable power switch that removes + power from the whole machine, not only the guest. Cut power at random times + weighted towards the rename and sync calls. The store's fault points exist + only in test builds, so targeting needs a separate instrumented build that + logs a timestamp before each boundary; the shipped binary must also be cut + untargeted, because instrumentation changes timing. Use at least + one consumer SSD with a volatile write cache and one device with power-loss + protection. Virtual machine resets alone do not count, because a hypervisor + may keep host-side caches. + +Windows has no equivalent of `dm-log-writes` in the inbox tooling. Its evidence +comes only from physical cuts. + +### Checks after each restart + +- The store opens, or refuses with a documented error. It never accepts a + ledger that a strict replay rejects, and it never repairs one. +- Every ledger replays to a state that the operation could have produced: + before it, after it, or an unresolved or uncertain operation that inspection + reports. A torn final record is refused, not ignored. +- A compaction leaves either the old ledger or the new ledger at + `ledger.jsonl`, each replaying to the same retained entries. A leftover + `ledger.compact` is counted and ignored. +- A workspace target holds exactly the expected bytes or exactly the proposed + bytes. Any other content is a failure, even if the ledger reports the + operation as uncertain. +- When the ledger records success, the target holds the proposed bytes and the + checkpoint's original and proposed payloads match their manifest. +- When the ledger records a finished deletion, the entry directory is absent. + +### Volume and stopping rule + +For each supported candidate cell, run every operation until at least 1,000 +physical cuts have landed inside it, and replay every flush-boundary prefix. +Any single failure of the checks stops qualification of that cell until the +cause is understood and fixed, and the full count starts again. + +### Known questions the campaign must settle + +- Whether the Windows directory flush used after a rename persists the new + entry. Microsoft documents no contract for it (ADR-0023), so the result can + only be a measured observation, not a guarantee. +- Whether ext4 with default options needs a parent sync after the compaction + rename, beyond the one the store already performs, on every tested kernel. +- Whether a device that ignores flushes can produce a state the checks above + reject. Such a device would be recorded as unsupported, not worked around. + +## Evidence and reporting + +Store each run's raw logs, replay images or their hashes, and the summary table +in the release evidence location that Phase G defines. Report counts of cuts, +outcomes per check, and every failure. Do not round partial runs up to a pass. +A qualified cell changes [platform support](platform-support.md) and the +file-access contract in the same change, with an ADR when a claim is added. + +## Not covered + +- Concurrent writers to the workspace target. The contract requires the + operator to stop them; the campaign keeps them stopped. +- Media corruption, bit rot, and firmware faults outside power loss. +- Recovery of history that compaction discarded. +- macOS, which is outside the first-release target. diff --git a/docs/platform-support.md b/docs/platform-support.md index ffc5f27..e7cd719 100644 --- a/docs/platform-support.md +++ b/docs/platform-support.md @@ -78,7 +78,9 @@ is not a supported-distribution matrix. publication, security-metadata preservation, and checkpoint/directory persistence evidence. Native apply tests exercise one rename and ordered syncs on the tested mount. They do not qualify a release filesystem matrix - or physical power-loss behavior. + or physical power-loss behavior. The + [filesystem qualification plan](filesystem-qualification.md) defines that + campaign; it has not run. Windows uses exact per-user checkpoint ACLs and a failing directory flush. Microsoft gives no contract for that flush, so directory-entry durability remains unqualified. There is no weaker fallback. diff --git a/docs/testing-standards.md b/docs/testing-standards.md index 96cd1a1..2144350 100644 --- a/docs/testing-standards.md +++ b/docs/testing-standards.md @@ -544,7 +544,7 @@ commit/sync boundaries; sleeps and pre-operation path swaps are insufficient. | Preconditions | Stale digest, stale size, and a changed entry observed before commit intent cause a controlled conflict, including swaps with equal bytes. A mismatch after intent stops the attempt and stays unresolved. Reject invalid UTF-8 and unsafe proposed-source objects. Equal proposed bytes cause no replacement or checkpoint. Check exact line endings and byte counts. | | Concurrent change | In-place writes and entry swaps with mismatches observable at the final check produce conflicts and leave workspace entries unchanged by the broker. Preserve the independent edit. An A-to-B-to-A write can go undetected when all checked metadata matches again. Exercise that case and changes after the check; report the documented non-CAS limit rather than asserting isolation. | | Native objects | Links, junctions/reparse points, hard links, devices, mount crossings, invalid native paths, unsupported metadata, and cross-filesystem staging refuse replacement. Verify stage and parent substitution checks. | -| Checkpoints | Exact prior/proposed bytes and digests, exclusive-name collisions, private modes/ACLs, 1 MiB payload bounds, 64 KiB manifests, 64 entries, aggregate 64 MiB quota, and bounded unknown-layout refusal. Count incomplete artifacts; do not evict evidence. | +| Checkpoints | Exact prior/proposed bytes and digests, exclusive-name collisions, private modes/ACLs, 1 MiB payload bounds, 64 KiB manifests, 64 entries, aggregate 128 MiB quota, and bounded unknown-layout refusal. Count incomplete artifacts; do not evict evidence. Ledger compaction keeps every retained entry's replayed state, drops only deleted entries' history, refuses unresolved work, runs before apply or deletion on a full ledger, and leaves a valid ledger at every injected fault. | | First use | Upgraded installations with no replacement state keep ordinary reads usable without creating replacement files. Interrupt each initialization/sync boundary. Validate the bounded initializing/ready anchor, reject orphaned or partial stores, and refuse to recreate a missing ledger after initialization. Settings changes remain usable. | | Publication | Observe a prepared durable checkpoint before the commit attempt. Preserve required security metadata. Assert one native commit attempt and verify both checkpoint payloads remain intact. No truncate, copy/delete, or weaker fallback. | | Failure and reopen | Inject failures at every intent, payload, manifest, stage, native commit, file/directory sync, outcome, and acknowledgement boundary. Inspect the final ledger and disk state. Post-commit uncertainty never becomes clean failure or success without evidence. |