@elytracms/studio 0.0.97 → 0.0.99

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,23 +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 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.
+ *    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: {
  * 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 } : {}) })
     }
@@ -145,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
@@ -156,9 +191,24 @@ 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.
+//
+// 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.
+//
+// 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({
@@ -171,6 +221,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. */
@@ -181,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.
  */
@@ -240,13 +292,31 @@ 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,
+  }
+}
+
+/** 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
 }
 
-/** 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 }
+/** 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
@@ -259,18 +329,33 @@ 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. 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
+ * 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`)? */
@@ -288,26 +373,77 @@ 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).
- * 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.
+ *
+ * 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`).
  *
- * A refusal marks the intent `rejected` (recording the id it named) and deletes NOTHING
+ * 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; 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,36 +452,78 @@ 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 }
   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 }
   }
   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.' })
   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 },
+  }
 }
 
 /**
  * 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 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.
  */
 export async function releaseIngestUploads(
   ctx: MutationCtx,
@@ -359,14 +537,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/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()
+    })
+  })
+})