@elytracms/studio 0.0.98 → 0.0.99

package/convex/ingest.test.ts

@@ -16,7 +16,7 @@ import { internalMutation } from './functions'
 import { defineStudioHttp } from './http'
 import { CONVEX_MAX_NESTING_DEPTH, measureMaxDepth } from '@elytracms/core/cms-core'
 import {
-  claimIngestUpload,
+  claimIngestUploads,
   ingestHandlerArgs,
   parseIngestPayload,
   recordIngestUpload,
@@ -77,12 +77,10 @@ const testIngestModule = {
       }
       if (payload.kind !== 'submission') return { ok: false, status: 422, message: 'Not a submission.' }
       if (payload.target !== 'contact') return { ok: false, status: 404, message: `No form “${payload.target}”.` }
-      const files: string[] = []
-      for (const claim of payload.uploads ?? []) {
-        const claimed = await claimIngestUpload(ctx, claim, payload.target, args.receivedAt)
-        if (!claimed.ok) return claimed
-        files.push(claimed.storageId)
-      }
+      // EC-695: one call for every upload, after every check that can refuse — all bound or none.
+      const claim = await claimIngestUploads(ctx, payload.uploads ?? [], payload.target, args.receivedAt)
+      if (!claim.ok) return claim
+      const files = claim.files.map((file) => file.storageId)
       const id = `sub_${(await ctx.db.query('records').collect()).length + 1}`
       await saveRecord(
         ctx,
@@ -601,6 +599,85 @@ describe('the claim binds only this intent’s bytes; release deletes only bound
     expect(measureMaxDepth(row).depth).toBe(2) // the row object → `data` → its string columns
     expect(measureMaxDepth(row).depth).toBeLessThanOrEqual(CONVEX_MAX_NESTING_DEPTH)
   })
+
+  // EC-695 — the claim is ALL-OR-NOTHING, in the engine: every claim judged, then all bound.
+  const intents = (t: ReturnType<typeof backend>) =>
+    t.run(async (ctx) =>
+      Object.fromEntries(
+        (await ctx.db.query('records').collect())
+          .filter((row) => row.kind === 'ingestUpload')
+          .map((row) => [row.recordId, (row.data as { state: string }).state]),
+      ),
+    )
+  const claimDirect = (t: ReturnType<typeof backend>, claims: { uploadId: string; storageId: string }[]) =>
+    t.run((ctx) => claimIngestUploads(ctx, claims, 'contact', '2026-10-26T12:00:00.000Z'))
+
+  it('EC-695: a submission with one refused claim binds NOTHING — the claims before it stay issued; nothing is deleted', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const [first, second, third] = [await declare(t), await declare(t), await declare(t)]
+    const [one, two] = [await storeFile(t, 400, 'image/png'), await storeFile(t, 400, 'image/png')]
+    const wrongType = await storeFile(t, 400, 'text/html') // the third's: the declared bytes, another type
+    const answer = await signedPost(t, {
+      ...SUBMISSION,
+      uploads: [
+        { uploadId: first, storageId: one },
+        { uploadId: second, storageId: two },
+        { uploadId: third, storageId: wrongType },
+      ],
+    })
+    expect(answer.status).toBe(415)
+    expect(await bindings(t)).toEqual([]) // per-claim binding would leave the first two bound, with no row
+    expect(await intents(t)).toEqual({ [first]: 'issued', [second]: 'issued', [third]: 'rejected' })
+    expect([await stored(t, one), await stored(t, two), await stored(t, wrongType)]).toEqual([true, true, true])
+    expect((await t.run(async (ctx) => ctx.db.query('records').collect())).some((row) => row.kind === 'testSubmission')).toBe(false)
+    // Control: the corrected submission (the same two uploads) binds both, in claim order.
+    const retry = await signedPost(t, {
+      ...SUBMISSION,
+      uploads: [
+        { uploadId: first, storageId: one },
+        { uploadId: second, storageId: two },
+      ],
+    })
+    expect(retry.status).toBe(200)
+    expect((await bindings(t)).map((binding) => binding.uploadId).sort()).toEqual([first, second].sort())
+    expect(await intents(t)).toEqual({ [first]: 'claimed', [second]: 'claimed', [third]: 'rejected' })
+  })
+
+  it('EC-695: called past the wire, a repeated upload or a repeated stored file is refused (400) with NOTHING written', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const [first, second] = [await declare(t), await declare(t)]
+    const file = await storeFile(t, 400, 'image/png')
+    const another = await storeFile(t, 400, 'image/png') // the same declared bytes, a second stored file
+    for (const repeat of [another, file]) {
+      const sameUpload = await claimDirect(t, [
+        { uploadId: first, storageId: file },
+        { uploadId: first, storageId: repeat }, // the one intent, the same file or ANOTHER file it would also pass for
+      ])
+      expect(sameUpload).toEqual({ ok: false, status: 400, message: 'Claim 2 names an upload an earlier claim of this submission names.' })
+    }
+    const sameFile = await claimDirect(t, [
+      { uploadId: first, storageId: file },
+      { uploadId: second, storageId: file },
+    ])
+    expect(sameFile).toEqual({ ok: false, status: 400, message: 'Claim 2 names a stored file an earlier claim of this submission names.' })
+    expect(await bindings(t)).toEqual([]) // deferred binds without the repeat check: two bindings, or one overwritten
+    expect(await intents(t)).toEqual({ [first]: 'issued', [second]: 'issued' })
+    expect([await stored(t, file), await stored(t, another)]).toEqual([true, true])
+    // Control: each claim once binds.
+    expect(await claimDirect(t, [{ uploadId: first, storageId: file }])).toEqual({
+      ok: true,
+      files: [{ storageId: file, field: 'cv', contentType: 'image/png', size: 400 }],
+    })
+    expect(await bindings(t)).toEqual([{ storageId: file, uploadId: first }])
+  })
+
+  it('EC-695: no claims is an empty success that writes nothing', async () => {
+    const t = backend()
+    expect(await claimDirect(t, [])).toEqual({ ok: true, files: [] })
+    expect(await t.run(async (ctx) => (await ctx.db.query('records').collect()).length)).toBe(0)
+  })
 })
 
 describe('the site’s route → the receiver, end to end (EC-617)', () => {

package/convex/ingest.ts

@@ -41,10 +41,10 @@ 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 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.
+ *    claims its stored files with {@link claimIngestUploads}, which checks that the deployment
+ *    stored each for ITS 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 them all or
+ *    none (EC-695); {@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: {
@@ -180,8 +180,8 @@ export function ingestReceiver(handlers: IngestHandlers = {}): PublicHttpAction
 // --- Submission-scoped uploads -------------------------------------------------------------
 //
 // The receiver issues a storage URL only for an upload a handler ACCEPTED and RECORDED as an
-// 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
+// intent (`recordIngestUpload`); a submission CLAIMS its uploads (`claimIngestUploads`), which
+// checks each stored file against its 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 refused, never attached), and the unclaimed intents an addon can
 // list (`unclaimedIngestUploads`) and surface. Convex returns the storage id to the uploader
@@ -191,7 +191,7 @@ export function ingestReceiver(handlers: IngestHandlers = {}): PublicHttpAction
 // 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}),
+// file only when the deployment's own facts say it is this upload's ({@link claimIngestUploads}),
 // it never deletes, and ingest bytes are deleted only through {@link releaseIngestUploads},
 // which deletes only what a claim bound.
 //
@@ -201,6 +201,14 @@ export function ingestReceiver(handlers: IngestHandlers = {}): PublicHttpAction
 // 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.
+//
+// EC-695 — a refusal never deletes. Causation holds only for bytes an attacker cannot predict:
+// a deterministic file can be declared by anyone holding an intent open before it is stored
+// (the RESIDUAL, `claimableFile`). So a submission's claims are judged ALL before any is bound
+// (`claimIngestUploads`): a refused submission binds nothing and has nothing to release, so a
+// substituted file is never deleted by a rollback. The substitution itself remains — A's
+// submission can hold B's predictable file, and B's claim is refused visibly as bound — and is
+// closed only by the engine receiving the bytes (a new route: EC-304 Phase B, the owner's).
 
 /** The upload intent — an engine-internal record kind (no public functions). */
 export const ingestUploadRecordKind = defineRecordKind({
@@ -225,7 +233,7 @@ export const ingestUploadRecordKind = defineRecordKind({
 /**
  * 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
+ * and "is it bound?" is one indexed read. Written only by {@link claimIngestUploads}, 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.
  */
@@ -293,10 +301,22 @@ function payloadColumns(payload: Extract<IngestPayload, { kind: 'upload' }>) {
   }
 }
 
-/** What a claim yields: the stored file's facts, or a refusal for the handler to return. */
-export type IngestUploadClaimResult =
-  | { ok: true; storageId: string; field: string; contentType: string; size: number }
-  | { ok: false; status: 409 | 413 | 415 | 422; message: string }
+/** One stored file a submission's claim bound: the deployment's id for it, and the intent's facts. */
+export interface IngestClaimedUpload {
+  storageId: string
+  field: string
+  contentType: string
+  size: number
+}
+
+/** A claim's refusal, for the handler to return as it is. */
+export type IngestUploadClaimRefusal = { ok: false; status: 400 | 409 | 413 | 415 | 422; message: string }
+
+/** What a submission's claim yields: every file it bound, in claim order — or the one refusal, with nothing bound. */
+export type IngestUploadsClaimResult = { ok: true; files: IngestClaimedUpload[] } | IngestUploadClaimRefusal
+
+/** A claim the judge accepted — its binding is written only once every claim of the submission is accepted. */
+type AcceptedClaim = IngestClaimedUpload & { uploadId: string }
 
 /**
  * EC-671 — whether the deployment's own facts say a stored file is this intent's to claim. The
@@ -314,7 +334,10 @@ export type IngestUploadClaimResult =
  *    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.
+ *    through B's URL pass 1–3 for A too, and fail 4 unless A predicted them. RESIDUAL (named,
+ *    not closed): bytes A CAN predict (a template, a generated file) pass 4 for A as well —
+ *    content equality is not uploader identity. EC-695 keeps that non-destructive (a refusal
+ *    binds nothing, {@link claimIngestUploads}); only the engine receiving the bytes closes it.
  *
  * 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
@@ -350,24 +373,74 @@ 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 + 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}).
+ * EC-695 — claim ALL of a submission's uploads for `target`, all or nothing: the engine's ONE
+ * claim primitive. Every claim is JUDGED first ({@link judgeIngestUploadClaim}); a binding is
+ * written only once every claim passed, in this one transaction. So a submission with one
+ * refused claim binds NOTHING, and there is nothing to release: no caller ever deletes bytes
+ * because a claim failed. (Before EC-695 a claim bound as it went and forms' rollback released
+ * what it had bound; with a predictable file — {@link claimableFile}'s residual — "bound in this
+ * call" could be ANOTHER intent's file, and a deliberately mismatching second claim made the
+ * rollback delete it.)
+ *
+ * Each claim's intent must exist, be unclaimed, belong to `target`, be younger than
+ * `INGEST_UPLOAD_TTL_MS`; its 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 its intent ({@link ingestBindingRecordKind}) — the fact every deletion
+ * reads ({@link releaseIngestUploads}) — and handed back in claim order.
  *
- * A refusal marks the intent `rejected` (recording the id it named) and deletes NOTHING
+ * Because the bindings wait for the whole verdict, the checks a binding would answer for a LATER
+ * claim of the same submission are answered from the claims already judged: an upload, or a
+ * stored file (by the deployment's own id), that an earlier claim named is refused (400, nothing
+ * written). The wire refuses the same repeats by their spelling first (`@elytracms/core/ingest`).
+ *
+ * The first refusal is returned as it is. If the claim's ownership or declaration checks refused
+ * it, its intent is marked `rejected` (recording the id it named) — and nothing is deleted
  * (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.
+ * uploader put them — the same residue as an upload never claimed. The claims judged before it
+ * were never bound, so their intents stay `issued` and a corrected submission can claim them.
+ *
+ * A handler calls this ONCE per submission, after every check of its own that can refuse: a
+ * mutation that RETURNS commits its writes (a claim made before a later refusal stays bound with
+ * no row to hold it); one that THROWS commits nothing.
+ */
+export async function claimIngestUploads(
+  ctx: MutationCtx,
+  claims: readonly IngestUploadClaim[],
+  target: string,
+  receivedAt: string,
+): Promise<IngestUploadsClaimResult> {
+  const accepted: AcceptedClaim[] = []
+  for (const [index, claim] of claims.entries()) {
+    const verdict = await judgeIngestUploadClaim(ctx, claim, target, receivedAt, index, accepted)
+    if (!verdict.ok) return verdict
+    accepted.push(verdict.claim)
+  }
+  const stamps = { createdAt: receivedAt, updatedAt: receivedAt }
+  for (const claim of accepted) {
+    await saveRecord(ctx, ingestBindingRecordKind, claim.storageId, { uploadId: claim.uploadId, target, boundAt: receivedAt }, stamps)
+    await saveRecord(ctx, ingestUploadRecordKind, claim.uploadId, { state: 'claimed', storageId: claim.storageId }, stamps)
+  }
+  return { ok: true, files: accepted.map(({ storageId, field, contentType, size }) => ({ storageId, field, contentType, size })) }
+}
+
+/**
+ * Judge ONE claim of a submission, given the claims of the same submission already accepted
+ * (`earlier`, not yet bound): its verdict, or its refusal. It writes only a refusal's `rejected`
+ * mark — never a binding ({@link claimIngestUploads} writes those, once every claim passed).
  */
-export async function claimIngestUpload(
+async function judgeIngestUploadClaim(
   ctx: MutationCtx,
   claim: IngestUploadClaim,
   target: string,
   receivedAt: string,
-): Promise<IngestUploadClaimResult> {
+  index: number,
+  earlier: readonly AcceptedClaim[],
+): Promise<{ ok: true; claim: AcceptedClaim } | IngestUploadClaimRefusal> {
+  // The intent's state check, for an intent an earlier claim of THIS submission already took.
+  if (earlier.some((accepted) => accepted.uploadId === claim.uploadId)) {
+    return { ok: false, status: 400, message: `Claim ${index + 1} names an upload an earlier claim of this submission names.` }
+  }
   const intent = await findRecordDoc(ctx, ingestUploadRecordKind, claim.uploadId)
   const columns = intent?.data as
     | { target: string; field: string; contentType: string; size: number; sha256?: string; state: string; issuedAt: string }
@@ -399,7 +472,12 @@ export async function claimIngestUpload(
   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 reject = async (refusal: { status: 413 | 415 | 422; message: string }): Promise<IngestUploadClaimResult> => {
+  // Check (2) of {@link claimableFile}, for a file an earlier claim of THIS submission already
+  // took — by the deployment's own id (`file._id`), so no second spelling of one id slips by.
+  if (earlier.some((accepted) => accepted.storageId === file._id)) {
+    return { ok: false, status: 400, message: `Claim ${index + 1} names a stored file an earlier claim of this submission names.` }
+  }
+  const reject = async (refusal: { status: 413 | 415 | 422; message: string }): Promise<IngestUploadClaimRefusal> => {
     await saveRecord(ctx, ingestUploadRecordKind, claim.uploadId, { state: 'rejected', storageId: claim.storageId }, stamps)
     return { ok: false, ...refusal }
   }
@@ -421,11 +499,12 @@ export async function claimIngestUpload(
   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: file._id, field: columns.field, contentType: columns.contentType, size: file.size }
+  // Accepted — to be 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.
+  return {
+    ok: true,
+    claim: { uploadId: claim.uploadId, storageId: file._id, field: columns.field, contentType: columns.contentType, size: file.size },
+  }
 }
 
 /**
@@ -441,8 +520,8 @@ export async function claimIngestUpload(
  *   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
+ * Call it when removing a row that holds claimed files — never for a refused submission, which
+ * bound nothing ({@link claimIngestUploads}, EC-695). 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.
  */

package/convex/path-segment-refusal.test.ts

@@ -0,0 +1,201 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import { makeFunctionReference } from 'convex/server'
+import type { FunctionReference } from 'convex/server'
+import { fieldPath, nodePath, nodePropPath, subFieldPath } from '@elytracms/core/cms-core'
+import type { CollectionDef, ValuePath } from '@elytracms/core/cms-core'
+import { 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-692 (Codex round 5 F29 — `tasks/codex-review-2026-10-28-r5/write-boundary-contracts.ts:41-80` run
+ * by `write-boundaries.convex.test.ts`, copied here and INVERTED; widened by the wave-0100 critic) on
+ * Convex, over the REAL `cms.ts` mutations. Two entry points:
+ *
+ * 1. Through operations (the production `ConvexPersistenceAdapter`): on the base a segment with one extra
+ *    key passed EC-684's raw refusal, the parse stripped the key, and the mutation applied the `__proto__`
+ *    segment — `ok: true` with the value lost, and `group → __proto__ → marker` wrote the marker to
+ *    `Object.prototype` in the process applying it.
+ * 2. A DIRECT authenticated call of `cms:patchDocument` / `cms:publishDocument` (`patches: v.any()`, no
+ *    parse, no `runAny`): on the base a `locale` or `sub` segment `__proto__` polluted `Object.prototype`
+ *    with NO extra key, a `field` segment reported `ok` and lost the value, and an `insert` at slot
+ *    `__proto__` threw out of the mutation. The locale "control" of the review holds only through
+ *    operations (zod's locale schema); through the mutation it was a counterexample.
+ *
+ * Now the applier judges every raw patch by the one path grammar before it follows a name, in this
+ * store as in memory, and every walk reads and writes own properties only.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+const P = 'site'
+const ref = { collection: 'post', id: 'p' }
+const STAMP = '2026-10-28T00:00:00.000Z'
+const proto = Object.prototype as unknown as Record<string, unknown>
+const patchDocument = makeFunctionReference<'mutation'>('cms:patchDocument')
+const publishDocument = makeFunctionReference<'mutation'>('cms:publishDocument')
+
+const collections: CollectionDef[] = [
+  {
+    id: 'post',
+    kind: 'document',
+    fields: [
+      { name: 'title', type: 'text' },
+      { name: 'group', type: 'object', multiple: false, fields: [] },
+      { name: 'body', type: 'blocks' },
+    ],
+  },
+]
+const card = (id: string) => ({ type: 'elytra/component' as const, id, componentId: 'Card', props: { title: { value: id } } })
+
+async function world() {
+  const t = convexTest(schema, modules)
+  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 client = {
+    query: (fn: FunctionReference<'query'>, args?: Record<string, unknown>) => admin.query(fn, args ?? {}),
+    mutation: (fn: FunctionReference<'mutation'>, args?: Record<string, unknown>) => admin.mutation(fn, args ?? {}),
+  } as unknown as ConvexHttpClient
+  const adapter = new ConvexPersistenceAdapter(client, P)
+  const ops = createOperations({ adapter, collections: () => collections, validateDocument: () => [] })
+  const created = await ops.documents.replace({
+    projectId: P,
+    document: { ...ref, values: { title: 'KEEP', group: {}, body: { version: 2, content: [card('c')] } } },
+    precondition: { ifAbsent: true },
+  })
+  expect(created.ok).toBe(true)
+  const stored = async () => (await adapter.cms.getDocument(P, ref))
+  /** The mutation called directly, as an authenticated client may: raw patches, no operations layer. */
+  const direct = (patches: unknown[]) =>
+    admin.mutation(patchDocument, { collection: ref.collection, docId: ref.id, patches, baseRevision: 1, at: STAMP }) as Promise<{
+      status: string
+      appliedCount?: number
+      refused?: { reason: string }[]
+    }>
+  return { t, admin, adapter, ops, stored, direct }
+}
+
+/** Assert `Object.prototype` carries no `marker` after `body` — and clean up in `finally`. */
+async function prototypeUnchanged(marker: string, body: () => Promise<void>): Promise<void> {
+  expect(Object.hasOwn(proto, marker)).toBe(false)
+  try {
+    await body()
+    expect(Object.hasOwn(proto, marker)).toBe(false)
+  } finally {
+    delete proto[marker]
+  }
+}
+
+const withExtra = (path: ValuePath): ValuePath => path.map((segment) => ({ ...segment, extra: true }))
+
+describe('EC-692 F29 inverted on Convex — through operations', () => {
+  const segments: [string, ValuePath][] = [
+    ['field', fieldPath('__proto__')],
+    ['sub', subFieldPath('group', undefined, '__proto__')],
+    ['locale', fieldPath('round5UnusedField', '__proto__')],
+    ['prop', nodePropPath('body', undefined, 'c', '__proto__')],
+  ]
+  for (const [name, path] of segments) {
+    it(`${name}: refused as validation with the extra key (never stripped) and without it`, async () => {
+      const { ops, stored } = await world()
+      const send = (at: ValuePath) => ops.documents.patch({ projectId: P, ref, baseRevision: 1, patches: [{ op: 'unset', path: at }] })
+      expect(await send(path)).toMatchObject({ ok: false, error: { code: 'validation', issues: [expect.objectContaining({ code: 'prototype-key' })] } })
+      expect(await send(withExtra(path))).toMatchObject({ ok: false, error: { code: 'validation' } })
+      expect((await stored()).revision).toBe(1)
+    })
+  }
+
+  it('slot: an insert at slot "__proto__" is refused as validation — CONTROL: an ordinary slot inserts', async () => {
+    const { ops, stored } = await world()
+    const insert = (slot: string) =>
+      ops.documents.patch({ projectId: P, ref, baseRevision: 1, patches: [{ op: 'insert', at: { parent: nodePath('body', undefined, 'c'), slot, index: 0 }, node: card('n') }] })
+    expect(await insert('__proto__')).toMatchObject({ ok: false, error: { code: 'validation' } })
+    expect((await stored()).revision).toBe(1)
+    expect((await insert('items')).ok).toBe(true)
+  })
+
+  it('the prototype trace: group → __proto__ (extra key) → marker is refused; Object.prototype unchanged', async () => {
+    const { ops, stored } = await world()
+    const marker = 'ec692ConvexOperationsMarker'
+    await prototypeUnchanged(marker, async () => {
+      const result = await ops.documents.patch({
+        projectId: P,
+        ref,
+        baseRevision: 1,
+        patches: [{ op: 'set', path: [...fieldPath('group'), { kind: 'sub', name: '__proto__', extra: true } as never, { kind: 'sub', name: marker }], value: 'PROBE' }],
+      })
+      expect(result).toMatchObject({ ok: false, error: { code: 'validation' } })
+      expect((await stored()).revision).toBe(1)
+    })
+  })
+
+  it('CONTROL — a sub-field named "constructor" applies, as an own key', async () => {
+    const { ops, stored } = await world()
+    const result = await ops.documents.patch({ projectId: P, ref, baseRevision: 1, patches: [{ op: 'set', path: subFieldPath('group', undefined, 'constructor', 'x'), value: 1 }] })
+    expect(result.ok).toBe(true)
+    expect((await stored()).document.values.group).toEqual({ constructor: { x: 1 } })
+  })
+})
+
+describe('EC-692 on Convex — a DIRECT call of cms:patchDocument (raw patches, no parse, no runAny)', () => {
+  const marker = 'ec692DirectMarker'
+  const raw: [string, unknown][] = [
+    ['locale (no extra key)', { op: 'set', path: [{ kind: 'field', name: marker }, { kind: 'locale', locale: '__proto__' }], value: 'POLLUTED' }],
+    ['sub (no extra key)', { op: 'set', path: subFieldPath('group', undefined, '__proto__', marker), value: 'POLLUTED' }],
+    ['field (no extra key)', { op: 'set', path: fieldPath('__proto__'), value: { [marker]: 'POLLUTED' } }],
+    ['prop (no extra key)', { op: 'set', path: nodePropPath('body', undefined, 'c', '__proto__'), value: 'x' }],
+    ['slot', { op: 'insert', at: { parent: nodePath('body', undefined, 'c'), slot: '__proto__', index: 0 }, node: card('n') }],
+    ['an extra segment key', { op: 'set', path: [{ kind: 'field', name: 'title', extra: true }], value: 'x' }],
+    ['a malformed patch', { op: 'set', path: [null], value: 'x' }],
+  ]
+  for (const [name, patch] of raw) {
+    it(`${name}: refused as invalid, nothing written, Object.prototype unchanged`, async () => {
+      const { direct, stored } = await world()
+      await prototypeUnchanged(marker, async () => {
+        const outcome = await direct([patch])
+        expect(outcome).toMatchObject({ status: 'conflict', appliedCount: 0, refused: [{ reason: 'invalid' }] })
+        expect((await stored()).revision).toBe(1)
+        expect((await stored()).document.values.title).toBe('KEEP')
+      })
+    })
+  }
+
+  it('CONTROL — the same mutation applies an ordinary patch and a real sub-field named "constructor"', async () => {
+    const { direct, stored } = await world()
+    expect(await direct([{ op: 'set', path: subFieldPath('group', undefined, 'constructor', 'x'), value: 1 }, { op: 'set', path: fieldPath('title'), value: 'NEW' }])).toMatchObject({ status: 'ok' })
+    const after = await stored()
+    expect(after.revision).toBe(2)
+    expect(after.document.values).toMatchObject({ title: 'NEW', group: { constructor: { x: 1 } } })
+  })
+
+  it('cms:publishDocument applies its hidden-clear patches by the same grammar: a "__proto__" locale refuses the publish, unpolluted', async () => {
+    const { admin, stored } = await world()
+    await prototypeUnchanged(marker, async () => {
+      const outcome = (await admin.mutation(publishDocument, {
+        collection: ref.collection,
+        docId: ref.id,
+        expectedRevision: 1,
+        at: STAMP,
+        patches: [{ op: 'set', path: [{ kind: 'field', name: marker }, { kind: 'locale', locale: '__proto__' }], value: 'POLLUTED' }],
+      })) as { status: string }
+      expect(outcome.status).toBe('conflict')
+      expect((await stored()).publishedVersion).toBeUndefined()
+    })
+  })
+})