Spec 0.6d: checkpoint format and loading rule as implemented cfb7d414eae6
- Author
- Andy McCall @andymccall <[email protected]>
- When
- · 2026-09-26 22:10 UTC
- Signature
- ✔ signed by Andy McCall
- Hash
cfb7d414eae61c2faac3a3b884f4a22e1835910ea7e1672863079312fde409b2- Depends on
- 315167f3e208 ff0af1ee299d
- Depended on by
- afaba5f1306d b3c5a59a875a
- In bookmarks
- agents-in-readme bare-hashes carried-not-removed carry-identical doctor-trust identical-sides keyless-tags main merge-remote-bookmark only-help-103 paths-for-resolutions-and-amend push-notes show-stat subrepo-pin-state switch-says
- In tags
- v0.1.0 v0.10.0 v0.11.0 v0.2.0 v0.3.0 v0.3.1 v0.4.0 v0.4.1 v0.4.2 v0.4.3 v0.4.4 v0.4.5 v0.4.6 v0.5.0 v0.5.1 v0.6.0 v0.7.0 v0.8.0 v0.9.0
- Edits
- 6 atoms, 0 tree operations, 1 file
Browse the tree at this change
modified docs/spec.md +14 −7
| … | 1 unchanged lines |
||
| 2 | 2 | ||
| 3 | 3 | | | | |
|
| 4 | 4 | |---|---| |
|
| 5 | - | | **Status** | Draft 0.6c | |
|
| 5 | + | | **Status** | Draft 0.6d | |
|
| 6 | 6 | | **Format version** | 1 | |
|
| 7 | 7 | | **Date** | 2026-09-26 | |
|
| 8 | 8 | | **Audience** | Implementers, security reviewers, and contributors | |
|
| … | 404 unchanged lines |
||
| 413 | 413 | ``` |
|
| 414 | 414 | Checkpoint { |
|
| 415 | 415 | version [0]: 1 |
|
| 416 | - | heads [1]: [ChangeHash] |
|
| 417 | - | tree [2]: [ { node, kind, mode, placements: [(parent, name)], content: ObjectRef /* blob */, graph: ObjectRef /* blob */ } ] |
|
| 418 | - | conflicted [3]: bool |
|
| 416 | + | heads [1]: [ChangeHash] // sorted |
|
| 417 | + | count [2]: u64 // changes in the state |
|
| 418 | + | payload [3]: ObjectRef // blob holding the serialized state |
|
| 419 | 419 | } |
|
| 420 | 420 | ``` |
|
| 421 | 421 | ||
| 422 | - | `content` is the live content of the node as a blob (with markers if conflicted). `graph` is a blob containing the file graph in run-length form: a sequence of `(ChangeHash, from, to, live: bool)` runs plus explicit edges wherever the graph departs from a single chain. The graph blob is sufficient to apply any further change without consulting history. Tombstones are retained because future changes may anchor to them. |
|
| 422 | + | The payload blob is a deterministic CBOR map `{0: version, 1: changes, 2: tree, 3: files, 4: replaces}`: |
|
| 423 | + | ||
| 424 | + | - `changes`: for every change in the state, `[hash, change id, [deps], message, hlc wall, hlc logical, kind, author]`, sorted by hash. Operations are not repeated: once applied they live in the graphs, and the store keeps the change objects. |
|
| 425 | + | - `tree`: the tree graph, `{0: nodes [[node, kind, introducer]], 1: placements [[change, index, node, parent, name]], 2: retired placements [[change, index, [deleters]]], 3: modes [[change, index, node, mode]], 4: retired modes [[change, index, [deleters]]]}`. |
|
| 426 | + | - `files`: `[[node, file graph]]` where a file graph is `{0: atoms [[change, index, content or null, [deleters]]], 1: edges [[from, to]]}` with vertices encoded as in §5.5 (`0` start, `1` end, `[hash, index]`). Tombstones keep their content so conflicts can show deleted context. |
|
| 427 | + | - `replaces`: `[[node, [[change, old blob or null, new blob or null]]]]`. |
|
| 423 | 428 | ||
| 424 | - | A checkpoint is valid only if it is bit-for-bit reproducible from its heads. Implementations MUST create a checkpoint at every tag, MUST create one at least every `core.checkpoint-interval` changes (default 256) along each bookmark, and MAY discard any checkpoint at any time. Clients fetching a state SHOULD request the nearest checkpoint and replay only the difference. |
|
| 429 | + | A checkpoint is valid only if it is bit-for-bit reproducible from its heads. Implementations MUST create one at least every `core.checkpoint-interval` changes (default 256) along each bookmark and MAY discard any checkpoint at any time; keeping only the newest per bookmark is enough. To load a state from heads `H`, a client walks from `H` and stops at any change the checkpoint contains; the checkpoint applies iff every one of its heads was reached, since a state is closed downward, and the walk yields exactly the changes to replay on top. Clients fetching a state SHOULD request the nearest checkpoint and replay only the difference. |
|
| 425 | 430 | ||
| 426 | 431 | ## 12. Operation log, workspaces, and the working copy |
|
| 427 | 432 | ||
| … | 406 unchanged lines |
||
| 834 | 839 | ||
| 835 | 840 | --- |
|
| 836 | 841 | ||
| 837 | - | *Changelog.* Draft 0.6c (2026-09-26): §23 import defines the base as the union of parent states, records author and commit trailers, skips submodules, and states the closure-versus-snapshot difference. |
|
| 842 | + | *Changelog.* Draft 0.6d (2026-09-27): §11 checkpoint format as implemented, with the loading rule. |
|
| 843 | + | ||
| 844 | + | Draft 0.6c (2026-09-26): §23 import defines the base as the union of parent states, records author and commit trailers, skips submodules, and states the closure-versus-snapshot difference. |
|
| 838 | 845 | ||
| 839 | 846 | Draft 0.6b (2026-09-26): §8.4 allows refusing a rewrite whose orphaned references have no specified conflict shape, defines removal, and notes the signature consequence. |
|
| 840 | 847 | ||
| … | 19 unchanged lines |