.gram meaning, persistence, and History/6 · r1

Archived revision r1, recorded 2026-10-12T08:13:38.753Z. Current page: .gram meaning, persistence, and History/6.

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.