@elytracms/studio 0.0.98 → 0.0.100

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

@@ -1,6 +1,6 @@
-import { ConvexError } from 'convex/values';
+import { ConvexError, convexToJson } from 'convex/values';
 import { DRAFT_VARIANT, documentKey, documentSchema } from '@elytracms/core/cms-core';
-import { PRESENCE_TTL_MS, RecordNotFoundError, PersistenceValidationError, RevisionPreconditionError, StrictReferencePreconditionError, presenceInputSchema, assetCreateDefaults, assetRecordFromRow, compareReferenceEntries, persistenceIssueSchema, presentWriteKeys, recordEntryFromWire, validateForPersistence, versionNotPinnableError, } from '@elytracms/core/persistence';
+import { BackendUnavailableError, PRESENCE_TTL_MS, RecordNotFoundError, PersistenceValidationError, RevisionPreconditionError, StrictReferencePreconditionError, presenceInputSchema, assetCreateDefaults, assetRecordFromRow, compareReferenceEntries, isPersistenceError, persistenceIssueSchema, presentWriteKeys, recordEntryFromWire, rejectedWriteMessage, validateForPersistence, versionNotPinnableError, } from '@elytracms/core/persistence';
 import { normalizeInviteEmail } from '@elytracms/core/persistence';
 import { createUuidIdFactory } from '@elytracms/core/determinism';
 import { SUBSCRIPTION_UNAUTHENTICATED_MESSAGE, queryRef, mutationRef } from './convex-client.js';
@@ -17,6 +17,104 @@ function newId(prefix) {
     mintUuid ??= createUuidIdFactory();
     return `${prefix}_${mintUuid()}`;
 }
+/**
+ * EC-686 — what a Convex call's promise rejects with, classified by WHO failed (the binding
+ * rule, wave-0100). `convex/browser` (1.42.1, `http_client.js`) rejects with a raw
+ * `TypeError` for a fetch rejection, with `Error(<body text>)` for any non-OK status (the
+ * status discarded), and with the function's `Error(message)` or `ConvexError` for a
+ * function failure: none of them says whether the store JUDGED the write. So a validation
+ * verdict the engine throws on purpose and this adapter maps ({@link asRailWriteError}) is
+ * that error, and anything else is a {@link BackendUnavailableError} carrying the original
+ * message (an expired session is read from it — `isSessionExpiredError`): the session
+ * keeps the write and re-sends it (`keepsFailedWrite`, EC-674). An `unknown` is then only
+ * ever a failure in THIS process, which the same input repeats.
+ */
+function backendFailure(error) {
+    const mapped = asRailWriteError(error);
+    if (isPersistenceError(mapped))
+        return mapped;
+    return new BackendUnavailableError(error instanceof Error ? error.message : String(error), { cause: error });
+}
+/**
+ * EC-686 — the client's calls with their promise classified ({@link backendFailure}), the
+ * one seam every repository calls through: never a whole adapter method, so a crash of
+ * this process before or after the call (a parse, a row mapping) stays `unknown`. The
+ * arguments are serialised for the wire here first (`convexToJson`, the client's own
+ * conversion): a value Convex cannot carry (a `$`-prefixed or non-ASCII key) fails in this
+ * process, never inside the call — it is the input, not the backend. The shared client
+ * itself is never patched (`lib/auth/**` reads its errors as they are).
+ */
+function judgedCalls(client) {
+    const judged = (args, call) => {
+        convexToJson(args);
+        return call().catch((error) => {
+            throw backendFailure(error);
+        });
+    };
+    return {
+        query: ((ref, args = {}) => judged(args, () => client.query(ref, args))),
+        mutation: ((ref, args = {}) => judged(args, () => client.mutation(ref, args))),
+    };
+}
+/** Issue code: a record write holding a value the Convex wire cannot carry (EC-702). */
+export const UNCARRIABLE_VALUE = 'uncarriable-value';
+/** Why Convex cannot carry `value` (its own conversion's reason, without the echoed object), or `undefined`. */
+function wireRefusal(value) {
+    try {
+        convexToJson(value);
+        return undefined;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return message.split(' (present at path')[0].split(' To learn about')[0].trim();
+    }
+}
+/**
+ * EC-702 — the located refusals of a record write's values the Convex wire cannot carry: a
+ * `Date`, a `Map`, a class instance, an `undefined` in a list, a `$`-prefixed or non-ASCII key.
+ * The judge is Convex's own conversion (`convexToJson`, the one {@link judgedCalls} runs on every
+ * call's arguments), run per column so the refusal names the column — and, below it, the deepest
+ * value or key that fails. The in-memory store refuses the same write located, by the column's
+ * own schema; without this the Convex path threw an unlocated `Error` in this process
+ * (`unknown`). Before EC-702 the operations' step 1 located it, by running the column schemas a
+ * second time.
+ */
+function uncarriableIssues(write) {
+    const issues = [];
+    for (const [column, value] of Object.entries(write)) {
+        const found = uncarriableAt(value, [column]);
+        if (found) {
+            issues.push({
+                code: UNCARRIABLE_VALUE,
+                message: `The Convex store cannot carry this value: ${found.reason}`,
+                path: found.path,
+                domain: 'persistence',
+            });
+        }
+    }
+    return issues;
+}
+function uncarriableAt(value, path) {
+    const reason = wireRefusal(value);
+    if (reason === undefined)
+        return undefined;
+    const plain = typeof value === 'object' &&
+        value !== null &&
+        (Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+    if (plain) {
+        for (const [key, item] of Object.entries(value)) {
+            const segment = Array.isArray(value) ? Number(key) : key;
+            // A key Convex refuses is the refusal itself, wherever its value is fine.
+            const keyReason = Array.isArray(value) ? undefined : wireRefusal({ [key]: null });
+            if (keyReason !== undefined)
+                return { path: [...path, segment], reason: keyReason };
+            const inner = uncarriableAt(item, [...path, segment]);
+            if (inner)
+                return inner;
+        }
+    }
+    return { path, reason };
+}
 /**
  * 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
@@ -411,11 +509,12 @@ class ConvexCmsRepository {
     }
 }
 /**
- * A rail write the handler rejected (EC-577): `resolveRecordWrite` found the write
- * invalid inside the transaction and threw a `validation` `ConvexError` — mapped
- * back onto the provider-neutral {@link PersistenceValidationError} the in-memory
- * adapter throws for the same write. `ConvexError` data survives a production
- * deployment's error redaction, unlike a plain thrown message.
+ * A write the handler rejected (EC-577): `resolveRecordWrite` (a rail or record write) or
+ * the asset upsert found the write invalid inside the transaction and threw a `validation`
+ * `ConvexError` — mapped back onto the provider-neutral {@link PersistenceValidationError}
+ * the in-memory adapter throws for the same write. `ConvexError` data survives a production
+ * deployment's error redaction, unlike a plain thrown message. EC-686: read by
+ * {@link backendFailure} for every call, so no call site maps it itself.
  */
 function asRailWriteError(error) {
     if (!(error instanceof ConvexError))
@@ -440,16 +539,12 @@ class ConvexAssetRepository {
         // EC-577: send the write as written — absent keys stay absent (keep), `null`
         // crosses the wire as the clear. The handler resolves it against the stored
         // row inside the transaction; the create defaults ride along for a create.
-        const doc = (await this.client
-            .mutation(mutationRef('assets:upsert'), {
+        const doc = (await this.client.mutation(mutationRef('assets:upsert'), {
             assetId: id,
             ...presentWriteKeys(write),
             defaults: assetCreateDefaults(projectId, id),
             createdAt: now,
             updatedAt: now,
-        })
-            .catch((error) => {
-            throw asRailWriteError(error);
         }));
         return assetRecordFromRow(doc, projectId);
     }
@@ -826,11 +921,7 @@ class ConvexRecordRepository {
         return `${this.kind.module}:${fn}`;
     }
     async list(projectId, query = {}) {
-        const rows = (await this.client
-            .query(queryRef(this.ref('list')), presentWriteKeys({ ...query }))
-            .catch((error) => {
-            throw asRailWriteError(error);
-        }));
+        const rows = (await this.client.query(queryRef(this.ref('list')), presentWriteKeys({ ...query })));
         return rows.map((row) => recordEntryFromWire(this.kind, row, projectId));
     }
     async get(projectId, id) {
@@ -849,15 +940,17 @@ class ConvexRecordRepository {
         const now = this.clock();
         const { id: givenId, ...write } = input;
         const id = givenId ?? newId(this.kind.idPrefix);
-        const row = (await this.client
-            .mutation(mutationRef(this.ref('save')), {
+        const sent = presentWriteKeys(write);
+        // EC-702: a value the wire cannot carry is the write's located refusal, as in memory.
+        const uncarriable = uncarriableIssues(sent);
+        if (uncarriable.length > 0) {
+            throw new PersistenceValidationError(rejectedWriteMessage(this.kind.kind, id, uncarriable), uncarriable);
+        }
+        const row = (await this.client.mutation(mutationRef(this.ref('save')), {
             [this.kind.idKey]: id,
-            ...presentWriteKeys(write),
+            ...sent,
             createdAt: now,
             updatedAt: now,
-        })
-            .catch((error) => {
-            throw asRailWriteError(error);
         }));
         return recordEntryFromWire(this.kind, row, projectId);
     }
@@ -931,23 +1024,26 @@ export class ConvexPersistenceAdapter {
      */
     constructor(client, projectId, options = {}) {
         this.client = client;
-        this.cms = new ConvexCmsRepository(client, options.reactive);
-        this.assets = new ConvexAssetRepository(client);
-        this.references = new ConvexReferenceIndexRepository(client);
-        this.members = new ConvexMembersRepository(client, projectId);
-        this.users = new ConvexUserRepository(client);
-        this.invites = new ConvexInviteRepository(client);
+        // EC-686: every repository calls through the classified calls; the probe below and the
+        // blob boundary (its own failure handling) keep the client as it is.
+        const calls = judgedCalls(client);
+        this.cms = new ConvexCmsRepository(calls, options.reactive);
+        this.assets = new ConvexAssetRepository(calls);
+        this.references = new ConvexReferenceIndexRepository(calls);
+        this.members = new ConvexMembersRepository(calls, projectId);
+        this.users = new ConvexUserRepository(calls);
+        this.invites = new ConvexInviteRepository(calls);
         const recordRepositories = new Map();
         this.records = (kind) => {
             let repository = recordRepositories.get(kind);
             if (!repository) {
-                repository = new ConvexRecordRepository(client, kind);
+                repository = new ConvexRecordRepository(calls, kind);
                 recordRepositories.set(kind, repository);
             }
             return repository;
         };
         this.blobs = new ConvexBlobStorage(client);
-        this.delivery = new ConvexDeliveryRepository(client);
+        this.delivery = new ConvexDeliveryRepository(calls);
     }
     async status() {
         try {