@toclocoinc/lattice-grid 1.21.0 → 1.23.0

package/README.md

@@ -4,7 +4,7 @@
 dependencies, no build step required. Optional adapters for React, Vue, Svelte
 and Web Components ship alongside it.
 
-Version 1.21.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.23.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 

package/docs/API.html

@@ -2764,11 +2764,16 @@ app.get('/api/orders', async (req, res) => {
       A worked example, executed on every build so it cannot go stale
       (<code>data-run</code>, PRD&nbsp;§7&nbsp;C3):
     </p>
-    <pre data-run="js" data-expect="3" data-covers="export:capabilitiesOf export:splitFilters"><code><span class="kw">const</span> { capabilitiesOf, splitFilters } = <span class="kw">await</span> import('../packages/core/src/source/pushdown.js');
+    <pre data-run="js" data-expect="3" data-covers="export:capabilitiesOf export:splitFilters export:resolveMutate"><code><span class="kw">const</span> { capabilitiesOf, splitFilters, resolveMutate } = <span class="kw">await</span> import('../packages/core/src/source/pushdown.js');
 
 <span class="cmt">// An adapter that understands three comparisons and nothing else.</span>
 <span class="kw">const</span> caps = capabilitiesOf({ filter: 'tree', operators: ['eq', 'gt', 'lt'] });
 
+<span class="cmt">// Read-only by declaration: an adapter that says nothing about writing</span>
+<span class="cmt">// cannot mutate, and one that opts in resolves to a complete capability.</span>
+<span class="kw">if</span> (resolveMutate() !== false) <span class="kw">throw</span> new Error('a silent adapter must stay read-only');
+<span class="kw">if</span> (!resolveMutate({ update: true }).update) <span class="kw">throw</span> new Error('an opt-in must resolve');
+
 <span class="cmt">// A conjunction splits: what the engine knows goes to it, the rest stays here.</span>
 <span class="kw">const</span> { pushed } = splitFilters({
   op: 'and',
@@ -2792,6 +2797,7 @@ app.get('/api/orders', async (req, res) =&gt; {
         <thead><tr><th>Export</th><th>Signature</th><th>Description</th></tr></thead>
         <tbody>
           <tr><td class="name">capabilitiesOf</td><td class="type">(declared?) =&gt; Required&lt;PushdownCapabilities&gt;</td><td class="desc">Resolves what an adapter declared against the defaults, giving a complete set with no absent keys to test for.</td></tr>
+          <tr><td class="name">resolveMutate</td><td class="type">(declared?) =&gt; false | MutateCapability</td><td class="desc">Resolves an adapter's <code>mutate</code> declaration against the defaults. Returns <code>false</code> when the adapter cannot mutate, so a source over it stays read-only by declaration and refuses a write loudly rather than dropping it.</td></tr>
           <tr><td class="name">splitFilters</td><td class="type">(filters, caps) =&gt; { pushed, residual }</td><td class="desc">Divides a condition tree into the half the engine takes and the half left over. A conjunction splits; a disjunction that is not fully supported stays whole on the client, because pushing part of an <code>or</code> returns fewer rows than the filter allows and the grid cannot recover what was never fetched.</td></tr>
           <tr><td class="name">planQuery</td><td class="type">(request, caps) =&gt; PushdownPlan</td><td class="desc">Plans one request: the query to send, the work to finish afterwards, whether the whole result is needed, and which parts stayed behind.</td></tr>
           <tr><td class="name">applyResidual</td><td class="type">(rows, residual, compute) =&gt; unknown[]</td><td class="desc">Applies whatever the engine could not, through the grid's own filter and sort kernels rather than a second implementation, so a residual predicate means exactly what the same predicate means anywhere else.</td></tr>
@@ -3183,6 +3189,7 @@ off();                                       <span class="cmt">// on() returns i
           <tr><td class="name">cell:pending</td><td class="type">{ row, key, colId, value, before, id }</td><td class="desc">Applied optimistically, not yet durable. Only with <code>edit.commit</code>.</td></tr>
           <tr><td class="name">cell:confirmed</td><td class="type">{ row, key, colId, value, id, superseded }</td><td class="desc">The write reached the server.</td></tr>
           <tr><td class="name">cell:reverted</td><td class="type">{ row, key, colId, rejected, restored, reason, id, superseded, applied }</td><td class="desc">The write failed. <code>applied: false</code> means a newer edit owned the cell, so nothing was written back.</td></tr>
+          <tr><td class="name">cell:conflict</td><td class="type">{ row, key, colId, value, serverRow, id }</td><td class="desc">The write succeeded but the server row had moved underneath it. Last-write-wins: <code>value</code> stands and <code>serverRow</code> carries the server's truth so the divergence is surfaced, never swallowed.</td></tr>
           <tr><td class="name">cell:edit:start</td><td class="type">{ row, key, colId, column }</td><td class="desc">An edit session opened.</td></tr>
           <tr><td class="name">cell:edit:end</td><td class="type">{ row, key, colId, valid, errors }</td><td class="desc">It closed: committed or cancelled.</td></tr>
           <tr><td class="name">cell:clicked</td><td class="type">{ row, key, index, colId, column, value, text, event }</td><td class="desc">A cell was clicked. Announcement only: nothing is consumed, so editing and selection behave unchanged.</td></tr>
@@ -4322,16 +4329,16 @@ grid.destroy();
     <p class="section-note">Each documented event is subscribed to and unsubscribed on every build. A consumer
     wiring a handler to a renamed event gets silence, which is indistinguishable from an event that
     has not fired yet — so the name is checked rather than left to be discovered.</p>
-    <pre data-run="js" data-expect="101" data-covers="event:cell:changed event:cell:clicked event:cell:confirmed event:cell:contextmenu event:cell:dblclicked event:cell:edit:end event:cell:edit:start event:cell:pending event:cell:reverted event:clipboard:copy event:column:filter:open event:column:grouped event:column:menu:open event:column:pivoted event:column:resized event:columns:changed event:columns:tagged event:comment:added event:comment:deleted event:comment:edited event:comment:failed event:comment:indexLoaded event:comment:resolved event:comment:threadClosed event:comment:threadOpened event:comment:unresolved event:destroy event:detail:toggled event:diff:changed event:diff:swapped event:export:progress event:facet:computed event:facet:expanded event:facet:failed event:facet:filtered event:form:closed event:form:error event:form:opened event:form:saved event:formatting:changed event:group:toggled event:header:contextmenu event:highlight:changed event:history:applied event:history:changed event:licence:changed event:page:changed event:permissions:changed event:presence:failed event:presence:joined event:presence:left event:presence:lockRefused event:presence:published event:presence:updated event:presentation:captured event:presentation:changed event:presentation:ended event:presentation:scale event:presentation:spotlight event:presentation:started event:presentation:view event:range:changed event:ready event:redaction:changed event:render:done event:render:first event:row:clicked event:row:copied event:row:dblclicked event:row:edit:end event:row:edit:start event:row:moved event:row:received event:row:sent event:rows:deferred event:rows:paused event:rows:queued event:rows:resumed event:scroll event:scroll:end event:selection:changed event:size:changed event:source:error event:stream:chunk event:stream:end event:stream:evicted event:timeline:attached event:timeline:detached event:timeline:seek event:timeline:seeking event:toolpanel:focus event:tree:loadAborted event:tree:loadFailed event:tree:loaded event:tree:loading event:view:applied event:view:default event:view:removed event:view:renamed event:view:saved event:views:changed"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+    <pre data-run="js" data-expect="102" data-covers="event:cell:changed event:cell:clicked event:cell:confirmed event:cell:conflict event:cell:contextmenu event:cell:dblclicked event:cell:edit:end event:cell:edit:start event:cell:pending event:cell:reverted event:clipboard:copy event:column:filter:open event:column:grouped event:column:menu:open event:column:pivoted event:column:resized event:columns:changed event:columns:tagged event:comment:added event:comment:deleted event:comment:edited event:comment:failed event:comment:indexLoaded event:comment:resolved event:comment:threadClosed event:comment:threadOpened event:comment:unresolved event:destroy event:detail:toggled event:diff:changed event:diff:swapped event:export:progress event:facet:computed event:facet:expanded event:facet:failed event:facet:filtered event:form:closed event:form:error event:form:opened event:form:saved event:formatting:changed event:group:toggled event:header:contextmenu event:highlight:changed event:history:applied event:history:changed event:licence:changed event:page:changed event:permissions:changed event:presence:failed event:presence:joined event:presence:left event:presence:lockRefused event:presence:published event:presence:updated event:presentation:captured event:presentation:changed event:presentation:ended event:presentation:scale event:presentation:spotlight event:presentation:started event:presentation:view event:range:changed event:ready event:redaction:changed event:render:done event:render:first event:row:clicked event:row:copied event:row:dblclicked event:row:edit:end event:row:edit:start event:row:moved event:row:received event:row:sent event:rows:deferred event:rows:paused event:rows:queued event:rows:resumed event:scroll event:scroll:end event:selection:changed event:size:changed event:source:error event:stream:chunk event:stream:end event:stream:evicted event:timeline:attached event:timeline:detached event:timeline:seek event:timeline:seeking event:toolpanel:focus event:tree:loadAborted event:tree:loadFailed event:tree:loaded event:tree:loading event:view:applied event:view:default event:view:removed event:view:renamed event:view:saved event:views:changed"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
 
 <span class="cmt">// Every documented event name, checked against the bus that would carry it.</span>
 <span class="cmt">// Subscribing to a name the grid does not know is the failure this catches:</span>
 <span class="cmt">// a consumer wiring a handler to a renamed event gets silence, and silence</span>
 <span class="cmt">// is indistinguishable from an event that simply has not fired yet.</span>
 <span class="kw">const</span> documented = [
-  'cell:changed', 'cell:clicked', 'cell:confirmed', 'cell:contextmenu',
-  'cell:dblclicked', 'cell:edit:end', 'cell:edit:start', 'cell:pending',
-  'cell:reverted', 'clipboard:copy', 'column:filter:open', 'column:grouped',
+  'cell:changed', 'cell:clicked', 'cell:confirmed', 'cell:conflict',
+  'cell:contextmenu', 'cell:dblclicked', 'cell:edit:end', 'cell:edit:start',
+  'cell:pending', 'cell:reverted', 'clipboard:copy', 'column:filter:open', 'column:grouped',
   'column:menu:open', 'column:pivoted', 'column:resized', 'columns:changed',
   'columns:tagged', 'comment:added', 'comment:deleted', 'comment:edited',
   'comment:failed', 'comment:indexLoaded', 'comment:resolved', 'comment:threadClosed',
@@ -5289,6 +5296,36 @@ grid.destroy();
         </tbody>
       </table>
     </div>
+    <h3 id="type-DatasetColumnDifference">DatasetColumnDifference</h3>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">column</td><td class="type">string</td><td class="desc">The column id, present on both grids.</td></tr>
+          <tr><td class="name">name</td><td class="type">string</td><td class="desc">The column's display name, or its id.</td></tr>
+          <tr><td class="name">measure</td><td class="type">'pooledStandardMeanDifference' | 'categoricalTotalVariation'</td><td class="desc">The effect size reported for this column's family: the pooled standardised mean difference (Cohen's d) for a numeric column, the total variation of the category mix for a categorical one. Never a p-value.</td></tr>
+          <tr><td class="name">magnitude</td><td class="type">number | null</td><td class="desc">The effect size in its own terms, or null when it has no scale here.</td></tr>
+          <tr><td class="name">distance</td><td class="type">number</td><td class="desc">The total variation distance between the two datasets, 0 to 1 — the common scale both families reduce to, and what the ranking sorts by.</td></tr>
+          <tr><td class="name">direction</td><td class="type">number</td><td class="desc">+1 when dataset A sits above dataset B, −1 below, 0 for a mix.</td></tr>
+          <tr><td class="name">nA</td><td class="type">number</td><td class="desc">How many rows the first grid's side stood on.</td></tr>
+          <tr><td class="name">nB</td><td class="type">number</td><td class="desc">How many rows the second grid's side stood on.</td></tr>
+          <tr><td class="name">reliable</td><td class="type">boolean</td><td class="desc">False when either side is too small to read the difference from.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3 id="type-DatasetComparison">DatasetComparison</h3>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">ranked</td><td class="type">DatasetColumnDifference[]</td><td class="desc">Every shared column, largest difference first.</td></tr>
+          <tr><td class="name">nA</td><td class="type">number</td><td class="desc">How many rows the first grid contributed (its filtered set).</td></tr>
+          <tr><td class="name">nB</td><td class="type">number</td><td class="desc">How many rows the second grid contributed (its filtered set).</td></tr>
+          <tr><td class="name">unmatched</td><td class="type">{ onlyA: string[]; onlyB: string[] }</td><td class="desc">Columns present on only one side, which cannot be compared.</td></tr>
+          <tr><td class="name">measures</td><td class="type">{ numeric: string; categorical: string; common: string }</td><td class="desc">The measure each family reports, and the common scale, named for a legend.</td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-DataType">DataType</h3>
     <div class="table-wrap">
       <table>
@@ -5515,7 +5552,7 @@ grid.destroy();
           <tr><td class="name">pasteInto</td><td class="type">(anchor: { key: string; colId: string }, text: string, extent?: { rows?: number; columns?: number }): number</td><td class="desc"></td></tr>
           <tr><td class="name">pastePreview</td><td class="type">boolean</td><td class="desc">Whether a bulk paste is previewed before it commits (`edit.pastePreview`, §12). <small>(read-only)</small></td></tr>
           <tr><td class="name">previewPaste</td><td class="type">(anchor: { key: string; colId: string }, text: string, extent?: { rows?: number; columns?: number }): {</td><td class="desc">Compute what a paste would change, without committing (§12). The engine behind `edit.pastePreview`: `changes` are the accepted writes with their old and new values (and whether each actually differs), `rejected` are the cells a commit would refuse, each with a reason.</td></tr>
-          <tr><td class="name">settle</td><td class="type">(id: string, ok: boolean, reason?: string): boolean</td><td class="desc"></td></tr>
+          <tr><td class="name">settle</td><td class="type">(</td><td class="desc">Report the outcome of an in-flight write (§18.3; §5.1-5.2 reconcile). `reconcile` carries server truth on a successful settle: `value` is a server-authoritative value written back before `cell:confirmed` (`returning: 'row'`); `conflict.serverRow` surfaces a last-write-wins conflict via `cell:conflict`. Omit both to keep the optimistic value.</td></tr>
           <tr><td class="name">pending</td><td class="type">(): OpenWrite[]</td><td class="desc"></td></tr>
           <tr><td class="name">status</td><td class="type">(key: string, colId: string): 'pending' | null</td><td class="desc"></td></tr>
         </tbody>
@@ -6229,6 +6266,49 @@ grid.destroy();
         </tbody>
       </table>
     </div>
+    <h3 id="type-MutateCapability">MutateCapability</h3>
+    <p class="section-note">What an adapter can persist back to its source — the write-back capability (§4.1), declared on `AdapterCapabilities.mutate`. `false` (the default) is read-only by declaration; a resolved block turns every kind off unless the adapter opts in.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">append</td><td class="type">boolean</td><td class="desc">The adapter can insert new rows. Wave 1: declared, not yet bridged. <small>(optional)</small></td></tr>
+          <tr><td class="name">update</td><td class="type">boolean</td><td class="desc">The adapter can patch existing rows. Wave 1: the wired kind (§4.3 Option A). <small>(optional)</small></td></tr>
+          <tr><td class="name">delete</td><td class="type">boolean</td><td class="desc">The adapter can remove rows. Wave 1: declared, not yet bridged. <small>(optional)</small></td></tr>
+          <tr><td class="name">returning</td><td class="type">'row' | 'key' | 'none'</td><td class="desc">The reconcile contract — what the server hands back after a successful mutation (§5.1). `'row'`: the authoritative row (id, computed columns, timestamps), reconciled before confirm. `'key'`: only the assigned key. `'none'` (the default): nothing — the optimistic value stands (last-write-wins). <small>(optional)</small></td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3 id="type-MutationOp">MutationOp</h3>
+    <p class="section-note">One mutation handed to `adapter.mutate(op, request)` (§4.2). Cell-scoped `update` is the only kind wave 1 synthesises; `append`/`delete` are part of the shape so it survives into a later structural build (card 770).</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">kind</td><td class="type">'append' | 'update' | 'delete'</td><td class="desc"></td></tr>
+          <tr><td class="name">rows</td><td class="type">unknown[]</td><td class="desc">append: the new rows (may lack a server-assigned key). <small>(optional)</small></td></tr>
+          <tr><td class="name">key</td><td class="type">string</td><td class="desc">update: the row key. <small>(optional)</small></td></tr>
+          <tr><td class="name">patch</td><td class="type">Record&lt;string, unknown&gt;</td><td class="desc">update: the changed columns only, matching `PendingWrite` semantics. <small>(optional)</small></td></tr>
+          <tr><td class="name">keys</td><td class="type">string[]</td><td class="desc">delete: the row key(s). <small>(optional)</small></td></tr>
+          <tr><td class="name">origin</td><td class="type">string</td><td class="desc">Provenance, carried through for auth / audit. <small>(optional)</small></td></tr>
+          <tr><td class="name">requestId</td><td class="type">string</td><td class="desc">Stable id for idempotent retry / dedupe. Reserved; retry is a non-goal in wave 1. <small>(optional)</small></td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3 id="type-MutationResult">MutationResult</h3>
+    <p class="section-note">The result of a mutation (§4.2) — the reconcile payload. A cell-update commit flows this back through `PendingWrites`: `ok: false` reverts and surfaces `reason`; `rows` (`returning: 'row'`) reconciles server truth before confirm; `conflict` surfaces a last-write-wins divergence via `cell:conflict`.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">ok</td><td class="type">boolean</td><td class="desc"></td></tr>
+          <tr><td class="name">rows</td><td class="type">unknown[]</td><td class="desc">`returning: 'row'` — the authoritative row(s) to reconcile to. <small>(optional)</small></td></tr>
+          <tr><td class="name">keys</td><td class="type">string[]</td><td class="desc">`returning: 'key'` — server-assigned key(s) for appended rows, in order. <small>(optional)</small></td></tr>
+          <tr><td class="name">reason</td><td class="type">string</td><td class="desc">On rejection — surfaced on `cell:reverted`, never swallowed. <small>(optional)</small></td></tr>
+          <tr><td class="name">conflict</td><td class="type">{ key: string; serverRow?: unknown }</td><td class="desc">The server's current value, for a surfaced last-write-wins conflict. <small>(optional)</small></td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-NumberFormat">NumberFormat</h3>
     <div class="table-wrap">
       <table>
@@ -6506,6 +6586,7 @@ grid.destroy();
           <tr><td class="name">name</td><td class="type">string</td><td class="desc">Used in diagnostics and in the message when work cannot be pushed. <small>(optional)</small></td></tr>
           <tr><td class="name">capabilities</td><td class="type">PushdownCapabilities</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">execute</td><td class="type">(query: RemoteRequest, request?: RemoteRequest):</td><td class="desc">Run the part of the query the adapter declared it could handle.</td></tr>
+          <tr><td class="name">mutate</td><td class="type">(op: MutationOp, request?: RemoteRequest): Promise&lt;MutationResult&gt;</td><td class="desc">Persist one mutation (§4.2). Present only when `capabilities.mutate` opts in. `createPushdownSource` synthesises an `edit.commit` that calls this for cell updates (§4.3 Option A); `request` threads the abort signal through the way `execute` receives it, and auth already lives on the adapter. <small>(optional)</small></td></tr>
         </tbody>
       </table>
     </div>
@@ -6533,6 +6614,7 @@ grid.destroy();
           <tr><td class="name">range</td><td class="type">boolean</td><td class="desc">Whether the engine can return a window rather than the whole result. <small>(optional)</small></td></tr>
           <tr><td class="name">total</td><td class="type">boolean</td><td class="desc">Whether it can report the count of matching rows. <small>(optional)</small></td></tr>
           <tr><td class="name">group</td><td class="type">boolean</td><td class="desc">Whether it can group and aggregate. <small>(optional)</small></td></tr>
+          <tr><td class="name">mutate</td><td class="type">false | MutateCapability</td><td class="desc">What the adapter can persist back — the write-back contract (§4.1). `false` (the default) is read-only by declaration. A declared block opts kinds in; `capabilitiesOf` resolves it to a full `MutateCapability` (or `false`). <small>(optional)</small></td></tr>
         </tbody>
       </table>
     </div>
@@ -7048,13 +7130,14 @@ grid.destroy();
       <table>
         <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
         <tbody>
-          <tr><td class="name">shadow</td><td class="type">(colId: string, kind: ShadowKind, rowKey: string, scope?: 'all' | 'filtered'): unknown</td><td class="desc">One shadow value for one row, by the column it shadows and the kind.</td></tr>
+          <tr><td class="name">shadow</td><td class="type">(colId: string, kind: ShadowKind, rowKey: string,</td><td class="desc">One shadow value for one row, by the column it shadows and the kind. For `kind: 'specStatus'`, `spec` carries the `{lower, upper, warnLower, warnUpper}` limits to judge the row's value against; other kinds ignore it.</td></tr>
           <tr><td class="name">running</td><td class="type">(colId: string, kind: 'total' | 'percent', rowKey: string): number | null</td><td class="desc">A running total at one row, down the grid as it is currently ordered.</td></tr>
           <tr><td class="name">rebase</td><td class="type">(colId?: string): void</td><td class="desc">Make the current values the new baseline: "mark all".</td></tr>
           <tr><td class="name">tracking</td><td class="type">(): { columns: string[]; rows: number; forgotten: number }</td><td class="desc">What the shadow histories are costing.</td></tr>
           <tr><td class="name">reduce</td><td class="type">(colId: string, fn: string): unknown</td><td class="desc">Reduce a column by a named kernel over the filtered rows.</td></tr>
           <tr><td class="name">profile</td><td class="type">(colId: string): ColumnProfile | null</td><td class="desc">Everything worth knowing about one column, in one pass each.</td></tr>
           <tr><td class="name">subsetVsPopulation</td><td class="type">(opts?: { columns?: string[] }): SubsetComparison</td><td class="desc">Which columns differ most between the filtered subset and the whole population it was drawn from, ranked by effect size — never by a p-value. The measure is stated per column; a numeric and a categorical column are put on one bounded scale so they rank against each other.</td></tr>
+          <tr><td class="name">datasetVsDataset</td><td class="type">(other: Grid, opts?: { columns?: string[] }): DatasetComparison</td><td class="desc">Which columns differ most between this grid and another, ranked by effect size — never by a p-value (BACKLOG-0000735). The generalisation of {@link subsetVsPopulation} from subset-vs-population to dataset-vs-dataset: two independent grids, yoked by passing one in, no shared store. A numeric column reports a pooled standardised mean difference (Cohen's d, symmetric in the two peers where Glass's delta is not); a categorical column the total variation of its category mix; both land on one bounded scale. Both sides are read over their filtered rows. Only shared columns are ranked; a column on one side alone is returned under `unmatched`.</td></tr>
           <tr><td class="name">correlation</td><td class="type">(a: string, b: string): number | null</td><td class="desc">Pearson's correlation between two columns.</td></tr>
           <tr><td class="name">covariance</td><td class="type">(a: string, b: string, opts?: { population?: boolean }): number | null</td><td class="desc">Covariance, a correlation before the scales are divided out.</td></tr>
           <tr><td class="name">regression</td><td class="type">(a: string, b: string): RegressionFit | null</td><td class="desc">Least-squares fit of `b` on `a`: in finance, beta and alpha.</td></tr>

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.21.0</p>
+    <p class="rail__sub">Developer guide · v1.23.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -3601,6 +3601,7 @@ socket.onmessage = (m) =&gt; {
           <tr><td class="sig">pending</td><td class="desc">Applied and painted, not yet acknowledged.</td><td class="desc"><code>cell:pending</code></td></tr>
           <tr><td class="sig">confirmed</td><td class="desc">The server accepted it. Nothing is written back.</td><td class="desc"><code>cell:confirmed</code></td></tr>
           <tr><td class="sig">reverted</td><td class="desc">The server refused it; the cell is rolled back.</td><td class="desc"><code>cell:reverted</code></td></tr>
+          <tr><td class="sig">conflict</td><td class="desc">The write was accepted but the server row had moved underneath it. Last-write-wins: your value stands and the server's truth is surfaced so you can reconcile it.</td><td class="desc"><code>cell:conflict</code></td></tr>
           <tr><td class="sig">superseded</td><td class="desc">A newer edit replaced it while it was in flight.</td><td class="desc">either, with <code>superseded: true</code></td></tr>
         </tbody>
       </table>
@@ -6137,6 +6138,7 @@ el.grid.sort.set([{ col: 'charge', dir: 'desc' }]);</code></pre>
           <tr><td class="name">cell:changed</td><td class="desc">A committed edit reached the data. undo distinguishes a rollback.</td></tr>
           <tr><td class="name">cell:clicked</td><td class="desc">A cell was clicked. Announcement only: nothing is consumed, so editing and selection behave unchanged.</td></tr>
           <tr><td class="name">cell:confirmed</td><td class="desc">The write reached the server.</td></tr>
+          <tr><td class="name">cell:conflict</td><td class="desc">The write was accepted but the server row had moved underneath it. Last-write-wins with the divergence surfaced: your value stands and serverRow carries the server's truth.</td></tr>
           <tr><td class="name">cell:contextmenu</td><td class="desc">Right-click on a cell.</td></tr>
           <tr><td class="name">cell:dblclicked</td><td class="desc">A cell was double-clicked. Carries the row, column, value and text.</td></tr>
           <tr><td class="name">cell:edit:end</td><td class="desc">It closed: committed or cancelled.</td></tr>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.21.0, type declarations
+ * Lattice Grid 1.23.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -639,6 +639,17 @@ export interface Column {
      * `'filtered'` ranks within what the filters left.
      */
     scope?: 'all' | 'filtered';
+    /**
+     * For `kind: 'specStatus'`, the hard specification the row is judged
+     * against. `lower`/`upper` are the pass limits (a value beyond either
+     * fails); the optional `warnLower`/`warnUpper` are inner thresholds that
+     * mark a still-in-spec reading `'WARN'`. Centred-target ± tolerance is a
+     * deliberate follow-up and is not read here.
+     */
+    lower?: number;
+    upper?: number;
+    warnLower?: number;
+    warnUpper?: number;
   };
   /**
    * A running total down the grid **as it is currently ordered**.
@@ -1130,6 +1141,68 @@ export interface OpenWrite {
   age: number;
 }
 
+/**
+ * What an adapter can persist back to its source — the write-back capability
+ * (§4.1), declared on `AdapterCapabilities.mutate`. `false` (the default) is
+ * read-only by declaration; a resolved block turns every kind off unless the
+ * adapter opts in.
+ */
+export interface MutateCapability {
+  /** The adapter can insert new rows. Wave 1: declared, not yet bridged. */
+  append?: boolean;
+  /** The adapter can patch existing rows. Wave 1: the wired kind (§4.3 Option A). */
+  update?: boolean;
+  /** The adapter can remove rows. Wave 1: declared, not yet bridged. */
+  delete?: boolean;
+  /**
+   * The reconcile contract — what the server hands back after a successful
+   * mutation (§5.1). `'row'`: the authoritative row (id, computed columns,
+   * timestamps), reconciled before confirm. `'key'`: only the assigned key.
+   * `'none'` (the default): nothing — the optimistic value stands
+   * (last-write-wins).
+   */
+  returning?: 'row' | 'key' | 'none';
+}
+
+/**
+ * One mutation handed to `adapter.mutate(op, request)` (§4.2). Cell-scoped
+ * `update` is the only kind wave 1 synthesises; `append`/`delete` are part of
+ * the shape so it survives into a later structural build (card 770).
+ */
+export interface MutationOp {
+  kind: 'append' | 'update' | 'delete';
+  /** append: the new rows (may lack a server-assigned key). */
+  rows?: unknown[];
+  /** update: the row key. */
+  key?: string;
+  /** update: the changed columns only, matching `PendingWrite` semantics. */
+  patch?: Record<string, unknown>;
+  /** delete: the row key(s). */
+  keys?: string[];
+  /** Provenance, carried through for auth / audit. */
+  origin?: string;
+  /** Stable id for idempotent retry / dedupe. Reserved; retry is a non-goal in wave 1. */
+  requestId?: string;
+}
+
+/**
+ * The result of a mutation (§4.2) — the reconcile payload. A cell-update commit
+ * flows this back through `PendingWrites`: `ok: false` reverts and surfaces
+ * `reason`; `rows` (`returning: 'row'`) reconciles server truth before confirm;
+ * `conflict` surfaces a last-write-wins divergence via `cell:conflict`.
+ */
+export interface MutationResult {
+  ok: boolean;
+  /** `returning: 'row'` — the authoritative row(s) to reconcile to. */
+  rows?: unknown[];
+  /** `returning: 'key'` — server-assigned key(s) for appended rows, in order. */
+  keys?: string[];
+  /** On rejection — surfaced on `cell:reverted`, never swallowed. */
+  reason?: string;
+  /** The server's current value, for a surfaced last-write-wins conflict. */
+  conflict?: { key: string; serverRow?: unknown };
+}
+
 export interface PaginationConfig {
   enabled?: boolean;
   pageSize?: number;
@@ -2056,6 +2129,12 @@ export interface PushdownCapabilities {
   total?: boolean;
   /** Whether it can group and aggregate. */
   group?: boolean;
+  /**
+   * What the adapter can persist back — the write-back contract (§4.1). `false`
+   * (the default) is read-only by declaration. A declared block opts kinds in;
+   * `capabilitiesOf` resolves it to a full `MutateCapability` (or `false`).
+   */
+  mutate?: false | MutateCapability;
 }
 
 /** An engine the grid can query, and what it is able to answer. */
@@ -2066,6 +2145,13 @@ export interface PushdownAdapter {
   /** Run the part of the query the adapter declared it could handle. */
   execute(query: RemoteRequest, request?: RemoteRequest):
     Promise<{ rows: unknown[]; total?: number }>;
+  /**
+   * Persist one mutation (§4.2). Present only when `capabilities.mutate` opts
+   * in. `createPushdownSource` synthesises an `edit.commit` that calls this for
+   * cell updates (§4.3 Option A); `request` threads the abort signal through the
+   * way `execute` receives it, and auth already lives on the adapter.
+   */
+  mutate?(op: MutationOp, request?: RemoteRequest): Promise<MutationResult>;
 }
 
 /** How one request was divided between the engine and the grid. */
@@ -2210,8 +2296,13 @@ export interface PushdownSourceConfig {
 }
 
 export interface StatisticsApi {
-  /** One shadow value for one row, by the column it shadows and the kind. */
-  shadow(colId: string, kind: ShadowKind, rowKey: string, scope?: 'all' | 'filtered'): unknown;
+  /**
+   * One shadow value for one row, by the column it shadows and the kind. For
+   * `kind: 'specStatus'`, `spec` carries the `{lower, upper, warnLower,
+   * warnUpper}` limits to judge the row's value against; other kinds ignore it.
+   */
+  shadow(colId: string, kind: ShadowKind, rowKey: string,
+    scope?: 'all' | 'filtered', spec?: object): unknown;
   /** A running total at one row, down the grid as it is currently ordered. */
   running(colId: string, kind: 'total' | 'percent', rowKey: string): number | null;
   /** Make the current values the new baseline: "mark all". */
@@ -2229,6 +2320,18 @@ export interface StatisticsApi {
    * on one bounded scale so they rank against each other.
    */
   subsetVsPopulation(opts?: { columns?: string[] }): SubsetComparison;
+  /**
+   * Which columns differ most between this grid and another, ranked by effect
+   * size — never by a p-value (BACKLOG-0000735). The generalisation of
+   * {@link subsetVsPopulation} from subset-vs-population to dataset-vs-dataset:
+   * two independent grids, yoked by passing one in, no shared store. A numeric
+   * column reports a pooled standardised mean difference (Cohen's d, symmetric
+   * in the two peers where Glass's delta is not); a categorical column the total
+   * variation of its category mix; both land on one bounded scale. Both sides
+   * are read over their filtered rows. Only shared columns are ranked; a column
+   * on one side alone is returned under `unmatched`.
+   */
+  datasetVsDataset(other: Grid, opts?: { columns?: string[] }): DatasetComparison;
   /** Pearson's correlation between two columns. */
   correlation(a: string, b: string): number | null;
   /** Covariance, a correlation before the scales are divided out. */
@@ -2336,7 +2439,18 @@ export type ShadowKind =
   | 'rate' | 'history' | 'firstValue' | 'streak'
   /** Where the row sits among the others, over every tracked row. */
   | 'rank' | 'rankAsc' | 'rankChange' | 'percentile' | 'quartile'
-  | 'zScore' | 'shareOfTotal';
+  | 'zScore' | 'shareOfTotal'
+  /**
+   * The row's pass/fail verdict against a hard-limit spec, as a value:
+   * `'PASS'`, `'WARN'` or `'FAIL'`. Sortable, filterable, groupable and
+   * exportable, and rolled up by the `passRate`/`failureCount` totals. Reads
+   * `{lower, upper}` (and optional inner `{warnLower, warnUpper}`) off the
+   * shadow declaration; centred-target ± tolerance is a deliberate follow-up.
+   */
+  | 'specStatus';
+
+/** The three verdicts a `specStatus` shadow can report. */
+export type SpecStatus = 'PASS' | 'WARN' | 'FAIL';
 
 export interface RegressionFit {
   slope: number;
@@ -2474,6 +2588,47 @@ export interface SubsetComparison {
   measures: { numeric: string; categorical: string; common: string };
 }
 
+export interface DatasetColumnDifference {
+  /** The column id, present on both grids. */
+  column: string;
+  /** The column's display name, or its id. */
+  name: string;
+  /**
+   * The effect size reported for this column's family: the pooled standardised
+   * mean difference (Cohen's d) for a numeric column, the total variation of the
+   * category mix for a categorical one. Never a p-value.
+   */
+  measure: 'pooledStandardMeanDifference' | 'categoricalTotalVariation';
+  /** The effect size in its own terms, or null when it has no scale here. */
+  magnitude: number | null;
+  /**
+   * The total variation distance between the two datasets, 0 to 1 — the common
+   * scale both families reduce to, and what the ranking sorts by.
+   */
+  distance: number;
+  /** +1 when dataset A sits above dataset B, −1 below, 0 for a mix. */
+  direction: number;
+  /** How many rows the first grid's side stood on. */
+  nA: number;
+  /** How many rows the second grid's side stood on. */
+  nB: number;
+  /** False when either side is too small to read the difference from. */
+  reliable: boolean;
+}
+
+export interface DatasetComparison {
+  /** Every shared column, largest difference first. */
+  ranked: DatasetColumnDifference[];
+  /** How many rows the first grid contributed (its filtered set). */
+  nA: number;
+  /** How many rows the second grid contributed (its filtered set). */
+  nB: number;
+  /** Columns present on only one side, which cannot be compared. */
+  unmatched: { onlyA: string[]; onlyB: string[] };
+  /** The measure each family reports, and the common scale, named for a legend. */
+  measures: { numeric: string; categorical: string; common: string };
+}
+
 export interface FormattingApi {
   list(scope?: FormattingScope): FormattingRule[];
   all(): Record<FormattingScope, FormattingRule[]>;
@@ -2535,7 +2690,7 @@ export type EventName =
   | 'rows:paused' | 'rows:resumed' | 'row:received' | 'row:sent' | 'row:copied'
   | 'row:moved' | 'source:error' | 'stream:chunk' | 'stream:end' | 'stream:evicted'
   /* Cells and editing */
-  | 'cell:changed' | 'cell:pending' | 'cell:confirmed' | 'cell:reverted'
+  | 'cell:changed' | 'cell:pending' | 'cell:confirmed' | 'cell:reverted' | 'cell:conflict'
   | 'cell:clicked' | 'cell:dblclicked' | 'cell:contextmenu'
   | 'cell:edit:start' | 'cell:edit:end' | 'row:edit:start' | 'row:edit:end'
   | 'row:clicked' | 'row:dblclicked'
@@ -2880,7 +3035,20 @@ export interface EditApi {
     changes: { key: string; colId: string; oldValue: unknown; newValue: unknown; changed: boolean }[];
     rejected: { key: string; colId: string; value: unknown; reason: 'permission' | 'readOnly' | 'validation' | 'locked' | 'missing' }[];
   };
-  settle(id: string, ok: boolean, reason?: string): boolean;
+  /**
+   * Report the outcome of an in-flight write (§18.3; §5.1-5.2 reconcile).
+   *
+   * `reconcile` carries server truth on a successful settle: `value` is a
+   * server-authoritative value written back before `cell:confirmed`
+   * (`returning: 'row'`); `conflict.serverRow` surfaces a last-write-wins
+   * conflict via `cell:conflict`. Omit both to keep the optimistic value.
+   */
+  settle(
+    id: string,
+    ok: boolean,
+    reason?: string,
+    reconcile?: { value?: unknown; conflict?: { serverRow?: unknown } },
+  ): boolean;
   pending(): OpenWrite[];
   status(key: string, colId: string): 'pending' | null;
 }
@@ -3944,10 +4112,18 @@ export const NO_CAPABILITIES: Readonly<Required<PushdownCapabilities>>;
  * per condition per query, and membership on an array is a scan. The declared
  * form and the resolved form differ, which is why this is its own type.
  */
-export type ResolvedCapabilities = Omit<Required<PushdownCapabilities>, 'operators'> & {
+export type ResolvedCapabilities = Omit<Required<PushdownCapabilities>, 'operators' | 'mutate'> & {
   operators: ReadonlySet<string>;
+  /** Resolved by `resolveMutate`: `false`, or every kind and `returning` present. */
+  mutate: false | Required<MutateCapability>;
 };
 
+/**
+ * Resolve an adapter's declared `mutate` block against the defaults (§4.1).
+ * `false` (or anything falsy) stays `false` — read-only by declaration.
+ */
+export function resolveMutate(declared?: boolean | MutateCapability): false | Required<MutateCapability>;
+
 export function capabilitiesOf(declared?: PushdownCapabilities): ResolvedCapabilities;
 
 /**