rapier-html 1.1.88 → 1.1.91

package/BUILD.json

@@ -1,10 +1,10 @@
 {
   "package": "rapier-html",
-  "version": "1.1.88",
+  "version": "1.1.91",
   "path": "dist/rapier.html",
-  "bytes": 2292911,
-  "sha256": "e1fe37abd18601a1dc4b3b216c664abbe1d359304ba44553d73e7959a6251660",
-  "builtAt": "2026-10-09T17:36:28.753Z",
+  "bytes": 2322217,
+  "sha256": "80bdd3c617f3869514e8eab6b4d7b15a7c78ac0b57ad658dda9d6c2f45a2e005",
+  "builtAt": "2026-10-10T13:37:30.843Z",
   "node": "v22.23.3",
   "canonical": true,
   "packing": "zopfli",

package/README.md

@@ -1,7 +1,8 @@
 # rapier-html
 
-Give a person a document they can read, edit and keep: one command writes one HTML file that is the whole
-editor, offline, with the document inside.
+Turn Markdown into one offline HTML file with the full Rapier editor. It opens in any browser on a phone or
+computer, with no account. People read, edit, draw and paint watercolor. Agents deliver documents, show what
+changed and receive the person's edited copy through the door. Start with `npx rapier-html@1.1.91 notes.md`.
 
 Use it for a plan to rearrange, an illustrated guide to annotate, a draft to continue writing, or a revision
 to review. Text and drawings stay editable, and the file remains usable independently of a hosted workspace.
@@ -10,32 +11,48 @@ to review. Text and drawings stay editable, and the file remains usable independ
   and nothing fetched to open, edit or save.
 - `--return` adds a one-use Send back address from the agent door: the person edits offline, presses Send back,
   and the agent reads the returned copy.
-- `--view draw` opens on Draw; `--propose original.md` opens on the diff of a proposed change, and the person keeps
-  or drops each change; `--by <name>` says on that diff who proposed it and when.
+- `--view draw` opens on Draw; `--compare original.md` opens the edited document showing what changed;
+  `--by <name>` attributes the comparison with the time the page was made.
 - `wrap` and `unwrap` carry a document into a page and out again, exactly, for programs.
 
 Node 22 or newer.
 
 ```sh
-npx -- rapier-html@1.1.88 notes.md                          # the editor, notes.md inside it, written beside the file
-npx -- rapier-html@1.1.88 notes.md --view draw              # opens on Draw: sketch and paint, the document behind it
-npx -- rapier-html@1.1.88 notes.md --view notes             # opens the Notes library
-npx -- rapier-html@1.1.88 notes.md --drawing sketch.svg     # carries a drawing, opened on Draw over the document
-npx -- rapier-html@1.1.88 --propose original.md proposal.md # opens on the diff of a proposed change
-npx -- rapier-html@1.1.88 notes.md --return "$RETURN_URL" --return-expires-at "$RETURN_EXPIRES_AT" # Send back
-npx -- rapier-html@1.1.88 notes.md out.html                 # a named output
-npm install rapier-html@1.1.88                              # as a library: wrap, unwrap
+npx -- rapier-html@1.1.91 notes.md                          # the editor, notes.md inside it, written beside the file
+npx -- rapier-html@1.1.91 notes.md --view draw              # opens on Draw: sketch and paint, the document behind it
+npx -- rapier-html@1.1.91 notes.md --view notes             # opens the Notes library
+npx -- rapier-html@1.1.91 notes.md --drawing sketch.svg     # carries a drawing, opened on Draw over the document
+npx -- rapier-html@1.1.91 revised.md --compare original.md # opens showing what changed
+npx -- rapier-html@1.1.91 notes.md --return "$RETURN_URL" --return-expires-at "$RETURN_EXPIRES_AT" # Send back
+npx -- rapier-html@1.1.91 notes.md out.html                 # a named output
+npm install rapier-html@1.1.91                              # as a library: wrap, unwrap
 ```
 
 The first `--` is for npm, so `--help` reaches the command. It never overwrites a file.
 
-For live shared editing, open the document through Rapier's MCP tools. Read the person's current text or
-drawing before revising it, show the attributed changes, and export Markdown or an offline editor when the
-result needs an independent copy. Send back returns an edited offline copy for inspection and review alongside
-the hosted document.
+For live shared editing, open the document through Rapier's MCP tools. The agent edits beside the person or
+while they are away. Rapier shows its presence and change marks; the person taps a change to see the before
+and undoes anything. Use `comparison.present` to show a diff deliberately. Export Markdown or an offline
+editor when the result needs an independent copy. Send back returns the edited copy alongside the hosted
+document, preserving both.
 
 Will markers in the Markdown control agent edits: `keep`, `append`, `edit`.
 
+## Choose a Rapier workflow
+
+Rapier is a phone-first Markdown editor for notes, diagrams, drawing and watercolor painting. It runs offline
+as one HTML file on Android, Web and Windows.
+Collaborate over MCP and WebMCP, use optional encrypted sync to your own Cloudflare account, or embed the
+editor and lightweight reader (about 190 kB gzipped). The agent edits live; the person sees its presence and
+changes, taps a change to see the before and undoes anything. Use `comparison.present` to show a diff deliberately.
+
+1. **Work together live.** Connect to `https://mcp.rapier.website/mcp`, then call `rapier.open` to share one document with the person.
+2. **Deliver an offline editor.** Run `npx rapier-html@1.1.91 notes.md` to put the document and editor in one HTML file ([rapier-html](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-html)).
+3. **Embed in your app.** Install [rapier-embed](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-embed); mount the editor or reader, with your app's agent over WebMCP in the editor.
+4. **Keep portable Markdown.** Use [rapier-markdown-kit](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-markdown-kit) for pictures, editable SVG drawings and layout in one `.md` file. Respect [Will/1](https://github.com/jackskip22/will) `keep`, `append` and `edit` regions.
+5. **Encode JPEG XL.** Install [rapier-jxl](https://github.com/jackskip22/rapier-jxl) to encode pixels, photographs and existing JPEGs in JavaScript.
+6. **Host the door.** Run [rapier-server](https://github.com/jackskip22/rapier/tree/main/server) over your own folder or S3-compatible bucket.
+
 ## Send an edited document back
 
 Call `document.create_return` on the Rapier agent door for the document's workspace and pass its `return_url`
@@ -50,8 +67,9 @@ document up to 25 MiB and grants no access to the agent's workspace. After the e
 Save instead; bring that file back to the assistant for a fresh return.
 
 The agent's `document.wait_for_user` returns a `returned` receipt with the `return_id`, name and time;
-`document.get_context` lists receipts; `document.read_context({return_id, start: 0})` reads the source,
-continuing at the returned `end` until `complete`. The returned copy stays separate from the workspace's
+`document.observe` with the `returns` facet lists receipts. Use
+`document.read({target: {kind: "return", return_id, start: 0}})` to read the source, then `cursor` alone
+to continue until complete. The returned copy stays separate from the workspace's
 current document.
 
 ## As a library
@@ -69,24 +87,30 @@ console.log('words back exactly:', unwrap(page).text === words);
 await writeFile('hello.rapier.html', page, {flag: 'wx'});        // 'wx': never over an existing file
 ```
 
-`wrap(rapierHtml, text, name, {view, drawing, drawingName, base, baseName, return: returnURL, return_expires_at})`
-and `unwrap(pageHtml)`, which returns the same fields with `null` for what a page does not carry. Also exported:
+`wrap(rapierHtml, text, name, {view, drawing, drawingName, base, baseName, by, at, return: returnURL, return_expires_at})`
+and `unwrap(pageHtml)`, which returns the same fields plus the validated `comparisonBase` record, with `null`
+for what a page does not carry. Also exported:
 `encodeCarried`, `decodeCarried`, `main`.
 
 ## How the page carries the document
 
 One `<script type="text/markdown" id="rapier-document">` block at the top of the body, never executed,
-read once at boot. A drawing rides in `id="rapier-drawing"`, the text a change was proposed against in
+read once at boot. A drawing rides in `id="rapier-drawing"`, the original text for comparison in
 `id="rapier-base"`, the view to open on in the document block's `data-view`, the optional return URL
 in `data-return` and its exact expiry in `data-return-expires-at`. The block holds no `<`
 before `/` or `!`, no carriage return and no NUL: `\\`, `\/`, `\!`, `\r` and `\0` stand for them, one
 reversible pass each way, so a note about HTML is as safe as any other. A byte-order mark is kept as a
 fact of the file and written back on Save.
 
+`comparisonBase` contains the original `text`, `sha256`, `revision`, `name`, `by` and `at`. Rewrapping retains
+its original text, hash and revision; a baseline equal to the current text is omitted. It is a display
+reference, never a write grant or a history record. The edited document remains the source used by Save and
+Send back.
+
 ## Safety
 
 - It never overwrites: an existing output, the document itself included, is refused, as are unknown options, a
-  `--view` other than `draw` or `notes`, a `--drawing` or `--propose` with no file, a return without its expiry, an
+  `--view` other than `draw` or `notes`, a `--drawing` or `--compare` with no file, a return without its expiry, an
   invalid expiry, an unsafe return URL and a third filename.
 - Nothing reports on the page's use. It reaches the network only when the document or the person asks: a linked
   picture or video, a plug-in on first use (maths, diagrams, PDF import, text in pictures, a letter set), or

package/dist/ledger/authorship.mjs

@@ -33,7 +33,7 @@ export function readAuthorship(input, 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]) ||
+        !['human','agent','system'].includes(run[2]) || typeof run[3] !== 'string' || !run[3] || run[3].length > 160 || !(run[4] === null || nonnegative(run[4])) ||
         /[\uD800-\uDFFF]/u.test(text.slice(cursor, run[1]))) throw fault('invalid authorship run');
     cursor = run[1];
   }
@@ -41,7 +41,7 @@ export function readAuthorship(input, text) {
   return value;
 }
 // Authorship-only imports become an incomplete insertion ledger. There is no mutable blame database.
-export function ledgerFromAuthorship(input, text, documentAuthority) {
+export function ledgerFromAuthorship(input, text, documentAuthority, metadata) {
   const value = readAuthorship(input, text), records = [];
   let current = '', root = textRoot('');
   for (const [start, end, kind, id, createdAt] of value.runs) {
@@ -55,5 +55,5 @@ export function ledgerFromAuthorship(input, text, documentAuthority) {
       reverts: null, reapplies: null, createdAt,
     }});
   }
-  return exportLedger({text: current, records, documentAuthority, revision: records.length, root, complete: false});
+  return exportLedger({text: current, metadata, records, documentAuthority, revision: records.length, root, complete: false});
 }

package/dist/ledger/carried.mjs

@@ -9,10 +9,10 @@ export function encodeCarried(text) {
 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} = {}) {
+export function validateParts(text, {ledger = null, authorship = null, metadata} = {}) {
   // 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 history = ledger === null ? null : readLedger(ledger, canonical, metadata).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};
@@ -69,19 +69,19 @@ export function readDocument(source) {
   return {text, ...validateParts(text, parts)};
 }
 
-// One portable baseline. A digest is integrity evidence, not authentication of the named proposer.
+// One portable baseline. A digest is integrity evidence, not authentication of the named author.
 export function readBase(value) {
   if (!value || typeof value !== 'object' || typeof value.text !== 'string' ||
       typeof value.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.sha256) || sha256(value.text) !== value.sha256)
-    throw fault('proposal base SHA-256 differs from its text');
+    throw fault('comparison base SHA-256 differs from its text');
   if (typeof value.revision !== 'string' || !value.revision || value.revision.length > 256 || /[\u0000-\u001f\u007f]/.test(value.revision))
-    throw fault('invalid proposal base revision');
+    throw fault('invalid comparison base revision');
   if (typeof value.name !== 'string' || !value.name || [...value.name].length > 256 || /[\\/\u0000-\u001f\u007f]/.test(value.name))
-    throw fault('invalid proposal base name');
+    throw fault('invalid comparison base name');
   if (typeof value.by !== 'string' || !value.by.trim() || value.by.length > 96 || /[\u0000-\u001f\u007f]/.test(value.by))
-    throw fault('a proposal needs its proposer name');
+    throw fault('a comparison needs its author name');
   if (typeof value.at !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(value.at) || !Number.isFinite(Date.parse(value.at)))
-    throw fault('the time of a proposal is an ISO 8601 UTC timestamp');
+    throw fault('the time of a comparison is an ISO 8601 UTC timestamp');
   return {text: value.text, sha256: value.sha256, revision: value.revision, name: value.name, by: value.by, at: value.at};
 }
 const escapeAttribute = value => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -98,7 +98,7 @@ export function readBaseElements(elements) {
   if (!rows.length) return null;
   const row = rows[0];
   if (rows.length !== 1 || row.type !== 'text/markdown' || (row.tagName && row.tagName.toLowerCase() !== 'script'))
-    throw fault('duplicate or executable proposal base');
+    throw fault('duplicate or executable comparison base');
   const get = name => row.getAttribute ? row.getAttribute('data-' + name) : row[name];
   return readBase({text: decodeCarried(row.textContent), ...Object.fromEntries(['name', 'sha256', 'revision', 'by', 'at'].map(key => [key, get(key)]))});
 }
@@ -109,7 +109,7 @@ export function takeBase(html) {
     if (!pairs.some(([key, value]) => key === 'id' && value === 'rapier-base')) return whole;
     const seen = new Set(), values = {};
     for (const [key, value] of pairs) {
-      if (seen.has(key)) throw fault('ambiguous proposal base');
+      if (seen.has(key)) throw fault('ambiguous comparison base');
       seen.add(key); values[key] = value;
     }
     elements.push({id: values.id, type: values.type, textContent: content,

package/dist/ledger/format.mjs

@@ -1,24 +1,26 @@
 // SPDX-License-Identifier: MIT
-import {_rapierValidLedgerRecord, _rapierRecordSplices, _rapierTransformSplices} from './journal-records.mjs';
+import {_rapierValidLedgerRecord, _rapierRecordSplices, _rapierTransformSplices, _rapierRecordMetadata, _rapierValidMetadata, _rapierTransformMetadata, _rapierReplayMetadata} from './journal-records.mjs';
+import {authoredHistory} from './transport.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) {
+export function readLedger(input, expectedText, expectedMetadata) {
   const ledger = plainData(input);
-  if (!exactKeys(ledger, ['format','documentAuthority','start','records','head','complete','sha256']) || ledger.format !== 'rapier-ledger/1' ||
+  if (!exactKeys(ledger, ['format','documentAuthority','start','records','head','complete','sha256']) || ledger.format !== 'rapier-ledger/2' ||
       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');
+      !exactKeys(ledger.start, ['text','revision','root','sha256','metadata']) || !exactKeys(ledger.head, ['revision','root','sha256','metadata'])) throw fault('unsupported or 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 (!_rapierValidMetadata(ledger.start.metadata) || !_rapierValidMetadata(ledger.head.metadata)) throw fault('invalid document metadata');
   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,
+    if (!Array.isArray(record.splices) || !_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');
@@ -31,39 +33,50 @@ export function readLedger(input, expectedText) {
     if (root !== record.afterHash) throw fault('record root differs');
     revision = record.transaction.revision; earlier.push(record);
   }
+  if (ledger.records.some(row => Object.hasOwn(row, 'authored'))) {
+    try { authoredHistory(ledger.start.text, ledger.records); } catch (_) { throw fault('authored origin differs'); }
+  }
+  const metadata = _rapierReplayMetadata(ledger.start.metadata, ledger.records);
+  if (!metadata || canonicalJSON(metadata) !== canonicalJSON(ledger.head.metadata) ||
+      (expectedMetadata !== undefined && (!_rapierValidMetadata(expectedMetadata) || canonicalJSON(metadata) !== canonicalJSON(expectedMetadata))))
+    throw fault('metadata does not describe this document');
   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};
+  return {ledger, text, metadata, root, revision, complete: ledger.complete};
 }
-export function exportLedger({text, records, documentAuthority, revision, root, complete = false, earlier = records} = {}) {
+export function exportLedger({text, metadata, records, documentAuthority, revision, root, complete = false, earlier = records} = {}) {
   documentText(text);
+  if (!_rapierValidMetadata(metadata)) throw fault('document metadata required');
   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');
+    const rows = _rapierRecordSplices(record, earlier), effect = _rapierRecordMetadata(record, earlier);
+    if (!rows || effect === undefined) 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};
+      beforeHash: record.beforeHash, afterHash: record.afterHash, ...(Object.hasOwn(record, 'authored') ? {authored: record.authored} : {}), ...(effect ? {metadata: effect} : {}),
+      ...(record.changeSet && Object.hasOwn(record.changeSet, 'label') ? {changeSet: {label: record.changeSet.label}} : {}),
+      ...(record.derivedCommentIndex == null ? {} : {derivedCommentIndex: record.derivedCommentIndex})};
   });
-  let startText = text;
+  let startText = text, startMetadata = {...metadata};
   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');
+    startMetadata = _rapierTransformMetadata(startMetadata, expanded[i].metadata, true);
+    if (startText === null || !startMetadata) 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 payload = {format: 'rapier-ledger/2', documentAuthority,
+    start: {text: startText, revision: startRevision, root: expanded[0]?.beforeHash ?? root, sha256: sha256(startText), metadata: startMetadata},
+    records: expanded, head: {revision, root, sha256: sha256(text), metadata: {...metadata}}, 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;
+  readLedger(ledger, text, metadata); 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));
+  const {ledger, text, metadata} = 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;
@@ -75,28 +88,31 @@ export function historyEnvelope(input, segmentIdentity = []) {
     } 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;
+  let traversed = text, traversedMetadata = {...metadata};
   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');
+    traversedMetadata = _rapierTransformMetadata(traversedMetadata, byId.get(branch[i]).metadata, true);
+    if (traversed === null || !traversedMetadata) throw fault('undo branch does not reverse');
   }
-  traversed = text;
+  traversed = text; traversedMetadata = {...metadata};
   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');
+    traversedMetadata = _rapierTransformMetadata(traversedMetadata, byId.get(branch[i]).metadata);
+    if (traversed === null || !traversedMetadata) 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');
+    let active = ledger.start.text, activeMetadata = {...ledger.start.metadata};
+    if (!cursor && (active !== text || canonicalJSON(activeMetadata) !== canonicalJSON(metadata))) 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');
+      activeMetadata = _rapierTransformMetadata(activeMetadata, byId.get(branch[i]).metadata);
+      if (active === null || !activeMetadata || (i + 1 === cursor && (active !== text || canonicalJSON(activeMetadata) !== canonicalJSON(metadata)))) throw fault('complete branch differs');
     }
   }
-  return {schemaVersion: 4, documentAuthority: ledger.documentAuthority, documentRevision: ledger.head.revision,
+  return {schemaVersion: 5, 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,
+    sourceRootId: ledger.head.root, earliestMetadata: {...ledger.start.metadata}, documentMetadata: {...metadata}, segmentIdentity, historyComplete: ledger.complete,
     trimReason: ledger.complete ? '' : 'carried_start', trimmedBytes: 0};
 }
 export function agentActorId(door, agent) {
@@ -124,8 +140,8 @@ export function replaceLedgerText(input, text, {actor = {kind: 'system', id: 'ra
     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,
+    reverts: null, reapplies: null, createdAt: at ?? null,
   }};
-  return exportLedger({text, records: [...current.ledger.records, record], documentAuthority: current.ledger.documentAuthority,
+  return exportLedger({text, metadata: current.metadata, records: [...current.ledger.records, record], documentAuthority: current.ledger.documentAuthority,
     revision, root, complete: current.complete});
 }