Repository navigation
feat(task): resume from a checked state file - #209
Draft
greenhat616 wants to merge 1 commit into
Draft
greenhat616 wants to merge 1 commit into
greenhat616 wants to merge 1 commit into
Conversation
greenhat616
force-pushed
the
feat/hardening-44-resume-engine
branch
from
November 13, 2026 07:44
d15eecd to
56d128a
Compare
greenhat616
marked this pull request as draft
November 13, 2026 08:55
A task with resume on, still crate-internal until the next change, now
resumes when it finds a state file it did not just create. It checks
the pair before it changes anything: the partial file must exist, the
state file must read cleanly, and the header must match the metadata
the adapter fetches again for this task. Then it verifies the CRC of
every kept block against the partial file.
A pair that cannot resume ends the task with ResumeRejected and leaves
both files exactly as they were. Otherwise the task writes the cleaned
records back, sizes the partial file, and downloads only the ranges
that are missing. Progress starts at the kept bytes, and a fully kept
file makes no request at all.
The result types are public now, because a public error and TaskInfo
cannot carry crate-private ones: ResumeReport, DroppedRecord,
DropReason, RejectReason, DownloadError::ResumeRejected,
TaskInfo::{resumable, resumed} and IoOp::Read. Every one is added to a
non-exhaustive type, and none can occur until resuming can be switched
on.
greenhat616
force-pushed
the
feat/hardening-44-resume-engine
branch
from
November 13, 2026 22:25
56d128a to
789fc2c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
C20b (T21), the second of three commits of C20 (resume) and the seventh commit of PR-9d in the download strategy hardening stack. It is stacked on #208 (C20a, the reader and checks), its base branch. C20c will make
Resumepublic, with docs and end-to-end tests. The design notes are in §11.5.5, §11.5.9, §11.5.10 and §14.30.2.What
Public result types (lead decision)
DownloadErroris public, so its newResumeRejectedvariant cannot carry a crate-private reason. The same holds forTaskInfo::resumed. So these are public now:ResumeReport,DroppedRecord,DropReasonandRejectReason, re-exported frombolt_load::task;DownloadError::ResumeRejected { reason, state_file }, shown ascannot resume from <state file>: <reason>;TaskInfo::{resumable, resumed};IoOp::Read.They are inert until C20c:
resumedis alwaysNone,resumableis alwaysfalse, and no task fails withResumeRejected. Their docs say so. The alternative, internal stand-ins swapped out in C20c, was rejected as throwaway plumbing.When a task resumes
An
Ontask whose state file existed before it took the lock and is not empty enters a new phase, Checking (B2). B2 changes neither file. Any other task starts as before, and an empty state file means a new start.Resume order (§11.5.5, §11.5.10)
Cancellation is checked between steps and is never raced against a file step.
ResumeRejected(MissingPartial).BadHeaderandOversizedare rejections; a read error isIo { Read }..meta(...). This is the implementer's reading of §14.27, agreed by the lead.Io { Read }with the block's range; onewarn!is logged per dropped record.Io { Write }), then sets the partial file's size (Io { Allocate }). Making the sizing a separate step is the implementer's decision; it shows in tests that the write-back comes first.How B2 ends (§11.5.9)
Phase C is entered before the first change to the state file, so B2 needs no
cutflag. Every failure from C on keeps a valid header plus a prefix of verified records, and reportskept_for_resume.Seeding
Info and fallback
resumableis true when the task keeps a state file, andresumedholds the report. A fallback to one connection clears both. The report moves into the published info once; snapshots share it through the existingArc<TaskInfo>and never copy it.Docs
task-api-spec §4.3 step 5, TASK-8 and the history notes describe B2 and the comparison against the adapter's own metadata.
Not breaking
#[non_exhaustive].DownloadError,IoOpandTaskInfoalready were.matches!.Resumestays crate-internal, so no user task takes any new path.Tests
task/tests/resume_from.rsruns real tasks on real files with step hooks. It covers:On" table.Mutations: 26 run, 25 caught. The one survivor drops the marking of kept blocks as recorded, and it is equivalent at the task level: kept blocks are never written, so they can never be recorded twice. A unit test covers the method itself.
Review
Reviewed with
/ccg:review, using the codex backend only (a single-model review).retrieve_metadid not race cancellation, so a stalled adapter could leave a cancelled task holding the lock. It is now in the same cancellable block, with a test.info.clone()deep-copied the report. The info now moves once.Checks
All on
+nightly-2026-11-06, with--no-fail-fast. Clippy allowsunnecessary_lazy_evaluationsuntil #183 merges.cargo fmt --all -- --check.-D warnings.cargo test --workspace --all-features --locked: 28 suites, 954 passed, 1 ignored (the benchmark).cargo test --workspace --locked: 28 suites, 883 passed, 1 ignored.RUSTDOCFLAGS=-Dwarnings cargo doc --no-deps --all-features -p bolt-load: the same 18 errors as its base.