.gram meaning, persistence, and History/6

@gram 2
doc blog-format-architecture
t .gram meaning, persistence, and History/6
d How the current .gram language separates readable meaning from recoverable, runtime-recorded revision history.
tag architecture
view document

::rich
# Why a knowledge format needs time

A useful knowledge artifact must preserve more than a final paragraph. A decision without its evidence, a task without its changing status, or a source detached from the claim it supports loses context needed for later review. .gram gives a document a stable identity and records typed entities, fields, explicit relations, literal content blocks, and source references. Document, card, graph, and timeline are ways to project that meaning; none changes the underlying entity semantics. The format is deliberately data, not a workflow engine, access-control system, animation language, or executable script.

The design goal is not to compress away human meaning. Short type and field codes make structure compact, while titles, descriptions, and rich prose keep the reason understandable to people and models. A parser can preserve source spans, comments, unknown fields, and unsupported constructs instead of silently normalizing away content it does not know.

## Meaning in @gram 2

A current document starts with `@gram 2`, one `doc` owner, and typed records with stable identifiers. For example, `D choose-retention` can hold a title, status, and `::reason` block; an `E export-test` record can hold a result and point to the decision with `supports`. The relation is explicit and directional. `source` can identify provenance records; `ref` can point to a URI. IDs are not derived from visible titles, so editing a title does not make relationships refer to a different object.

Fields are textual values, including dates and quantities. Their interpretation belongs to the consuming view or record convention; the parser does not silently turn a string into a changed fact. Rich body content is literal and not executable. Unknown block names remain data. A label such as `private` does not encrypt a file or grant a permission. Those boundaries matter when a file moves between apps or is sent to a service.

## Revision and the role of History/6

The current writer stores the source at the front and a `@gram-history 6` trailer after it. The history stores revision headers and reverse line hunks sufficient to reconstruct earlier exact source states. Each revision is linked by a chain hash. Core records revision metadata such as actor and recorded time; an AI-authored document fragment does not invent those runtime facts. Current source and historical states are distinct: opening today’s source does not by itself recreate an earlier state, but replay through Core can.

Writes use a compare-and-swap boundary: the writer compares the observed base revision and, where required, expected whole-file hash before replacing the file. That protects against a stale update in the cooperating writer protocol; it is not a cryptographic signature and does not make an uncooperating external editor safe. Legacy History/0–5 and @gram 1 inputs are read or migrated under Core rules. History/6 migration preserves revision metadata; a bare @gram 1 JSON `::rich` block is not silently promoted by current rules.

## A small worked fragment

For example, a `D fallback` record titled “Retain the offline route” can have `x accepted` and a reason block stating that the verified export remains usable without a service account. A separate `E export-check` record can state that a copied file reopened offline and declare `supports fallback`.

The fragment makes the decision and evidence separately addressable. A client can show the relationship as a graph edge or readable line. It does not claim who performed the test or when; those are runtime provenance values only when recorded by the writer.

## Tradeoffs and further reading

Embedding custom semantics into each type would make the language brittle; treating all content as free text would make relations and history less inspectable. The format keeps a small typed vocabulary and permits unknown data, while Core owns parsing, canonicalization, history replay, and safe write transactions. Application caches and search indexes remain derived. The current architecture is not a guarantee that every renderer supports every rich block or every old format equally.

Read `spec/language.md` for syntax and links, `spec/rich-document.md` for rich structures, `spec/architecture.md` for Core projections and responsibilities, and `native/history6.rs` for the current journal implementation. Verification checks describe executable coverage, but historical benchmark results must not be presented as proof of current performance.

## Sources

Claims describe the checked Core README, language and architecture specifications, rich-document specification, and current History/6 implementation.
::end

SRC format-readme
d Internal source reviewed at revision 625edecee877ddf5f6c303cb478c64fa4cbca651 on branch main (README.md); not publicly available.
t Format repository README
SRC language-spec
d Internal source reviewed at revision 625edecee877ddf5f6c303cb478c64fa4cbca651 on branch main (spec/language.md); not publicly available.
t .gram language specification
SRC architecture-spec
d Internal source reviewed at revision 625edecee877ddf5f6c303cb478c64fa4cbca651 on branch main (spec/architecture.md); not publicly available.
t Format architecture specification
SRC rich-spec
d Internal source reviewed at revision 625edecee877ddf5f6c303cb478c64fa4cbca651 on branch main (spec/rich-document.md); not publicly available.
t Rich document specification
SRC history6-impl
d Internal source reviewed at revision 625edecee877ddf5f6c303cb478c64fa4cbca651 on branch main (native/history6.rs); not publicly available.
t Current History/6 implementation
K meaning
t Explicit typed entities and relations carry document meaning
d Stable IDs, fields, blocks, and links keep claims addressable without deriving identity from titles.
source language-spec
supports history
K history
t History/6 preserves exact earlier source states
d Current source leads the file; reverse line hunks and chained revisions support replay of prior source.
source architecture-spec
source history6-impl
R runtime-provenance
t Runtime, not authored prose, records revision metadata
d Actors, recorded time, revision identity and chain metadata are supplied by the writing runtime, not invented in content.
source format-readme
supports history

K format-boundary
d Scope labels and references do not encrypt bytes, enforce ACLs, or make arbitrary renderer blocks executable.
source language-spec
t A data format is not an access-control system
supports meaning