@elytracms/studio 0.0.91 → 0.0.93

package/dist/lib/operations/__fixtures__/write-document.d.ts

@@ -0,0 +1,30 @@
+import type { CmsDocument } from '@elytracms/core/cms-core';
+import type { DocumentOperations } from '../operations-package.js';
+/**
+ * EC-595 A2 — a TEST helper: write a whole document through the revisioned verbs,
+ * `documents.replace` at the stored revision (or insert-if-absent when there is none).
+ * Studio tests that only need "this document now holds these values" (seeding, a later
+ * edit) use it in place of the deleted whole-document upsert; a test about concurrency
+ * passes its own precondition to `documents.replace` / `documents.patch` instead.
+ */
+export declare function writeDocument(ops: {
+    readonly documents: Pick<DocumentOperations, 'get' | 'replace'>;
+}, projectId: string, document: Omit<CmsDocument, 'values'> & {
+    readonly values?: CmsDocument['values'];
+}): Promise<import("@elytracms/core/operations").OperationResult<{
+    createdAt: string;
+    updatedAt: string;
+    projectId: string;
+    document: {
+        collection: string;
+        id: string;
+        values: Record<string, unknown>;
+        alias?: string | undefined;
+        localized?: Record<string, Record<string, unknown>> | undefined;
+    };
+    variant: string;
+    revision: number;
+    publishedVersion?: number | undefined;
+    publishedAt?: string | undefined;
+    hasUnpublishedChanges?: boolean | undefined;
+}>>;

package/dist/lib/operations/__fixtures__/write-document.js

@@ -0,0 +1,16 @@
+/**
+ * EC-595 A2 — a TEST helper: write a whole document through the revisioned verbs,
+ * `documents.replace` at the stored revision (or insert-if-absent when there is none).
+ * Studio tests that only need "this document now holds these values" (seeding, a later
+ * edit) use it in place of the deleted whole-document upsert; a test about concurrency
+ * passes its own precondition to `documents.replace` / `documents.patch` instead.
+ */
+export async function writeDocument(ops, projectId, document) {
+    const current = await ops.documents.get({ projectId, ref: { collection: document.collection, id: document.id } });
+    return ops.documents.replace({
+        projectId,
+        document: { ...document, values: document.values ?? {} },
+        precondition: current.ok ? { revision: current.value.revision } : { ifAbsent: true },
+    });
+}
+//# sourceMappingURL=write-document.js.map

package/dist/lib/operations/__fixtures__/write-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-document.js","sourceRoot":"","sources":["../../../../src/lib/operations/__fixtures__/write-document.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAwE,EACxE,SAAiB,EACjB,QAAmF;IAEnF,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;IACjH,OAAO,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC;QAC3B,SAAS;QACT,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,IAAI,EAAE,EAAE;QACxD,YAAY,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE;KACrF,CAAC,CAAA;AACJ,CAAC","sourcesContent":["import type { CmsDocument } from '@elytracms/core/cms-core'\nimport type { DocumentOperations } from '../operations-package'\n\n/**\n * EC-595 A2 — a TEST helper: write a whole document through the revisioned verbs,\n * `documents.replace` at the stored revision (or insert-if-absent when there is none).\n * Studio tests that only need \"this document now holds these values\" (seeding, a later\n * edit) use it in place of the deleted whole-document upsert; a test about concurrency\n * passes its own precondition to `documents.replace` / `documents.patch` instead.\n */\nexport async function writeDocument(\n  ops: { readonly documents: Pick<DocumentOperations, 'get' | 'replace'> },\n  projectId: string,\n  document: Omit<CmsDocument, 'values'> & { readonly values?: CmsDocument['values'] },\n) {\n  const current = await ops.documents.get({ projectId, ref: { collection: document.collection, id: document.id } })\n  return ops.documents.replace({\n    projectId,\n    document: { ...document, values: document.values ?? {} },\n    precondition: current.ok ? { revision: current.value.revision } : { ifAbsent: true },\n  })\n}\n"]}

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

@@ -1,50 +1,143 @@
-import type { CmsDocument, CollectionDef, DocumentRef, PropFieldLookup } from '@elytracms/core/cms-core';
+import type { CmsDocument, CollectionDef, DocumentPatch, DocumentRef, PropFieldLookup, RefusedPatch, ValuePath } from '@elytracms/core/cms-core';
 import type { CmsDocumentRecord } from '@elytracms/core/persistence';
 import type { OperationError, OperationsClient } from './operations-package.js';
 /**
- * CMS session → operations persistence (EC-141). The CMS store keeps documents
- * and collections as optimistic session state (synchronous editing, validation
- * feedback while typing); every mutation is mirrored onto the operations layer
- * through `documents.*` / `schema.*` commands in dispatch order.
+ * CMS session → operations persistence (EC-141 → EC-595 part A2): the PATCH QUEUE.
  *
- * Baseline: the persisted seed only covers the sample project. Before the
- * first mirrored command, the persister ensures the project has a persisted
- * schema + documents matching the session's starting state (kit imports,
- * sample fixtures), so deletes/updates address records that exist.
+ * 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}.
+ *
+ * **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:
+ *
+ *     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.
+ *
+ * **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 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
+ * whole-document dialog, never a silent overwrite.
  */
+/** One refused patch awaiting the user's decision (EC-595 binding point 5). */
+export interface DocumentConflict {
+    /** Stable id for the UI (`<key>|<path>`); one conflict per path. */
+    readonly id: string;
+    readonly ref: DocumentRef;
+    /** The refused patch — "mine". */
+    readonly patch: DocumentPatch;
+    /** The submitted target path. */
+    readonly path: ValuePath;
+    /** The value at that path on the server NOW — "theirs" (`undefined` = absent). */
+    readonly theirs: unknown;
+    /** `conflict` — changed since the base; `invalid` — never resolved (e.g. its node is gone). */
+    readonly reason: RefusedPatch['reason'];
+    /** The server revision the refusal was made at. */
+    readonly revision: number;
+    /** Who changed the path (the patch log's actor), once resolved; `undefined` while unknown. */
+    readonly actor?: string;
+}
+/** How one {@link CmsPersister.commit} ended once its patches were acknowledged. */
+export type CommitOutcome = {
+    readonly status: 'applied';
+    readonly record: CmsDocumentRecord;
+}
+/** Refused per field — the conflicts stay open on the document for the user to resolve. */
+ | {
+    readonly status: 'refused';
+    readonly conflicts: readonly DocumentConflict[];
+}
+/** A transport / authorization failure (also reported through `onError`). */
+ | {
+    readonly status: 'failed';
+    readonly error: OperationError;
+};
 export interface CmsPersister {
-    upsertDocument(doc: CmsDocument): void;
+    /** 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). */
+    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.
+     */
+    commit(ref: DocumentRef, patches: readonly DocumentPatch[], view?: CmsDocument, bases?: readonly (number | undefined)[]): 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.
+     */
+    replace(document: CmsDocument): void;
     deleteDocument(ref: DocumentRef): void;
-    /** Publish (EC-224): snapshot the current draft as a new version and pin it live. */
-    publishDocument(ref: DocumentRef): void;
-    /** Unpublish (EC-224): clear the live version pin + any legacy published marker. */
     unpublishDocument(ref: DocumentRef): void;
-    upsertCollection(collection: CollectionDef): void;
-    /** Run the baseline seed now (e.g. before applying an AI changeset). */
-    ensureBaseline(): Promise<void>;
-    /** Await every queued command. */
-    flush(): Promise<void>;
+    /**
+     * Adopt a server row pushed by the document subscription (EC-595 point 7): applied
+     * under the local patches (local wins until flushed); held while a write is in flight
+     * and applied after it, so an echo of our own write never races its result.
+     * `undefined` = the document is gone.
+     */
+    adoptSnapshot(ref: DocumentRef, record: CmsDocumentRecord | undefined): void;
+    /** The unresolved conflicts on a document. */
+    conflicts(ref: DocumentRef): readonly DocumentConflict[];
+    /** Resolve a conflict: `theirs` adopts the server value; `mine` re-sends at the current base. */
+    resolveConflict(ref: DocumentRef, conflictId: string, choice: 'theirs' | 'mine'): void;
+    /** Await every queued write (of one document, or all). The FORCED FLUSH's persistence half. */
+    flush(ref?: DocumentRef): Promise<void>;
 }
 export interface CmsPersisterOptions {
     projectId: string;
     getOperations: () => Promise<OperationsClient>;
-    /** Session collections/documents at baseline time (read lazily via refs). */
+    /** The session's collections (read lazily via a ref) — the create/import canonicaliser's lens. */
     getCollections: () => readonly CollectionDef[];
-    getDocuments: () => readonly CmsDocument[];
-    /**
-     * Component-prop field-defs by component id (EC-277): the manifest half of the
-     * write-time self-typing lens, so a composition's static relation/asset props are
-     * self-typed too ("schema leads, component adopts"). Omit → document fields are
-     * still self-typed; composition static props pass through.
-     */
+    /** Component-prop field-defs (EC-277), so a created document's composition props are canonical too. */
     lookupManifest?: PropFieldLookup;
+    /** A failed / denied write that is not a per-field conflict — rendered by the session, never silent. */
     onError: (error: OperationError) => void;
     /**
-     * Called with the AUTHORITATIVE saved record after each queued upsert lands
-     * (EC-449). The session adopts server-computed record state from it — today the
-     * write-chokepoint `hasUnpublishedChanges` verdict behind the amber "changed"
-     * list dot. Optional: omitting it changes nothing.
+     * 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.
+     */
+    onDocument?: (ref: DocumentRef, document: CmsDocument | undefined) => void;
+    /**
+     * A server row was adopted (EC-449 and friends): the session stamps the chokepoint's
+     * `hasUnpublishedChanges`, `updatedAt`, `publishedAt` from it — and, since the row
+     * carries the CANONICAL saved values, the session adopts those too (EC-586
+     * found-but-left: the studio never adopted the saved canonical document).
      */
-    onDocumentSaved?: (record: CmsDocumentRecord) => void;
+    onRecord?: (record: CmsDocumentRecord) => void;
+    /** A document's conflict list changed. */
+    onConflicts?: (ref: DocumentRef, conflicts: readonly DocumentConflict[]) => void;
 }
+/** What the session hydrated for a document: its value and the revision it is at. */
+export type TrackedRow = Pick<CmsDocumentRecord, 'document' | 'revision'>;
 export declare function createCmsPersister(options: CmsPersisterOptions): CmsPersister;