rapier-markdown-kit 1.1.90 → 1.1.92

package/README.md

@@ -1,7 +1,8 @@
 # rapier-markdown-kit
 
-Read, write and style Self-contained Markdown in your own code: one `.md` file that carries its pictures, layout
-and colour.
+Read, render and write Self-contained Markdown in browsers and Node: one `.md` file with pictures, editable SVG
+drawings, layout and colour. Build portable documents for people and agents. Will/1 regions mark what an agent
+may edit, append to or preserve. MIT, no dependencies.
 
 - Everything past CommonMark and GFM is an HTML comment other readers ignore or an ordinary reference
   definition, so every Markdown app still reads the file.
@@ -15,6 +16,10 @@ To show documents in your app without writing a renderer, frame the read-only re
 `npm install rapier-embed` (`build: 'reader'`). To hand a person the whole editor around their document as one
 offline file, run `npx rapier-html notes.md`.
 
+In the editor, an agent edits live beside the person or while they are away. Rapier shows its presence and changes;
+the person taps a change to see what was there before and undoes anything. `comparison.present` lets the agent
+deliberately show a diff. The kit supplies the portable source and history those tools use.
+
 ```sh
 npm install rapier-markdown-kit
 ```
@@ -27,6 +32,18 @@ import {parseWill} from 'rapier-markdown-kit/will';       // Will/1 markers: kee
 import {parseAssets} from 'rapier-markdown-kit/assets';   // the picture appendix
 ```
 
+## 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.
+
+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 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.
+
 ## The shared renderer
 
 `rapier-markdown-kit/render` exports `createRenderer`, `createMarkdownRenderer`,
@@ -42,7 +59,7 @@ 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'});
+const {html, filename} = await writer.render(source, {filename: 'report.md'});
 ```
 
 `createMarkdownRenderer(host).render(source, metadata)` returns the semantic HTML.
@@ -55,9 +72,10 @@ DOM objects between document realms.
 This **DOM-hosted library** requires a 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.
+separately supplied host or vendor. The [editor host binding](https://github.com/jackskip22/rapier/blob/main/src/editor/render-host.js)
+lists the renderer's dependencies. [rapier-server](https://github.com/jackskip22/rapier/blob/main/server/README.md)
+provides a complete local host with a pinned Chromium process. Its Word exporter and filesystem service are AGPL,
+not part of this MIT package.
 
 Serialization tests preserve source bytes through HTML export and recovery. Server integration
 tests also check the exported HTTP response through a browser DOM.
@@ -272,8 +290,9 @@ tolerance.
 
 ## Licence
 
-MIT, the full text in `LICENSE`; every module and the stylesheet keep their own MIT line. Pretext's licence, notice and
-pinned source inventory are in `dist/agent/vendor/pretext/`. The Rapier editor is AGPL-3.0-only and
+MIT, the full text in `LICENSE`; Rapier-owned modules and the stylesheet keep their MIT line. Pretext's licence, notice and
+pinned source inventory are in `dist/agent/vendor/pretext/`. The history projection's jsdiff dependency is BSD-3-Clause;
+`dist/agent/diff.mjs` carries its complete upstream copyright, conditions and disclaimer. The Rapier editor is AGPL-3.0-only and
 none of it is in this package. The kit carries Rapier's release number, written from the one
 value the editor's release reads.
 
@@ -294,7 +313,7 @@ import {exportLedger, readLedger, authorship, merge} from 'rapier-markdown-kit/r
 import {writeDocument, readDocument} from 'rapier-markdown-kit/ledger/carried';
 
 const ledger = exportLedger({
-  text: 'Hello', records: [], documentAuthority: 'example-document', complete: true,
+  text: 'Hello', metadata: {filename: 'Hello.md', docKind: 'markdown'}, records: [], documentAuthority: 'example-document', complete: true,
 });
 const saved = writeDocument('Hello', {ledger});
 const reopened = readDocument(saved);
@@ -308,23 +327,40 @@ console.assert(together.text === 'Hello');
 
 ## The format
 
-`rapier-ledger/1` is a plain JSON object:
+`rapier-ledger/2` 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}
+{format, documentAuthority, start: {text, revision, root, sha256, metadata}, records,
+ head: {revision, root, sha256, metadata}, complete, sha256}
+records[]: {transaction, splices: [{pos, removed, inserted}], beforeHash, afterHash, metadata?, authored?}
 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
+`format` is `rapier-ledger/2`. `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.
+64 splices. Metadata is {filename, docKind}; a record may carry filename or docKind pairs {before, after}. Metadata-only acts keep equal source roots and an empty splice list. Inverses reference retained act IDs, so later metadata choices survive selective Undo. File handles and save permissions are never portable. The existing record validator remains authoritative for field bounds.
+
+An optional `authored: {basis, source, splices}` preserves an act's original placement
+when concurrent transport changes its physical `record.splices`. `basis` is the sorted,
+minimal frontier of canonical act IDs observed at authoring; its causal closure is
+reconstructed from these same records, including metadata-only acts and inverse
+dependencies. `source` is the SHA-256 of the exact UTF-8 source before the original
+sequential `splices`. An ordinary untransported record omits this field; its retained
+prefix supplies the same evidence. Transport preserves the evidence and the original
+act ID, author, time, turn, label, metadata choices and inverse targets. It neither
+copies the growing prefix into each record nor creates another journal.
+
+Use `readLedger` or `exportLedger` to validate retained history and `merge` or
+`transposeAuthored` to transport it. Validation proves the causal closure, source
+hash and exact original-to-physical placement; field shape or equal final text alone
+is insufficient. Do not attach new authored evidence to an arbitrary physical copy.
+Selective Undo uses this evidence to preserve concurrent insertions at their original
+gaps, even when a replacement split into several physical splices.
 
 `start.sha256` and `head.sha256` hash UTF-8 text. The envelope `sha256` hashes
 canonical JSON of every other envelope field: recursively sorted object keys,
@@ -340,16 +376,17 @@ actual document. `historyEnvelope` additionally proves the editor's Undo/Redo br
 a fresh hash of the whole current text. SHA-256 of the exact checkpoint text is
 separate. 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.
+revision gap in a partial ledger; each retained splice must still replay exactly. An incomplete ledger never
+claims to reconstruct events it does not contain.
+
+`actor.kind` is `human`, `agent` or `system`. Canonical doors mint an opaque provenance
+`actor.id` independent of the private principal and retain a supplied display name
+separately as `actor.name` (host names at most 96 characters). The private principal-to-author
+mapping stays in the existing private owner; neither raw nor hashed access credentials
+belong in portable authorship. 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.
+principal's read handles or authenticated document access.
 
 ## Optional carried parts
 
@@ -359,7 +396,7 @@ 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 |
+| `#rapier-ledger` | `application/json`, `rapier-ledger/2` | The whole history |
 
 Each body uses the same reversible `encodeCarried`/`decodeCarried` escape as the
 page's source. `writeParts`, `readParts` and `takeParts` implement it. Duplicate,
@@ -392,10 +429,10 @@ 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.
+The comparison page's `#rapier-base` is independent: `text/markdown`, with
+`data-name`, `data-revision`, `data-sha256`, `data-by` and `data-at`, carries an exact
+display reference. It is not reconstructed from the optional ledger and never
+replaces current source. `rapier-html --compare original.md revised.md` packages both texts.
 
 ## Merging copies without a server
 
@@ -414,22 +451,19 @@ unchanged. `review.required` names an unresolved result; a UI must not auto-acce
 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.
+copy import 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
+MCP uses the request's client metadata, outside tool arguments; a 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.
+Rapier's live history supports before previews and Undo for individual acts or turns, preserving later edits.
+A carried ledger preserves the history included in that file and explicitly identifies an incomplete start.
+Full history includes removed text and can be much larger than the current document; choose it separately for
+each outgoing file. Authorship is also optional. Neither part verifies identities or synchronizes copies.

package/dist/agent/diff.mjs

@@ -0,0 +1,52 @@
+/*! jsdiff 9.0.0 — derivative bundle. Upstream licence, reproduced complete:
+		https://github.com/kpdecker/jsdiff/blob/v9.0.0/LICENSE
+
+BSD 3-Clause License
+
+Copyright (c) 2009-2015, Kevin Decker <kpdecker@gmail.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+	 list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+	 this list of conditions and the following disclaimer in the documentation
+	 and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+	 contributors may be used to endorse or promote products derived from
+	 this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+/* Rapier note on this derivative bundle: the wall clock and the scheduler are injected.
+   `diffWithOptionsObj` reads `options.now()` instead of `Date.now()` and `options.schedule(fn,
+   ms)` instead of `setTimeout(fn, ms)`. Callers that want a real-time `timeout` or the async
+   callback path pass `{ now: Date.now, schedule: setTimeout }` (the Compare Worker in
+   editor/engine.js); callers that want a deterministic result bound only by `maxEditLength` pass
+   neither (the kernel), and the diff then depends on nothing but its two input strings. This keeps
+   one diff factory for the whole app and keeps agent/kernel.mjs inside the decision-purity gate
+   (tools/purity-gate.mjs) without any per-file exemption. */
+export function createDiff(){var O=Object.defineProperty;var Y=Object.getOwnPropertyDescriptor;var B=Object.getOwnPropertyNames;var Q=Object.prototype.hasOwnProperty;var X=(i,e)=>{for(var n in e)O(i,n,{get:e[n],enumerable:!0})},Z=(i,e,n,t)=>{if(e&&typeof e=="object"||typeof e=="function")for(let l of B(e))!Q.call(i,l)&&l!==n&&O(i,l,{get:()=>e[l],enumerable:!(t=Y(e,l))||t.enumerable});return i};var K=i=>Z(O({},"__esModule",{value:!0}),i);var oe={};X(oe,{diffChars:()=>diffChars,diffLines:()=>y,diffWordsWithSpace:()=>z,structuredPatch:()=>U});var C=class{diff(e,n,t={}){let l;typeof t=="function"?(l=t,t={}):"callback"in t&&(l=t.callback);let o=this.castInput(e,t),r=this.castInput(n,t),u=this.removeEmpty(this.tokenize(o,t)),a=this.removeEmpty(this.tokenize(r,t));return this.diffWithOptionsObj(u,a,t,l)}diffWithOptionsObj(e,n,t,l){var o;let r=s=>{if(s=this.postProcess(s,t),l){t.schedule(function(){l(s)},0);return}else return s},u=n.length,a=e.length,f=1,c=u+a;t.maxEditLength!=null&&(c=Math.min(c,t.maxEditLength));let w=(o=t.timeout)!==null&&o!==void 0?o:1/0,p=(t.now?t.now():0)+w,m=[{oldPos:-1,lastComponent:void 0}],x=this.extractCommon(m[0],n,e,0,t);if(m[0].oldPos+1>=a&&x+1>=u)return r(this.buildValues(m[0].lastComponent,n,e));let v=-1/0,P=1/0,E=()=>{for(let s=Math.max(v,-f);s<=Math.min(P,f);s+=2){let d,h=m[s-1],g=m[s+1];h&&(m[s-1]=void 0);let F=!1;if(g){let q=g.oldPos-s;F=g&&0<=q&&q<u}let D=h&&h.oldPos+1<a;if(!F&&!D){m[s]=void 0;continue}if(!D||F&&h.oldPos<g.oldPos?d=this.addToPath(g,!0,!1,0,t):d=this.addToPath(h,!1,!0,1,t),x=this.extractCommon(d,n,e,s,t),d.oldPos+1>=a&&x+1>=u)return r(this.buildValues(d.lastComponent,n,e))||!0;m[s]=d,d.oldPos+1>=a&&(P=Math.min(P,s-1)),x+1>=u&&(v=Math.max(v,s+1))}f++};if(l)(function s(){t.schedule(function(){if(f>c||(t.now?t.now():0)>p)return l(void 0);E()||s()},0)})();else for(;f<=c&&(t.now?t.now():0)<=p;){let s=E();if(s)return s}}addToPath(e,n,t,l,o){let r=e.lastComponent;return r&&!o.oneChangePerToken&&r.added===n&&r.removed===t?{oldPos:e.oldPos+l,lastComponent:{count:r.count+1,added:n,removed:t,previousComponent:r.previousComponent}}:{oldPos:e.oldPos+l,lastComponent:{count:1,added:n,removed:t,previousComponent:r}}}extractCommon(e,n,t,l,o){let r=n.length,u=t.length,a=e.oldPos,f=a-l,c=0;for(;f+1<r&&a+1<u&&this.equals(t[a+1],n[f+1],o);)f++,a++,c++,o.oneChangePerToken&&(e.lastComponent={count:1,previousComponent:e.lastComponent,added:!1,removed:!1});return c&&!o.oneChangePerToken&&(e.lastComponent={count:c,previousComponent:e.lastComponent,added:!1,removed:!1}),e.oldPos=a,f}equals(e,n,t){return t.comparator?t.comparator(e,n):e===n||!!t.ignoreCase&&e.toLowerCase()===n.toLowerCase()}removeEmpty(e){let n=[];for(let t=0;t<e.length;t++)e[t]&&n.push(e[t]);return n}castInput(e,n){return e}tokenize(e,n){return Array.from(e)}join(e){return e.join("")}postProcess(e,n){return e}buildValues(e,n,t){let l=[],o;for(;e;)l.push(e),o=e.previousComponent,delete e.previousComponent,e=o;l.reverse();let r=l.length,u=0,a=0,f=0;for(;u<r;u++){let c=l[u];if(c.removed)c.value=this.join(t.slice(f,f+c.count)),f+=c.count;else{c.value=this.join(n.slice(a,a+c.count));a+=c.count,c.added||(f+=c.count)}}return l}};var I="a-zA-Z0-9_\\u{AD}\\u{C0}-\\u{D6}\\u{D8}-\\u{F6}\\u{F8}-\\u{2C6}\\u{2C8}-\\u{2D7}\\u{2DE}-\\u{2FF}\\u{1E00}-\\u{1EFF}";var R=class extends C{tokenize(e){let n=new RegExp(`(\\r?\\n)|[${I}]+|[^\\S\\n\\r]+|[^${I}]`,"ug");return e.match(n)||[]}},J=new R;function z(i,e,n){return J.diff(i,e,n)}var $=class extends C{constructor(){super(...arguments),this.tokenize=ie}equals(e,n,t){return t.ignoreWhitespace?((!t.newlineIsToken||!e.includes(`
+`))&&(e=e.trim()),(!t.newlineIsToken||!n.includes(`
+`))&&(n=n.trim())):t.ignoreNewlineAtEof&&!t.newlineIsToken&&(e.endsWith(`
+`)&&(e=e.slice(0,-1)),n.endsWith(`
+`)&&(n=n.slice(0,-1))),super.equals(e,n,t)}},V=new $;function y(i,e,n){return V.diff(i,e,n)}function ie(i,e){e.stripTrailingCr&&(i=i.replace(/\r\n/g,`
+`));let n=[],t=i.split(/(\n|\r\n)/);t[t.length-1]||t.pop();for(let l=0;l<t.length;l++){let o=t[l];l%2&&!e.newlineIsToken?n[n.length-1]+=o:n.push(o)}return n}function U(i,e,n,t,l,o,r){let u;r?typeof r=="function"?u={callback:r}:u=r:u={},typeof u.context>"u"&&(u.context=4);let a=u.context;if(u.newlineIsToken)throw new Error("newlineIsToken may not be used with patch-generation functions, only with diffing functions");if(u.callback){let{callback:c}=u;y(n,t,Object.assign(Object.assign({},u),{callback:w=>{let p=f(w);c(p)}}))}else return f(y(n,t,u));function f(c){if(!c)return;c.push({value:"",lines:[]});function w(s){return s.map(function(d){return" "+d})}let p=[],m=0,x=0,v=[],P=1,E=1;for(let s=0;s<c.length;s++){let d=c[s],h=d.lines||le(d.value);if(d.lines=h,d.added||d.removed){if(!m){let g=c[s-1];m=P,x=E,g&&(v=a>0?w(g.lines.slice(-a)):[],m-=v.length,x-=v.length)}for(let g of h)v.push((d.added?"+":"-")+g);d.added?E+=h.length:P+=h.length}else{if(m)if(h.length<=a*2&&s<c.length-2)for(let g of w(h))v.push(g);else{let g=Math.min(h.length,a);for(let D of w(h.slice(0,g)))v.push(D);let F={oldStart:m,oldLines:P-m+g,newStart:x,newLines:E-x+g,lines:v};p.push(F),m=0,x=0,v=[]}P+=h.length,E+=h.length}}for(let s of p)for(let d=0;d<s.lines.length;d++)s.lines[d].endsWith(`
+`)?s.lines[d]=s.lines[d].slice(0,-1):(s.lines.splice(d+1,0,"\"),d++);return{oldFileName:i,newFileName:e,oldHeader:l,newHeader:o,hunks:p}}}function le(i){let e=i.endsWith(`
+`),n=i.split(`
+`).map(t=>t+`
+`);return e?n.pop():n.push(n.pop().slice(0,-1)),n}function diffChars(before,after,options){return new C().diff(before,after,options)}return K(oe);}
+export const {diffChars, diffLines, diffWordsWithSpace, structuredPatch} = createDiff();

package/dist/kit/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/kit/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/kit/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});
 }