@elytracms/studio 0.0.96 → 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,
@@ -39,22 +41,30 @@ import { findRecordDoc, listRecordWire, saveRecord } from './record-functions'
  *    analytics addon must fail visibly (EC-618's counsel gate relies on it);
  * 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 it against what the
- *    upload request declared.
+ *    claims the stored file with {@link claimIngestUpload}, which checks that the deployment
+ *    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
 >
 
@@ -96,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) => {
@@ -126,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 } : {}) })
     }
@@ -147,10 +183,24 @@ export function ingestReceiver(handlers: IngestHandlers = {}): PublicHttpAction
 // intent (`recordIngestUpload`); a submission CLAIMS it (`claimIngestUpload`), which checks the
 // stored file against the intent. Abuse is bounded by: the route's limiter and bot gate on every
 // URL issued, `INGEST_MAX_UPLOAD_BYTES` per file, the URL's one-hour life, the post-upload check
-// (an over-size or mistyped file is deleted, never kept), and the unclaimed intents an addon can
+// (an over-size or mistyped file is refused, never attached), and the unclaimed intents an addon can
 // list (`unclaimedIngestUploads`) and surface. Convex returns the storage id to the uploader
 // only, so the bytes of an upload no submission ever claims cannot be located by the engine —
 // that is the documented residue, bounded by the limits above.
+//
+// EC-671 — ownership. The storage id a claim names is the VISITOR's word: nothing at intent
+// time can record it (`generateUploadUrl` takes no argument; the id reaches the uploader
+// alone), and an asset's storage id is public on the delivery snapshot. So a claim binds a
+// 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({
@@ -163,12 +213,33 @@ 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. */
     storageId: z.string().optional(),
   },
 })
 
+/**
+ * EC-671 — the engine's ONE ownership fact for ingest bytes: a record per stored file a claim
+ * bound to its intent, keyed BY the storage id (`recordId`), so a file is bound at most once
+ * and "is it bound?" is one indexed read. Written only by {@link claimIngestUpload}, in the
+ * claim's transaction; read by the claim (a file another claim bound is refused) and by
+ * {@link releaseIngestUploads}. Engine-internal (no public functions), like the intent.
+ */
+export const ingestBindingRecordKind = defineRecordKind({
+  kind: 'ingestBinding',
+  module: 'ingest',
+  time: 'boundAt',
+  fields: {
+    uploadId: z.string().min(1),
+    target: z.string().min(1),
+    boundAt: z.string().min(1),
+  },
+})
+
 let mintUploadUuid: (() => string) | undefined
 
 export interface IngestUploadPolicy {
@@ -213,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. */
@@ -221,11 +298,69 @@ export type IngestUploadClaimResult =
   | { ok: true; storageId: string; field: string; contentType: string; size: number }
   | { ok: false; status: 409 | 413 | 415 | 422; message: string }
 
+/**
+ * EC-671 — whether the deployment's own facts say a stored file is this intent's to claim. The
+ * storage id cannot be recorded at intent time (it reaches the uploader alone), so ownership
+ * is read from `_storage` facts and engine rows; a file is claimable only when ALL hold:
+ *
+ * 1. it was stored AFTER the intent was issued — compared in ONE clock: the intent row's
+ *    `_creationTime` against the file's, both stamped by the deployment at insert (`issuedAt`
+ *    is the HTTP action's clock, at millisecond grain: a file stored in the same millisecond
+ *    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);
+ * 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; 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`)? */
+async function assetReferencesStorage(ctx: MutationCtx, storageId: string): Promise<boolean> {
+  const asFile = await ctx.db
+    .query('assets')
+    .withIndex('by_storage', (q) => q.eq('storageKey', storageId))
+    .first()
+  if (asFile) return true
+  const asThumb = await ctx.db
+    .query('assets')
+    .withIndex('by_thumb_storage', (q) => q.eq('thumb.storageKey', storageId))
+    .first()
+  return asThumb !== null
+}
+
 /**
  * Claim one upload for a submission to `target`: the intent must exist, be unclaimed,
- * belong to `target`, be younger than `INGEST_UPLOAD_TTL_MS`, and the STORED file must match
- * it (size ≤ declared, same content type). A mismatched file is deleted and the intent
- * marked `rejected` — never kept.
+ * belong to `target`, be younger than `INGEST_UPLOAD_TTL_MS`; the stored file must be this
+ * 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}).
+ *
+ * A refusal marks the intent `rejected` (recording the id it named) and deletes NOTHING
+ * (EC-671): the named id is the visitor's word, and even a file that passed every ownership
+ * check may belong to someone the engine cannot see. A refused upload's bytes stay where the
+ * uploader put them — the same residue as an upload never claimed.
  */
 export async function claimIngestUpload(
   ctx: MutationCtx,
@@ -235,30 +370,113 @@ 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 (!columns || columns.target !== target) return { ok: false, status: 422, message: `Unknown upload “${claim.uploadId}”.` }
+  if (!intent || !columns || columns.target !== target) {
+    return { ok: false, status: 422, message: `Unknown upload “${claim.uploadId}”.` }
+  }
   if (columns.state !== 'issued') return { ok: false, status: 409, message: `Upload “${claim.uploadId}” was already claimed.` }
   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 }
   if (!file) return { ok: false, status: 422, message: `No stored file “${claim.storageId}”.` }
-  const refused =
-    file.size > columns.size
-      ? ({ status: 413, message: 'The stored file is larger than the upload declared.' } as const)
-      : (file.contentType ?? '') !== columns.contentType
-        ? ({ status: 415, message: 'The stored file is not of the declared type.' } as const)
-        : undefined
-  if (refused) {
-    await ctx.storage.delete(storageId)
+  const reject = async (refusal: { status: 413 | 415 | 422; message: string }): Promise<IngestUploadClaimResult> => {
     await saveRecord(ctx, ingestUploadRecordKind, claim.uploadId, { state: 'rejected', storageId: claim.storageId }, stamps)
-    return { ok: false, ...refused }
+    return { ok: false, ...refusal }
+  }
+  const intentRow = await ctx.db.get(intent._id)
+  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.' })
+  if ((file.contentType ?? '') !== columns.contentType) {
+    return reject({ status: 415, message: 'The stored file is not of the declared type.' })
+  }
+  // Bound — and handed back — under the deployment's own id for the file (`file._id`), the
+  // spelling checks (2) and (3) read, never the string the visitor sent.
+  await saveRecord(ctx, ingestBindingRecordKind, file._id, { uploadId: claim.uploadId, target, boundAt: receivedAt }, stamps)
   await saveRecord(ctx, ingestUploadRecordKind, claim.uploadId, { state: 'claimed', storageId: claim.storageId }, stamps)
-  return { ok: true, storageId: claim.storageId, field: columns.field, contentType: columns.contentType, size: file.size }
+  return { ok: true, storageId: file._id, field: columns.field, contentType: columns.contentType, size: file.size }
+}
+
+/**
+ * Delete ingest bytes an addon holds (EC-671) — the ONE way they are deleted, and it deletes
+ * 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,
+  storageIds: readonly string[],
+): Promise<{ deleted: string[]; kept: string[] }> {
+  const deleted: string[] = []
+  const kept: string[] = []
+  for (const storageId of new Set(storageIds)) {
+    const binding = await findRecordDoc(ctx, ingestBindingRecordKind, storageId)
+    if (!binding) {
+      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)
+    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. */

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/receipt-races.test.ts

@@ -0,0 +1,184 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import { getFunctionName, makeFunctionReference } from 'convex/server'
+import type { FunctionReference } from 'convex/server'
+import { measureMaxDepth } from '@elytracms/core/cms-core'
+import { createChangesets, createOperations } from '@elytracms/core/operations'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import schema from './schema'
+
+// convex-test fires a `runAfter(0)` on a REAL timer (the publish trigger's revalidation);
+// fake timers keep it queued.
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime('2026-10-28T00:00:00.000Z')
+})
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/**
+ * EC-663 — the Codex review's F16 and F17 counterexamples on Convex (round 3,
+ * `races.convex.test.ts`), copied and INVERTED: the real `cms:*` handlers, schema and triggers
+ * under convex-test, driven by the production operations and changesets over the production
+ * `ConvexPersistenceAdapter`. Each race is an explicit interleaving — the client HOLDS one
+ * store mutation after every check, runs the colleague's operation, then sends the held
+ * mutation — and the mutation REFUSES inside its transaction. convex-test serialises
+ * mutations, so this proves the sink's check and its refusal, not Convex's OCC retry.
+ *
+ * F17's wiring changed on purpose (an adapted copy, as the preamble requires): the hidden-clear
+ * no longer lands BEFORE `cms:publishDocument` — it is part of it — so at the pause the draft
+ * still holds the hidden value (the probe asserted it was already gone).
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+const projectId = 'receipt-races'
+const ref = { collection: 'post', id: 'p' }
+const author = { collection: 'author', id: 'a' }
+
+async function world() {
+  const t = convexTest(schema, modules)
+  const stamp = '2026-10-28T00:00:00Z'
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: 'user_admin', role: 'admin', createdAt: stamp, updatedAt: stamp })
+  })
+  const admin = t.withIdentity({ subject: 'user_admin', issuer: 'https://convex.test' })
+  const held = new Map<string, { reached(): void; gate: Promise<void> }>()
+  const client = {
+    query: (fn: FunctionReference<'query'>, args?: Record<string, unknown>) => admin.query(fn, args ?? {}),
+    mutation: async (fn: FunctionReference<'mutation'>, args?: Record<string, unknown>) => {
+      const key = `${getFunctionName(fn)}#${String(args?.docId)}`
+      const pause = held.get(key)
+      if (pause) {
+        held.delete(key)
+        pause.reached()
+        await pause.gate
+      }
+      return admin.mutation(fn, args ?? {})
+    },
+  } as unknown as ConvexHttpClient
+  const adapter = new ConvexPersistenceAdapter(client, projectId)
+  const collections = () => [
+    { id: 'author', kind: 'document' as const, fields: [{ name: 'name', type: 'text' as const }] },
+    { id: 'post', kind: 'document' as const, fields: [
+      { name: 'title', type: 'text' as const },
+      { name: 'hidden', type: 'text' as const, form: { hidden: () => true } },
+      { name: 'author', type: 'relation' as const, target: 'author', multiple: false, strict: true },
+    ] },
+  ]
+  const options = { adapter, collections, validateDocument: () => [] }
+  const ops = createOperations(options)
+  const changesets = createChangesets(options)
+  /** Hold the next `cms:<verb>` mutation for document `id` at the client. */
+  const hold = (verb: string, id: string) => {
+    let reached!: () => void
+    let resume!: () => void
+    const at = new Promise<void>((r) => { reached = r })
+    const gate = new Promise<void>((r) => { resume = r })
+    held.set(`cms:${verb}#${id}`, { reached, gate })
+    return { at, resume }
+  }
+  const put = async (document: { collection: string; id: string; values: Record<string, unknown> }) => {
+    expect((await ops.documents.replace({ projectId, document, precondition: { ifAbsent: true } })).ok).toBe(true)
+  }
+  return { t, admin, adapter, ops, changesets, hold, put }
+}
+
+for (const inverse of ['pin', 'unpublish'] as const) {
+  it(`F16 Convex: a ${inverse} inverse refuses in its mutation when a colleague published after its checks`, async () => {
+    const { adapter, ops, changesets, hold, put } = await world()
+    await put({ ...ref, values: { title: 'one' } })
+    if (inverse === 'pin') expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true)
+    const applied = await changesets.apply(changesets.create({ title: 'publish', steps: [{ operation: 'documents.publish', input: { projectId, ref } }] }))
+    expect(applied.ok).toBe(true)
+    if (!applied.ok) throw new Error(applied.error.message)
+    const pause = hold(inverse === 'pin' ? 'publishDocumentVersion' : 'unpublishDocument', ref.id)
+    const reverting = changesets.revert(applied.value)
+    await pause.at
+    expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true)
+    const b = await adapter.cms.getDocument(projectId, ref)
+    expect(b.publishedVersion).toBe(inverse === 'pin' ? 3 : 2)
+    pause.resume()
+    // Inverted: the revert refuses and the colleague's publication stays live.
+    const reverted = await reverting
+    expect(reverted.ok).toBe(false)
+    if (!reverted.ok) expect(reverted.error.code).toBe('conflict')
+    expect((await adapter.cms.getDocument(projectId, ref)).publishedVersion).toBe(b.publishedVersion)
+  })
+}
+
+it('F16 Convex control: a revert with nothing racing it lands (the precondition is not a blanket refusal)', async () => {
+  const { adapter, ops, changesets, put } = await world()
+  await put({ ...ref, values: { title: 'one' } })
+  expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true) // v1
+  const applied = await changesets.apply(changesets.create({ title: 'publish', steps: [{ operation: 'documents.publish', input: { projectId, ref } }] }))
+  if (!applied.ok) throw new Error(applied.error.message)
+  expect((await adapter.cms.getDocument(projectId, ref)).publishedVersion).toBe(2)
+  expect((await changesets.revert(applied.value)).ok).toBe(true)
+  expect((await adapter.cms.getDocument(projectId, ref)).publishedVersion).toBe(1)
+})
+
+it('F17 Convex (adapted wiring): a publish its mutation refuses cleared nothing — compensation’s rollback claim is true', async () => {
+  const { adapter, ops, changesets, hold, put } = await world()
+  await put({ ...author, values: { name: 'Ada' } })
+  await put({ ...ref, values: { hidden: 'KEEP DRAFT', author: { type: 'reference', ...author } } })
+  expect((await ops.documents.publish({ projectId, ref: author })).ok).toBe(true)
+  const before = await adapter.cms.getDocument(projectId, ref)
+  const pause = hold('publishDocument', ref.id)
+  const applying = changesets.apply(changesets.create({ title: 'publish', steps: [{ operation: 'documents.publish', input: { projectId, ref } }] }))
+  await pause.at
+  // Changed wiring: the clear is part of the held mutation, so nothing is cleared yet.
+  expect((await adapter.cms.getDocument(projectId, ref)).document.values.hidden).toBe('KEEP DRAFT')
+  expect((await ops.documents.unpublish({ projectId, ref: author })).ok).toBe(true)
+  pause.resume()
+  const result = await applying
+  expect(result.ok).toBe(false)
+  if (result.ok) throw new Error('expected strict conflict')
+  expect(result.error.message).toContain('All previously applied steps were rolled back')
+  // Inverted: the refused publish wrote nothing.
+  const after = await adapter.cms.getDocument(projectId, ref)
+  expect(after.document.values.hidden).toBe('KEEP DRAFT')
+  expect(after.revision).toBe(before.revision)
+  expect(after.publishedVersion).toBeUndefined()
+})
+
+describe('EC-663 Convex — the mutations enforce the new preconditions themselves', () => {
+  const pinRef = makeFunctionReference<'mutation'>('cms:publishDocumentVersion')
+  const unpublishRef = makeFunctionReference<'mutation'>('cms:unpublishDocument')
+
+  it('cms:publishDocumentVersion / cms:unpublishDocument with a stale expectedRevision return conflict and write nothing', async () => {
+    const { admin, adapter, ops, put } = await world()
+    await put({ ...ref, values: { title: 'one' } })
+    expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true) // r2, v1
+    const at = '2026-10-28T00:00:01Z'
+    const pin = await admin.mutation(pinRef, { collection: 'post', docId: 'p', version: 1, updatedAt: at, publishedAt: at, expectedRevision: 1 })
+    expect(pin).toMatchObject({ status: 'conflict', current: { revision: 2 } })
+    const unpublish = await admin.mutation(unpublishRef, { collection: 'post', docId: 'p', updatedAt: at, expectedRevision: 1 })
+    expect(unpublish).toMatchObject({ status: 'conflict', current: { revision: 2 } })
+    const kept = await adapter.cms.getDocument(projectId, ref)
+    expect([kept.revision, kept.publishedVersion]).toEqual([2, 1])
+    // Control: at the current revision both land.
+    expect(await admin.mutation(unpublishRef, { collection: 'post', docId: 'p', updatedAt: at, expectedRevision: 2 })).toMatchObject({ revision: 3 })
+    expect(await admin.mutation(pinRef, { collection: 'post', docId: 'p', version: 1, updatedAt: at, publishedAt: at, expectedRevision: 3 })).toMatchObject({ status: 'ok' })
+  })
+
+  it('a publish with a hidden-clear is ONE mutation: patch row at +1, publish row at +2, the pinned snapshot cleared', async () => {
+    const { t, adapter, ops, put } = await world()
+    await put({ ...ref, values: { title: 'T', hidden: 'gone' } })
+    const published = await ops.documents.publish({ projectId, ref })
+    expect(published.ok).toBe(true)
+    const log = await adapter.cms.listDocumentPatches(projectId, ref)
+    expect(log.map((row) => `${row.revision}:${row.kind}`)).toEqual(['1:replace', '2:patch', '3:publish'])
+    const record = await adapter.cms.getDocument(projectId, ref)
+    expect(record.document.values).toEqual({ title: 'T' })
+    expect(record.hasUnpublishedChanges).toBe(false)
+    expect((await adapter.cms.getDocumentVersion(projectId, ref, 1)).snapshot.values).toEqual({ title: 'T' })
+    // The stored row stays inside Convex's 16-level cap.
+    const rows = await t.run((ctx) => ctx.db.query('cmsDocuments').collect())
+    for (const row of rows) expect(measureMaxDepth(row).depth).toBeLessThanOrEqual(16)
+  })
+})