Repository navigation
docs(task): design the state file and resume - #200
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
docs/hardening-36-resume-design
branch
from
November 13, 2026 07:44
4c72bc0 to
ba270dd
Compare
greenhat616
marked this pull request as draft
November 13, 2026 08:55
Design §11.5 for T21. The maintainer decided D15 to D19 on 2026-11-09. - The task does the mechanism and the caller the policy. Resume::On resumes or fails with ResumeRejected, and starting over belongs above the task. - An advisory lock on <dest>.boltload covers the whole task, for Off too (#152). - The state file is binary, with a header CRC and fixed-size records that each carry a CRC. - Each 1 MiB block of the partial file has a CRC32C that is checked on resume, and a block that fails is downloaded again. The design also covers: - crash-safe orderings for every path; - a retention table by phase; - the lead's answers to the remaining questions; - the changes to task-api-spec (STATUS-6, STATUS-12, STATUS-13, TASK-8, the initialization sequence); - the split into C31, C34, C32, C33 and C20. Tamper resistance is a non-goal.
greenhat616
force-pushed
the
docs/hardening-36-resume-design
branch
from
November 13, 2026 22:26
ba270dd to
81a5fa9
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.
The design for T21, resume, the last part of PR-9 in the download strategy hardening stack. This PR changes docs only: no code. It is stacked on #199, which is its base branch. The new section is design §11.5. task-api-spec.md and tasks.md change to match.
Decisions
Maintainer, 2026-11-09 (§3)
TaskBuilder::resume(Resume)withResume { Off (default), On }. The state file is<dest>.boltload, and all its I/O happens inInitializing.ResumeRejected { reason }without changing either file.Onwith no state file, or an empty one, is a fresh start.Offtasks too. This fixes 同一目标路径的多个任务共用 .downloading 临时文件 #152. It usesfs4.Threat model
Resume only has to detect when the state file and the partial file disagree, and accidental corruption. Tamper resistance, signing and MACs are explicit non-goals. A future client may sign the state, and the task then reads it unsigned.
Lead (§11.5.12)
TaskInfo::resumabletells the caller whether anOntask is actually checkpointing.Offon a filesystem without locks warns and goes on unlocked;Onfails.resumefeature.What §11.5 specifies
kept_for_resumeis set only for a usable pair. Panics follow the same table (TASK-8).ResumeReportandDroppedRecord { position, reason, range };full_streamare never checkpointed. A one-connectionOntask runs on the concurrent engine with conditional ranges.Split (§11.5.13 and the tasks.md table)
fix(task)!: lock a destination for the whole task. It fixes 同一目标路径的多个任务共用 .downloading 临时文件 #152.feat(core): carry the If-Range validator in adapter meta.feat(task): checksum and sync written blocks at checkpoints, including a bench of the sync and CRC costs.feat(task): write a state file while downloading. It stays internal and only writes.feat(task): resume from a checked state file, which adds the public API.Review
The design was reviewed before any code with
/ccg:review, using the codex backend only (a single-model review).Round 1 (52). It found nine Majors, among them:
The maintainer then revised D16 and D18 and added D19.
Round 2 (80). It found two Majors in completion: the state was not invalidated before it was deleted, and there was no phase after the rename. Both are fixed with phase P.
Round 3: PASS (90/100). Its three Minors and two suggestions are applied: the completion outcomes split per step and for power loss, the writeback phase, TASK-8 following the phase table, the §4.3 initialization order, and the crash-loss wording.