@elytracms/studio 0.0.97 → 0.0.98

package/dist/lib/operations/cms-persistence.d.ts

@@ -42,7 +42,9 @@ import type { OperationError, OperationsClient } from './operations-package.js';
  *   pending whole-document write its snapshot's authoring revision, and over that each
  *   own unacknowledged write shown (queued, in flight, an open conflict's "mine") with
  *   the base it was authored at. `revisionOfView(view, path)` is the revision the content
- *   at `path` was authored against (the earliest of the writes covering it);
+ *   at `path` was authored against: the earliest of the floor and of the shown writes that
+ *   OVERLAP `path` — at it, at an ancestor, or at a descendant, whose content the value at
+ *   `path` contains (EC-681, Codex F23); a sibling's write does not lower it.
  *   `revisionOfView(view)` — a whole-document writer — the EARLIEST of all. The record is
  *   immutable, so it outlives the pending write: an edit started on a view that showed a
  *   snapshot keeps the snapshot's revision after the snapshot is refused or fails
@@ -59,9 +61,12 @@ import type { OperationError, OperationsClient } from './operations-package.js';
  *   after it (nothing foreign happened in between), or to an own write's revision when
  *   the patch only touches positions that write covered and the write was sent at or
  *   below the patch's base (the store refused every foreign change of those positions in
- *   between, or the write would not have applied). Without it, the session's second
- *   edit of a position, made at the revision its first was authored against, would be
- *   refused by its own first write.
+ *   between, or the write would not have applied) — or, EC-681, across a revision someone
+ *   else wrote that the patch log shows touched none of the patch's positions (the store
+ *   would not refuse the patch on it), read only when an own write beyond it would
+ *   otherwise refuse the patch. Without it, the session's second edit of a position, made
+ *   at the revision its first was authored against, would be refused by its own first
+ *   write — and an edit of a parent, authored over an own child write, by that child's.
  * - **The provisional view** (`undefined` authoring revision): a document whose view
  *   has no revision yet — our own create in flight, or a document the session never
  *   tracked (a staged transfer). Writes on it are based on the revision our create

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

@@ -1,23 +1,46 @@
-import { applyDocumentPatches, documentKey, formatValuePath, isValuePathPrefix, readValueAt, selfTypeDocument, semanticValueEqual, touchedPaths, valuePathsOverlap, } from '@elytracms/core/cms-core';
+import { applyDocumentPatches, documentKey, formatValuePath, isValuePathPrefix, readValueAt, selfTypeDocument, semanticValueEqual, touchedPaths, touchedPathsOfEntry, valuePathsOverlap, } from '@elytracms/core/cms-core';
 import { createPersistQueue } from './persist-queue.js';
 /** 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;
 /**
- * EC-667 — the revision the content a view shows at `path` was authored against: the
- * earliest of the floor and every shown write covering `path` (a write at `path` or at
- * an ancestor of it). `undefined` path — a whole-document writer — the earliest of all.
- * A write at a DESCENDANT of `path` does not lower it: that position's own token is
- * lower, and the write still pending when an edit of `path` commits lowers it there.
+ * EC-667 → EC-681 — the revision the content a view shows at `path` was authored against:
+ * a token describes the WHOLE value a writer of `path` may replace. It is the earliest of
+ * 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.
+ *
+ * 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`
+ * started on this view commits, and that edit still carries the descendant's old content.
+ * The own descendant write that then APPLIES is lifted across at send time ({@link lift}).
  */
 function provenanceAt(provenance, path) {
     let at = provenance.floor;
     for (const write of provenance.writes) {
-        if (path === undefined || write.paths.some((covered) => isValuePathPrefix(covered, path))) {
+        if (path === undefined || write.paths.some((written) => valuePathsOverlap(written, path))) {
             at = earlierBase(at, write.base);
         }
     }
     return at;
 }
+/**
+ * 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.
+ */
+function mayOverlap(a, b) {
+    const fieldOf = (path) => {
+        const node = path.findIndex((segment) => segment.kind === 'node');
+        return node < 0 ? undefined : path.slice(0, node);
+    };
+    const fieldA = fieldOf(a);
+    const fieldB = fieldOf(b);
+    return fieldA && fieldB ? valuePathsOverlap(fieldA, fieldB) : valuePathsOverlap(a, b);
+}
 /** 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)}`;
@@ -63,6 +86,25 @@ export function importWrite(persister, document, 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.
+ *
+ * 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).
+ */
+function keepsFailedWrite(error) {
+    return error.code === 'backend-unavailable' || error.code === 'unknown';
+}
 /** A write against a document this session no longer holds (deleted here or elsewhere). */
 function goneError(ref) {
     return { code: 'not-found', message: 'The document is gone.', entity: 'cms-document', key: documentKey(ref) };
@@ -246,12 +288,23 @@ export function createCmsPersister(options) {
             entry.own.splice(0, entry.own.length - OWN_WRITES_KEPT);
     }
     /**
-     * EC-647 — THE lift: the base a write authored at `base` is SENT at. Only across this
-     * persister's own writes (see the module doc): a run of consecutive own revisions
-     * right after the base, or an own write that covered every position `paths` touch and
-     * was sent at or below the base. Never across a revision anyone else wrote.
+     * EC-647 → EC-681 — THE lift: the base a write authored at `base` is SENT at. It crosses
+     * a revision only where the store's refusal on it would be a refusal of OUR content —
+     * 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
+     *    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;
+     * 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.
      */
-    function lift(entry, base, paths) {
+    function lift(entry, base, paths, log) {
         let lifted = base;
         for (;;) {
             if (entry.own.some((write) => write.revision === lifted + 1)) {
@@ -265,11 +318,38 @@ export function createCmsPersister(options) {
                     write.sentBase <= lifted &&
                     paths.every((path) => write.paths.some((covered) => isValuePathPrefix(covered, path))))
                 : undefined;
-            if (!covering)
-                return lifted;
-            lifted = covering.revision;
+            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)))) {
+                lifted += 1;
+                continue;
+            }
+            return lifted;
         }
     }
+    /**
+     * EC-681 — the patch log {@link lift} rule 3 reads for a queued patch: only when an own
+     * write the store would refuse it on lies beyond its lift (an own write that may overlap
+     * its positions, past a revision someone else wrote), read after that lift. `undefined`
+     * 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 blocking = entry.own.some((write) => write.revision > lifted &&
+            (write.paths === undefined || write.paths.some((own) => paths.some((path) => mayOverlap(own, path)))));
+        if (!blocking)
+            return undefined;
+        const read = await operations.documents.listPatches({
+            projectId: options.projectId,
+            ref: entry.ref,
+            afterRevision: lifted,
+        });
+        return read.ok ? new Map(read.value.map((row) => [row.revision, row])) : undefined;
+    }
     /**
      * 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
@@ -390,6 +470,24 @@ export function createCmsPersister(options) {
             // The actor is decoration on a conflict the user can already resolve.
         }
     }
+    /**
+     * EC-674 — a write that failed without a per-field conflict: KEPT when the store did not
+     * judge it ({@link keepsFailedWrite}) — back at the head of the queue, still shown,
+     * 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.
+     */
+    function failedWrite(entry, writes, error) {
+        const kept = keepsFailedWrite(error);
+        if (kept)
+            entry.queue.unshift(...writes);
+        else
+            emitDocument(entry);
+        options.onError(error);
+        return kept;
+    }
     /** 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
@@ -423,14 +521,13 @@ export function createCmsPersister(options) {
                 });
                 adopt(entry, result.value);
             }
-            else {
-                if (result.error.code === 'conflict' && 'current' in result.error && result.error.current) {
-                    adopt(entry, result.error.current);
-                }
-                else
-                    emitDocument(entry);
+            else if (result.error.code === 'conflict' && 'current' in result.error && result.error.current) {
+                adopt(entry, result.error.current);
                 options.onError(result.error);
             }
+            else if (failedWrite(entry, [write], result.error)) {
+                return false;
+            }
         }
         finally {
             entry.inFlightReplace = undefined;
@@ -453,10 +550,15 @@ export function createCmsPersister(options) {
             if (!head)
                 return;
             if (head.kind === 'replace') {
-                await sendReplace(entry, operations, head);
+                if (!(await sendReplace(entry, operations, head)))
+                    return;
                 continue;
             }
-            const sendBase = (queued) => lift(entry, queued.base, touchedPaths(queued.patch));
+            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 first = sendBase(head);
             let end = 1;
             while (end < entry.queue.length) {
@@ -528,14 +630,15 @@ export function createCmsPersister(options) {
                 settleAll(run, { status: 'failed', error });
                 return;
             }
-            // A transport / authorization failure: the patches stay local (shown, unsent) and
-            // the error is visible; the next commit or forced flush retries them. The commits
-            // waiting on them learn of the failure now.
+            // 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.
             settleAll(run, { status: 'failed', error });
-            entry.queue.unshift(...run.map((queued) => ({ ...queued, settle: [] })));
+            const kept = failedWrite(entry, run.map((queued) => ({ ...queued, settle: [] })), error);
             adoptHeld(entry);
-            options.onError(error);
-            return;
+            if (kept)
+                return;
         }
     }
     function upsertConflict(entry, refused, revision, base) {