@elytracms/studio 0.0.98 → 0.0.100

package/dist/lib/operations/cms-persistence.js

@@ -1,5 +1,7 @@
-import { applyDocumentPatches, documentKey, formatValuePath, isValuePathPrefix, readValueAt, selfTypeDocument, semanticValueEqual, touchedPaths, touchedPathsOfEntry, valuePathsOverlap, } from '@elytracms/core/cms-core';
+import { applyDocumentPatches, documentKey, expandValuePath, fieldPositionPatches, formatValuePath, isValuePathPrefix, readValueAt, selfTypeDocument, semanticValueEqual, touchedPaths, touchedPathsOfEntry, valuePathsOverlap, } from '@elytracms/core/cms-core';
 import { createPersistQueue } from './persist-queue.js';
+/** EC-686 — a decomposed alias is re-sent at most this often (each time a colleague wrote the document in between). */
+const ALIAS_ATTEMPTS = 3;
 /** How many own writes a document's ledger keeps (an older base just stops lifting — a conflict, never a borrow). */
 const OWN_WRITES_KEPT = 256;
 /**
@@ -8,7 +10,8 @@ const OWN_WRITES_KEPT = 256;
  * the floor and of every shown write whose positions OVERLAP `path` structurally — a write
  * at an ancestor of `path`, at `path`, or at a DESCENDANT of it (the value at `path`
  * contains that write's content). A write at a sibling position does not lower it.
- * `undefined` path — a whole-document writer — the earliest of all.
+ * `undefined` path — a whole-document writer — the earliest of all. `path` and the writes'
+ * positions are in the view's structural form (EC-693: node ancestry included).
  *
  * Minted when the view is shown, never when the edit commits (Codex F18, F23): a
  * descendant write may be refused and its conflict resolved before an edit of `path`
@@ -28,9 +31,10 @@ function provenanceAt(provenance, path) {
  * EC-681 — whether a write at `a` may overlap one at `b` as the STORE judges it: THE
  * conflict relation (`valuePathsOverlap`) unless BOTH name a component node — then any two
  * in overlapping field positions. The store compares node paths EXPANDED by their ancestry
- * (`value-path.ts`); the persister holds the submitted form, so it never claims two node
- * paths of one field apart. Conservative by construction: a "may" that is wrong costs a
- * lift (a conflict at worst), never a borrow.
+ * (`value-path.ts`) against ITS document, which may hold a colleague's move this session
+ * has not adopted, so the persister never claims two node paths of one field apart — not
+ * even in their expanded form (EC-693 kept this conservative on purpose). Conservative by
+ * construction: a "may" that is wrong costs a lift (a conflict at worst), never a borrow.
  */
 function mayOverlap(a, b) {
     const fieldOf = (path) => {
@@ -41,6 +45,40 @@ function mayOverlap(a, b) {
     const fieldB = fieldOf(b);
     return fieldA && fieldB ? valuePathsOverlap(fieldA, fieldB) : valuePathsOverlap(a, b);
 }
+/**
+ * EC-693 — THE containment fact the persister reads (Codex F28): the positions each patch
+ * touches as THE merge reports them — `applyDocumentPatches(...).applied`, the patches
+ * applied in order over `document`, each expanded against the document it applied to
+ * (node ancestry included). `undefined` for a patch the merge does not apply there (its
+ * node is not in that document): it has no position in it. Never a second expansion.
+ *
+ * The merge puts every input patch in exactly one of `applied` (in input order) and
+ * `refused` (the input object itself); a fresh object per input keeps a patch object that
+ * occurs twice apart.
+ */
+function mergedPositions(document, patches) {
+    if (patches.length === 0)
+        return { document, positions: [] };
+    const inputs = patches.map((patch) => ({ ...patch }));
+    const merged = applyDocumentPatches({ document, patches: inputs, since: [] });
+    const refused = new Set(merged.refused.map((refusal) => refusal.patch));
+    let next = 0;
+    return {
+        document: merged.document,
+        positions: inputs.map((input) => (refused.has(input) ? undefined : touchedPaths(merged.applied[next++]))),
+    };
+}
+/**
+ * EC-693 — the positions an applied run touched at the store: {@link mergedPositions} over
+ * the row the run was sent from, in order. The store applied exactly these patches, in this
+ * order, and would have refused one whose node (or an ancestor) a change since its base had
+ * moved — so the ancestry each landed under is the row's. The submitted form where the merge
+ * has none.
+ */
+function footprint(row, patches) {
+    const merged = row ? mergedPositions(row, patches).positions : [];
+    return patches.flatMap((patch, index) => merged[index] ?? touchedPaths(patch));
+}
 /** A patch's identity within one call: op + target path (no two value writes of one path share a run). */
 function targetKey(op, path) {
     return `${op} ${formatValuePath(path)}`;
@@ -51,9 +89,32 @@ function patchTarget(patch) {
 function conflictId(ref, path) {
     return `${documentKey(ref)}|${formatValuePath(path)}`;
 }
-/** Paths two patches have in common (either touches a prefix of the other's). */
-function patchesOverlap(a, b) {
-    return touchedPaths(a).some((p) => touchedPaths(b).some((q) => valuePathsOverlap(p, q)));
+function pathsOverlap(a, b) {
+    return a.some((p) => b.some((q) => valuePathsOverlap(p, q)));
+}
+/**
+ * Whether two own writes may touch a common position (either touches a prefix of the
+ * other's): as submitted, or — EC-693 — where both touch the view (node ancestry
+ * included: a write of a parent node and one of its child's prop). Either is enough; a
+ * "may" lowers a base (a conflict at worst), never borrows one.
+ */
+function patchesOverlap(a, b, positions) {
+    if (pathsOverlap(touchedPaths(a), touchedPaths(b)))
+        return true;
+    const atA = positions?.get(a);
+    const atB = positions?.get(b);
+    return atA !== undefined && atB !== undefined && pathsOverlap(atA, atB);
+}
+/**
+ * EC-693 — two value writes of ONE position (the open conflict a later edit replaces): the
+ * same submitted path, or the same position in the view.
+ */
+function samePosition(a, b, positions) {
+    if (samePath(a.path, b.path))
+        return true;
+    const atA = positions.get(a)?.[0];
+    const atB = positions.get(b)?.[0];
+    return atA !== undefined && atB !== undefined && samePath(atA, atB);
 }
 /** A `set`/`unset` on exactly one path — the shape a later edit of the same field supersedes. */
 function isValueWrite(patch) {
@@ -81,29 +142,56 @@ function earlierBase(a, b) {
  */
 export function importWrite(persister, document, shown) {
     if (shown && persister.revisionOf(document) !== undefined) {
-        persister.replace(document, persister.revisionOfView(shown));
+        // EC-686: with the row it was judged against — what a refusal decomposes it against.
+        persister.replace(document, persister.revisionOfView(shown), shown);
     }
     else
         persister.create(document);
 }
 /**
- * EC-674 — THE classification of a write that failed without a per-field conflict (one
- * declaration, read by the whole-document and the patch path): `true` = KEPT — put back,
- * still shown, re-sent by the next commit or forced flush — for every failure the store did
- * not JUDGE: `backend-unavailable` and `unknown`, whatever the message. `false` = DROPPED
- * for the store's verdicts, `validation`, `unauthorized` and `not-found`: the same write is
- * refused the same way again, so it is reported and the writes behind it drain.
+ * EC-674 → EC-686 — THE classification of a write that failed without a per-field conflict
+ * (one declaration, read by the whole-document and the patch path): `true` = KEPT — put
+ * back, still shown, re-sent by the next commit or forced flush — for the one failure the
+ * store did not JUDGE, `backend-unavailable`, whatever the message. `false` = DROPPED for
+ * the store's verdicts, `validation`, `unauthorized` and `not-found`, and for `unknown`: the
+ * same write fails the same way again, so it is reported and the writes behind it drain.
  *
- * Why every `unknown` (measured, EC-674): no adapter emits `backend-unavailable`, and a
- * network failure, a gateway's 5xx, an expired session and a crash all arrive as `unknown`
- * with whatever text the transport carried — no message set can name every transient (an
- * OCC exhaustion, a timeout, a new runtime's wording). Dropping one loses the edit; keeping
- * a deterministic `unknown` (an undeclared field type's `canonicalise` crash) loses nothing:
- * its error stays visible, each commit or flush re-sends it once, and the document's later
- * writes wait behind it. Loss ranks above a wedge (the v1 bar).
+ * Why `unknown` is now a verdict (EC-686, classify by WHO failed — the binding rule): the
+ * Convex adapter makes every failure out of a backend call that is not a mapped engine
+ * error `backend-unavailable` (a network failure, a gateway's 5xx, an expired session, an
+ * OCC exhaustion or a timeout, keeping the backend's message), so an `unknown` is a failure
+ * of the engine in THIS process — an undeclared field type's `canonicalise` crash — which
+ * the same input repeats. Kept, it waited in front of every later write of the document
+ * (EC-674's accepted cost); dropped, it is visible and nothing behind it waits.
  */
 function keepsFailedWrite(error) {
-    return error.code === 'backend-unavailable' || error.code === 'unknown';
+    return error.code === 'backend-unavailable';
+}
+/**
+ * EC-686 — a dropped verdict on a run as a whole that may be one patch's alone: `validation`
+ * (an input or value issue), `unauthorized` (an authorization hook may judge by the
+ * patches), an in-process `unknown` (one patch's crash). Not `not-found` — the document is
+ * gone for every patch — and never a kept failure.
+ */
+function isolates(error) {
+    return error.code === 'validation' || error.code === 'unauthorized' || error.code === 'unknown';
+}
+/**
+ * EC-686 — the patches a verdict on a whole run names (`validation` issues located at
+ * `['patches', i, …]`, i in the run): `undefined` when any issue is not located there (or
+ * the verdict carries none) — then no patch is known innocent.
+ */
+function locatedCulprits(error, size) {
+    if (error.code !== 'validation' || !error.issues?.length)
+        return undefined;
+    const culprits = new Set();
+    for (const issue of error.issues) {
+        const index = issue.path?.[0] === 'patches' ? issue.path[1] : undefined;
+        if (typeof index !== 'number' || !Number.isInteger(index) || index < 0 || index >= size)
+            return undefined;
+        culprits.add(index);
+    }
+    return culprits;
 }
 /** A write against a document this session no longer holds (deleted here or elsewhere). */
 function goneError(ref) {
@@ -118,6 +206,42 @@ function unauthoredError(ref) {
         messageRef: { key: 'cms.conflict.unauthored' },
     };
 }
+/**
+ * EC-686 — a slot change someone else's slot change came before: the alias has no position
+ * to hold an ordinary conflict on, so theirs is kept, and the author is told (the table
+ * cell's precedent, `cms.conflict.cellRefused`).
+ */
+function aliasRefusedError(ref) {
+    return {
+        code: 'conflict',
+        key: documentKey(ref),
+        message: 'The slot was changed by someone else since you chose it — theirs is kept. Choose it again to change it.',
+        messageRef: { key: 'cms.conflict.aliasRefused' },
+    };
+}
+/** `document` with its slot alias set (or removed) — a fresh object. */
+function withAlias(document, alias) {
+    const next = { ...document };
+    if (alias === undefined)
+        delete next.alias;
+    else
+        next.alias = alias;
+    return next;
+}
+/**
+ * EC-686 item 1 — what a whole-document snapshot changed against the view it was made from,
+ * position by position: a `set` (or an `unset`, the value gone) of every field position —
+ * `values[f]`, `localized[l][f]` — whose value differs by THE equality. Every value change of
+ * a document is one of these; its slot `alias` is the one key that is not.
+ *
+ * EC-703 (Codex round 6 F33): THE own-property per-position diff (`fieldPositionPatches`,
+ * cms-core — the one the publish strip reads too). This copy read `bucket.after[key]`, so a
+ * removed field named after an `Object.prototype` member became `set constructor = Object`
+ * and every later `documentOf` threw (measured).
+ */
+function positionPatches(view, snapshot) {
+    return fieldPositionPatches(view, snapshot);
+}
 export function createCmsPersister(options) {
     const queue = createPersistQueue((error) => {
         options.onError({
@@ -130,6 +254,28 @@ export function createCmsPersister(options) {
     const shown = new WeakMap();
     /** A server row's document: every position at its revision. */
     const registerRow = (row) => shown.set(row.document, { floor: row.revision, writes: [] });
+    /** EC-693: {@link serverPositions}, per server row and patch (a row and a queued patch never change). */
+    const atRow = new WeakMap();
+    /**
+     * EC-693 — where a patch lands in the server row the session holds (`entry.base`, at or
+     * after every write the own-write ledger records): its positions as THE merge reports
+     * them on that row alone ({@link mergedPositions}), the submitted form where the merge does
+     * not apply it there. What {@link lift} and the actor lookup read — never the view's
+     * evolving frame: an own write still queued ahead of the patch (a move of its node) has
+     * not happened at the store.
+     */
+    function serverPositions(entry, patch) {
+        const row = entry.base?.document;
+        if (!row)
+            return touchedPaths(patch);
+        let byPatch = atRow.get(row);
+        if (!byPatch)
+            atRow.set(row, (byPatch = new WeakMap()));
+        let positions = byPatch.get(patch);
+        if (!positions)
+            byPatch.set(patch, (positions = mergedPositions(row, [patch]).positions[0] ?? touchedPaths(patch)));
+        return positions;
+    }
     function entryOf(ref) {
         const key = documentKey(ref);
         let entry = entries.get(key);
@@ -168,45 +314,73 @@ export function createCmsPersister(options) {
     }
     /**
      * The session's view: base ⊕ unresolved mine ⊕ in-flight ⊕ queued (the pure merge, no
-     * log; a whole-document write resets it to its snapshot). Registered with what it was
-     * authored against, position by position (EC-647 → EC-667: the base's revision, a
-     * pending snapshot's, each shown write's base); a provisional view has none.
+     * log; a whole-document write resets it to its snapshot) — and, EC-693, `extra` (a
+     * commit's patches) over it. With what each shown position was authored against (EC-647
+     * → EC-667: the base's revision, a pending snapshot's, each shown write's base) and where
+     * each shown write — and each of `extra` — touches the view ({@link mergedPositions}):
+     * computed on every call, never frozen when a write is queued, so a colleague's move
+     * adopted underneath moves the pending write's position with its node.
      */
-    function display(entry) {
+    function compose(entry, extra = []) {
         const baseDocument = entry.base?.document ?? entry.provisional;
         if (entry.deleted || !baseDocument)
             return undefined;
         let document = baseDocument;
         let floor = entry.base?.revision;
-        let patches = entry.conflicts.map((conflict) => conflict.patch);
-        let writes = entry.conflicts.map((conflict) => ({
-            paths: touchedPaths(conflict.patch),
-            base: entry.conflictBases.get(conflict.id),
-        }));
+        let shownWrites = entry.conflicts.map((conflict) => ({ patch: conflict.patch, base: entry.conflictBases.get(conflict.id) }));
         const pending = [
             ...entry.inFlight,
             ...(entry.inFlightReplace ? [entry.inFlightReplace] : []),
             ...entry.queue,
         ];
+        // EC-686: a pending decomposed alias shows over everything before it (the newest wins).
+        let alias;
         for (const queued of pending) {
             if (queued.kind === 'replace') {
                 // The snapshot was authored over everything before it (the editor's draft): every
                 // position now shows content authored at the SNAPSHOT's revision (EC-667).
-                patches = [];
-                writes = [];
+                shownWrites = [];
                 document = queued.document;
                 floor = queued.base;
+                alias = undefined;
+            }
+            else if (queued.kind === 'alias') {
+                alias = { value: queued.alias };
             }
             else {
-                patches.push(queued.patch);
-                writes.push({ paths: touchedPaths(queued.patch), base: queued.base });
+                shownWrites.push({ patch: queued.patch, base: queued.base });
             }
         }
-        if (patches.length > 0)
-            document = applyDocumentPatches({ document, patches, since: [] }).document;
-        if (entry.base)
-            shown.set(document, { floor, writes });
-        return document;
+        const merged = mergedPositions(document, [...shownWrites.map((write) => write.patch), ...extra]);
+        // A write the merge did not apply in this view shows nothing: its submitted form keeps
+        // the tokens it may concern conservative.
+        const writes = shownWrites.map((write, index) => ({
+            patch: write.patch,
+            paths: merged.positions[index] ?? touchedPaths(write.patch),
+            base: write.base,
+        }));
+        const positions = new Map();
+        for (const write of writes)
+            positions.set(write.patch, write.paths);
+        extra.forEach((patch, index) => {
+            const at = merged.positions[shownWrites.length + index];
+            if (at)
+                positions.set(patch, at);
+        });
+        return { document: alias ? withAlias(merged.document, alias.value) : merged.document, floor, writes, positions: positions };
+    }
+    /**
+     * The session's view ({@link compose}), registered with what it was authored against,
+     * position by position; a provisional view has none.
+     */
+    function display(entry) {
+        const view = compose(entry);
+        if (!view)
+            return undefined;
+        if (entry.base) {
+            shown.set(view.document, { floor: view.floor, writes: view.writes.map(({ paths, base }) => ({ paths, base })) });
+        }
+        return view.document;
     }
     function emitDocument(entry) {
         if (entry.deleted)
@@ -293,18 +467,23 @@ export function createCmsPersister(options) {
      * never a change by anyone else of a position the write touches. Three rules, applied
      * until none moves it:
      * 1. the next revision is one of this persister's own writes (a run of own writes);
-     * 2. an own write that covered every position `paths` touch (each at or under one of its
+     * 2. an own write that covered every position `patch` touches (each at or under one of its
      *    paths) and was sent at or below the lifted base: its revision — the store refused
-     *    every foreign change of those positions in between, or it would not have applied;
+     *    every foreign change of those positions in between, or it would not have applied.
+     *    EC-693: both read where they land at the store — the own write's {@link footprint},
+     *    the patch's {@link serverPositions} — node ancestry included: a submitted path names
+     *    a node's ancestry as the writer believed it, the store reads it from the document;
      * 3. (EC-681, `log` given) the next revision is someone else's and touched none of
-     *    `paths` ({@link mayOverlap}, the store's own row reading `touchedPathsOfEntry`): the
-     *    store would not refuse the write on it, so crossing it moves nothing — it only lets
-     *    rule 1 reach an own write beyond it. That is the case rule 2 cannot prove: an
-     *    ancestor's write over an own DESCENDANT write (whose acceptance says nothing of the
-     *    ancestor's other descendants), past an unrelated colleague write in between.
-     * A whole-document write (`paths` undefined) takes rule 1 only.
+     *    the patch's positions ({@link mayOverlap}, the store's own row reading
+     *    `touchedPathsOfEntry`): the store would not refuse the write on it, so crossing it
+     *    moves nothing — it only lets rule 1 reach an own write beyond it. That is the case
+     *    rule 2 cannot prove: an ancestor's write over an own DESCENDANT write (whose
+     *    acceptance says nothing of the ancestor's other descendants), past an unrelated
+     *    colleague write in between.
+     * A whole-document write (`patch` undefined) takes rule 1 only.
      */
-    function lift(entry, base, paths, log) {
+    function lift(entry, base, patch, log) {
+        const paths = patch ? () => serverPositions(entry, patch) : undefined;
         let lifted = base;
         for (;;) {
             if (entry.own.some((write) => write.revision === lifted + 1)) {
@@ -316,14 +495,14 @@ export function createCmsPersister(options) {
                     write.paths !== undefined &&
                     write.sentBase !== undefined &&
                     write.sentBase <= lifted &&
-                    paths.every((path) => write.paths.some((covered) => isValuePathPrefix(covered, path))))
+                    paths().every((path) => write.paths.some((covered) => isValuePathPrefix(covered, path))))
                 : undefined;
             if (covering) {
                 lifted = covering.revision;
                 continue;
             }
             const foreign = paths ? log?.get(lifted + 1) : undefined;
-            if (foreign && !touchedPathsOfEntry(foreign).some((logged) => paths.some((path) => mayOverlap(logged, path)))) {
+            if (foreign && !touchedPathsOfEntry(foreign).some((logged) => paths().some((path) => mayOverlap(logged, path)))) {
                 lifted += 1;
                 continue;
             }
@@ -337,10 +516,10 @@ export function createCmsPersister(options) {
      * when not needed or not readable — then no lift, a conflict at worst, never a borrow.
      */
     async function liftLog(entry, operations, queued) {
-        const paths = touchedPaths(queued.patch);
-        const lifted = lift(entry, queued.base, paths);
+        const lifted = lift(entry, queued.base, queued.patch);
         const blocking = entry.own.some((write) => write.revision > lifted &&
-            (write.paths === undefined || write.paths.some((own) => paths.some((path) => mayOverlap(own, path)))));
+            (write.paths === undefined ||
+                write.paths.some((own) => serverPositions(entry, queued.patch).some((path) => mayOverlap(own, path)))));
         if (!blocking)
             return undefined;
         const read = await operations.documents.listPatches({
@@ -353,12 +532,16 @@ export function createCmsPersister(options) {
     /**
      * EC-647 — the base a write is QUEUED with: the revision it was authored against, or
      * the earlier base of an own unacknowledged write on the same positions (the view
-     * showed mine there, not whatever may sit underneath it).
+     * showed mine there, not whatever may sit underneath it) — EC-693: as submitted, or in
+     * the view (`positions`).
      */
-    function authoredBase(entry, patch, authored) {
+    function authoredBase(entry, patch, authored, positions) {
         let base = authored;
-        const overlaps = (other) => patch === undefined || patchesOverlap(other, patch);
+        const overlaps = (other) => patch === undefined || patchesOverlap(other, patch, positions);
         for (const queued of [...entry.inFlight, ...entry.queue]) {
+            // A decomposed alias names no value position (and is sent at the row it then finds).
+            if (queued.kind === 'alias')
+                continue;
             if (queued.kind === 'replace' || overlaps(queued.patch))
                 base = earlierBase(base, queued.base);
         }
@@ -379,7 +562,7 @@ export function createCmsPersister(options) {
         if (entry.created === undefined)
             return;
         for (const queued of entry.queue)
-            if (queued.base === undefined)
+            if (queued.kind !== 'alias' && queued.base === undefined)
                 queued.base = entry.created;
     }
     /**
@@ -405,6 +588,9 @@ export function createCmsPersister(options) {
         }
         const read = await operations.documents.get({ projectId: options.projectId, ref: entry.ref });
         if (!read.ok) {
+            // The writes stay queued for the next flush; their commits learn why now (EC-686).
+            if (!entry.scheduled)
+                settleWaiting(entry, { status: 'failed', error: read.error });
             options.onError(read.error);
             return false;
         }
@@ -439,7 +625,12 @@ export function createCmsPersister(options) {
         adopt(entry, record);
         return true;
     }
-    /** Who changed a refused path — the newest patch-log row in (base, current] touching it. Best-effort. */
+    /**
+     * Who changed a refused path — the newest patch-log row in (base, current] touching it.
+     * Best-effort. The log stores its paths expanded (node ancestry included), so the refused
+     * patch is read where it lands in the server row ({@link serverPositions}, EC-693) — a
+     * child prop's conflict names its parent there, as the colleague's logged write does.
+     */
     async function resolveActors(entry, sentBase, refused) {
         try {
             const operations = await options.getOperations();
@@ -454,10 +645,10 @@ export function createCmsPersister(options) {
             entry.conflicts = entry.conflicts.map((conflict) => {
                 if (conflict.actor !== undefined || !refused.some((r) => r.id === conflict.id))
                     return conflict;
+                const at = serverPositions(entry, conflict.patch);
                 const row = [...log.value]
                     .reverse()
-                    .find((candidate) => candidate.kind === 'replace' ||
-                    candidate.patches.some((patch) => touchedPaths(patch).some((path) => valuePathsOverlap(path, conflict.path))));
+                    .find((candidate) => candidate.kind === 'replace' || candidate.patches.some((patch) => pathsOverlap(touchedPaths(patch), at)));
                 if (!row?.actor)
                     return conflict;
                 changed = true;
@@ -476,18 +667,124 @@ export function createCmsPersister(options) {
      * re-sent by the next commit or forced flush at its own authoring base (a retry never
      * borrows a newer revision) — or DROPPED on the store's verdict, and the view re-derived
      * without it. Reported either way. `true` when kept: the drain stops there, so nothing
-     * committed after it is sent ahead of it. The one path for both the whole-document write
-     * and the patch run.
+     * committed after it is sent ahead of it — and, EC-686, every commit still waiting on a
+     * write queued behind it settles now ({@link settleWaiting}). The one path for both the
+     * whole-document write and the patch run.
      */
     function failedWrite(entry, writes, error) {
         const kept = keepsFailedWrite(error);
-        if (kept)
+        if (kept) {
             entry.queue.unshift(...writes);
+            // A drain already scheduled (a commit made meanwhile) re-sends them at once: they
+            // settle with its outcome instead.
+            if (!entry.scheduled)
+                settleWaiting(entry, { status: 'failed', error });
+        }
         else
             emitDocument(entry);
         options.onError(error);
         return kept;
     }
+    /**
+     * EC-686 — the drain stopped with writes still queued (kept, shown, re-sent by the next
+     * commit or forced flush): the commits waiting on them settle with why, never left
+     * hanging until a later flush lands them (an awaiting caller — a table cell, bulk
+     * set-field — would wait with them). Each settles once; the write stays queued. Not
+     * when a drain is already scheduled: it re-sends them at once, and they settle with it.
+     */
+    function settleWaiting(entry, outcome) {
+        entry.queue = entry.queue.map((queued) => {
+            if (queued.kind !== 'patch' || queued.settle.length === 0)
+                return queued;
+            settleAll([queued], outcome);
+            return { ...queued, settle: [] };
+        });
+    }
+    /**
+     * EC-686 — a verdict on a run of several patches as a whole ({@link isolates}): its
+     * innocents are not dropped with its culprit. A `validation` that
+     * locates every culprit ({@link locatedCulprits}) drops those, and the rest go back to the
+     * head of the queue to be re-sent once as a run (`'resent'`); otherwise each patch is
+     * re-sent once alone (`'alone'`), so the refusal finds its culprit. The verdict is
+     * reported once; a culprit's commit settles `failed` now, an innocent's after its
+     * re-send. The re-sent patches keep their authoring bases (lift rule 1 crosses each
+     * own revision a re-send lands at), and are never isolated again.
+     */
+    function isolate(entry, run, error) {
+        const culprits = locatedCulprits(error, run.length);
+        const resend = culprits
+            ? run.filter((_, index) => !culprits.has(index)).map((queued) => ({ ...queued, isolated: 'resent' }))
+            : run.map((queued) => ({ ...queued, isolated: 'alone' }));
+        if (culprits)
+            settleAll(run.filter((_, index) => culprits.has(index)), { status: 'failed', error });
+        entry.queue.unshift(...resend);
+        emitDocument(entry);
+        options.onError(error);
+    }
+    /**
+     * EC-686 item 1 (the owner's ruling, 2026-10-28: per-position) — a whole-document write the
+     * store refused, in the writes that re-send it: what its author changed against the view
+     * the snapshot was made from ({@link positionPatches}), each authored where that view had
+     * it (its token at the position — EC-667 — else the snapshot's revision). Sent next, each
+     * lands on the current row, or — a position someone else changed since — becomes that
+     * field's ordinary conflict, the authored value still shown. Never the snapshot again: a
+     * whole-document keep-mine would re-send it over every colleague change since.
+     *
+     * The slot alias, the key the grammar has no position for, follows them alone
+     * ({@link QueuedAlias}) when the row still carries the alias the author saw; when someone
+     * else changed it too, there is no position for a conflict — theirs is kept and the author
+     * is told (`aliasRefused`). `undefined` when nothing can be judged per position: no view,
+     * or no revision (an insert-if-absent).
+     */
+    function decompose(entry, write, current) {
+        const base = write.base ?? entry.created;
+        const view = write.authoredOn;
+        if (base === undefined || !view)
+            return undefined;
+        const provenance = shown.get(view);
+        const writes = positionPatches(view, write.document).map((patch) => ({
+            kind: 'patch',
+            patch,
+            base: (provenance ? provenanceAt(provenance, touchedPaths(patch)[0]) : undefined) ?? base,
+            settle: [],
+        }));
+        let aliasRefused = false;
+        const alias = write.document.alias;
+        if (alias !== view.alias && alias !== current.alias) {
+            if (current.alias === view.alias)
+                writes.push({ kind: 'alias', alias, authored: view.alias, attempt: write.aliasAttempt ?? 0 });
+            else
+                aliasRefused = true;
+        }
+        return { writes, aliasRefused };
+    }
+    /**
+     * EC-686 — the queue's head is a decomposed alias: it becomes the whole-document write that
+     * carries it — the server row the session holds, unchanged, with the alias, at that row's
+     * revision (so it changes the alias and nothing else; a write since refuses it, and it is
+     * decomposed again, at most {@link ALIAS_ATTEMPTS} times) — or it is done: the row already
+     * carries it, or someone else changed the slot since the author's view (theirs kept, told).
+     */
+    function resolveAlias(entry, write) {
+        entry.queue.shift();
+        const row = entry.base;
+        if (!row || row.document.alias === write.alias) {
+            emitDocument(entry);
+            return;
+        }
+        if (row.document.alias !== write.authored || write.attempt >= ALIAS_ATTEMPTS) {
+            emitDocument(entry);
+            options.onError(aliasRefusedError(entry.ref));
+            return;
+        }
+        entry.queue.unshift({
+            kind: 'replace',
+            document: withAlias(row.document, write.alias),
+            base: row.revision,
+            authoredOn: row.document,
+            aliasAttempt: write.attempt + 1,
+        });
+    }
     /** Send one queued whole-document write at the revision its snapshot was authored against. `false` → stop draining. */
     async function sendReplace(entry, operations, write) {
         const precondition = write.base !== undefined
@@ -522,8 +819,15 @@ export function createCmsPersister(options) {
                 adopt(entry, result.value);
             }
             else if (result.error.code === 'conflict' && 'current' in result.error && result.error.current) {
+                // EC-686 item 1: refused as a whole — re-sent per position, in its place in the queue.
+                const parts = decompose(entry, write, result.error.current.document);
+                if (parts)
+                    entry.queue.unshift(...parts.writes);
                 adopt(entry, result.error.current);
-                options.onError(result.error);
+                if (!parts)
+                    options.onError(result.error);
+                else if (parts.aliasRefused)
+                    options.onError(aliasRefusedError(entry.ref));
             }
             else if (failedWrite(entry, [write], result.error)) {
                 return false;
@@ -554,21 +858,29 @@ export function createCmsPersister(options) {
                     return;
                 continue;
             }
+            if (head.kind === 'alias') {
+                resolveAlias(entry, head);
+                continue;
+            }
             const log = await liftLog(entry, operations, head);
             // The queue may have moved while the log was read (a superseding edit, a delete): start over.
             if (entry.queue[0] !== head)
                 continue;
-            const sendBase = (queued) => lift(entry, queued.base, touchedPaths(queued.patch), log);
+            const sendBase = (queued) => lift(entry, queued.base, queued.patch, log);
             const first = sendBase(head);
             let end = 1;
-            while (end < entry.queue.length) {
+            // EC-686: a patch re-sent after its run was refused travels only with the run's other
+            // innocents — or alone ({@link isolate}).
+            while (head.isolated !== 'alone' && end < entry.queue.length) {
                 const next = entry.queue[end];
-                if (next.kind !== 'patch' || sendBase(next) !== first)
+                if (next.kind !== 'patch' || next.isolated !== head.isolated || sendBase(next) !== first)
                     break;
                 end += 1;
             }
             const run = entry.queue.splice(0, end);
             entry.inFlight = run;
+            // EC-693: the row the run is sent from — where its applied patches land ({@link footprint}).
+            const sentFrom = entry.base?.document;
             const result = await operations.documents.patch({
                 projectId: options.projectId,
                 ref: entry.ref,
@@ -580,7 +892,7 @@ export function createCmsPersister(options) {
                 recordOwn(entry, {
                     revision: result.value.revision,
                     sentBase: first,
-                    paths: run.flatMap((queued) => touchedPaths(queued.patch)),
+                    paths: footprint(sentFrom, run.map((queued) => queued.patch)),
                 });
                 adopt(entry, result.value);
                 adoptHeld(entry);
@@ -613,7 +925,7 @@ export function createCmsPersister(options) {
                     recordOwn(entry, {
                         revision: current.revision,
                         sentBase: first,
-                        paths: applied.flatMap((queued) => touchedPaths(queued.patch)),
+                        paths: footprint(sentFrom, applied.map((queued) => queued.patch)),
                     });
                 }
                 adopt(entry, current);
@@ -630,10 +942,19 @@ export function createCmsPersister(options) {
                 settleAll(run, { status: 'failed', error });
                 return;
             }
+            // EC-686 — a verdict on a run of several patches, not yet isolated: re-sent once
+            // without its culprits. A `not-found` is the document's and names none; a kept
+            // failure is not a verdict.
+            if (run.length > 1 && head.isolated === undefined && isolates(error)) {
+                isolate(entry, run, error);
+                adoptHeld(entry);
+                continue;
+            }
             // EC-674 — any other failure: the commits waiting on the run learn of it now. One the
             // store did not judge keeps the patches (shown, unsent; the next commit or forced flush
-            // re-sends them); a verdict (validation, unauthorized, not-found) drops them, and the
-            // writes behind it drain — put back, it would be refused in front of every later write.
+            // re-sends them); a verdict (validation, unauthorized, not-found, an in-process
+            // `unknown`) drops them, and the writes behind it drain — put back, it would be refused
+            // in front of every later write.
             settleAll(run, { status: 'failed', error });
             const kept = failedWrite(entry, run.map((queued) => ({ ...queued, settle: [] })), error);
             adoptHeld(entry);
@@ -684,7 +1005,10 @@ export function createCmsPersister(options) {
         },
         revisionOfView: (view, path) => {
             const provenance = shown.get(view);
-            return provenance ? provenanceAt(provenance, path) : undefined;
+            if (!provenance)
+                return undefined;
+            // EC-693: the asked position in the view's structural form, as its shown writes are.
+            return provenanceAt(provenance, path && (expandValuePath(view, path) ?? path));
         },
         adoptRecord(record) {
             const entry = entryOf(record.document);
@@ -712,6 +1036,8 @@ export function createCmsPersister(options) {
             }
             if (!entry.base && !entry.provisional && view)
                 entry.provisional = view;
+            // EC-693: where the shown own writes and these patches touch the view they were authored on.
+            const positions = compose(entry, patches)?.positions ?? new Map();
             let conflictsChanged = false;
             let unauthored = false;
             const waits = [];
@@ -728,15 +1054,19 @@ export function createCmsPersister(options) {
                 }
                 // A field with an unresolved conflict: the new value replaces MINE, unsent —
                 // the user decides (keep mine sends it), never an implicit overwrite of theirs.
-                const open = entry.conflicts.find((conflict) => patchesOverlap(conflict.patch, patch));
-                if (open && isValueWrite(patch) && isValueWrite(open.patch) && samePath(open.patch.path, patch.path)) {
+                // EC-693: the conflict at THIS position, as submitted or in the view — never merely
+                // the first overlapping one (an open conflict at an ancestor would hide it).
+                const open = isValueWrite(patch)
+                    ? entry.conflicts.find((conflict) => isValueWrite(conflict.patch) && samePosition(conflict.patch, patch, positions))
+                    : undefined;
+                if (open) {
                     const replaced = { ...open, patch };
                     entry.conflicts = entry.conflicts.map((c) => (c === open ? replaced : c));
                     conflictsChanged = true;
                     settle({ status: 'refused', conflicts: [replaced] });
                     continue;
                 }
-                const base = authoredBase(entry, patch, authored);
+                const base = authoredBase(entry, patch, authored, positions);
                 // A later value write of the same field supersedes an unsent one (keeping the
                 // EARLIER base — the user never saw a foreign value of a field they were typing
                 // in). Only after the last queued whole-document write: one before it is sent
@@ -819,7 +1149,7 @@ export function createCmsPersister(options) {
                         options.onError(result.error);
                         // EC-647: the writes authored on the document we meant to create have no
                         // revision to be based on — never the revision of a row someone else wrote.
-                        dropQueued(entry, { status: 'failed', error: result.error }, (queued) => queued.base === undefined);
+                        dropQueued(entry, { status: 'failed', error: result.error }, (queued) => queued.kind !== 'alias' && queued.base === undefined);
                     }
                 }
                 finally {
@@ -831,7 +1161,7 @@ export function createCmsPersister(options) {
                     await drain(entry);
             });
         },
-        replace(document, revision) {
+        replace(document, revision, authoredOn) {
             const doc = canonical(document);
             const entry = entryOf(doc);
             if (entry.deleted) {
@@ -847,7 +1177,8 @@ export function createCmsPersister(options) {
             // holds them), the ones committed after it are sent after it (it does not). EC-647
             // (Codex F10): one with no authoring revision on a document this session tracks and
             // did not create is refused there, in order — never sent at the tracked revision.
-            entry.queue.push({ kind: 'replace', document: doc, base: authoredBase(entry, undefined, revision) });
+            // EC-686: with the document it was made from — what a refusal decomposes it against.
+            entry.queue.push({ kind: 'replace', document: doc, base: authoredBase(entry, undefined, revision), ...(authoredOn ? { authoredOn } : {}) });
             emitDocument(entry);
             schedule(entry);
         },