@elytracms/studio 0.0.91 → 0.0.93

package/dist/components/cms/cms-store.js

@@ -1,66 +1,73 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { createCollectionRegistry, createDocumentStore, documentKey, documentReachabilityIssues, documentSchema, resolveDocumentTitle, seedDefaults, resolveSingletonDocument, titleFieldOf, validateDocument, valuesInLocale, writeField, } from '@elytracms/core/cms-core';
+import { applyDocumentPatches, createCollectionRegistry, createDocumentStore, documentKey, documentReachabilityIssues, documentSchema, resolveDocumentTitle, seedDefaults, titleFieldOf, validateDocument, valuesInLocale, writeField, } from '@elytracms/core/cms-core';
+import { createUuidIdFactory } from '@elytracms/core/persistence';
 import { translate } from '@elytracms/studio/lib/i18n';
 import { configureStudioLocales, useStudioLocale } from '@elytracms/studio/lib/locale';
 import { studioManifestLookup } from '@elytracms/studio/lib/registry';
 import { resolveDeploymentCollections, resolveDeploymentLocaleConfig, resolveDeploymentRoutes, } from '@elytracms/studio/lib/workspace';
 import { Heading, Panel, Stack, Text } from '@elytracms/studio/ui';
 import { assetLibraryOracle, gateValidateOptions } from './gate-validation.js';
-import { clearSessionDocumentValidator, setSessionDocumentValidator, } from '@elytracms/studio/lib/cms/document-gate';
 import { matchesRef, removeDoc, replaceDoc, upsertDoc } from './document-ref-utils.js';
 import { createRequiredContext } from '@elytracms/studio/lib/required-context';
-import { createCmsPersister, getStudioOperations } from '@elytracms/studio/lib/operations';
+import { createCmsPersister, getStudioActor, getStudioOperations } from '@elytracms/studio/lib/operations';
+import { publishInSession, publishWithRevision as publishRevision, } from '@elytracms/studio/lib/operations/publish-with-revision';
+import { operationErrorMessage } from '@elytracms/studio/lib/persona/labels';
+import { fieldWritePatch } from '@elytracms/studio/lib/cms/field-patch';
 import { ALL_VIEW_ID, DEFAULT_VIEW_OVERRIDE_ID, canonicalViewState, configViewIssues, defaultConfigViewId, defaultViewState, deprecatedDefaultFlagViewIds, hasDefaultViewOverride, pseudoColumns, resolveCollectionViews, viewStatesEqual, } from '@elytracms/studio/lib/cms-views';
 import { useOptionalAssets } from '../assets/assets-store.js';
 import { consumeStagedDocuments } from './document-staging.js';
 import { commitCellEdit } from './cell-edit.js';
 import { runBulkAction } from './bulk-actions.js';
-import { cleanHiddenForPublish } from './publish-clean.js';
 const { Context: CmsContext, useRequired: useCms } = createRequiredContext('Cms');
-function primaryField(collection) {
-    return titleFieldOf(collection)?.name ?? collection.fields[0]?.name ?? 'id';
-}
+/** The stable empty conflict list (referential stability for the surfaces' memos). */
+const NO_CONFLICTS = [];
 /**
- * EC-316 (bug fix) — mint a fresh, COLLISION-FREE document id for `+ New`.
- *
- * `seq` is an in-memory, per-session counter (reset to 0 on every reload). A
- * document minted `new-<collection>-<n>` in a PRIOR session can already occupy
- * whatever `n` this session's counter would next reissue — the pre-fix bug:
- * `+ New` on a `post` collection that already held a (possibly published)
- * `new-post-1` handed out that SAME id again, silently opening the existing
- * document for editing instead of creating a fresh draft. Walking the counter
- * past every id already in `existingIds` makes the mint collision-free
- * regardless of what a prior session left behind.
+ * EC-595 thin presence — ONE id per tab (per page load): the heartbeat's identity, so a
+ * second tab of the same user is a second presence, and the editor leaves itself out.
  */
-export function mintDocumentId(collectionId, seq, existingIds) {
-    let id;
-    do {
-        seq.current += 1;
-        id = `new-${collectionId}-${seq.current}`;
-    } while (existingIds.has(id));
-    return id;
+const PRESENCE_SESSION_ID = createUuidIdFactory()();
+function primaryField(collection) {
+    return titleFieldOf(collection)?.name ?? collection.fields[0]?.name ?? 'id';
 }
 /**
- * Build a fresh document for `collectionId`: a collision-free id (EC-316, via
- * {@link mintDocumentId} against every id `existingDocs` already holds for
- * this collection) and the collection's declared field defaults (EC-297, via
- * `seedDefaults` — a localized default lands in the project's default-locale
- * bucket, EC-580). Pure — the sensitive part of the insert sequence shared by
- * `createDocument` and `ensureSingletonDocument`'s empty branch (via the
- * private `insertNewDocument` below), factored out so it's unit-testable
- * without a `CmsProvider`.
+ * Build a fresh document for `collectionId` (EC-297 / EC-578): an id from THE injected
+ * id factory — UUIDs in the studio, so two sessions can never mint the same id (the old
+ * per-session `new-<collection>-<n>` counter minted `new-post-1` in both, and the second
+ * create overwrote the first) — and the collection's declared field defaults
+ * (`seedDefaults`; a localized default lands in the project's default-locale bucket,
+ * EC-580). Pure — unit-testable without a `CmsProvider`.
  */
-export function buildNewDocument(collectionId, registry, seq, existingDocs, locales) {
-    const existingIds = new Set(existingDocs.filter((d) => d.collection === collectionId).map((d) => d.id));
-    const id = mintDocumentId(collectionId, seq, existingIds);
+export function buildNewDocument(collectionId, registry, newId, locales) {
     const collection = registry.get(collectionId);
     return {
         collection: collectionId,
-        id,
+        id: newId(),
         ...(collection ? seedDefaults(collection, locales) : { values: {} }),
     };
 }
+/**
+ * EC-274 → EC-595 A2 (critic correction 9) — a singleton's first document:
+ * `documents.create({ singleton: true })` (the store's `ifCollectionEmpty`
+ * precondition). The race loser's `conflict` carries the winner's row, which it ADOPTS
+ * — two sessions opening an empty singleton end up on ONE document. Exported for tests.
+ */
+export async function createOrAdoptSingleton(operations, projectId, collectionId, seeded) {
+    const result = await operations.documents.create({
+        projectId,
+        collection: collectionId,
+        values: seeded.values ?? {},
+        ...(seeded.localized ? { localized: seeded.localized } : {}),
+        singleton: true,
+    });
+    if (result.ok)
+        return { ok: true, record: result.value, adopted: false };
+    const error = result.error;
+    if (error.code === 'conflict' && 'current' in error && error.current) {
+        return { ok: true, record: error.current, adopted: true };
+    }
+    return { ok: false, error };
+}
 /**
  * Does `docs` already hold a document for `collectionId`? `ensureSingletonDocument`'s
  * empty branch re-checks this INSIDE the `setDocuments` updater (against the
@@ -148,7 +155,9 @@ export function CmsProvider(props) {
 function MissingProjectLocales() {
     return (_jsx(Panel, { className: "m-6 p-6", children: _jsxs(Stack, { gap: "2", children: [_jsx(Heading, { level: 2, size: "h4", children: translate('cms.session.noLocales.title') }), _jsx(Text, { size: "sm", tone: "subtle", children: translate('cms.session.noLocales.body') })] }) }));
 }
-function CmsSession({ children, projectId, initialCollections, initialDocuments, initialPublishedKeys, initialTimestamps, initialPublishTimestamps, initialChangedKeys, seedReflectsWrites, localeConfig, }) {
+function CmsSession({ children, projectId, initialCollections, initialDocuments, initialPublishedKeys, initialTimestamps, initialPublishTimestamps, initialChangedKeys, initialRevisions, idFactory, seedReflectsWrites, localeConfig, }) {
+    // EC-578: THE id factory for this session (documents created here).
+    const [newId] = useState(() => idFactory ?? createUuidIdFactory());
     const [documents, setDocuments] = useState(() => {
         const seeded = (initialDocuments ?? []).map((d) => structuredClone(d));
         // EC-320 (0.0.44 follow-up): merge any documents STAGED by the
@@ -259,8 +268,12 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
     // changed verdict for the record's ref. Referentially stable — the persister
     // closes over it once.
     const adoptSavedRecord = useCallback((record) => {
-        stampHasUnpublishedChanges({ collection: record.document.collection, id: record.document.id }, record.hasUnpublishedChanges);
-    }, [stampHasUnpublishedChanges]);
+        const ref = { collection: record.document.collection, id: record.document.id };
+        stampHasUnpublishedChanges(ref, record.hasUnpublishedChanges);
+        // EC-595 A2: an adopted row also carries the chokepoint's last-write instant.
+        if (record.updatedAt)
+            stampUpdatedAt(ref, record.updatedAt);
+    }, [stampHasUnpublishedChanges, stampUpdatedAt]);
     const [activeViews, setActiveViews] = useState({});
     // The live table state per collection where it diverges from the active
     // view; absent key = exactly the active view's state (not dirty).
@@ -277,10 +290,11 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
         ...(initialCollections ?? []),
     ]);
     const [persistError, setPersistError] = useState(null);
-    const seq = useRef(0);
-    // EC-274: collection ids whose lone singleton document this session has already
-    // created — a synchronous guard so a re-invoked effect (or StrictMode's double
-    // mount) never materializes a second document under a freshly generated id.
+    // EC-595 A2: the open per-field conflicts, by document key.
+    const [conflictsByKey, setConflictsByKey] = useState(() => new Map());
+    // EC-274 → EC-595 A2: collection ids whose singleton create this session already
+    // issued — a synchronous guard so a re-invoked effect (or StrictMode's double mount)
+    // never issues a second create (the store's `ifCollectionEmpty` would refuse it anyway).
     const ensuredSingletons = useRef(new Set());
     // Latest session state for the persister's lazy baseline (no re-subscribing).
     const collectionsRef = useRef(collections);
@@ -293,17 +307,34 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
             projectId,
             getOperations: async () => (await getStudioOperations()).operations,
             getCollections: () => collectionsRef.current,
-            getDocuments: () => documentsRef.current,
             // EC-277: self-type composition static props on write (the manifest half of
             // the lens), so extraction stays schema-free. Document fields self-type via
             // the schema alone (above); the registry adds blocks/embed prop coverage.
             lookupManifest: studioManifestLookup(),
             onError: setPersistError,
-            // EC-449: adopt the server-computed `hasUnpublishedChanges` verdict from
-            // every queued upsert's authoritative record (saves, imports, bulk-cleaned
-            // drafts) — the amber list dot follows the chokepoint, never a client guess.
-            onDocumentSaved: adoptSavedRecord,
+            // EC-595 A2: the persister owns the session's view of every document it writes —
+            // the adopted server row with the unflushed local patches re-applied — so an
+            // adopted row (a write result, a subscription push, a conflict's current) shows
+            // here at once, canonical values included (EC-586 found-but-left).
+            onDocument: (ref, doc) => setDocuments((prev) => (doc ? upsertDoc(prev, doc) : removeDoc(prev, ref))),
+            // EC-449: adopt the server-computed `hasUnpublishedChanges` verdict (and the
+            // timestamps) from every adopted row — the chokepoint's, never a client guess.
+            onRecord: adoptSavedRecord,
+            onConflicts: (ref, conflicts) => setConflictsByKey((prev) => {
+                const next = new Map(prev);
+                if (conflicts.length === 0)
+                    next.delete(documentKey(ref));
+                else
+                    next.set(documentKey(ref), conflicts);
+                return next;
+            }),
         });
+        // The base every hydrated document's patches are made against (EC-595 A2).
+        for (const doc of initialDocuments ?? []) {
+            const revision = initialRevisions?.[documentKey(doc)];
+            if (revision !== undefined)
+                persisterRef.current.track({ document: doc, revision });
+        }
     }
     // EC-224: published-ness IS the version pointer (`publishedKeys`) — the SOLE
     // studio source of truth. Declared up here (EC-497) because it is part of THE
@@ -311,10 +342,6 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
     // helpers — now also takes.
     const isPublished = useCallback((ref) => publishedKeys.has(documentKey(ref)), [publishedKeys]);
     const registry = useMemo(() => createCollectionRegistry(collections), [collections]);
-    // EC-497: the gate seam registers ONCE and reads through refs, so it always sees
-    // the latest session without re-registering on every keystroke.
-    const registryRef = useRef(registry);
-    registryRef.current = registry;
     const store = useMemo(() => createDocumentStore(documents), [documents]);
     // Asset references are validated against the REAL asset library (assets live in
     // their own repository, not as CMS documents). EC-588: the oracle returns the
@@ -348,18 +375,36 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
         // detail header, which read the same view.
         return resolveDocumentTitle(collection, valuesInLocale(collection, doc, activeLocale, localeConfig), ref.id);
     }, [documents, registry, localeConfig, activeLocale]);
-    const saveDocument = useCallback((doc) => {
-        // Replace-or-append (upsert): a brand-new document must still land even
-        // though nothing in the session matches its ref yet.
-        setDocuments((prev) => upsertDoc(prev, doc));
-        stampUpdatedAt(doc); // EC-445: a save bumps the $updatedAt column
-        persisterRef.current?.upsertDocument(doc);
+    const commitPatches = useCallback((ref, patches, bases) => {
+        if (patches.length === 0)
+            return Promise.resolve(undefined);
+        stampUpdatedAt(ref); // EC-445: a write bumps the $updatedAt column (the row's own stamp follows)
+        const persister = persisterRef.current;
+        const current = documentsRef.current.find((d) => matchesRef(d, ref));
+        if (!persister) {
+            // A fixture session (no project): apply locally, the same merge the stores run.
+            if (current) {
+                const next = applyDocumentPatches({ document: current, patches, since: [] }).document;
+                setDocuments((prev) => replaceDoc(prev, next));
+            }
+            return Promise.resolve(undefined);
+        }
+        return persister.commit(ref, patches, current, bases);
+    }, [stampUpdatedAt]);
+    const insertDocument = useCallback((doc) => {
+        stampUpdatedAt(doc); // EC-445: a fresh document's $updatedAt starts at creation
+        const persister = persisterRef.current;
+        if (persister)
+            persister.create(doc);
+        else
+            setDocuments((prev) => upsertDoc(prev, doc));
     }, [stampUpdatedAt]);
     const commitFieldEdit = useCallback((input) => {
         // Pure map-replace: an edit always targets a document already open in
         // the session, so a miss (already gone) is a no-op, never an append.
         const replaceWith = (doc) => setDocuments((prev) => replaceDoc(prev, doc));
         const persister = persisterRef.current;
+        const ref = { collection: input.doc.collection, id: input.doc.id };
         return commitCellEdit({
             registry,
             documents: documentsRef.current,
@@ -375,20 +420,35 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
                 replaceWith(doc);
                 stampUpdatedAt(doc);
             },
-            rollbackSession: replaceWith,
+            // EC-595 A2: in a persisted session the persister's view is the truth — a
+            // refused cell shows theirs (mine is dropped, see below), a failed one keeps
+            // the local value queued for the next flush (no silent loss).
+            rollbackSession: (previous) => replaceWith(persister?.documentOf(ref) ?? previous),
             ...(persister && projectId !== undefined
                 ? {
+                    // EC-595 A2: ONE field patch through the persister's queue — at the
+                    // revision the row was at — never a whole-document side channel.
                     dispatch: async (next) => {
-                        // Make sure the persisted baseline + every queued mutation
-                        // landed first, then issue the commit's single command.
-                        await persister.ensureBaseline();
-                        const { operations } = await getStudioOperations();
-                        const result = await operations.documents.upsert({ projectId, document: next });
-                        // EC-449: adopt the chokepoint's changed verdict (inline edits
-                        // bypass the persister queue, so its hook doesn't see them).
-                        if (result.ok)
-                            adoptSavedRecord(result.value);
-                        return result;
+                        const patch = fieldWritePatch(input.collection, next, input.field.name, input.locale);
+                        const outcome = await persister.commit(ref, [patch], input.doc);
+                        if (outcome.status === 'applied')
+                            return { ok: true, value: outcome.record };
+                        if (outcome.status === 'failed')
+                            return { ok: false, error: outcome.error };
+                        // Refused: someone changed this cell's field since the row loaded. A
+                        // table cell has no room for take/keep, so it takes theirs and says so;
+                        // the editor offers the choice.
+                        for (const conflict of outcome.conflicts)
+                            persister.resolveConflict(ref, conflict.id, 'theirs');
+                        return {
+                            ok: false,
+                            error: {
+                                code: 'conflict',
+                                key: documentKey(ref),
+                                message: 'This field was changed by someone else since you loaded it — their value is shown.',
+                                messageRef: { key: 'cms.conflict.cellRefused' },
+                            },
+                        };
                     },
                 }
                 : {}),
@@ -400,61 +460,47 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
         isPublished,
         findAsset,
         stampUpdatedAt,
-        adoptSavedRecord,
     ]);
-    // Shared insert sequence (EC-326): existingIds/mint/seedDefaults (via
-    // `buildNewDocument`) + optimistic append + persist, consumed by both
-    // `createDocument` (always inserts) and `ensureSingletonDocument`'s empty
-    // branch (`guardExisting: true` — re-checks "no document for this collection
-    // yet" against the LATEST `prev` inside the `setDocuments` updater, not the
-    // `documentsRef.current` snapshot the caller already checked, so a
-    // concurrent invocation — StrictMode's double-invoked effect — can never
-    // materialize a second singleton document).
-    const insertNewDocument = useCallback((collectionId, options) => {
-        const doc = buildNewDocument(collectionId, registry, seq, documentsRef.current, localeConfig);
-        setDocuments((prev) => options?.guardExisting && hasDocumentFor(prev, collectionId) ? prev : [...prev, doc]);
-        stampUpdatedAt(doc); // EC-445: a fresh draft's $updatedAt starts at creation time
-        persisterRef.current?.upsertDocument(doc);
-        return doc;
-    }, [registry, stampUpdatedAt, localeConfig]);
     const createDocument = useCallback((collectionId) => {
-        const doc = insertNewDocument(collectionId);
+        // EC-578: the id comes from the injected factory; create is insert-if-absent.
+        const doc = buildNewDocument(collectionId, registry, newId, localeConfig);
+        insertDocument(doc);
         return { collection: collectionId, id: doc.id };
-    }, [insertNewDocument]);
-    // EC-274 (re-scopes EC-217): a singleton is a UI lens, not a fixed id. Resolve
-    // the collection's lone document and return its ref; if none exists yet, create
-    // one with a NORMAL generated id (never the collection id — no code ever names a
-    // literal doc id). Idempotent under React effects/StrictMode: the create guard
-    // keys on "any document in this collection", so a re-invocation never adds a
-    // second. On drift (>1 doc) the studio routes to the list, so this defensively
-    // returns the first; the empty draft persists like any create.
+    }, [registry, newId, localeConfig, insertDocument]);
+    // EC-274 (re-scopes EC-217): a singleton is a UI lens, not a fixed id. When the
+    // session holds none of the collection's documents, create one through
+    // `documents.create({ singleton: true })` (EC-595 A2) — the store's
+    // `ifCollectionEmpty` precondition, so two sessions on an empty singleton make ONE
+    // document; the loser's conflict carries the winner's row, which it adopts. Either
+    // way the document lands in the session and the gate opens it. Idempotent (the ref
+    // guard); a fixture session (no project) creates locally.
     const ensureSingletonDocument = useCallback((collectionId) => {
+        if (documentsRef.current.some((d) => d.collection === collectionId))
+            return;
+        if (ensuredSingletons.current.has(collectionId))
+            return;
+        ensuredSingletons.current.add(collectionId);
         const collection = registry.get(collectionId);
-        const resolution = collection
-            ? resolveSingletonDocument(collection, documentsRef.current)
-            : { kind: 'empty' };
-        if (resolution.kind === 'ready') {
-            return { collection: collectionId, id: resolution.doc.id };
-        }
-        if (resolution.kind === 'drift') {
-            return { collection: collectionId, id: resolution.docs[0].id };
-        }
-        // Empty: create the lone document once. The ref guard (synchronous) plus the
-        // updater's "any doc in collection" check make this idempotent under a
-        // re-invoked effect or StrictMode's double mount — never a second draft.
-        const existing = documentsRef.current.find((d) => d.collection === collectionId);
-        if (existing)
-            return { collection: collectionId, id: existing.id };
-        if (ensuredSingletons.current.has(collectionId)) {
-            return { collection: collectionId, id: `new-${collectionId}-pending` };
+        const seeded = collection ? seedDefaults(collection, localeConfig) : { values: {} };
+        const persister = persisterRef.current;
+        if (!persister || projectId === undefined) {
+            const doc = { collection: collectionId, id: newId(), ...seeded };
+            setDocuments((prev) => (hasDocumentFor(prev, collectionId) ? prev : [...prev, doc]));
+            return;
         }
-        ensuredSingletons.current.add(collectionId);
-        // EC-316: same collision-free mint as `createDocument` (via the shared
-        // `insertNewDocument` — defensive here, the singleton-empty branch only
-        // runs when no document exists yet).
-        const doc = insertNewDocument(collectionId, { guardExisting: true });
-        return { collection: collectionId, id: doc.id };
-    }, [registry, insertNewDocument]);
+        void (async () => {
+            const { operations } = await getStudioOperations();
+            const outcome = await createOrAdoptSingleton(operations, projectId, collectionId, seeded);
+            if (!outcome.ok) {
+                setPersistError(outcome.error);
+                ensuredSingletons.current.delete(collectionId);
+                return;
+            }
+            persister.track(outcome.record);
+            adoptSavedRecord(outcome.record);
+            setDocuments((prev) => upsertDoc(prev, outcome.record.document));
+        })();
+    }, [registry, localeConfig, projectId, newId, adoptSavedRecord]);
     const deleteDocument = useCallback((ref) => {
         setDocuments((prev) => removeDoc(prev, ref));
         persisterRef.current?.deleteDocument(ref);
@@ -501,19 +547,47 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
             stampHasUnpublishedChanges(ref, record.value.hasUnpublishedChanges);
         }
     }, [projectId, setPublished, stampUpdatedAt, stampPublishedAt, stampHasUnpublishedChanges]);
-    const publishDocument = useCallback(async (ref) => {
-        setPublished(ref, true); // optimistic
-        // EC-273: no clearing here — the draft is already free of conditionally-hidden
-        // values (the editor clears them on write), so the snapshot the publish op
-        // pins is clean by construction.
-        persisterRef.current?.publishDocument(ref);
-        await persisterRef.current?.flush();
-        await reconcilePublished(ref);
-    }, [setPublished, reconcilePublished]);
+    /**
+     * EC-595 binding point 6 — publish the revision the client validated. FORCED FLUSH
+     * first (the pending patches land, the session adopts the committed draft), then
+     * `documents.publish({ expectedRevision })`: the store refuses when the draft moved
+     * since (a colleague's save landed in between — Codex P05). On that refusal the
+     * session adopts the current row, RE-VALIDATES it, and retries — bounded, and never
+     * past a validation error the new draft carries. Returns the outcome so a bulk run
+     * can report it.
+     */
+    const publishWithRevision = useCallback(async (ref) => {
+        const persister = persisterRef.current;
+        if (!persister || projectId === undefined)
+            return { ok: true, value: undefined };
+        const { operations } = await getStudioOperations();
+        return publishRevision(ref, {
+            flush: (target) => persister.flush(target),
+            revisionOf: (target) => persister.revisionOf(target),
+            publish: (target, expectedRevision) => operations.documents.publish({
+                projectId,
+                ref: target,
+                ...(expectedRevision !== undefined ? { expectedRevision } : {}),
+            }),
+            adopt: (record) => persister.adoptRecord(record),
+            documentOf: (target) => persister.documentOf(target),
+            validate: (doc) => validateRef.current(doc),
+        });
+    }, [projectId]);
+    const publishDocument = useCallback((ref) => 
+    // EC-585: the hidden-clear runs INSIDE `documents.publish` (for this and every
+    // other caller), and a refusal rejects — see `publishInSession`.
+    publishInSession(ref, {
+        markPublished: (target) => setPublished(target, true), // optimistic
+        publish: publishWithRevision,
+        reconcile: reconcilePublished,
+        report: setPersistError,
+        describe: operationErrorMessage,
+    }), [setPublished, reconcilePublished, publishWithRevision]);
     const unpublishDocument = useCallback(async (ref) => {
         setPublished(ref, false); // optimistic
         persisterRef.current?.unpublishDocument(ref);
-        await persisterRef.current?.flush();
+        await persisterRef.current?.flush(ref);
         await reconcilePublished(ref);
     }, [setPublished, reconcilePublished]);
     const loadDocumentVersions = useCallback(async (ref) => {
@@ -540,10 +614,10 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
     const restoreDocumentVersion = useCallback(async (ref, version, scope) => {
         if (projectId === undefined)
             return null;
-        // Land any queued edits before the restore reads the current draft to
-        // snapshot it (same ordering contract as commitFieldEdit/runBulk). This is
-        // what makes a granular (field/block) restore merge over the LATEST draft.
-        await persisterRef.current?.ensureBaseline();
+        // FORCED FLUSH: land any queued edits before the restore reads the current draft
+        // to snapshot it. This is what makes a granular (field/block) restore merge over
+        // the LATEST draft — and the restore replaces AT the revision it read (EC-595).
+        await persisterRef.current?.flush(ref);
         const { operations } = await getStudioOperations();
         const result = await operations.documents.restore({
             projectId,
@@ -555,15 +629,15 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
             setPersistError(result.error);
             return null;
         }
-        const restored = result.value.document;
-        // Pure map-replace: a restore always targets a document already open in
-        // the session.
-        setDocuments((prev) => replaceDoc(prev, restored));
-        // EC-449: a restore is a save-shaped write — adopt the chokepoint's fresh
-        // changed verdict from the returned record (e.g. restoring a published
-        // doc's draft to an older version flips the dot to amber immediately).
+        // EC-595 A2: the restored row is adopted as the new base (its revision, its
+        // canonical values, its changed flag — EC-449) and shows in the session.
+        const persister = persisterRef.current;
+        if (persister)
+            persister.adoptRecord(result.value);
+        else
+            setDocuments((prev) => replaceDoc(prev, result.value.document));
         adoptSavedRecord(result.value);
-        return restored;
+        return persister?.documentOf(ref) ?? result.value.document;
     }, [projectId, adoptSavedRecord]);
     /**
      * EC-497 — THE option bag (AD-497a), built once and used by every surface that
@@ -596,22 +670,15 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
             ...documentReachabilityIssues({ routes: resolveDeploymentRoutes(), localeConfig }, collection, doc, { siblings: documents.filter((sibling) => sibling.collection === doc.collection) }),
         ];
     }, [registry, validateOptions, documents, localeConfig]);
-    /**
-     * EC-497 — publish the session's canonical validator to the gate seam, so the
-     * operations-layer `documents.publish` gate judges a document with exactly these
-     * rules instead of the weaker, mode-dependent ones it read off the adapter's
-     * schema record. `[]` for a collection the config does not declare preserves the
-     * EC-183/AD-11 data-store rule (studio system collections carry no config field
-     * rules); a validator kept fresh through a ref means the seam sees the latest
-     * session without re-registering per keystroke.
-     */
-    const gateRef = useRef(validate);
-    gateRef.current = validate;
-    useEffect(() => {
-        const owned = (doc) => registryRef.current.has(doc.collection) ? gateRef.current(doc) : [];
-        setSessionDocumentValidator(owned);
-        return () => clearSessionDocumentValidator(owned);
-    }, []);
+    // The publish retry re-validates with the session's latest rules (a ref: no churn).
+    const validateRef = useRef(validate);
+    validateRef.current = validate;
+    // EC-595 A2 (F23): this session no longer publishes its validator to a module-global
+    // gate seam. The publish gate validates with the operations bundle's runtime
+    // validator (`lib/operations/runtime-validator.ts` — the operation's project config +
+    // oracles prefetched through the adapter), so mounting a second provider (the
+    // transfer dialog) can no longer change a verdict. `validate` above stays the
+    // session's DISPLAY validation (the editor's issues, cell edit, import, AI).
     const importDocuments = useCallback((collectionId, raw) => {
         const report = { added: 0, rejected: [] };
         // Pre-parse so intra-batch relation/asset targets resolve during validation.
@@ -659,9 +726,20 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
             // Replace-or-append (upsert): an imported row may be brand new to the
             // session, so each accepted document must land even with no prior
             // entry for its ref.
-            setDocuments((prev) => accepted.reduce((acc, doc) => upsertDoc(acc, doc), prev));
-            for (const doc of accepted)
-                persisterRef.current?.upsertDocument(doc);
+            // EC-595 A2: a row new to the store is CREATED (insert-if-absent); a row the
+            // session already holds is REPLACED at the revision it was loaded at — an import
+            // never overwrites a change made since.
+            const persister = persisterRef.current;
+            if (!persister)
+                setDocuments((prev) => accepted.reduce((acc, doc) => upsertDoc(acc, doc), prev));
+            for (const doc of accepted) {
+                if (!persister)
+                    continue;
+                if (persister.revisionOf(doc) !== undefined)
+                    persister.replace(doc);
+                else
+                    persister.create(doc);
+            }
             // EC-224: imports land as the working DRAFT. Publish-ness is the version
             // pointer (`publishedKeys`), set by publishing — never carried in the
             // imported row — so an import never auto-publishes; the editor publishes
@@ -762,20 +840,19 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
         let dispatch;
         const persister = persisterRef.current;
         if (persister && projectId !== undefined) {
-            // Pending queued mutations + baseline land first, then one awaited
-            // command per item (same ordering contract as commitFieldEdit).
-            await persister.ensureBaseline();
+            // Pending queued writes land first, then one awaited command per item.
+            await persister.flush();
             const { operations } = await getStudioOperations();
-            dispatch = (bulkAction, ref) => {
+            dispatch = async (bulkAction, ref) => {
                 if (bulkAction === 'delete')
                     return operations.documents.delete({ projectId, ref });
+                // EC-595 point 6: publish the revision validated, with the same retry.
                 if (bulkAction === 'publish')
-                    return operations.documents.publish({ projectId, ref });
+                    return publishWithRevision(ref);
                 if (bulkAction === 'unpublish')
                     return operations.documents.unpublish({ projectId, ref });
-                // set-field: upsert the document carrying the new value. The write
-                // path self-types it through the schema lens (EC-277); a scalar field
-                // stores its scalar as-is.
+                // set-field: ONE field patch per document through the persister (EC-595 A2) —
+                // the operation canonicalises the value by the field (EC-277/EC-586).
                 const current = documentsRef.current.find((d) => matchesRef(d, ref));
                 if (!current) {
                     return Promise.resolve({
@@ -788,15 +865,24 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
                         },
                     });
                 }
-                return operations.documents
-                    .upsert({ projectId, document: setFieldDoc(current) })
-                    .then((result) => {
-                    // EC-449: adopt the chokepoint's changed verdict per set-field item
-                    // (bulk dispatch bypasses the persister queue and its hook).
-                    if (result.ok)
-                        adoptSavedRecord(result.value);
-                    return result;
-                });
+                const written = setFieldDoc(current);
+                const outcome = await persister.commit(ref, [fieldWritePatch(collection, written, setField.field, activeLocale)], current);
+                if (outcome.status === 'applied')
+                    return { ok: true, value: outcome.record };
+                if (outcome.status === 'failed')
+                    return { ok: false, error: outcome.error };
+                // Refused: the field changed since — the item fails visibly; theirs stays.
+                for (const conflict of outcome.conflicts)
+                    persister.resolveConflict(ref, conflict.id, 'theirs');
+                return {
+                    ok: false,
+                    error: {
+                        code: 'conflict',
+                        key: documentKey(ref),
+                        message: 'This field was changed by someone else since you loaded it — their value is kept.',
+                        messageRef: { key: 'cms.conflict.cellRefused' },
+                    },
+                };
             };
         }
         return runBulkAction({
@@ -813,27 +899,9 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
                 isPublished,
                 ...(findAsset ? { findAsset } : {}),
             })),
-            // EC-425: bulk publish joins the single-document clean point — the
-            // SAME shared hidden-strip `doPublish` runs (EC-273 field values +
-            // EC-394 component props, session registry), per item.
-            // EC-580: in the session's locale views — the single publish's same step.
-            ...(collection
-                ? {
-                    cleanForPublish: (doc) => cleanHiddenForPublish(collection, doc, undefined, localeConfig),
-                }
-                : {}),
-            // Land a cleaned draft exactly the way the editor's publish does:
-            // session apply + the persister's self-typing upsert (EC-277 manifest
-            // lens), flushed so the serial queue lands the upsert BEFORE the
-            // awaited publish command snapshots the stored draft.
-            applyCleaned: async (_ref, cleaned) => {
-                setDocuments((prev) => replaceDoc(prev, cleaned));
-                const persister = persisterRef.current;
-                if (persister && projectId !== undefined) {
-                    persister.upsertDocument(cleaned);
-                    await persister.flush();
-                }
-            },
+            // EC-585: no clean step here — the hidden-clear runs inside the one publish
+            // operation each item's `publishWithRevision` dispatches (EC-425's shared
+            // clean point, moved to where every publish path crosses it).
             // EC-224: a succeeded publish/unpublish moves the version pointer
             // (`publishedKeys`) via setPublished — there is no separate flat
             // `state` mirror to keep in sync (published-ness is derived from the
@@ -850,7 +918,13 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
             // locale-aware path the dispatched upsert used). Not a plain
             // `replaceDoc` — the replacement is computed FROM each matched
             // document (`setFieldDoc(d)`), not a fixed value to swap in.
-            applySetField: (ref) => setDocuments((prev) => prev.map((d) => (matchesRef(d, ref) ? setFieldDoc(d) : d))),
+            // A persisted session's view already holds the committed patch (the persister);
+            // a fixture session folds the value locally.
+            applySetField: (ref) => {
+                if (persisterRef.current)
+                    return;
+                setDocuments((prev) => prev.map((d) => (matchesRef(d, ref) ? setFieldDoc(d) : d)));
+            },
             ...(dispatch ? { dispatch } : {}),
         }, collectionId, ids, action, setField);
     }, [
@@ -862,9 +936,62 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
         setPublished,
         isPublished,
         findAsset,
-        adoptSavedRecord,
         stampHasUnpublishedChanges,
+        publishWithRevision,
     ]);
+    // EC-595 point 7 — follow one open document: pushed rows go to the persister (applied
+    // under the local edits), presence to the caller. The capability lives on the
+    // operations bundle (the UI never holds a reactive Convex client).
+    const subscribeDocument = useCallback((ref, onPresence) => {
+        if (projectId === undefined)
+            return () => { };
+        let stop = () => { };
+        let stopped = false;
+        void getStudioOperations().then((studio) => {
+            if (stopped)
+                return;
+            stop = studio.subscribeDocument(projectId, ref, {
+                onSnapshot: (snapshot) => {
+                    persisterRef.current?.adoptSnapshot(ref, snapshot.record);
+                    onPresence(snapshot.presence);
+                },
+            });
+        });
+        return () => {
+            stopped = true;
+            stop();
+        };
+    }, [projectId]);
+    // EC-595 thin presence: this tab's heartbeat on a document (the focused field's path).
+    const reportPresence = useCallback((ref, path) => {
+        if (projectId === undefined)
+            return;
+        const actor = getStudioActor();
+        void getStudioOperations()
+            .then((studio) => studio.reportPresence(projectId, ref, {
+            sessionId: PRESENCE_SESSION_ID,
+            ...(actor ? { actor: actor.id } : {}),
+            ...(actor?.name ? { actorName: actor.name } : {}),
+            ...(path ? { path } : {}),
+        }))
+            .catch(() => {
+            // Reported on the operations bus (EC-403 sees an expiry); presence is advisory.
+        });
+    }, [projectId]);
+    const clearPresence = useCallback((ref) => {
+        if (projectId === undefined)
+            return;
+        void getStudioOperations()
+            .then((studio) => studio.clearPresence(projectId, ref, PRESENCE_SESSION_ID))
+            .catch(() => { });
+    }, [projectId]);
+    const replaceDocument = useCallback((doc) => {
+        const persister = persisterRef.current;
+        if (persister)
+            persister.replace(doc);
+        else
+            setDocuments((prev) => replaceDoc(prev, doc));
+    }, []);
     const store$ = useMemo(() => ({
         ...(projectId !== undefined ? { projectId } : {}),
         collections,
@@ -874,10 +1001,21 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
         documentsOf: (collectionId) => documents.filter((d) => d.collection === collectionId),
         getDocument,
         titleOf,
-        saveDocument,
+        commitPatches,
+        revisionOf: (ref) => persisterRef.current?.revisionOf(ref),
+        insertDocument,
+        newDocumentId: newId,
         commitFieldEdit,
         createDocument,
         ensureSingletonDocument,
+        documentConflicts: (ref) => conflictsByKey.get(documentKey(ref)) ?? NO_CONFLICTS,
+        resolveConflict: (ref, conflictId, choice) => persisterRef.current?.resolveConflict(ref, conflictId, choice),
+        adoptDocumentSnapshot: (ref, record) => persisterRef.current?.adoptSnapshot(ref, record),
+        subscribeDocument,
+        reportPresence,
+        clearPresence,
+        presenceSessionId: PRESENCE_SESSION_ID,
+        replaceDocument,
         deleteDocument,
         isPublished,
         documentUpdatedAt,
@@ -919,8 +1057,7 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
         addCollection: (def) => setCollections((prev) => [...prev.filter((c) => c.id !== def.id), def]),
         persistError,
         clearPersistError: () => setPersistError(null),
-        ensurePersistedBaseline: () => persisterRef.current?.ensureBaseline() ?? Promise.resolve(),
-        flushPersistence: () => persisterRef.current?.flush() ?? Promise.resolve(),
+        flushPersistence: (ref) => persisterRef.current?.flush(ref) ?? Promise.resolve(),
     }), [
         projectId,
         collections,
@@ -930,10 +1067,17 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
         getCollection,
         getDocument,
         titleOf,
-        saveDocument,
+        commitPatches,
+        insertDocument,
+        newId,
         commitFieldEdit,
         createDocument,
         ensureSingletonDocument,
+        conflictsByKey,
+        subscribeDocument,
+        reportPresence,
+        clearPresence,
+        replaceDocument,
         deleteDocument,
         isPublished,
         documentUpdatedAt,