@elytracms/studio 0.0.95 → 0.0.97

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

@@ -2,41 +2,81 @@ import type { CmsDocument, CollectionDef, DocumentPatch, DocumentRef, PropFieldL
 import type { CmsDocumentRecord } from '@elytracms/core/persistence';
 import type { OperationError, OperationsClient } from './operations-package.js';
 /**
- * CMS session → operations persistence (EC-141 → EC-595 part A2): the PATCH QUEUE.
+ * CMS session → operations persistence (EC-141 → EC-595 part A2 → EC-647): the PATCH QUEUE.
  *
  * The CMS session keeps documents as optimistic, synchronous state; every write is
  * mirrored onto the operations layer through the revisioned aggregate's two verbs
  * (EC-595, ratified 2026-10-24): `documents.patch` for editing, `documents.replace`
- * for whole-document writers (create, import). There is no document diffing anywhere:
- * every writer EMITS the patches it made at its source (the form's field path, the
- * canvas's node patches, the AI proposal's field changes, bulk set-field, transfer) and
- * hands them to {@link CmsPersister.commit}.
+ * for whole-document writers (create, import, the slot alias). There is no document
+ * diffing anywhere: every writer EMITS the patches it made at its source (the form's
+ * field path, the canvas's node patches, the AI proposal's field changes, bulk
+ * set-field, transfer) and hands them to {@link CmsPersister.commit}.
  *
- * **Per document, the persister keeps** the server row it last adopted (`base` — its
- * revision is what a patch is made against), the committed-but-unacknowledged patches
- * (each with the revision the user's view was at when it was made), and the refused
- * paths awaiting a decision. It derives the session's view of the document from them:
+ * **Per document, the persister keeps** the server row it last adopted (`base`), the
+ * committed-but-unacknowledged writes (each with the revision it was AUTHORED against),
+ * the refused paths awaiting a decision, and the writes it made itself (the own-write
+ * ledger). It derives the session's view of the document from them:
  *
  *     display = base.document ⊕ unresolved conflicts (mine) ⊕ in-flight ⊕ queued
  *
  * by re-applying the patches with THE merge (`applyDocumentPatches`, `since: []`) — the
- * same pure function both stores run. So local edits win on their paths until they are
- * flushed (EC-595 point 7), and a server row adopted underneath them (a write result,
- * a subscription push, a conflict's `current`) shows everywhere else at once.
+ * same pure function both stores run (a queued whole-document write resets the view to
+ * its snapshot at its place in the order). So local edits win on their paths until they
+ * are flushed (EC-595 point 7), and a server row adopted underneath them (a write
+ * result, a subscription push, a conflict's `current`) shows everywhere else at once.
  *
- * **Base revisions are per patch** (not per call): a patch is checked against the
- * changes in `(its base, current]`, so a colleague's change that arrived (by subscribe)
- * AFTER the user started typing in a field is still detected on that field. A patch
- * whose path our own successful write just covered moves its base to that write's
- * revision — the server guarantees no other session touched the path in between, so
- * a second edit of a field during the first one's flight never conflicts with itself.
- * Consecutive runs of equal base are sent in commit order, one `documents.patch` call
- * per run.
+ * **A value and the revision it was authored against travel together (EC-647).** Every
+ * view this persister shows is registered with the revision it is at
+ * ({@link CmsPersister.revisionOfView} — the shown document object IS the token), and a
+ * writer hands each patch over WITH the revision of the view it was authored on
+ * (`bases`, required). The persister never substitutes a newer revision for it — not at
+ * commit (the old `bases ?? tracked revision` default), not at send (the old
+ * `queued.base ?? entry.base.revision`), not in a whole-document `replace` (which read
+ * the tracked revision at SEND time — Codex F10), and not for an untracked document
+ * (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
+ *   later write takes the earlier base, so a colleague's hidden change is still refused
+ *   on it (same-field supersession has always kept the earlier base for this reason).
+ * - **The own-write ledger.** A base may be LIFTED, at send time, across revisions this
+ *   persister wrote — and only those: across a run of consecutive own revisions right
+ *   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.
+ * - **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
+ *   landed at, or — untracked — on a read of the document that EQUALS the view they were
+ *   authored on; anything else is refused as a conflict per position.
+ *
+ * Consecutive runs of equal (lifted) base are sent in commit order, one
+ * `documents.patch` call per run; a queued whole-document write is sent in its place in
+ * that order.
  *
  * **A refused path is a conflict ON THAT FIELD** ({@link DocumentConflict}): the
  * session shows "changed by X — take theirs / keep mine"; until the user decides, the
  * field keeps showing mine (and further edits of it replace mine without being sent);
- * keep-mine re-sends at the current base, take-theirs drops mine. Never a
+ * keep-mine re-sends at the current base — the ONE deliberate "at the current base"
+ * write: the user chose it after seeing theirs; take-theirs drops mine. Never a
  * whole-document dialog, never a silent overwrite.
  */
 /** One refused patch awaiting the user's decision (EC-595 binding point 5). */
@@ -67,7 +107,7 @@ export type CommitOutcome = {
     readonly status: 'refused';
     readonly conflicts: readonly DocumentConflict[];
 }
-/** A transport / authorization failure (also reported through `onError`). */
+/** A transport / authorization failure, or a write that named no authoring revision (also reported through `onError`). */
  | {
     readonly status: 'failed';
     readonly error: OperationError;
@@ -75,29 +115,58 @@ 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 (`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;
     /**
-     * Commit patches a writer made (at the session's current view) and flush them. The
-     * session's view updates synchronously (via `onDocument`); the patches persist in
-     * order through `documents.patch`. `view` — the session's current document, the
-     * provisional base of a document this session holds no revision for (a staged
-     * transfer); its revision is read before the first send. `bases` — per patch, the
-     * revision the user's view was at when they STARTED that edit (an editor field typed
-     * across a colleague's change); absent → the revision the view is at now.
+     * EC-647 — the revision a document value this persister SHOWED is at: every view it
+     * emits (`onDocument`, {@link documentOf}) and every row it tracks is registered with
+     * its revision, so a writer holding the value it displayed holds its revision too —
+     * 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).
      */
-    commit(ref: DocumentRef, patches: readonly DocumentPatch[], view?: CmsDocument, bases?: readonly (number | undefined)[]): Promise<CommitOutcome>;
+    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
+     * `documents.patch`. `bases` — REQUIRED, one per patch: the revision of the view the
+     * writer authored that patch against (an editor field: the revision its draft was at
+     * when the user STARTED that edit; the canvas: the revision of the value its delta is
+     * measured from; a table row: {@link revisionOfView} of the row it showed; an AI
+     * proposal: the revision of the read it was built from). `undefined` entries mean the
+     * view was provisional (see the module doc) — on a document this session tracks and
+     * did not create, such a patch is refused. `view` — the session's current document,
+     * the provisional view of a document this session holds no revision for (a staged
+     * transfer).
+     */
+    commit(ref: DocumentRef, patches: readonly DocumentPatch[], bases: readonly (number | undefined)[], view?: CmsDocument): Promise<CommitOutcome>;
     /** Adopt a server row one of the session's OWN direct writes returned (publish, restore). */
     adoptRecord(record: CmsDocumentRecord): void;
     /** Create a document (insert-if-absent: `documents.replace` `{ ifAbsent: true }`). */
     create(document: CmsDocument): void;
     /**
-     * Write a whole document at the session's tracked revision (or insert-if-absent when
-     * untracked): an import. A move since then is refused as a conflict, never overwritten.
+     * Write a whole document at the revision it was AUTHORED against (EC-647 — the
+     * snapshot and its revision travel together; Codex F10): an import, the slot alias. A
+     * move since then — by anyone but this session's own writes — is refused as a
+     * conflict, never overwritten. `revision` `undefined`: the snapshot was authored on a
+     * provisional view (our own pending create; insert-if-absent when untracked). Sent in
+     * its place among the session's queued patches.
      */
-    replace(document: CmsDocument): void;
+    replace(document: CmsDocument, revision: number | undefined): void;
     deleteDocument(ref: DocumentRef): void;
     unpublishDocument(ref: DocumentRef): void;
     /**
@@ -125,7 +194,8 @@ export interface CmsPersisterOptions {
     onError: (error: OperationError) => void;
     /**
      * The session's view of a document changed (an optimistic commit, an adopted server
-     * row, a resolved conflict) — `undefined` when the document is gone. Synchronous.
+     * row, a resolved conflict) — `undefined` when the document is gone. Synchronous. The
+     * document object is registered with its revision ({@link CmsPersister.revisionOfView}).
      */
     onDocument?: (ref: DocumentRef, document: CmsDocument | undefined) => void;
     /**
@@ -140,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;