[03/03] service-backup: stage and restore BackupSets idempotently with service-owned validation #18

Activity

1. chrischeng-c4

   added

   priority:p1Do nextDo next

   phase:created

   agent::claude-code

   lib:service-backup

   type:change

   epic:3029

   depends-on:3035

   on Jul 30, 2026
2. chrischeng-c4

   added this to the service-backup: versioned BackupSet lifecycle - streaming, atomic publication, restart-safe restore milestone on Aug 30, 2026
3. chrischeng-c4

   transferred this issue fromfaberline/axiomon Sep 27, 2026
4. chrischeng-c4 commented on Oct 23, 2026

   

   chrischeng-c4

   on Oct 23, 2026

   ContributorAuthor

   More actions

   Scope of this spec: the first PR of #18 only — R3 and R6 as pure domain logic (the persisted restore progress ledger and its transitions), plus the part of AC2 that a pure state machine can prove. Manifest resolution (R1), disk staging and download (R2), the service adapter (R4), readiness wiring (R5) and AC1/AC3/AC4 need later specs on this issue, after #16's streaming traits and BackupSetV1 are on main. This PR adds types only, performs no I/O, and changes no existing public item. It does not depend on #16: its inputs are plain strings and integers.

   Goal

   A restore that is interrupted at any step must resume without re-applying finished work and without mistaking a half-written file for a finished one. Add one pure domain type, RestoreLedger, that records which set is being restored and the state of each artifact, enforces the legal transitions, serializes to one canonical JSON document for the later staging code to persist, and refuses to start a different set over an in-progress or committed restore. Later PRs of #18 persist it atomically (through storage-durable) and drive it from the download, verify and apply steps.

   Acceptance

   • New domain files under crates/service-backup/src/domain/ (one main type per file): restore_ledger.rs (RestoreLedger, ArtifactStage, RestorePhase), restore_ledger_error.rs (RestoreLedgerError, a thiserror enum with one variant per failure below). Declare them in src/domain.rs and re-export from src/lib.rs next to the current exports.
   • RestoreLedger::begin(set_id: &str, manifest_digest: &str, artifacts: &[(String, u64)]) -> Result<Self, RestoreLedgerError>: set_id is non-empty, at most 128 bytes, of [A-Za-z0-9._-]; manifest_digest is "sha256:" plus 64 lowercase hex chars; artifacts is a non-empty list of (name, size_bytes) with unique non-empty names, at most 1024 entries. Every artifact starts at ArtifactStage::Pending, the phase at RestorePhase::Staging.
   • ArtifactStage is Pending, Verified, Applied; RestorePhase is Staging, Applying, Committed. Transitions, each a method returning Result<(), RestoreLedgerError>: mark_verified(name) (Pending → Verified; repeating it on Verified or Applied is Ok and changes nothing), begin_apply() (Staging → Applying, only when every artifact is Verified; repeating it while Applying is Ok), mark_applied(name) (only in Applying, Verified → Applied; repeating on Applied is Ok), commit() (Applying → Committed, only when every artifact is Applied; repeating on Committed is Ok). An unknown artifact name, a skipped step, or a transition from the wrong phase returns the matching error variant and leaves the ledger unchanged.
   • RestoreLedger::resume(&self, set_id: &str, manifest_digest: &str) -> Result<ResumePoint, RestoreLedgerError> with ResumePoint::{Fresh, Continue, AlreadyCommitted}: the same set_id and manifest_digest give AlreadyCommitted when Committed, else Continue; a different set_id, or the same set_id with another digest (a replaced manifest), returns RestoreLedgerError::ConflictingSet carrying both ids, and never changes the ledger. (Fresh is returned by a free function RestoreLedger::resume_or_begin(existing: Option<Self>, set_id, manifest_digest, artifacts) -> Result<(Self, ResumePoint), RestoreLedgerError> when existing is None.)
   • pending(&self) -> Vec<&str> (artifacts still Pending, in manifest order), unapplied(&self) -> Vec<&str> (artifacts not yet Applied, in manifest order), phase(), set_id(), manifest_digest() accessors.
   • to_json(&self) -> Vec<u8> writes compact JSON with a "version": 1 field, artifacts in their original order; RestoreLedger::from_json(bytes: &[u8]) -> Result<Self, RestoreLedgerError> refuses input over 1 MiB before parsing, unknown fields, unsupported versions, and any document that violates the invariants of begin or of the phase (for example Committed with an artifact not Applied, or Staging with an Applied artifact). Serde uses camelCase and deny_unknown_fields. from_json(to_json(x)) round-trips.
   • Crash model test: for every prefix of the full transition sequence of a 3-artifact ledger, serialize, reload, resume with the same ids, replay the whole sequence (idempotent repeats allowed), and reach Committed with each artifact applied exactly once. "Applied exactly once" is proved by counting the mark_applied calls that changed state.
   • No new dependency: use serde and serde_json as already declared in crates/service-backup/Cargo.toml.
   • New test module crates/service-backup/tests/it/restore_ledger.rs, registered in tests/it/main.rs without a feature gate, with one case each for: the valid full path; each invalid begin input; each illegal transition; idempotent repeats; ConflictingSet for a different set and for a replaced manifest; AlreadyCommitted replay; the JSON round trip; each rejected JSON document (oversized, unknown field, version 2, inconsistent phase); and the crash-prefix test above.

   Never

   • Do not change BackupSink, SnapshotSource, run_backup_once, fetch_backup_object, or any sink/source adapter.
   • Do not do I/O, read clocks or use randomness in the new domain files (std::fs, SystemTime::now, Utc::now); ddd.toml [policy.domain] forbids them. The later infrastructure PR owns persistence.
   • Do not derive schemars::JsonSchema on the new types, and do not change tests/it/schema_golden.rs or tests/it/wire_golden.rs.
   • Do not depend on BackupSetV1 or any other unmerged [01/03] service-backup: define streaming BackupSetV1 manifest and single-object compatibility #16 or [02/03] service-backup: publish immutable BackupSets manifest-last and retain complete sets #17 type.
   • Do not add a dependency to crates/service-backup/Cargo.toml.
   • Do not edit README.md, llms.txt, src/api/llm.rs, or docs/ in this PR.
   • Do not touch other crates, ddd.toml, or CI.

   Gate

   cargo test --locked -p service-backup
   cargo test --locked -p service-backup --all-features
   cargo clippy --locked -p service-backup --all-features --all-targets -- -D warnings
   cargo fmt -p service-backup -- --check
5. chrischeng-c4

   added

   todoReady for the work step of the issue loopReady for the work step of the issue loop

   doingThe work step of the issue loop is on itThe work step of the issue loop is on it

   and removed

   priority:p1Do nextDo next

   todoReady for the work step of the issue loopReady for the work step of the issue loop

   on Oct 24, 2026
6. chrischeng-c4 commented on Oct 24, 2026

   

   chrischeng-c4

   on Oct 24, 2026

   ContributorAuthor

   More actions

   Work submitted in #64; waiting for required CI on the current head.
7. chrischeng-c4

   modified the milestones: service-backup: versioned BackupSet lifecycle - streaming, atomic publication, restart-safe restore, core@0.7.0 on Oct 24, 2026