@elytracms/studio 0.0.96 → 0.0.97

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

@@ -36,6 +36,19 @@ import type { OperationError, OperationsClient } from './operations-package.js';
  * (which sent at whatever revision a later read returned). A write that cannot name the
  * revision it was authored against is refused, visibly — it never borrows one.
  *
+ * - **A view's token is per position (EC-667, Codex F18).** A view that shows a pending
+ *   write is a COMPOSITE: no single underlying revision names it. Each shown view is
+ *   registered with its provenance at display time — the base's revision, or under a
+ *   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);
+ *   `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
+ *   (before EC-667 the composite was named by the base's revision — a colleague's change
+ *   adopted underneath a pending snapshot lent the edit its revision, and the edit,
+ *   authored on the old content, overwrote it).
  * - **A position under one of this session's own unacknowledged writes** (queued, in
  *   flight, or an open conflict's "mine") was authored against THAT write's base: the
  *   view showed mine there, not a colleague's change that may sit underneath it. The
@@ -102,7 +115,13 @@ export type CommitOutcome = {
 export interface CmsPersister {
     /** Adopt a server row as this session's base for its document (hydration, a create result). */
     track(row: TrackedRow): void;
-    /** The revision the session's view of a document is at now (`undefined` = untracked). */
+    /**
+     * The revision of the server row the session last adopted for a document (`undefined` =
+     * untracked). A document deleted since still answers its removed lifetime's last
+     * revision (EC-673): a publish conditioned on it is refused, never sent unconditionally
+     * into a re-creation this session never showed — so whether to create or replace is
+     * never decided on it alone ({@link importWrite} decides on the row the session shows).
+     */
     revisionOf(ref: DocumentRef): number | undefined;
     /** The session's view of a tracked document (base ⊕ local), or `undefined`. */
     documentOf(ref: DocumentRef): CmsDocument | undefined;
@@ -113,8 +132,14 @@ export interface CmsPersister {
      * the pair cannot drift apart. `undefined` for a value the persister never showed (a
      * copy, a fixture), or a provisional view (our own create in flight, an untracked
      * document).
+     *
+     * EC-667 — per position: `path` given, the revision the content the view shows AT
+     * `path` was authored against (an editor's first keystroke there); without it, the
+     * EARLIEST authoring revision of any position the view shows — the token of a
+     * whole-document writer (a replace, an import). A view showing a pending write is never
+     * named by the base's revision alone (see the module doc).
      */
-    revisionOfView(view: CmsDocument): number | undefined;
+    revisionOfView(view: CmsDocument, path?: ValuePath): number | undefined;
     /**
      * Commit patches a writer made and flush them. The session's view updates
      * synchronously (via `onDocument`); the patches persist in order through
@@ -185,4 +210,18 @@ export interface CmsPersisterOptions {
 }
 /** What the session hydrated for a document: its value and the revision it is at. */
 export type TrackedRow = Pick<CmsDocumentRecord, 'document' | 'revision'>;
+/**
+ * An import's whole-document write (EC-595 A2 → EC-647 → EC-673): a row the session SHOWS
+ * and holds a revision for is REPLACED at the revision of the row it showed (the one the
+ * import was judged against); any other row is CREATED (insert-if-absent).
+ *
+ * EC-673: the decision is the SHOWN row's, never the tracked revision alone. A document
+ * deleted earlier in the session is not shown, but its entry can still answer a
+ * revision — the editor's Delete and a colleague's delete keep the deleted lifetime's
+ * base, and the list's bulk Delete never tells the persister at all. Deciding on that
+ * revision sent the import down `replace`: queued on a deleted entry and skipped, or
+ * refused as unauthored with the deleted lifetime's values shown again. A replace with no
+ * shown row could never be right anyway — it names no revision it was authored against.
+ */
+export declare function importWrite(persister: Pick<CmsPersister, 'revisionOf' | 'revisionOfView' | 'replace' | 'create'>, document: CmsDocument, shown: CmsDocument | undefined): void;
 export declare function createCmsPersister(options: CmsPersisterOptions): CmsPersister;

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

@@ -2,6 +2,22 @@ import { applyDocumentPatches, documentKey, formatValuePath, isValuePathPrefix,
 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.
+ */
+function provenanceAt(provenance, path) {
+    let at = provenance.floor;
+    for (const write of provenance.writes) {
+        if (path === undefined || write.paths.some((covered) => isValuePathPrefix(covered, path))) {
+            at = earlierBase(at, write.base);
+        }
+    }
+    return at;
+}
 /** 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)}`;
@@ -27,6 +43,30 @@ function samePath(a, b) {
 function earlierBase(a, b) {
     return a === undefined || b === undefined ? undefined : Math.min(a, b);
 }
+/**
+ * An import's whole-document write (EC-595 A2 → EC-647 → EC-673): a row the session SHOWS
+ * and holds a revision for is REPLACED at the revision of the row it showed (the one the
+ * import was judged against); any other row is CREATED (insert-if-absent).
+ *
+ * EC-673: the decision is the SHOWN row's, never the tracked revision alone. A document
+ * deleted earlier in the session is not shown, but its entry can still answer a
+ * revision — the editor's Delete and a colleague's delete keep the deleted lifetime's
+ * base, and the list's bulk Delete never tells the persister at all. Deciding on that
+ * revision sent the import down `replace`: queued on a deleted entry and skipped, or
+ * refused as unauthored with the deleted lifetime's values shown again. A replace with no
+ * shown row could never be right anyway — it names no revision it was authored against.
+ */
+export function importWrite(persister, document, shown) {
+    if (shown && persister.revisionOf(document) !== undefined) {
+        persister.replace(document, persister.revisionOfView(shown));
+    }
+    else
+        persister.create(document);
+}
+/** 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) };
+}
 /** The refusal of a write that names no revision it was authored against (EC-647). */
 function unauthoredError(ref) {
     return {
@@ -44,8 +84,10 @@ export function createCmsPersister(options) {
         });
     });
     const entries = new Map();
-    /** EC-647: every document value this persister showed or tracked → the revision it is at. */
+    /** EC-647 / EC-667: every document value this persister showed or tracked → what it was authored against. */
     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: [] });
     function entryOf(ref) {
         const key = documentKey(ref);
         let entry = entries.get(key);
@@ -84,15 +126,21 @@ 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 the revision
-     * it is at (EC-647) — the base's; a provisional view has none.
+     * 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.
      */
     function display(entry) {
         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),
+        }));
         const pending = [
             ...entry.inFlight,
             ...(entry.inFlightReplace ? [entry.inFlightReplace] : []),
@@ -100,17 +148,22 @@ export function createCmsPersister(options) {
         ];
         for (const queued of pending) {
             if (queued.kind === 'replace') {
-                // The snapshot was authored over everything before it (the editor's draft).
+                // 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 = [];
                 document = queued.document;
+                floor = queued.base;
             }
-            else
+            else {
                 patches.push(queued.patch);
+                writes.push({ paths: touchedPaths(queued.patch), base: queued.base });
+            }
         }
         if (patches.length > 0)
             document = applyDocumentPatches({ document, patches, since: [] }).document;
         if (entry.base)
-            shown.set(document, entry.base.revision);
+            shown.set(document, { floor, writes });
         return document;
     }
     function emitDocument(entry) {
@@ -128,7 +181,7 @@ export function createCmsPersister(options) {
         if (entry.base && record.revision < entry.base.revision)
             return;
         entry.base = record;
-        shown.set(record.document, record.revision);
+        registerRow(record);
         options.onRecord?.(record);
         emitDocument(entry);
     }
@@ -160,12 +213,22 @@ export function createCmsPersister(options) {
         if (entry.deleted)
             return;
         entry.deleted = true;
-        dropQueued(entry, {
-            status: 'failed',
-            error: { code: 'not-found', message: 'The document is gone.', entity: 'cms-document', key: documentKey(entry.ref) },
-        });
+        dropQueued(entry, { status: 'failed', error: goneError(entry.ref) });
         options.onDocument?.(entry.ref, undefined);
     }
+    /**
+     * EC-673 — writes queued on a document this session no longer holds (one put back by a
+     * failed send after a delete, a "keep mine" on a document that went away): refused and
+     * REPORTED, never left in the queue for the drain to skip — nor sent into a later
+     * re-create of the id, whose first revision the own-write ledger would lift them across.
+     */
+    function refuseQueued(entry) {
+        if (entry.queue.length === 0)
+            return;
+        const error = goneError(entry.ref);
+        dropQueued(entry, { status: 'failed', error });
+        options.onError(error);
+    }
     function schedule(entry) {
         if (entry.scheduled)
             return;
@@ -378,7 +441,11 @@ export function createCmsPersister(options) {
     }
     /** Send the queue — runs of equal (lifted) base, whole-document writes in their place — until it is empty or a write fails. */
     async function drain(entry) {
-        while (entry.queue.length > 0 && !entry.deleted) {
+        while (entry.queue.length > 0) {
+            if (entry.deleted) {
+                refuseQueued(entry);
+                return;
+            }
             const operations = await options.getOperations();
             if (!(await baseOnRead(entry, operations)))
                 return;
@@ -503,7 +570,7 @@ export function createCmsPersister(options) {
     return {
         track(row) {
             const entry = entryOf(row.document);
-            shown.set(row.document, row.revision);
+            registerRow(row);
             if (!entry.base || row.revision > entry.base.revision)
                 entry.base = row;
         },
@@ -512,7 +579,10 @@ export function createCmsPersister(options) {
             const entry = entries.get(documentKey(ref));
             return entry ? display(entry) : undefined;
         },
-        revisionOfView: (view) => shown.get(view),
+        revisionOfView: (view, path) => {
+            const provenance = shown.get(view);
+            return provenance ? provenanceAt(provenance, path) : undefined;
+        },
         adoptRecord(record) {
             const entry = entryOf(record.document);
             if (entry.deleted)
@@ -522,11 +592,14 @@ export function createCmsPersister(options) {
         },
         commit(ref, patches, bases, view) {
             const entry = entryOf(ref);
-            if (patches.length === 0 || entry.deleted) {
-                return Promise.resolve({
-                    status: 'failed',
-                    error: { code: 'not-found', message: 'The document is gone.', entity: 'cms-document', key: documentKey(ref) },
-                });
+            if (patches.length === 0)
+                return Promise.resolve({ status: 'failed', error: goneError(ref) });
+            if (entry.deleted) {
+                // EC-673: a write that cannot be sent is reported, not only settled — the editor's
+                // committer and the transfer dialog do not read the outcome.
+                const error = goneError(ref);
+                options.onError(error);
+                return Promise.resolve({ status: 'failed', error });
             }
             if (!Array.isArray(bases)) {
                 // EC-647: a writer that names no authoring revision at all — never given the tracked one.
@@ -605,7 +678,17 @@ export function createCmsPersister(options) {
         create(document) {
             const doc = canonical(document);
             const entry = entryOf(doc);
-            // A fresh document: nothing of an earlier incarnation of this ref carries over.
+            // A fresh document: nothing of an earlier incarnation of this ref carries over —
+            // EC-673: its queued writes (refused and reported, never sent into this one) and its
+            // open conflicts (a colleague's delete keeps them; their "mine" is not laid over this one).
+            if (entry.deleted) {
+                refuseQueued(entry);
+                if (entry.conflicts.length > 0) {
+                    entry.conflicts = [];
+                    entry.conflictBases.clear();
+                    emitConflicts(entry);
+                }
+            }
             entry.deleted = false;
             entry.base = undefined;
             entry.own = [];
@@ -648,6 +731,13 @@ export function createCmsPersister(options) {
         replace(document, revision) {
             const doc = canonical(document);
             const entry = entryOf(doc);
+            if (entry.deleted) {
+                // EC-673: a document this session no longer holds has nothing to replace — refused
+                // and reported here, never queued for a drain that skips it (or a re-create of the
+                // id that would send it). A new document of the id is a `create`.
+                options.onError(goneError(entry.ref));
+                return;
+            }
             if (!entry.base && !entry.provisional)
                 entry.provisional = doc;
             // Queued in its place: the patches committed before it are sent first (the snapshot
@@ -660,10 +750,7 @@ export function createCmsPersister(options) {
         },
         deleteDocument(ref) {
             const entry = entryOf(ref);
-            dropQueued(entry, {
-                status: 'failed',
-                error: { code: 'not-found', message: 'The document is gone.', entity: 'cms-document', key: documentKey(ref) },
-            });
+            dropQueued(entry, { status: 'failed', error: goneError(ref) });
             entry.conflicts = [];
             entry.conflictBases.clear();
             entry.deleted = true;