@elytracms/studio 0.0.97 → 0.0.98

package/convex/ingest.ts

@@ -1,5 +1,5 @@
 import { httpActionGeneric, makeFunctionReference } from 'convex/server'
-import type { FunctionReference, PublicHttpAction } from 'convex/server'
+import type { FunctionReference, GenericActionCtx, GenericDataModel, PublicHttpAction } from 'convex/server'
 import { v } from 'convex/values'
 import type { GenericId } from 'convex/values'
 import { z } from 'zod'
@@ -7,7 +7,9 @@ import {
   INGEST_MAX_BODY_BYTES,
   INGEST_MAX_UPLOAD_BYTES,
   INGEST_SIGNATURE_HEADER,
+  INGEST_UPLOAD_SHA256,
   INGEST_UPLOAD_TTL_MS,
+  compareIngestUploadSha256,
   ingestPayloadSchema,
   readIngestReceiverBody,
   verifyIngestSignature,
@@ -40,22 +42,29 @@ import { findRecordDoc, listRecordWire, saveRecord } from './record-functions'
  * 7. an accepted `upload` gets ONE short-lived storage URL (`ctx.storage.generateUploadUrl`)
  *    — the bytes go browser → storage, cross-origin by design; the submission that follows
  *    claims the stored file with {@link claimIngestUpload}, which checks that the deployment
- *    stored it for THIS intent (EC-671) and that it matches what the upload request declared,
- *    and binds it; {@link releaseIngestUploads} is the only way such bytes are deleted.
+ *    stored it for THIS intent (EC-671) — its bytes the ones the upload request declared by
+ *    SHA-256 (EC-685) — and that it matches the declared size and type, and binds it;
+ *    {@link releaseIngestUploads} is the only way such bytes are deleted.
  *
  * The engine never imports an addon: the handler is an internal-mutation REFERENCE the
  * consumer passes in its one `http.ts` line (`defineStudioHttp({ auth, ingest: {
  * submission: formsIngest } })`), exported by the addon's `./convex` entry.
  */
 
-/** What an ingest handler receives: the verified, parsed payload and the receipt time. */
-export const ingestHandlerArgs = { payload: v.any(), receivedAt: v.string() }
+/**
+ * What an ingest handler receives: the verified, parsed payload, the receipt time, and — only
+ * when the receiver RETRIES the request (EC-618) — which attempt this is. `attempt` is absent on
+ * the first run (so a handler declared with the first two arguments alone runs unchanged) and
+ * `2…INGEST_HANDLER_ATTEMPTS` on a retry; the payload and `receivedAt` are the same on every
+ * attempt. A handler that does not care ignores it.
+ */
+export const ingestHandlerArgs = { payload: v.any(), receivedAt: v.string(), attempt: v.optional(v.number()) }
 
 /** An addon's ingest handler: an INTERNAL mutation (never client-callable). */
 export type IngestHandlerRef = FunctionReference<
   'mutation',
   'internal',
-  { payload: IngestPayload; receivedAt: string },
+  { payload: IngestPayload; receivedAt: string; attempt?: number },
   IngestHandlerResult
 >
 
@@ -97,6 +106,32 @@ function utf8Length(text: string): number {
   return new TextEncoder().encode(text).byteLength
 }
 
+/**
+ * How many times the receiver runs a handler whose mutation THREW before the failure surfaces
+ * (EC-618). A Convex mutation cannot observe its own optimistic-concurrency conflict — Convex
+ * re-executes it and reports exhaustion only to the caller, this `runMutation` — so the receiver
+ * is where a request gets another attempt (`attempt: 2, 3` — see {@link ingestHandlerArgs}).
+ * A thrown mutation committed nothing, so a retry never counts twice. A handler's REFUSAL
+ * (`{ ok: false }`) is an answer, never retried.
+ */
+export const INGEST_HANDLER_ATTEMPTS = 3
+
+async function runIngestHandler(
+  ctx: Pick<GenericActionCtx<GenericDataModel>, 'runMutation'>,
+  handler: IngestHandlerRef,
+  payload: IngestPayload,
+  receivedAt: string,
+): Promise<IngestHandlerResult> {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      // Attempt 1 passes exactly the two arguments every handler has always received.
+      return await ctx.runMutation(handler, attempt === 1 ? { payload, receivedAt } : { payload, receivedAt, attempt })
+    } catch (error) {
+      if (attempt >= INGEST_HANDLER_ATTEMPTS) throw error
+    }
+  }
+}
+
 /** The receiver `httpAction` (see the module header). */
 export function ingestReceiver(handlers: IngestHandlers = {}): PublicHttpAction {
   return httpActionGeneric(async (ctx, request) => {
@@ -127,7 +162,7 @@ export function ingestReceiver(handlers: IngestHandlers = {}): PublicHttpAction
         handled: false,
       })
     }
-    const result = await ctx.runMutation(handler, { payload: body, receivedAt: new Date().toISOString() })
+    const result = await runIngestHandler(ctx, handler, body, new Date().toISOString())
     if (!result.ok) {
       return json(result.status, { error: result.message, ...(result.issues ? { issues: result.issues } : {}) })
     }
@@ -159,6 +194,13 @@ export function ingestReceiver(handlers: IngestHandlers = {}): PublicHttpAction
 // file only when the deployment's own facts say it is this upload's ({@link claimIngestUpload}),
 // it never deletes, and ingest bytes are deleted only through {@link releaseIngestUploads},
 // which deletes only what a claim bound.
+//
+// EC-685 — causation. Eligibility (stored after the intent, unbound, no asset's) is not
+// ownership: with intents A and B open, bytes stored through B's URL were eligible for A. So
+// the intent DECLARES the bytes' SHA-256 before they exist, and the claim requires the digest
+// the deployment computed at store time (`_storage.sha256`) to equal it — A can bind B's bytes
+// only by predicting them. Ownership is also kept true when a delete spends it: release keeps
+// a bound file an asset references now, and `assets:deleteBlob` keeps bytes a binding holds.
 
 /** The upload intent — an engine-internal record kind (no public functions). */
 export const ingestUploadRecordKind = defineRecordKind({
@@ -171,6 +213,8 @@ export const ingestUploadRecordKind = defineRecordKind({
     field: z.string().min(1),
     contentType: z.string().min(1),
     size: z.number().int().positive(),
+    /** EC-685: the SHA-256 the upload declared for its bytes (lowercase hex) — what makes the claim causal. */
+    sha256: z.string().regex(INGEST_UPLOAD_SHA256),
     state: z.enum(['issued', 'claimed', 'rejected']),
     issuedAt: z.string().min(1),
     /** The id the intent's claim NAMED (claimed or rejected) — what was asked, not what is owned. */
@@ -240,7 +284,13 @@ export async function recordIngestUpload(
 }
 
 function payloadColumns(payload: Extract<IngestPayload, { kind: 'upload' }>) {
-  return { target: payload.target, field: payload.field, contentType: payload.contentType, size: payload.size }
+  return {
+    target: payload.target,
+    field: payload.field,
+    contentType: payload.contentType,
+    size: payload.size,
+    sha256: payload.sha256,
+  }
 }
 
 /** What a claim yields: the stored file's facts, or a refusal for the handler to return. */
@@ -259,18 +309,30 @@ export type IngestUploadClaimResult =
  *    before the intent would compare equal);
  * 2. no claim bound it already ({@link ingestBindingRecordKind});
  * 3. no asset row references it — `storageKey` or `thumb.storageKey` (an asset's storage id is
- *    public on the delivery snapshot the moment its row exists).
+ *    public on the delivery snapshot the moment its row exists);
+ * 4. EC-685: its bytes are the ones the intent DECLARED — the digest the deployment computed
+ *    when it stored them (`_storage.sha256`) equals the intent's `sha256`, through the ONE
+ *    comparator (`compareIngestUploadSha256`, which reads the stored digest by its form). Checks
+ *    1–3 are eligibility; this one is causation: with intents A and B open, bytes stored
+ *    through B's URL pass 1–3 for A too, and fail 4 unless A predicted them.
+ *
+ * A stored digest in neither form (`unreadable`) is its own answer — a deployment fault, the
+ * same for every file, refused visibly and never read as a match. It is read first, so it
+ * says nothing about which ownership check a named file would fail.
  *
  * Hiding `storageKey` would not be ownership; these are.
  */
 async function claimableFile(
   ctx: MutationCtx,
-  file: { _id: GenericId<'_storage'>; _creationTime: number },
-  intentCreatedAt: number,
-): Promise<boolean> {
-  if (file._creationTime < intentCreatedAt) return false
-  if (await findRecordDoc(ctx, ingestBindingRecordKind, file._id)) return false
-  return !(await assetReferencesStorage(ctx, file._id))
+  file: { _id: GenericId<'_storage'>; _creationTime: number; sha256: string },
+  intent: { createdAt: number; sha256: string },
+): Promise<'claimable' | 'not-this-intent' | 'digest-unreadable'> {
+  const digest = compareIngestUploadSha256(intent.sha256, file.sha256)
+  if (digest === 'unreadable') return 'digest-unreadable'
+  if (file._creationTime < intent.createdAt) return 'not-this-intent'
+  if (await findRecordDoc(ctx, ingestBindingRecordKind, file._id)) return 'not-this-intent'
+  if (await assetReferencesStorage(ctx, file._id)) return 'not-this-intent'
+  return digest === 'same' ? 'claimable' : 'not-this-intent'
 }
 
 /** Check (3): does any asset row reference these bytes, as its file or its preview (`thumb`)? */
@@ -290,7 +352,8 @@ async function assetReferencesStorage(ctx: MutationCtx, storageId: string): Prom
 /**
  * Claim one upload for a submission to `target`: the intent must exist, be unclaimed,
  * belong to `target`, be younger than `INGEST_UPLOAD_TTL_MS`; the stored file must be this
- * intent's ({@link claimableFile}, EC-671) and match it (size ≤ declared, same content type).
+ * intent's ({@link claimableFile}, EC-671 + EC-685: its bytes the declared ones) and match it
+ * (size ≤ declared, same content type).
  * A claimed file is BOUND to the intent ({@link ingestBindingRecordKind}) — the fact every
  * deletion reads ({@link releaseIngestUploads}).
  *
@@ -307,7 +370,7 @@ export async function claimIngestUpload(
 ): Promise<IngestUploadClaimResult> {
   const intent = await findRecordDoc(ctx, ingestUploadRecordKind, claim.uploadId)
   const columns = intent?.data as
-    | { target: string; field: string; contentType: string; size: number; state: string; issuedAt: string }
+    | { target: string; field: string; contentType: string; size: number; sha256?: string; state: string; issuedAt: string }
     | undefined
   if (!intent || !columns || columns.target !== target) {
     return { ok: false, status: 422, message: `Unknown upload “${claim.uploadId}”.` }
@@ -316,6 +379,22 @@ export async function claimIngestUpload(
   if (Date.parse(receivedAt) - Date.parse(columns.issuedAt) > INGEST_UPLOAD_TTL_MS) {
     return { ok: false, status: 422, message: `Upload “${claim.uploadId}” expired.` }
   }
+  // LEGACY (marked, EC-685): an intent issued before uploads declared their digest cannot be
+  // checked for causation. It is refused with its own reason, BEFORE any write: its row lacks
+  // the column the kind now requires, and whether the record rule accepts a write onto such a
+  // row is the record store's business (measured on 6310b7b4: it does; EC-682 rewrites that
+  // validator) — this branch never asks. Without it the claim would still be refused (the
+  // digest compares `different`), under the generic answer. Such intents are claimable for at
+  // most INGEST_UPLOAD_TTL_MS after the deploy (the expiry above refuses them first
+  // afterwards); delete this branch one release after EC-685 shipped.
+  const declared = columns.sha256
+  if (typeof declared !== 'string') {
+    return {
+      ok: false,
+      status: 422,
+      message: `Upload “${claim.uploadId}” was issued before uploads declared their SHA-256 — upload the file again.`,
+    }
+  }
   const storageId = claim.storageId as GenericId<'_storage'>
   const file = await ctx.db.system.get(storageId).catch(() => null)
   const stamps = { createdAt: receivedAt, updatedAt: receivedAt }
@@ -325,8 +404,17 @@ export async function claimIngestUpload(
     return { ok: false, ...refusal }
   }
   const intentRow = await ctx.db.get(intent._id)
-  if (!intentRow || !(await claimableFile(ctx, file, intentRow._creationTime))) {
-    // One answer for all three checks: which one failed is not the visitor's to learn.
+  const verdict = intentRow
+    ? await claimableFile(ctx, file, { createdAt: intentRow._creationTime, sha256: declared })
+    : 'not-this-intent'
+  if (verdict === 'digest-unreadable') {
+    return reject({
+      status: 422,
+      message: `The deployment's stored digest of “${claim.storageId}” is in neither form the claim reads (64 hex or 44 base64 characters), so the upload cannot be verified.`,
+    })
+  }
+  if (verdict !== 'claimable') {
+    // One answer for all four checks: which one failed is not the visitor's to learn.
     return reject({ status: 422, message: `Upload “${claim.uploadId}” did not store the file “${claim.storageId}”.` })
   }
   if (file.size > columns.size) return reject({ status: 413, message: 'The stored file is larger than the upload declared.' })
@@ -342,10 +430,21 @@ export async function claimIngestUpload(
 
 /**
  * Delete ingest bytes an addon holds (EC-671) — the ONE way they are deleted, and it deletes
- * only files a claim BOUND: the bytes and their binding go together. Any other id is KEPT and
- * returned in `kept` — an asset's, an id a write put into a row by hand, a file claimed before
- * bindings existed — because ingest cannot show it owns them. Call it for a refused
- * submission's already-claimed files and when removing a row that holds claimed files.
+ * only files a claim BOUND that no asset references NOW: the bytes and their binding go
+ * together. Any other id is KEPT and returned in `kept`:
+ *
+ * - an id with no binding — an asset's, an id a write put into a row by hand, a file claimed
+ *   before bindings existed — because ingest cannot show it owns them;
+ * - EC-685: a bound file an asset row references now (`storageKey` or `thumb.storageKey` — an
+ *   editor promoted the upload to an asset with `assets:upsert`, a legitimate edit). Ownership
+ *   has passed to the asset: the binding is spent (deleted) and the bytes stay, so the
+ *   asset's own delete removes them later. Read in this transaction, so no asset can acquire
+ *   the file between the check and the delete.
+ *
+ * Call it for a refused submission's already-claimed files and when removing a row that holds
+ * claimed files. The mirror is `assets:deleteBlob`, which keeps bytes a binding holds
+ * ({@link ingestBindingHolds}): each delete path re-checks the OTHER owner in its own
+ * transaction.
  */
 export async function releaseIngestUploads(
   ctx: MutationCtx,
@@ -359,14 +458,27 @@ export async function releaseIngestUploads(
       kept.push(storageId)
       continue
     }
+    await ctx.db.delete(binding._id)
+    if (await assetReferencesStorage(ctx, storageId)) {
+      kept.push(storageId) // the asset owns the bytes now (EC-685)
+      continue
+    }
     const id = storageId as GenericId<'_storage'>
     if (await ctx.db.system.get(id).catch(() => null)) await ctx.storage.delete(id)
-    await ctx.db.delete(binding._id)
     deleted.push(storageId)
   }
   return { deleted, kept }
 }
 
+/**
+ * EC-685 — does an ingest binding hold these bytes (a claimed upload a submission still owns)?
+ * The one reader `assets:deleteBlob` asks before it deletes stored bytes, so an asset an
+ * editor created over a submission's file never takes the submission's bytes with it.
+ */
+export async function ingestBindingHolds(ctx: QueryCtx | MutationCtx, storageId: string): Promise<boolean> {
+  return (await findRecordDoc(ctx, ingestBindingRecordKind, storageId)) !== null
+}
+
 /** Upload intents of `target` still unclaimed past their life — the visible orphan finding. */
 export async function unclaimedIngestUploads(
   ctx: QueryCtx | MutationCtx,

package/convex/prototype-key.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import type { FunctionReference } from 'convex/server'
+import type { CmsDocument, CollectionDef } from '@elytracms/core/cms-core'
+import { createOperations } from '@elytracms/core/operations'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import schema from './schema'
+
+/**
+ * EC-684 (Codex round 4, F27) — the `convex-parity` measurement the refusal rests on, and the refusal
+ * itself over the production `ConvexPersistenceAdapter` (its client a call-through onto convex-test's
+ * REAL `cms.ts` mutations — the wiring of `depth-codec-lookalike.test.ts`).
+ *
+ * 1. Re-measured (Codex measured it in `codec-own-keys.convex.test.ts`): the Convex value converters
+ *    rebuild objects by assignment (`convex/src/values/value.ts` `jsonToConvex` / `convexToJsonInternal`),
+ *    so an own `__proto__` key written straight through the adapter — past the operations layer — is
+ *    lost before any sink, at the top level of `values` and nested. The known-positive control: an
+ *    ordinary own key on the same path survives, so the instrument CAN see a key survive.
+ * 2. So the in-memory store keeping the key would be drift; the operations layer refuses it on the raw
+ *    input, located, in this store too, and nothing is written.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+const P = 'site'
+const ADMIN = 'user_admin'
+const AT = '2026-10-28T12:00:00.000Z'
+
+const collections: CollectionDef[] = [
+  { id: 'post', kind: 'document', fields: [{ name: 'payload', type: 'object', multiple: false, fields: [] }] },
+]
+
+interface Backend {
+  query: (ref: FunctionReference<'query'>, args: Record<string, unknown>) => Promise<unknown>
+  mutation: (ref: FunctionReference<'mutation'>, args: Record<string, unknown>) => Promise<unknown>
+}
+
+function asAdapterClient(backend: Backend): ConvexHttpClient {
+  return {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => backend.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => backend.mutation(ref, args ?? {}),
+  } as unknown as ConvexHttpClient
+}
+
+async function harness() {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: ADMIN, role: 'admin', createdAt: AT, updatedAt: AT })
+  })
+  const adapter = new ConvexPersistenceAdapter(asAdapterClient(t.withIdentity({ subject: ADMIN, issuer: 'https://convex.test' })), P)
+  const ops = createOperations({ adapter, collections: () => collections, validateDocument: () => [] })
+  const rows = async () => t.run(async (ctx) => (await ctx.db.query('cmsDocuments').collect()).map((row) => row.docId))
+  return { adapter, ops, rows }
+}
+
+const parse = <T = Record<string, unknown>>(json: string): T => JSON.parse(json) as T
+const ownProto = (value: unknown) => typeof value === 'object' && value !== null && Object.hasOwn(value, '__proto__')
+
+describe('EC-684 on Convex — an own `__proto__` key', () => {
+  it('re-measured: written straight through the adapter (past operations), Convex loses it before the sink — CONTROL: an ordinary own key survives', async () => {
+    const { adapter } = await harness()
+    const document = parse<CmsDocument>('{"collection":"post","id":"direct","values":{"__proto__":{"text":"TOP"},"payload":{"__proto__":{"text":"NESTED"},"ordinary":{"text":"KEEP"}}}}')
+    expect(ownProto(document.values)).toBe(true)
+    expect(ownProto(document.values.payload)).toBe(true)
+    await adapter.cms.replaceDocument(P, document, { ifAbsent: true })
+    const stored = (await adapter.cms.getDocument(P, { collection: 'post', id: 'direct' })).document
+    expect((stored.values.payload as Record<string, unknown>).ordinary).toEqual({ text: 'KEEP' })
+    expect(ownProto(stored.values)).toBe(false)
+    expect(ownProto(stored.values.payload)).toBe(false)
+  })
+
+  it('through the operations layer it is refused on the raw input, located — and nothing reaches the store', async () => {
+    const { ops, rows } = await harness()
+    const values = parse('{"__proto__":{"text":"TOP"},"payload":{"__proto__":{"text":"NESTED"}}}')
+    const result = await ops.documents.replace({ projectId: P, document: { collection: 'post', id: 'refused', values }, precondition: { ifAbsent: true } })
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.error.code).toBe('validation')
+    expect(result.error.code === 'validation' ? result.error.issues.map((issue) => [issue.code, issue.path]) : []).toEqual([
+      ['prototype-key', ['document', 'values', '__proto__']],
+      ['prototype-key', ['document', 'values', 'payload', '__proto__']],
+    ])
+    expect(await rows()).toEqual([])
+    // CONTROL: the same write without the key goes through.
+    const plain = await ops.documents.replace({ projectId: P, document: { collection: 'post', id: 'plain', values: { payload: { text: 'x' } } }, precondition: { ifAbsent: true } })
+    expect(plain.ok).toBe(true)
+    expect(await rows()).toEqual(['plain'])
+  })
+})

package/convex/records-zod-refinements.convex.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { z } from 'zod'
+import { z as newerZod } from 'zod-copy-newer'
+import { z as olderZod } from 'zod-copy-older'
+import { defineRecordKind } from '@elytracms/core/persistence'
+import type { AnyRecordKind, RecordColumnSchema } from '@elytracms/core/persistence'
+import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
+
+/**
+ * EC-682 (Codex round 4 F24, a regression of 0.0.97) — the generated Convex record functions
+ * (`defineRecordFunctions(kind).save` → `saveRecord` → `resolveRecordSave`, in the transaction)
+ * for a kind whose column carries a refinement on its `.optional()` / `.default()` WRAPPER and
+ * comes from another zod release than the engine's. Measured before: the adoption judged only
+ * the wrapper's `innerType`, so `'forbidden'` — refused by the column's own `safeParse` — was
+ * STORED (create and edit). Now a supplied value is judged by the whole column; the engine's own
+ * copy is the control row (composed as it is, refused before too). `zod-copy-older` (4.1.13) and
+ * `zod-copy-newer` (4.6.7) are real second copies (aliased devDependencies), not mocks.
+ */
+
+const MESSAGE = 'forbidden value'
+const notForbidden = (value: string | undefined) => value !== 'forbidden'
+
+// The copies' builders differ only in their TYPES (EC-639 owns those); the runtime is the subject here.
+type Vendor = typeof z
+const COPIES = [
+  ['own', 'the engine’s own copy (the control)', z],
+  ['older', 'an OLDER zod copy (4.1.13)', olderZod as unknown as Vendor],
+  ['newer', 'a NEWER zod copy (4.6.7)', newerZod as unknown as Vendor],
+] as const
+
+const SHAPES = [
+  // The defect: the refinement is the WRAPPER's own check.
+  ['OptionalRefine', 'optional().refine()', (v: Vendor) => v.string().optional().refine(notForbidden, MESSAGE)],
+  ['DefaultRefine', 'default().refine()', (v: Vendor) => v.string().default('safe').refine(notForbidden, MESSAGE)],
+  // The neighbours: the refinement sits on the inner type (judged before this change too).
+  ['RefineOptional', 'refine().optional()', (v: Vendor) => v.string().refine(notForbidden, MESSAGE).optional()],
+  ['RefineDefault', 'refine().default()', (v: Vendor) => v.string().refine(notForbidden, MESSAGE).default('safe')],
+] as const
+
+const CASES = COPIES.flatMap(([copy, copyLabel, vendor]) =>
+  SHAPES.map(([shape, shapeLabel, build]) => {
+    const kind = defineRecordKind({
+      kind: `${copy}${shape}`,
+      module: `${copy}${shape}Notes`,
+      fields: { code: build(vendor) as unknown as RecordColumnSchema },
+    })
+    return [`${copyLabel}, \`z.string().${shapeLabel}\``, { kind, defaulted: shape.includes('Default') }] as const
+  }),
+)
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+  ...Object.fromEntries(CASES.map(([, { kind }]) => [`./${kind.module}.ts`, async () => defineRecordFunctions(kind)])),
+}
+
+const STAMP = '2026-10-28T00:00:00.000Z'
+
+async function editorBackend() {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: 'editor', role: 'editor', createdAt: STAMP, updatedAt: STAMP })
+  })
+  return { t, editor: t.withIdentity({ subject: 'editor', issuer: 'https://convex.test' }) }
+}
+
+describe.each(CASES)('EC-682 — Convex record save, %s', (_label, { kind, defaulted }: { kind: AnyRecordKind; defaulted: boolean }) => {
+  const save = makeFunctionReference<'mutation'>(`${kind.module}:save`)
+  const get = makeFunctionReference<'query'>(`${kind.module}:get`)
+  const write = (id: string, columns: Record<string, unknown> = {}) => ({ [kind.idKey]: id, ...columns, createdAt: STAMP, updatedAt: STAMP })
+
+  it('refuses `forbidden` on create with the column’s own message, in the transaction — nothing stored', async () => {
+    const { t, editor } = await editorBackend()
+    await expect(editor.mutation(save, write('created', { code: 'forbidden' }))).rejects.toThrow(/code: forbidden value/)
+    expect(await t.run(async (ctx) => ctx.db.query('records').collect())).toEqual([])
+  })
+
+  it('saves `safe`, refuses an edit to `forbidden`, keeps the stored value', async () => {
+    const { editor } = await editorBackend()
+    expect(await editor.mutation(save, write('edited', { code: 'safe' }))).toMatchObject({ code: 'safe' })
+    await expect(editor.mutation(save, write('edited', { code: 'forbidden' }))).rejects.toThrow(/code: forbidden value/)
+    expect(await editor.query(get, { [kind.idKey]: 'edited' })).toMatchObject({ code: 'safe' })
+  })
+
+  it('an absent key is the wrapper’s: the optional stays absent, the default is the column’s own (`safe`)', async () => {
+    const { editor } = await editorBackend()
+    const created = (await editor.mutation(save, write('absent'))) as Record<string, unknown>
+    if (defaulted) expect(created.code).toBe('safe')
+    else expect('code' in created).toBe(false)
+  })
+})

package/dist/components/cms/cms-store.d.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 import type { CmsDocument, CmsValidationIssue, CollectionDef, CollectionRegistry, DocumentPatch, DocumentRef, FieldDef, ValuePath, Locale, LocaleConfig, LocalizedString, RestoreScope, ValidateDocumentOptions } from '@elytracms/core/cms-core';
 import type { CmsDocumentRecord, DocumentVersionRecord, IdFactory, PresenceEntry } from '@elytracms/core/persistence';
+import type { ImportRejection } from './import-batch.js';
 import type { CommitOutcome, DocumentConflict, OperationError, OperationsClient } from '../../lib/operations/index.js';
 import type { TableViewState } from '../../lib/cms-views/index.js';
 import type { CellCommitInput, CellCommitOutcome } from './cell-edit.js';
@@ -24,10 +25,7 @@ export interface SavedView {
 }
 export interface ImportReport {
     added: number;
-    rejected: {
-        id: string;
-        issues: CmsValidationIssue[];
-    }[];
+    rejected: ImportRejection[];
 }
 /**
  * A document's recorded version history plus its live pin (EC-224), as the

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

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { applyDocumentPatches, createCollectionRegistry, createDocumentStore, documentKey, documentReachabilityIssues, documentSchema, resolveDocumentTitle, seedDefaults, titleFieldOf, touchedPaths, validateDocument, valuesInLocale, writeField, } from '@elytracms/core/cms-core';
+import { applyDocumentPatches, createCollectionRegistry, createDocumentStore, documentKey, documentReachabilityIssues, resolveDocumentTitle, seedDefaults, titleFieldOf, touchedPaths, validateDocument, valuesInLocale, writeField, } from '@elytracms/core/cms-core';
 import { createUuidIdFactory } from '@elytracms/core/persistence';
 import { translate } from '../../lib/i18n/index.js';
 import { configureStudioLocales, useStudioLocale } from '../../lib/locale/index.js';
@@ -9,6 +9,7 @@ import { resolveDeploymentCollections, resolveDeploymentLocaleConfig, resolveDep
 import { Heading, Panel, Stack, Text } from '@elytracms/studio/ui';
 import { assetLibraryOracle, gateValidateOptions } from './gate-validation.js';
 import { matchesRef, removeDoc, replaceDoc, upsertDoc } from './document-ref-utils.js';
+import { parseImportBatch } from './import-batch.js';
 import { createRequiredContext } from '../../lib/required-context.js';
 import { createCmsPersister, getStudioActor, getStudioOperations, importWrite } from '../../lib/operations/index.js';
 import { publishInSession, publishWithRevision as publishRevision, } from '../../lib/operations/publish-with-revision.js';
@@ -684,28 +685,9 @@ function CmsSession({ children, projectId, initialCollections, initialDocuments,
     // 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.
-        const parsedBatch = [];
-        const schemaFails = [];
-        for (const item of raw) {
-            const parsed = documentSchema.safeParse({ ...item, collection: collectionId });
-            if (parsed.success)
-                parsedBatch.push(parsed.data);
-            else
-                schemaFails.push({ item, error: parsed });
-        }
-        for (const { item, error } of schemaFails) {
-            report.rejected.push({
-                id: item?.id ?? translate('cms.list.import.noId'),
-                issues: (error.success ? [] : error.error.issues).map((e) => ({
-                    code: 'invalid-field-value',
-                    severity: 'error',
-                    message: e.message,
-                    path: e.path.map((p) => (typeof p === 'symbol' ? String(p) : p)),
-                })),
-            });
-        }
+        const { parsed: parsedBatch, rejected } = parseImportBatch(collectionId, raw);
+        const report = { added: 0, rejected: [...rejected] };
         // Validate each against existing docs PLUS the rest of the batch.
         const batchStore = createDocumentStore([...documents, ...parsedBatch]);
         const accepted = [];