Reference
Revision history and recovery
History/6 replay, legacy readers, selectors, CAS and stale-write recovery.
Explore as .gram
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 a gram_patch response is lost, the public tools provide no standalone receipt lookup; resend the exact same intent with the same request ID so Core can replay its receipt. If the outcome remains unknown, do not invent success or change the request. A gram_create has no request ID; read the target path before further action after a lost response. 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 patch, retry the exact same intent and request ID; for a create, read the target path first. For a stale cursor/read, reacquire current page/state before proceeding. Never edit the journal trailer directly.
Source
r3 · · Portal-reference-finalize
History/6 replay, legacy readers, selectors, CAS and stale-write recovery.
Source3
sha256:3016646205124dac6dd2b7cabc3883a8cace7ff4f71f391c714578196a1c0ac3@gram 2
doc portal-reference-history-guide
t Revision history and recovery
d History/6 replay, legacy readers, selectors, CAS and stale-write recovery.
view document
::rich
# 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 a `gram_patch` response is lost, the public tools provide no standalone receipt lookup; resend the exact same intent with the same request ID so Core can replay its receipt. If the outcome remains unknown, do not invent success or change the request. A `gram_create` has no request ID; read the target path before further action after a lost response. 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 patch, retry the exact same intent and request ID; for a create, read the target path first. For a stale cursor/read, reacquire current page/state before proceeding. Never edit the journal trailer directly.
::end
SRC format-language
t .gram language specification
ref https://github.com/clab-one/thegram-format/blob/main/spec/language.md
SRC format-rich
t Current rich document specification
ref https://github.com/clab-one/thegram-format/blob/main/spec/rich-document.md
SRC format-history6
t Current History/6 specification
ref https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md