@elytracms/studio 0.0.91 → 0.0.93

package/dist/lib/persistence/convex-adapter.js

@@ -1,23 +1,22 @@
 import { ConvexError } from 'convex/values';
-import { documentKey, documentSchema } from '@elytracms/core/cms-core';
-import { RecordNotFoundError, PersistenceValidationError, assetCreateDefaults, assetRecordFromRow, compareReferenceEntries, highestRole, isKnownRole, persistenceIssueSchema, presentWriteKeys, redirectEntryFromRow, validateForPersistence, } from '@elytracms/core/persistence';
+import { DRAFT_VARIANT, documentKey, documentSchema } from '@elytracms/core/cms-core';
+import { PRESENCE_TTL_MS, RecordNotFoundError, PersistenceValidationError, presenceInputSchema, assetCreateDefaults, assetRecordFromRow, compareReferenceEntries, highestRole, isKnownRole, persistenceIssueSchema, presentWriteKeys, redirectEntryFromRow, validateForPersistence, versionNotPinnableError, } from '@elytracms/core/persistence';
 import { normalizeInviteEmail } from '@elytracms/core/persistence';
-import { queryRef, mutationRef } from './convex-client.js';
+import { createUuidIdFactory } from '@elytracms/core/determinism';
+import { SUBSCRIPTION_UNAUTHENTICATED_MESSAGE, queryRef, mutationRef } from './convex-client.js';
 import { ConvexBlobStorage } from './convex-blob-storage.js';
 const realClock = () => new Date().toISOString();
-function newId(prefix) {
-    const rand = typeof globalThis.crypto?.randomUUID === 'function'
-        ? globalThis.crypto.randomUUID()
-        : Math.abs(Date.parse(new Date().toISOString())).toString(36);
-    return `${prefix}_${rand}`;
-}
-// --- CMS, Assets ----------------------------------------------------------
 /**
- * Deterministic, config-owned schema timestamps (EC-183). CMS collections live
- * in `elytra.config.ts`, not the backend, so the synthesized `CmsSchemaRecord`
- * carries a stable placeholder rather than DB-row timestamps.
+ * EC-578: asset and redirect ids come from the ONE id factory documents and nodes use
+ * (`createUuidIdFactory`, `crypto.getRandomValues`). The old fallback minted a
+ * millisecond timestamp when `crypto.randomUUID` was missing (any non-secure context),
+ * so two writes in one millisecond collided; the factory refuses loudly instead.
  */
-const CONFIG_SCHEMA_TIMESTAMP = '2026-01-01T00:00:00.000Z';
+let mintUuid;
+function newId(prefix) {
+    mintUuid ??= createUuidIdFactory();
+    return `${prefix}_${mintUuid()}`;
+}
 /**
  * Row → contract record. `projectId` is the caller's (the row has none): before
  * EC-577 this copied the row's nonexistent `projectId`, so every connected
@@ -27,6 +26,8 @@ function docRecordFromDoc(doc, projectId) {
     return {
         projectId,
         document: doc.document,
+        variant: doc.variant ?? DRAFT_VARIANT,
+        revision: doc.revision,
         ...(doc.publishedVersion !== undefined ? { publishedVersion: doc.publishedVersion } : {}),
         // EC-447: carry the materialized publish instant onto the contract record so the
         // studio's $publishedAt column + its reconcile read the authoritative value.
@@ -51,66 +52,168 @@ function versionRecordFromDoc(doc, projectId) {
         createdAt: doc.createdAt,
         ...(doc.label ? { label: doc.label } : {}),
         ...(doc.origin ? { origin: doc.origin } : {}),
+        ...(doc.kind ? { kind: doc.kind } : {}),
     };
 }
+/**
+ * The Convex CMS repository — the client half of the revisioned aggregate (EC-595). It
+ * maps the handlers' outcomes onto the provider-neutral contract (a conflict is DATA,
+ * never a throw) and keeps the EC-153 not-found taxonomy client-side. EC-583: documents
+ * only — no schema methods (the collections ride the operations context).
+ */
 class ConvexCmsRepository {
     client;
-    collections;
+    reactive;
     clock;
-    /**
-     * @param collections the active project's config-owned CMS collections
-     *   (EC-183, AD-11), injected from `elytra.config.ts`. The Convex backend has
-     *   no `cmsSchemas` table — `findSchema`/`getSchema` serve these instead.
-     */
-    constructor(client, collections = [], clock = realClock) {
+    constructor(client, reactive, clock = realClock) {
         this.client = client;
-        this.collections = collections;
+        this.reactive = reactive;
         this.clock = clock;
     }
-    async saveSchema(_projectId, _collections) {
-        // Read-only (EC-183, AD-11): the CMS collection schema is owned by
-        // `elytra.config.ts`; the backend stores documents only. A write here is a
-        // visible, structured error rather than a silent no-op (the studio's CMS
-        // schema surfaces are read-only; legitimate writers were removed in EC-183).
-        throw new PersistenceValidationError('CMS collection schema is owned by elytra.config.ts and cannot be written to the backend.', [
-            {
-                code: 'schema-config-owned',
-                message: 'Edit elytra.config.ts to change collections; the backend stores documents only.',
-                path: [],
-                domain: 'cms',
-            },
-        ]);
-    }
-    /** Config-owned schema (EC-183): the active project's collections from config. */
-    configSchema(projectId) {
+    async replaceDocument(projectId, document, precondition, _options) {
+        // A pure document store (EC-183, AD-11): shape-parse only. The actor the patch log
+        // records is the server's authenticated caller, never a client claim.
+        const parsedDoc = documentSchema.parse(document);
+        const result = (await this.client.mutation(mutationRef('cms:replaceDocument'), {
+            collection: parsedDoc.collection,
+            docId: parsedDoc.id,
+            document: parsedDoc,
+            precondition,
+            at: this.clock(),
+        }));
+        if (result.status === 'ok')
+            return { status: 'ok', record: docRecordFromDoc(result.row, projectId) };
         return {
-            projectId,
-            collections: [...this.collections],
-            createdAt: CONFIG_SCHEMA_TIMESTAMP,
-            updatedAt: CONFIG_SCHEMA_TIMESTAMP,
+            status: 'conflict',
+            current: result.current ? docRecordFromDoc(result.current, projectId) : undefined,
+            ...(result.existing ? { existing: docRecordFromDoc(result.existing, projectId) } : {}),
         };
     }
-    async getSchema(projectId) {
-        return this.configSchema(projectId);
+    async patchDocument(projectId, ref, patches, baseRevision, _options) {
+        const result = (await this.client.mutation(mutationRef('cms:patchDocument'), {
+            collection: ref.collection,
+            docId: ref.id,
+            patches: [...patches],
+            baseRevision,
+            at: this.clock(),
+        }));
+        if (result.status === 'missing') {
+            throw new RecordNotFoundError('cms-document', `${projectId}/${documentKey(ref)}`);
+        }
+        const record = docRecordFromDoc(result.row, projectId);
+        return result.status === 'ok'
+            ? { status: 'ok', record }
+            : { status: 'conflict', record, refused: result.refused, appliedCount: result.appliedCount };
     }
-    async findSchema(projectId) {
-        return this.configSchema(projectId);
+    async publishDocument(projectId, ref, expectedRevision, options = {}) {
+        const result = (await this.client.mutation(mutationRef('cms:publishDocument'), {
+            collection: ref.collection,
+            docId: ref.id,
+            expectedRevision,
+            ...(options.label ? { label: options.label } : {}),
+            ...(options.origin ? { origin: options.origin } : {}),
+            at: this.clock(),
+        }));
+        if (result.status === 'missing') {
+            throw new RecordNotFoundError('cms-document', `${projectId}/${documentKey(ref)}`);
+        }
+        if (result.status === 'conflict') {
+            return { status: 'conflict', current: docRecordFromDoc(result.current, projectId) };
+        }
+        return {
+            status: 'ok',
+            record: docRecordFromDoc(result.row, projectId),
+            version: versionRecordFromDoc(result.version, projectId),
+        };
     }
-    async upsertDocument(projectId, document) {
-        // The backend is a pure document store (EC-183, AD-11): collection-membership
-        // validation lives in `@elytracms/core/cms-core` `validateDocument`, which the studio
-        // runs pre-dispatch (cell edits, imports). We still parse the canonical
-        // document shape so malformed blobs never reach storage.
-        const parsedDoc = documentSchema.parse(document);
-        const now = this.clock();
-        const doc = (await this.client.mutation(mutationRef('cms:upsertDocument'), {
-            collection: parsedDoc.collection,
-            docId: parsedDoc.id,
-            document: parsedDoc,
-            createdAt: now,
-            updatedAt: now,
+    async listDocumentPatches(projectId, ref, afterRevision) {
+        const rows = (await this.client.query(queryRef('cms:listDocumentPatches'), {
+            collection: ref.collection,
+            docId: ref.id,
+            ...(afterRevision !== undefined ? { afterRevision } : {}),
+        }));
+        return rows.map((row) => ({
+            projectId,
+            collection: row.collection,
+            docId: row.docId,
+            variant: row.variant,
+            revision: row.revision,
+            kind: row.kind,
+            ...(row.actor !== undefined ? { actor: row.actor } : {}),
+            at: row.at,
+            patches: row.patches,
         }));
-        return docRecordFromDoc(doc, projectId);
+    }
+    /**
+     * EC-595 binding point 7 — the narrow document subscription over the REACTIVE client:
+     * TWO reactive queries behind this one subject — `cms:watchDocument` (the draft row)
+     * and `cms:watchPresence` (its heartbeats) — merged into one snapshot stream, the
+     * first snapshot once both have answered (EC-595 A2: one query re-pushed the whole row
+     * on every heartbeat — measured in `convex/presence-cost.test.ts`). A rejected session
+     * token surfaces as `onError(Unauthenticated …)` — EC-403's session-expired predicate
+     * matches it — never as a silently stopped stream. Without a reactive client the
+     * subscription fails loudly through `onError`.
+     */
+    subscribeDocument(projectId, ref, listener) {
+        if (!this.reactive) {
+            listener.onError?.(new Error('subscribeDocument: this Convex adapter was built without a reactive client.'));
+            return () => { };
+        }
+        const reactive = this.reactive();
+        const args = { collection: ref.collection, docId: ref.id };
+        let row;
+        let presence;
+        // One failure (a dropped socket, an expired token) reaches BOTH queries: report it
+        // once, until a query answers again.
+        let reported;
+        const fail = (error) => {
+            if (reported === error.message)
+                return;
+            reported = error.message;
+            listener.onError?.(error);
+        };
+        const emit = () => {
+            reported = undefined;
+            if (row === undefined || presence === undefined)
+                return;
+            listener.onSnapshot({
+                record: row.value ? docRecordFromDoc(row.value, projectId) : undefined,
+                presence,
+            });
+        };
+        const unsubscribeRow = reactive.onUpdate(queryRef('cms:watchDocument'), args, (value) => {
+            row = { value: value.row };
+            emit();
+        }, fail);
+        const unsubscribePresence = reactive.onUpdate(queryRef('cms:watchPresence'), args, (value) => {
+            presence = value;
+            emit();
+        }, fail);
+        const unhookAuth = reactive.onAuthLost(() => fail(new Error(SUBSCRIPTION_UNAUTHENTICATED_MESSAGE)));
+        return () => {
+            unhookAuth();
+            unsubscribeRow();
+            unsubscribePresence();
+        };
+    }
+    async reportPresence(projectId, ref, presence) {
+        const parsed = presenceInputSchema.parse(presence);
+        await this.client.mutation(mutationRef('cms:reportPresence'), {
+            collection: ref.collection,
+            docId: ref.id,
+            sessionId: parsed.sessionId,
+            ...(parsed.actorName !== undefined ? { actorName: parsed.actorName } : {}),
+            ...(parsed.path !== undefined ? { path: parsed.path } : {}),
+            at: this.clock(),
+            ttlMs: PRESENCE_TTL_MS,
+        });
+    }
+    async clearPresence(projectId, ref, sessionId) {
+        await this.client.mutation(mutationRef('cms:clearPresence'), {
+            collection: ref.collection,
+            docId: ref.id,
+            sessionId,
+        });
     }
     async getDocument(projectId, ref) {
         const found = await this.findDocument(projectId, ref);
@@ -193,22 +296,28 @@ class ConvexCmsRepository {
         return versionRecordFromDoc(doc, projectId);
     }
     async publishDocumentVersion(projectId, ref, version) {
-        // Taxonomy enforced adapter-side (the handler is lenient): the document and
-        // the pinned version must both exist (each throws RecordNotFoundError).
-        await this.getDocument(projectId, ref);
-        await this.getDocumentVersion(projectId, ref, version);
-        // EC-447: pass a fresh publish-action instant as the SET-ONCE candidate (the
-        // handler writes it only when the row has no `publishedAt` yet). One `now` for
-        // both stamps — this IS the publish moment.
+        // EC-595: pin integrity is enforced IN the transaction (the version must exist for
+        // this document); the outcomes map onto the EC-153 not-found taxonomy here. EC-447:
+        // one `now` for both stamps — the publish-action instant is the SET-ONCE candidate.
         const now = this.clock();
-        const doc = (await this.client.mutation(mutationRef('cms:publishDocumentVersion'), {
+        const result = (await this.client.mutation(mutationRef('cms:publishDocumentVersion'), {
             collection: ref.collection,
             docId: ref.id,
             version,
             updatedAt: now,
             publishedAt: now,
         }));
-        return docRecordFromDoc(doc, projectId);
+        if (result.status === 'missing') {
+            throw new RecordNotFoundError('cms-document', `${projectId}/${documentKey(ref)}`);
+        }
+        if (result.status === 'missing-version') {
+            throw new RecordNotFoundError('cms-document-version', `${projectId}/${documentKey(ref)}#${version}`);
+        }
+        // EC-585: the version was recorded by a snapshot, never by a publish — the same
+        // refusal the in-memory store raises.
+        if (result.status === 'not-pinnable')
+            throw versionNotPinnableError(`${projectId}/${documentKey(ref)}`, version);
+        return docRecordFromDoc(result.row, projectId);
     }
     async unpublishDocument(projectId, ref) {
         const existing = await this.getDocument(projectId, ref);
@@ -715,13 +824,19 @@ export class ConvexPersistenceAdapter {
      * @param client      the Convex client bound to this deployment (one project).
      * @param projectId   the slug of this deployment's one project (EC-179). Used to
      *   stamp deployment-scoped member records onto the still-project-keyed contract.
-     * @param collections the active project's config-owned CMS collections (EC-183,
-     *   AD-11), from `elytra.config.ts`. The backend has no `cmsSchemas` table, so
-     *   the CMS repository serves the schema from these.
+     *
+     * @param options.reactive the reactive client a document subscription runs on (EC-595),
+     *   built lazily — the studio passes `() => getReactiveConvexClient(url)`. Absent (a
+     *   seed script, a test double without push), `subscribeDocument` fails loudly.
+     *
+     * EC-583: the third argument is no longer the collections. They only fed the
+     * synthesized schema record (`getSchema`/`findSchema`), which the contract no longer
+     * has — collections reach the operations layer on its context
+     * (`createOperations({ collections })`).
      */
-    constructor(client, projectId, collections = []) {
+    constructor(client, projectId, options = {}) {
         this.client = client;
-        this.cms = new ConvexCmsRepository(client, collections);
+        this.cms = new ConvexCmsRepository(client, options.reactive);
         this.assets = new ConvexAssetRepository(client);
         this.references = new ConvexReferenceIndexRepository(client);
         this.members = new ConvexMembersRepository(client, projectId);