OXYGENHUB

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