Reference
Revision history and recovery
History/6 replay, legacy readers, selectors, CAS and stale-write recovery.
Explore as .gram
Text
# Revision history and recovery
## Current journal
The current writer stores the latest `@gram 2` source at the front of the file and a `@gram-history 6` trailer after it. Revision zero captures the initial source; each later revision has runtime-recorded metadata and reverse line hunks that reconstruct the prior state. A SHA-256 chain binds each revision header and reconstructed source. Core audits the complete journal before writes. History bytes and revision metadata are runtime-owned; do not author or hand-edit the trailer.
`gram_state` selects one state by exactly one of `revision`, `recorded_at` or `effective_at`. A historical MCP read includes `at` and cites the current document CAS identity separately. `gram_changes` is an incremental revision summary; `gram_range` is a bounded event/range view; neither replaces full Core replay. `gram_read` without a selector reads the current document outline/section, not a replay.
## CAS and idempotent patching
Before a patch, obtain the current `base_revision` and artifact `hash` from a current document result. Send both as `base_revision` and `expected_hash`, plus a unique `request_id` of 1–128 characters and nonempty operations. The request ID is the idempotency key for that exact intent: reuse it only when retrying the identical request after an uncertain response. A different payload with the same ID is `E_REQUEST_REUSE`. Create has `base_revision: null` and does not accept a request ID.
If the response is lost, ask Core for the receipt or retry only the identical request with the same ID. A successful receipt can be replayed; if the outcome is unknown, do not invent success or change the request. On stale CAS/conflict, reread current revision and hash, reconsider the intended change against that state, and submit a new request ID.
## Legacy distinctions
`@gram 1` and History/1–5 are legacy read inputs, not current output. Current writes use @gram 2 and History/6. Core's explicit History/6 migration preserves revisions and metadata. Mutating older history or @gram 1 follows Core's implicit migration rules, may renumber legacy rich-node IDs, and reports migration provenance. Bare legacy JSON in a rich block is rejected with `E_MIGRATION`; legacy JSON-rich is not current gram-rich/1 interchange. History/5 was a former writer format and is not a current migration target for History/1–4.
For an ambiguous write, retrieve the receipt before retrying; for a stale cursor/read, reacquire current page/state before proceeding. Never edit the journal trailer directly.
Source
.gram language specification
https://github.com/clab-one/thegram-format/blob/main/spec/language.mdCurrent History/6 specification
https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.mdr0 ·
History/6 replay, legacy readers, selectors, CAS and stale-write recovery.
0Needs attention
Source2
.gram language specification
Current History/6 specification
r0 source2999 bytes ·
sha256:5fd5cb7e4b6ff7642f863fdee36b28b27009958512441dfeb7dac3563281d6c5@gram 2
doc portal-reference-history-guide
t Revision history and recovery
d History/6 replay, legacy readers, selectors, CAS and stale-write recovery.
::body
# Revision history and recovery
## Current journal
The current writer stores the latest `@gram 2` source at the front of the file and a `@gram-history 6` trailer after it. Revision zero captures the initial source; each later revision has runtime-recorded metadata and reverse line hunks that reconstruct the prior state. A SHA-256 chain binds each revision header and reconstructed source. Core audits the complete journal before writes. History bytes and revision metadata are runtime-owned; do not author or hand-edit the trailer.
`gram_state` selects one state by exactly one of `revision`, `recorded_at` or `effective_at`. A historical MCP read includes `at` and cites the current document CAS identity separately. `gram_changes` is an incremental revision summary; `gram_range` is a bounded event/range view; neither replaces full Core replay. `gram_read` without a selector reads the current document outline/section, not a replay.
## CAS and idempotent patching
Before a patch, obtain the current `base_revision` and artifact `hash` from a current document result. Send both as `base_revision` and `expected_hash`, plus a unique `request_id` of 1–128 characters and nonempty operations. The request ID is the idempotency key for that exact intent: reuse it only when retrying the identical request after an uncertain response. A different payload with the same ID is `E_REQUEST_REUSE`. Create has `base_revision: null` and does not accept a request ID.
If the response is lost, ask Core for the receipt or retry only the identical request with the same ID. A successful receipt can be replayed; if the outcome is unknown, do not invent success or change the request. On stale CAS/conflict, reread current revision and hash, reconsider the intended change against that state, and submit a new request ID.
## Legacy distinctions
`@gram 1` and History/1–5 are legacy read inputs, not current output. Current writes use @gram 2 and History/6. Core's explicit History/6 migration preserves revisions and metadata. Mutating older history or @gram 1 follows Core's implicit migration rules, may renumber legacy rich-node IDs, and reports migration provenance. Bare legacy JSON in a rich block is rejected with `E_MIGRATION`; legacy JSON-rich is not current gram-rich/1 interchange. History/5 was a former writer format and is not a current migration target for History/1–4.
For an ambiguous write, retrieve the receipt before retrying; for a stale cursor/read, reacquire current page/state before proceeding. Never edit the journal trailer directly.
::end
SRC format-language
ref https://github.com/clab-one/thegram-format/blob/main/spec/language.md
t .gram language specification
SRC format-history6
ref https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md
t Current History/6 specification