rapier-markdown-kit 1.1.55 → 1.1.57

package/LICENSE

@@ -25,7 +25,12 @@ grammar, marks and reference style (`spec/md-layout.mjs`, `spec/md-marks.mjs`, `
 (`layout/model.mjs`, `layout/line-plan.mjs`), the Will grammar (`agent/will.mjs`), the picture appendix reader and writer
 (`spec/md-assets.mjs`), the two shared-page reference readers (`tools/read-shared-page.mjs`,
 `tools/read-shared-page.py`), and the host helper `packages/rapier-embed/embed.mjs`. The vendored Pretext (`agent/vendor/pretext`) and micromark carry their
-own MIT notices. Everything else in Rapier is AGPL-3.0-only (see `LICENSE`).
+own MIT notices. The edit-ledger module (`kit/rapier-ledger.mjs`, `kit/ledger/*.mjs`) and
+its editor compatibility import (`editor/journal-records.mjs`) are also covered. The
+record validator/replayer and text-only conflict merger were moved, not copied,
+into that module; the Notes index merger and the rest of the agent/editor remain
+AGPL-3.0-only. The wrapper's carrier-staging helper
+(`skills/rapier-html/package-files.mjs`) is MIT. Everything else in Rapier is AGPL-3.0-only (see `LICENSE`).
 
 The picture appendix reader and writer used to be part of `images/assets.mjs`, a file that also
 holds JPEG XL/raster header inspection and SVG sanitizing -- both of which reach the editor's own

package/README.md

@@ -26,6 +26,47 @@ import {parseWill} from 'rapier-markdown-kit/will';       // Will/1 markers: kee
 import {parseAssets} from 'rapier-markdown-kit/assets';   // the picture appendix
 ```
 
+## The shared renderer
+
+`rapier-markdown-kit/render` exports `createRenderer`, `createMarkdownRenderer`,
+`createRenderStyles`, `createRenderSanitizer` and `createPrintRenderer`. These are the
+actual editor/Share owners, not a second Markdown dialect or a lookalike stylesheet.
+Their host dependencies are explicit named properties in each factory's first argument;
+no factory reaches into an editor session to find its document. `style.css` is the exact
+MIT `spec/markdown-style.css`, including the numbered-list, checkbox, callout, table,
+footnote and picture-layout treatment.
+
+```js
+import {createRenderer} from 'rapier-markdown-kit/render';
+
+// host is your bound DOM/codec/Markdown/image/style environment. Its named ports are
+// declared at the top of createRenderer; preparation returns a detached semantic root.
+const writer = createRenderer(host);
+const {html, filename} = await writer.render(source, {filename: 'proposal.md'});
+```
+
+`createMarkdownRenderer(host).render(source, metadata)` returns the semantic HTML.
+The page writer's `render` returns `{html, filename}` asynchronously and preserves the
+original source, including BOM and line endings, in the SHA-256-verified source carrier.
+Every existing lower-level method is also returned for hosts that compose the stages.
+Create a new bound instance when its parser or host state changes; do not share mutable
+DOM objects between document realms.
+
+This is a **DOM-hosted library**, not a bundled headless browser, DOM shim, parser or
+image decoder. Supplying only `{source}` or running it in bare Node without those ports
+is not supported. A host must provide a real DOM and sanitizer, the Rapier grammar,
+portable image preparation, style access and the named codec/layout ports it uses.
+Those dependencies keep their own licences: the MIT grant here does not relicense a
+separately supplied host or vendor. The repository's `editor/render-host.js` binds the
+editor; `server/` provides a complete local host with a pinned Chromium process. Its
+Word exporter and filesystem service are AGPL, not part of this MIT package.
+
+The extraction receipt in the existing `html-export-corpus` row fixes all 226 baseline
+writer pages byte for byte. That corpus supplies a clean DOM and named style/sanitizer
+adapters: it proves serialization and source recovery, not browser appearance or
+sanitizer security. The server's integration cells additionally use a real DOM and
+round-trip the actual HTTP output.
+
 ## What it gives you
 
 | Import | What it is |
@@ -36,7 +77,9 @@ import {parseAssets} from 'rapier-markdown-kit/assets';   // the picture appendi
 | `rapier-markdown-kit/will` | The Will/1 grammar (a separate, optional standard): the markers around an agent's intent regions. |
 | `rapier-markdown-kit/assets` | The picture appendix: the reference definitions a document's pictures live in. It never decodes a picture. |
 | `rapier-markdown-kit/style.css` | The reference style: type, lists, tables, tasks, pictures and the document's other markup, scoped to `.md-render`. |
-| `rapier-markdown-kit` | All five in one import. |
+| `rapier-markdown-kit/rapier-ledger` | The MIT edit-ledger format, replay, authorship projection and offline merge. |
+| `rapier-markdown-kit/ledger/carried` | Checked optional parts for pages and saved Markdown. |
+| `rapier-markdown-kit` | The modules above as named namespaces. |
 
 Every convention is plain Markdown or an HTML comment other readers ignore. Laying lines out as Rapier does takes
 the host's font metrics (below).
@@ -240,3 +283,156 @@ value the editor's release reads.
 
 Each module has one home in the Rapier source (`spec/`, `layout/`, `agent/`), where Rapier itself reads it; `dist/`
 is that closure copied byte for byte, and `style.css` is the same `spec/markdown-style.css` Rapier bundles.
+
+
+## rapier-ledger
+
+The edit ledger and its carried parts. MIT, no dependencies; part of
+`rapier-markdown-kit`. The editor and this module use the **same** record validator,
+splice replayer, root transition and interval transport. This is not a second history store.
+
+```js
+import {exportLedger, readLedger, authorship, merge} from 'rapier-markdown-kit/rapier-ledger';
+import {writeDocument, readDocument} from 'rapier-markdown-kit/ledger/carried';
+
+const ledger = exportLedger({
+  text: 'Hello', records: [], documentAuthority: 'example-document', complete: true,
+});
+const saved = writeDocument('Hello', {ledger});
+const reopened = readDocument(saved);
+const verified = readLedger(reopened.ledger, reopened.text);
+console.assert(verified.text === 'Hello');
+const clean = writeDocument(verified.text, {authorship: authorship(ledger)});
+console.assert(readDocument(clean).ledger === null);
+const together = merge(ledger, reopened.ledger);
+console.assert(together.text === 'Hello');
+```
+
+## The format at launch
+
+`rapier-ledger/1` is a plain JSON object:
+
+```
+{format, documentAuthority, start: {text, revision, root, sha256}, records,
+ head: {revision, root, sha256}, complete, sha256}
+records[]: {transaction, splices: [{pos, removed, inserted}], beforeHash, afterHash}
+transaction: {id, documentAuthority, baseRevision, revision, actor: {kind, id},
+ transport, operation, requestId, sourceTransactionId, affectedBlockIds,
+ parent, reverts, reapplies, createdAt}
+```
+
+`format` is `rapier-ledger/1`. `start.text` is the exact text before the first
+retained record. Every outgoing record carries its own splices, including Undo and
+Redo. Offsets and ranges count UTF-16 code units; no boundary may cut a surrogate
+pair. Splices execute in their recorded order. UTF-8 checksums preserve CRLF, tabs,
+NUL and non-ASCII text. The canonical text limit is 25 MiB; each record has at most
+64 splices. The existing record validator remains authoritative for field bounds.
+
+`start.sha256` and `head.sha256` hash UTF-8 text. The envelope `sha256` hashes
+canonical JSON of every other envelope field: recursively sorted object keys,
+array order preserved, JSON string/number spelling. Plain finite scalar data only:
+no accessors, sparse arrays, cycles, undefined, negative zero or unpaired surrogates.
+Readers reject unknown envelope/start/head fields, bad checksums, invalid records,
+invalid source boundaries, a replay/root mismatch, or a head different from the
+actual document. `historyEnvelope` additionally proves the editor's Undo/Redo branch.
+
+**Roots are path-dependent.** `textRoot(text)` mints the existing
+`chars:fnv-base36:adler-base36` initial root. Each splice advances it with
+`rootAfter(priorRoot, splice)`, matching the source store. A later root is **not**
+a fresh hash of the whole current text. SHA-256 of the exact checkpoint text is
+separate. This distinction preserves the editor's actual format rather than the
+earlier design shorthand. A nonzero start names a retained checkpoint; it does not
+claim to reconstruct discarded events. `complete: false` also permits a stated
+revision gap from the editor's pruning of cancelling navigation pairs; each
+remaining splice must still replay exactly. It is never a claim about missing edits.
+
+`actor.kind` is `human`, `agent` or `system`. A named agent's `actor.id` is
+`<door>/<host-given name>` (name at most 96 characters, combined id at most 160).
+Without a name, the door stands alone. The name is a **host-supplied claim**, not a
+verified identity. Timestamps are supplied record times, not independently attested.
+Checksums detect inconsistency/corruption, **not forgery**: anyone able to rewrite a
+file can rewrite its checksums and labels. Importing a label never grants a live
+principal's read handles, review authority or undo permissions.
+
+## Optional carried parts
+
+The default is **neither part**. In a self-contained page these inert scripts stand
+beside the document's existing carried source:
+
+| Element | Type and contents | Choice |
+| --- | --- | --- |
+| `#rapier-authorship` | `application/json`, `rapier-authorship/1` | Who wrote what |
+| `#rapier-ledger` | `application/json`, `rapier-ledger/1` | The whole history |
+
+Each body uses the same reversible `encodeCarried`/`decodeCarried` escape as the
+page's source. `writeParts`, `readParts` and `takeParts` implement it. Duplicate,
+executable, malformed or wrong-document parts are refused. If both are present,
+the authorship projection recomputed from the ledger must agree exactly.
+
+`rapier-authorship/1` is `{format, sha256, runs}`. `sha256` hashes the **current**
+text. Runs are `[start, end, actorKind, actorId, at]`, in order, nonoverlapping and
+covering every current character. A start without earlier authorship is attributed
+to `system/unattributed`, time zero. Insertions take the inserting record's actor
+and time; deleted runs disappear. Thus the projection contains **no removed text**.
+An authorship-only import becomes a clearly incomplete insertion ledger; future
+attribution is again derived from that one ledger, never a mutable blame database.
+
+A Markdown file carries the same optional JSON at EOF, outside its exact source:
+
+```
+
+
+<!-- rapier-carried/1
+{"ledger":...,"authorship":...}
+-->
+
+```
+
+The writer escapes `<` and `>` in that JSON. This versioned EOF marker is reserved;
+an unfinished marker is refused, not silently imported as prose. The reader strips
+only that exact suffix, validates it against the remaining exact text, and treats a
+leading BOM as file metadata. Other Markdown readers ignore the comment. Plain
+saves without a choice are unchanged byte for byte. For executable code, use a web
+page to carry metadata rather than appending a Markdown comment to program source.
+
+The existing proposal page's `#rapier-base` is independent: `text/markdown`, with
+`data-revision`, `data-sha256`, `data-by` and `data-at`, carries the proposal's
+baseline. It is **not** reconstructed from an optional ledger, and this module does
+not implement the separate proposal-tool/CLI workflow.
+
+## Merging copies without a server
+
+`merge(first, second)` locates a common checkpoint with the same root **and exact
+text**, then transports the second copy's record splices over the first's through
+the shared interval transport. It preserves the first's ancestry and incoming
+actors/times, minting local revision/root links. Both the public reader and the
+editor's restore reader can replay the result. Both merge orders yield the same
+text for independently edited nonoverlapping ranges; their ordered ledgers need
+not be identical. Full and conflict receipts make repeated imports idempotent.
+
+Overlaps fall back to the existing text three-way merge. Unresolved alternatives
+are carried in the existing `note-conflict:v1` envelope, never silently selected.
+Different Will `keep` regions require conflict review even when one copy was
+unchanged. `review.required` names an unresolved result; a UI must not auto-accept
+it. Rapier offers carried-copy imports from Compare through its existing review,
+checks the live document again at commit, and installs the proven ledger before
+publishing its receipt or opening the durable-save barrier. A rejected or stale
+proposal mutates nothing. A failed install rolls the source and undo window back.
+Copies without a proven common checkpoint are refused by this API.
+
+## Host integration and retention
+
+The embed helper accepts `agentName`; the checked `rapier-connect` message carries
+`agent: {name}`. WebMCP uses the registration owner's supplied client name. Modern
+MCP uses the request's client metadata, outside tool arguments; a legacy stateless
+request without a supplied name stays unnamed. MCP editor snapshots include the
+server's retained journal only in editor metadata, not in model-facing tool results.
+The browser proves a replay suffix before preserving remote writers under local
+revision links; missing remote events never become an invented complete history.
+
+Rapier retains its existing 500-record / 4-MiB in-memory window. A carried file can
+outlive that window; reopening may trim it again. The module preserves an explicitly
+incomplete start. Full history includes removed text and can be much larger than
+the current document; it is opt-in for each outgoing file, never a persistent
+preference. Authorship is also opt-in. Neither option implies signatures, identity
+verification, infinite retention, a relay server or automatic synchronization.

package/dist/kit/index.mjs

@@ -4,3 +4,5 @@ export * from './marks.mjs';
 export * from './model.mjs';
 export * from './will.mjs';
 export * from './assets.mjs';
+export * from './render-entry.mjs';
+export * as ledger from './rapier-ledger.mjs';

package/dist/kit/ledger/authorship.mjs

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+import {readLedger, exportLedger, textRoot, rootAfter} from './format.mjs';
+import {_rapierTransformSplices} from './journal-records.mjs';
+import {sha256} from './hash.mjs';
+import {plainData, documentText, nonnegative, exactKeys, fault} from './data.mjs';
+function coalesce(runs) {
+  const out = [];
+  for (const run of runs) {
+    if (run[0] === run[1]) continue;
+    const last = out.at(-1);
+    if (last && last[1] === run[0] && last.slice(2).every((value, i) => value === run[i + 2])) last[1] = run[1];
+    else out.push(run.slice());
+  }
+  return out;
+}
+export function authorship(input) {
+  const {ledger, text} = readLedger(input);
+  let runs = ledger.start.text ? [[0, ledger.start.text.length, 'system', 'unattributed', 0]] : [];
+  for (const record of ledger.records) for (const row of record.splices) {
+    const cut = row.pos + row.removed.length, delta = row.inserted.length - row.removed.length, before = [], after = [];
+    for (const run of runs) {
+      if (run[0] < row.pos) before.push([run[0], Math.min(run[1], row.pos), ...run.slice(2)]);
+      if (run[1] > cut) after.push([Math.max(run[0], cut) + delta, run[1] + delta, ...run.slice(2)]);
+    }
+    const tx = record.transaction;
+    runs = coalesce([...before, [row.pos, row.pos + row.inserted.length, tx.actor.kind, tx.actor.id, tx.createdAt], ...after]);
+  }
+  return {format: 'rapier-authorship/1', sha256: sha256(text), runs};
+}
+export function readAuthorship(input, text) {
+  documentText(text); const value = plainData(input);
+  if (!exactKeys(value, ['format','sha256','runs']) || value.format !== 'rapier-authorship/1' || value.sha256 !== sha256(text) || !Array.isArray(value.runs)) throw fault('authorship is not for this text');
+  let cursor = 0;
+  for (const run of value.runs) {
+    if (!Array.isArray(run) || run.length !== 5 || run[0] !== cursor || !nonnegative(run[1]) || run[1] <= cursor || run[1] > text.length ||
+        !['human','agent','system'].includes(run[2]) || typeof run[3] !== 'string' || !run[3] || run[3].length > 160 || !nonnegative(run[4]) ||
+        /[\uD800-\uDFFF]/u.test(text.slice(cursor, run[1]))) throw fault('invalid authorship run');
+    cursor = run[1];
+  }
+  if (cursor !== text.length) throw fault('authorship does not cover the text');
+  return value;
+}
+// Authorship-only imports become an incomplete insertion ledger. There is no mutable blame database.
+export function ledgerFromAuthorship(input, text, documentAuthority) {
+  const value = readAuthorship(input, text), records = [];
+  let current = '', root = textRoot('');
+  for (const [start, end, kind, id, createdAt] of value.runs) {
+    const row = {pos: start, removed: '', inserted: text.slice(start, end)}, revision = records.length + 1;
+    const beforeHash = root; root = rootAfter(root, row);
+    current = _rapierTransformSplices(current, [row]);
+    records.push({beforeHash, afterHash: root, splices: [row], transaction: {
+      id: documentAuthority.slice(0, 48) + ':authorship:' + revision.toString(36), documentAuthority,
+      baseRevision: revision - 1, revision, actor: {kind, id}, transport: 'platform', operation: 'authorship.import',
+      requestId: null, sourceTransactionId: null, affectedBlockIds: [], parent: records.at(-1)?.transaction.id ?? null,
+      reverts: null, reapplies: null, createdAt,
+    }});
+  }
+  return exportLedger({text: current, records, documentAuthority, revision: records.length, root, complete: false});
+}

package/dist/kit/ledger/carried.mjs

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+import {readLedger} from './format.mjs';
+import {authorship as projectAuthorship, readAuthorship} from './authorship.mjs';
+import {canonicalJSON, fault} from './data.mjs';
+export function encodeCarried(text) {
+  return String(text).replace(/[\\\r\0]|<[/!]/g, m => m === '\\' ? '\\\\' : m === '\r' ? '\\r' : m === '\0' ? '\\0' : m === '</' ? '\\/' : '\\!');
+}
+export function decodeCarried(text) {
+  return String(text).replace(/\\([\\/!r0])/g, (_, c) => c === '\\' ? '\\' : c === 'r' ? '\r' : c === '0' ? '\0' : c === '/' ? '</' : '<!');
+}
+export function validateParts(text, {ledger = null, authorship = null} = {}) {
+  // A file's leading BOM is metadata, as in the editor's source intake.
+  const canonical = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+  const history = ledger === null ? null : readLedger(ledger, canonical).ledger;
+  const runs = authorship === null ? null : readAuthorship(authorship, canonical);
+  if (history && runs && canonicalJSON(projectAuthorship(history)) !== canonicalJSON(runs)) throw fault('authorship differs from ledger replay');
+  return {ledger: history, authorship: runs};
+}
+export function writeParts(text, options) {
+  const parts = validateParts(text, options);
+  return Object.entries(parts).filter(([, value]) => value !== null).map(([name, value]) =>
+    '<script type="application/json" id="rapier-' + name + '">' + encodeCarried(JSON.stringify(value)) + '</script>\n').join('');
+}
+// Pure adapter: the browser supplies inert script elements, Node supplies parsed script records.
+export function readParts(text, elements) {
+  const parts = {ledger: null, authorship: null};
+  for (const element of elements) {
+    const name = element.id === 'rapier-ledger' ? 'ledger' : element.id === 'rapier-authorship' ? 'authorship' : null;
+    if (!name) continue;
+    if (parts[name] !== null || element.type !== 'application/json' || (element.tagName && element.tagName.toLowerCase() !== 'script')) throw fault('duplicate or executable carried part');
+    try { parts[name] = JSON.parse(decodeCarried(element.textContent)); }
+    catch (_) { throw fault('invalid carried JSON'); }
+    if (parts[name] === null) throw fault('empty carried part');
+  }
+  return validateParts(text, parts);
+}
+// The wrapper only removes whole script elements. Strings inside other scripts are not carriers.
+export function takeParts(html, text) {
+  const elements = [];
+  const stripped = html.replace(/<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi, (whole, attrs, content) => {
+    const attributes = [...attrs.matchAll(/(?:^|\s)([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/g)];
+    const ids = attributes.filter(m => m[1].toLowerCase() === 'id').map(m => m[2] ?? m[3] ?? m[4]);
+    if (!ids.some(id => id === 'rapier-ledger' || id === 'rapier-authorship')) return whole;
+    const types = attributes.filter(m => m[1].toLowerCase() === 'type').map(m => m[2] ?? m[3] ?? m[4]);
+    if (ids.length !== 1 || types.length !== 1) throw fault('ambiguous carried part');
+    elements.push({id: ids[0], type: types[0].toLowerCase(), textContent: content}); return '';
+  });
+  if (elements.length && text === null) throw fault('carried history without a document');
+  return {html: stripped, ...readParts(text ?? '', elements)};
+}
+const OPEN = '\n\n<!-- rapier-carried/1\n', CLOSE = '\n-->\n';
+// One optional HTML comment at EOF; every other Markdown reader ignores it. Source is never rewritten.
+export function writeDocument(text, options) {
+  const parts = validateParts(text, options);
+  if (!parts.ledger && !parts.authorship) return text;
+  const json = JSON.stringify(parts).replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+  return text + OPEN + json + CLOSE;
+}
+export function readDocument(source) {
+  const at = source.lastIndexOf(OPEN);
+  if (at < 0) return {text: source, ledger: null, authorship: null};
+  if (!source.endsWith(CLOSE)) throw fault('unfinished document metadata');
+  let parts;
+  try { parts = JSON.parse(source.slice(at + OPEN.length, -CLOSE.length)); }
+  catch (_) { throw fault('invalid document metadata'); }
+  if (!parts || Object.keys(parts).length !== 2 || !Object.hasOwn(parts, 'ledger') || !Object.hasOwn(parts, 'authorship')) throw fault('invalid document parts');
+  const text = source.slice(0, at);
+  return {text, ...validateParts(text, parts)};
+}

package/dist/kit/ledger/data.mjs

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// Only plain JSON data enters the public format. Accessors and toJSON are never executed.
+export function fault(message) { return Object.assign(new Error('Ledger: ' + message), {code: 'ledger_invalid'}); }
+export function canonicalJSON(value, depth = 0, active = new Set()) {
+  if (value === null || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'string') { if (/[\uD800-\uDFFF]/u.test(value)) throw fault('unpaired surrogate'); return JSON.stringify(value); }
+  if (typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0)) return JSON.stringify(value);
+  if (!value || typeof value !== 'object' || depth > 64 || active.has(value)) throw fault('not plain JSON data');
+  const array = Array.isArray(value), proto = Object.getPrototypeOf(value);
+  if (!array && proto !== null && (Object.getPrototypeOf(proto) !== null || Object.getOwnPropertyDescriptor(proto, 'constructor')?.value?.name !== 'Object')) throw fault('not a plain object');
+  const descriptors = Object.getOwnPropertyDescriptors(value), keys = Reflect.ownKeys(descriptors);
+  for (const key of keys) {
+    if (array && key === 'length') continue;
+    const field = descriptors[key];
+    if (typeof key !== 'string' || ['__proto__', 'constructor', 'prototype'].includes(key) || !Object.hasOwn(field, 'value') || !field.enumerable) throw fault('non-data property');
+  }
+  if (array && (keys.length !== value.length + 1 || keys.some(k => k !== 'length' && (!/^(0|[1-9]\d*)$/.test(k) || +k >= value.length)))) throw fault('sparse array');
+  active.add(value);
+  const encode = item => canonicalJSON(item, depth + 1, active);
+  const out = array ? '[' + Array.from({length: value.length}, (_, i) => encode(descriptors[i].value)).join(',') + ']'
+    : '{' + keys.sort().map(key => JSON.stringify(key) + ':' + encode(descriptors[key].value)).join(',') + '}';
+  active.delete(value); return out;
+}
+export function plainData(value) { return JSON.parse(canonicalJSON(typeof value === 'string' ? JSON.parse(value) : value)); }
+export function exactKeys(value, keys) {
+  return value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+export function documentText(text) {
+  if (typeof text !== 'string' || /[\uD800-\uDFFF]/u.test(text)) throw fault('document is not whole-character text');
+  if (new TextEncoder().encode(text).length > 25 * 1024 * 1024) throw fault('document exceeds the editor text limit');
+  return text;
+}
+export const nonnegative = value => Number.isSafeInteger(value) && value >= 0 && !Object.is(value, -0);

package/dist/kit/ledger/format.mjs

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: MIT
+import {_rapierValidLedgerRecord, _rapierRecordSplices, _rapierTransformSplices} from './journal-records.mjs';
+import {textRoot, rootAfter, sha256} from './hash.mjs';
+import {canonicalJSON, plainData, documentText, exactKeys, nonnegative, fault} from './data.mjs';
+export {textRoot, rootAfter};
+const digest = value => sha256(canonicalJSON(value));
+const rootShape = value => typeof value === 'string' && /^\d+:[a-z0-9]+:[a-z0-9]+$/.test(value);
+export function readLedger(input, expectedText) {
+  const ledger = plainData(input);
+  if (!exactKeys(ledger, ['format','documentAuthority','start','records','head','complete','sha256']) || ledger.format !== 'rapier-ledger/1' ||
+      typeof ledger.documentAuthority !== 'string' || !ledger.documentAuthority || ledger.documentAuthority.length > 256 ||
+      typeof ledger.complete !== 'boolean' || !Array.isArray(ledger.records) ||
+      !exactKeys(ledger.start, ['text','revision','root','sha256']) || !exactKeys(ledger.head, ['revision','root','sha256'])) throw fault('invalid envelope');
+  const {sha256: claimed, ...payload} = ledger;
+  if (claimed !== digest(payload)) throw fault('envelope checksum differs');
+  let text = documentText(ledger.start.text), root = ledger.start.root, revision = ledger.start.revision;
+  if (!nonnegative(revision) || !rootShape(root) || (revision === 0 && root !== textRoot(text)) || ledger.start.sha256 !== sha256(text) ||
+      (ledger.complete && revision !== 0)) throw fault('invalid start');
+  const earlier = [];
+  for (const record of ledger.records) {
+    if (!Array.isArray(record.splices) || !record.splices.length || !_rapierValidLedgerRecord(record, earlier.at(-1) || null, earlier,
+        ledger.documentAuthority, 25 * 1024 * 1024, text => new TextEncoder().encode(text).length, !ledger.complete) ||
+        record.transaction.baseRevision < revision || (record.transaction.baseRevision !== revision && ledger.complete) ||
+        (record.transaction.baseRevision === revision && record.beforeHash !== root)) throw fault('record chain differs');
+    // A pruned cancelling pair leaves a stated revision gap, just as in the editor's restore reader.
+    if (record.transaction.baseRevision !== revision) root = record.beforeHash;
+    const next = _rapierTransformSplices(text, record.splices);
+    if (next === null) throw fault('splice does not replay');
+    text = documentText(next);
+    for (const row of record.splices) root = rootAfter(root, row);
+    if (root !== record.afterHash) throw fault('record root differs');
+    revision = record.transaction.revision; earlier.push(record);
+  }
+  if (ledger.head.revision !== revision || ledger.head.root !== root || ledger.head.sha256 !== sha256(text) ||
+      (expectedText !== undefined && text !== expectedText)) throw fault('history does not describe this document');
+  return {ledger, text, root, revision, complete: ledger.complete};
+}
+export function exportLedger({text, records, documentAuthority, revision, root, complete = false, earlier = records} = {}) {
+  documentText(text);
+  if (!Array.isArray(records) || !Array.isArray(earlier)) throw fault('records required');
+  // Inspect before touching properties: exporting must not call accessors on an alleged record.
+  records = plainData(records); earlier = plainData(earlier);
+  const expanded = records.map(record => {
+    const rows = _rapierRecordSplices(record, earlier);
+    if (!rows) throw fault('navigation target was not retained');
+    return {transaction: record.transaction, splices: rows.map(row => ({pos: row.pos, removed: row.removed, inserted: row.inserted})),
+      beforeHash: record.beforeHash, afterHash: record.afterHash};
+  });
+  let startText = text;
+  for (let i = expanded.length - 1; i >= 0; i--) {
+    startText = _rapierTransformSplices(startText, expanded[i].splices, true);
+    if (startText === null) throw fault('history does not reverse from this document');
+  }
+  revision ??= expanded.at(-1)?.transaction.revision ?? 0;
+  root ??= expanded.at(-1)?.afterHash ?? textRoot(text);
+  documentAuthority ??= expanded[0]?.transaction.documentAuthority;
+  const startRevision = expanded[0]?.transaction.baseRevision ?? revision;
+  const payload = {format: 'rapier-ledger/1', documentAuthority,
+    start: {text: startText, revision: startRevision, root: expanded[0]?.beforeHash ?? root, sha256: sha256(startText)},
+    records: expanded, head: {revision, root, sha256: sha256(text)}, complete: complete === true && startRevision === 0 && expanded.every((row, i) => !i || row.transaction.baseRevision === expanded[i - 1].transaction.revision)};
+  const ledger = {...payload, sha256: digest(payload)};
+  readLedger(ledger, text); return ledger;
+}
+// Derived navigation, never a second history. A target older than start is intentionally unavailable.
+export function historyEnvelope(input, segmentIdentity = []) {
+  const {ledger, text} = readLedger(input), ids = new Set(ledger.records.map(row => row.transaction.id));
+  let branch = [], cursor = 0;
+  for (const {transaction: tx} of ledger.records) {
+    const target = tx.reverts || tx.reapplies;
+    if (target) {
+      if (!ids.has(target)) continue;
+      if (tx.reverts && branch[cursor - 1] === target) cursor--;
+      else if (tx.reapplies && branch[cursor] === target) cursor++;
+      else throw fault('invalid navigation order');
+    } else { branch = branch.slice(0, cursor); branch.push(tx.id); cursor = branch.length; }
+  }
+  const byId = new Map(ledger.records.map(row => [row.transaction.id, row]));
+  let traversed = text;
+  for (let i = cursor - 1; i >= 0; i--) {
+    traversed = _rapierTransformSplices(traversed, byId.get(branch[i]).splices, true);
+    if (traversed === null) throw fault('undo branch does not reverse');
+  }
+  traversed = text;
+  for (let i = cursor; i < branch.length; i++) {
+    traversed = _rapierTransformSplices(traversed, byId.get(branch[i]).splices);
+    if (traversed === null) throw fault('redo branch does not replay');
+  }
+  if (ledger.complete) {
+    if (ledger.records.length && !branch.length) throw fault('complete history lost its branch');
+    let active = ledger.start.text;
+    if (!cursor && active !== text) throw fault('complete history start differs');
+    for (let i = 0; i < branch.length; i++) {
+      active = _rapierTransformSplices(active, byId.get(branch[i]).splices);
+      if (active === null || (i + 1 === cursor && active !== text)) throw fault('complete branch differs');
+    }
+  }
+  return {schemaVersion: 4, documentAuthority: ledger.documentAuthority, documentRevision: ledger.head.revision,
+    ledger: ledger.records, branch, cursor, earliestRevision: ledger.start.revision, earliestHash: ledger.start.root,
+    sourceRootId: ledger.head.root, segmentIdentity, historyComplete: ledger.complete,
+    trimReason: ledger.complete ? '' : 'carried_start', trimmedBytes: 0};
+}
+export function agentActorId(door, agent) {
+  if (typeof door !== 'string' || !door || door.length > 160 || /[\u0000-\u001f\u007f]/.test(door)) throw fault('invalid door');
+  if (agent == null) return door;
+  agent = plainData(agent);
+  if (!exactKeys(agent, ['name']) || typeof agent.name !== 'string' || !agent.name.trim() || agent.name.length > 96 ||
+      /[\u0000-\u001f\u007f]/.test(agent.name) || door.length + agent.name.length + 1 > 160) throw fault('invalid host-given name');
+  return door + '/' + agent.name;
+}
+
+// A writer changing representation records that change, rather than attaching an unrelated head.
+export function replaceLedgerText(input, text, {actor = {kind: 'system', id: 'rapier'}, operation = 'document.replace', at} = {}) {
+  const current = readLedger(input); documentText(text);
+  if (current.text === text) return current.ledger;
+  let start = 0, a = current.text.length, b = text.length;
+  while (start < a && start < b && current.text[start] === text[start]) start++;
+  if (start && /[\uDC00-\uDFFF]/.test(current.text[start] || text[start] || '')) start--;
+  while (a > start && b > start && current.text[a - 1] === text[b - 1]) { a--; b--; }
+  if (/[\uDC00-\uDFFF]/.test(current.text[a] || text[b] || '')) { a++; b++; }
+  const splices = [{pos: start, removed: current.text.slice(start, a), inserted: text.slice(start, b)}];
+  const revision = current.revision + 1, root = rootAfter(current.root, splices[0]);
+  const record = {beforeHash: current.root, afterHash: root, splices, transaction: {
+    id: current.ledger.documentAuthority.slice(0, 48) + ':export:' + revision.toString(36),
+    documentAuthority: current.ledger.documentAuthority, baseRevision: current.revision, revision,
+    actor, transport: 'platform', operation, requestId: null, sourceTransactionId: null,
+    affectedBlockIds: [], parent: current.ledger.records.at(-1)?.transaction.id ?? null,
+    reverts: null, reapplies: null, createdAt: at ?? current.ledger.records.at(-1)?.transaction.createdAt ?? 0,
+  }};
+  return exportLedger({text, records: [...current.ledger.records, record], documentAuthority: current.ledger.documentAuthority,
+    revision, root, complete: current.complete});
+}

package/dist/kit/ledger/hash.mjs

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+// The editor's path-dependent root, plus synchronous SHA-256 for file readers (including offline wrappers).
+export function textRoot(text) {
+  let fnv = 0x811c9dc5, a = 1, b = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    fnv = Math.imul(fnv ^ c, 16777619); a = (a + c) % 65521; b = (b + a) % 65521;
+  }
+  return text.length + ':' + (fnv >>> 0).toString(36) + ':' + (((b << 16) | a) >>> 0).toString(36);
+}
+export function rootAfter(root, row) {
+  return textRoot(String(root || '') + ':' + row.pos + ':' + textRoot(row.removed) + ':' + textRoot(row.inserted));
+}
+const K = new Uint32Array([
+  0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
+  0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
+  0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
+  0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
+  0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
+  0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
+  0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
+  0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2,
+]);
+const rotate = (x, n) => (x >>> n) | (x << (32 - n));
+export function sha256(text) {
+  const bytes = new TextEncoder().encode(text);
+  const padded = new Uint8Array(Math.ceil((bytes.length + 9) / 64) * 64);
+  padded.set(bytes); padded[bytes.length] = 0x80;
+  const data = new DataView(padded.buffer), bits = bytes.length * 8;
+  data.setUint32(padded.length - 8, Math.floor(bits / 0x100000000)); data.setUint32(padded.length - 4, bits >>> 0);
+  const h = new Uint32Array([0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19]), w = new Uint32Array(64);
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    for (let i = 0; i < 16; i++) w[i] = data.getUint32(offset + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const x = w[i - 15], y = w[i - 2];
+      w[i] = w[i - 16] + (rotate(x, 7) ^ rotate(x, 18) ^ (x >>> 3)) + w[i - 7] + (rotate(y, 17) ^ rotate(y, 19) ^ (y >>> 10));
+    }
+    let [a,b,c,d,e,f,g,k] = h;
+    for (let i = 0; i < 64; i++) {
+      const t1 = (k + (rotate(e, 6) ^ rotate(e, 11) ^ rotate(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i]) >>> 0;
+      const t2 = ((rotate(a, 2) ^ rotate(a, 13) ^ rotate(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+      k = g; g = f; f = e; e = (d + t1) >>> 0; d = c; c = b; b = a; a = (t1 + t2) >>> 0;
+    }
+    for (const [i, value] of [a,b,c,d,e,f,g,k].entries()) h[i] += value;
+  }
+  return [...h].map(x => x.toString(16).padStart(8, '0')).join('');
+}