@elytracms/studio 0.0.97 → 0.0.98

package/convex/assets.ts

@@ -5,6 +5,7 @@ import { liftLegacyAlt as legacyAltLift, rejectedWriteMessage, resolveAssetWrite
 import type { DataModel } from './functions'
 import { internalMutation, mutation, query } from './functions'
 import { requireCapability } from './guard'
+import { ingestBindingHolds } from './ingest'
 
 /**
  * Asset metadata persistence (EC-044) + byte storage (EC-151). Bytes live in
@@ -210,15 +211,28 @@ export const getServeUrl = query({
   },
 })
 
-/** Delete stored bytes. Metadata removal is a separate `assets:remove` call. */
+/**
+ * Delete stored bytes. Metadata removal is a separate `assets:remove` call.
+ *
+ * EC-685 — unless an ingest binding holds them: an editor may create an asset over a form
+ * submission's uploaded file (`upsert` allows it — promoting an upload is a legitimate edit),
+ * and deleting that asset must not take the submission's file with it. Such bytes are KEPT,
+ * read in this transaction, and the call returns normally (`{ deleted: false, heldBy:
+ * 'ingest' }`): the studio deletes an asset's bytes BEFORE its row (`deleteAsset`), so a
+ * refusal would leave the asset undeletable, while keeping them is the correct ownership —
+ * the asset row goes, the submission keeps its file, and removing the submission deletes it
+ * (`releaseIngestUploads`, the mirror check).
+ */
 export const deleteBlob = mutation({
   args: { storageKey: v.string() },
-  handler: async (ctx, { storageKey }) => {
+  handler: async (ctx, { storageKey }): Promise<{ deleted: true } | { deleted: false; heldBy: 'ingest' }> => {
     // EC-150 / EC-304: destructive — gate at `editor`, matching `assets:remove`.
     // Under the old `requireUserId` an authenticated non-member could delete the
     // bytes of any published asset (storageKeys are harvestable from the public
     // `delivery:snapshot`), knocking every image off the live site.
     await requireCapability(ctx, 'content.write')
+    if (await ingestBindingHolds(ctx, storageKey)) return { deleted: false, heldBy: 'ingest' }
     await ctx.storage.delete(asStorageId(storageKey))
+    return { deleted: true }
   },
 })

package/convex/ingest-attempt.test.ts

@@ -0,0 +1,161 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { v } from 'convex/values'
+import { z } from 'zod'
+import { INGEST_RECEIVER_PATH, signedIngestRequest } from '@elytracms/core/ingest'
+import type { IngestHandlerResult } from '@elytracms/core/ingest'
+import { defineRecordKind } from '@elytracms/core/persistence'
+import schema from './schema'
+import { internalMutation } from './functions'
+import { defineStudioHttp } from './http'
+import { INGEST_HANDLER_ATTEMPTS, ingestHandlerArgs, parseIngestPayload } from './ingest'
+import type { IngestHandlerRef } from './ingest'
+import { saveRecord } from './record-functions'
+
+/**
+ * EC-618 (the ratified low-volume lever, the critic's correction 1) — the receiver RETRIES a
+ * handler whose mutation THREW, with an additive, optional `attempt` argument. A Convex mutation
+ * cannot observe its own optimistic-concurrency conflict: Convex re-executes it, and exhaustion
+ * surfaces only to the caller — the receiver's `ctx.runMutation` (measured on the dev deployment
+ * in wave-0095: every receiver 500 of the burst was an `analytics:ingest` execution that failed
+ * after its retries). So the receiver is where a handler gets its next attempt; analytics uses
+ * it to open an overflow shard, every other handler ignores it.
+ *
+ * convex-test SERIALISES mutations, so no write conflict can happen here: the failure is
+ * INJECTED (a handler that writes, then throws on its early attempts). What this proves is the
+ * receiver's contract — attempt 1 carries no `attempt` key, a throw is retried with `attempt: n`,
+ * a thrown attempt committed nothing, a refusal is final, the attempts are bounded — never
+ * Convex's OCC (that is the dev-deployment burst, `pnpm dev:ingest rosy-armadillo-302 ec618-burst`).
+ */
+
+const SECRET = 'ec618-attempt-secret'
+const env = () => (globalThis as { process: { env: Record<string, string | undefined> } }).process.env
+
+const hitKind = defineRecordKind({
+  kind: 'testHit',
+  module: 'testAttempt',
+  keys: ['label'],
+  fields: { label: z.string().min(1), attempt: z.number().int().positive() },
+})
+
+/** Every execution the handlers saw, with the `attempt` they were given (`undefined` = the key was absent). */
+let seen: { handler: string; attempt: number | undefined; keys: string[] }[] = []
+/** The flaky handler throws on every attempt below this one (after writing — the write must not commit). */
+let succeedFrom = 1
+
+async function writeHit(ctx: Parameters<typeof saveRecord>[0], label: string, attempt: number, receivedAt: string) {
+  const id = `hit_${(await ctx.db.query('records').collect()).length + 1}`
+  await saveRecord(ctx, hitKind, id, { label, attempt }, { createdAt: receivedAt, updatedAt: receivedAt })
+  return id
+}
+
+const testAttemptModule = {
+  /** Writes its hit, then throws while `attempt < succeedFrom` — an exhausted write conflict, injected. */
+  flaky: internalMutation({
+    args: ingestHandlerArgs,
+    handler: async (ctx, args): Promise<IngestHandlerResult> => {
+      seen.push({ handler: 'flaky', attempt: args.attempt, keys: Object.keys(args).sort() })
+      const payload = parseIngestPayload(args.payload)
+      const attempt = args.attempt ?? 1
+      const id = await writeHit(ctx, payload.kind === 'event' ? String(payload.data['name']) : payload.kind, attempt, args.receivedAt)
+      if (attempt < succeedFrom) throw new Error(`injected: the write conflicted on every retry (attempt ${attempt})`)
+      return { ok: true, id }
+    },
+  }),
+  /** A handler declared with the PRE-attempt arguments (strict: an extra key would be refused). */
+  legacy: internalMutation({
+    args: { payload: v.any(), receivedAt: v.string() },
+    handler: async (ctx, args): Promise<IngestHandlerResult> => {
+      seen.push({ handler: 'legacy', attempt: undefined, keys: Object.keys(args).sort() })
+      return { ok: true, id: await writeHit(ctx, 'legacy', 1, args.receivedAt) }
+    },
+  }),
+  /** A refusal is an ANSWER, not a failure: never retried. */
+  refusing: internalMutation({
+    args: ingestHandlerArgs,
+    handler: async (_ctx, args): Promise<IngestHandlerResult> => {
+      seen.push({ handler: 'refusing', attempt: args.attempt, keys: Object.keys(args).sort() })
+      return { ok: false, status: 409, message: 'Refused on purpose.' }
+    },
+  }),
+}
+
+const ref = (name: string) => makeFunctionReference<'mutation'>(`testAttempt:${name}`) as unknown as IngestHandlerRef
+const silentAuth = { addHttpRoutes: () => {} }
+
+function backend(event: IngestHandlerRef) {
+  return convexTest(schema, {
+    ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+    './_generated/api.ts': async () => ({}),
+    './testAttempt.ts': async () => testAttemptModule,
+    './http.ts': async () => ({ default: defineStudioHttp({ auth: silentAuth, ingest: { event } }) }),
+  })
+}
+
+async function post(t: ReturnType<typeof backend>, name = 'pageview') {
+  const signed = await signedIngestRequest({ kind: 'event', data: { name } }, SECRET)
+  return t.fetch(INGEST_RECEIVER_PATH, { method: 'POST', headers: signed.headers, body: signed.body })
+}
+
+async function hits(t: ReturnType<typeof backend>) {
+  return t.run(async (ctx) =>
+    (await ctx.db.query('records').collect()).filter((row) => row.kind === hitKind.kind).map((row) => row.data as { label: string; attempt: number }),
+  )
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date('2026-10-28T12:00:00.000Z'))
+  env()['ELYTRA_INGEST_SECRET'] = SECRET
+  seen = []
+  succeedFrom = 1
+})
+afterEach(() => {
+  vi.useRealTimers()
+  delete env()['ELYTRA_INGEST_SECRET']
+})
+
+describe('the receiver retries a handler that THREW, with an additive `attempt` (EC-618)', () => {
+  it('attempt 1 carries no `attempt` key — a handler declared with the pre-attempt arguments runs unchanged', async () => {
+    const t = backend(ref('legacy'))
+    expect((await post(t)).status).toBe(200)
+    expect(seen).toEqual([{ handler: 'legacy', attempt: undefined, keys: ['payload', 'receivedAt'] }])
+    expect(await hits(t)).toEqual([{ label: 'legacy', attempt: 1 }])
+  })
+
+  it('a throw is retried with `attempt: 2`; the thrown attempt committed nothing (no double count)', async () => {
+    succeedFrom = 2
+    const t = backend(ref('flaky'))
+    const response = await post(t)
+    expect(response.status).toBe(200)
+    expect(seen.map((entry) => entry.attempt)).toEqual([undefined, 2])
+    expect(seen[1]!.keys).toEqual(['attempt', 'payload', 'receivedAt'])
+    // Attempt 1 wrote its hit and threw: rolled back. Only attempt 2's write is stored.
+    expect(await hits(t)).toEqual([{ label: 'pageview', attempt: 2 }])
+  })
+
+  it('the attempts are bounded: a handler that throws every time is run INGEST_HANDLER_ATTEMPTS times, then the failure surfaces', async () => {
+    succeedFrom = Number.POSITIVE_INFINITY
+    const t = backend(ref('flaky'))
+    // convex-test rethrows a throwing httpAction to the caller; a deployment answers 500.
+    await expect(post(t)).rejects.toThrow(/injected: the write conflicted on every retry \(attempt 3\)/)
+    expect(INGEST_HANDLER_ATTEMPTS).toBe(3)
+    expect(seen.map((entry) => entry.attempt)).toEqual([undefined, 2, 3])
+    expect(await hits(t)).toEqual([]) // nothing committed by any of them
+  })
+
+  it('a refusal is final — relayed as it was, never retried', async () => {
+    const t = backend(ref('refusing'))
+    const response = await post(t)
+    expect(response.status).toBe(409)
+    expect(seen).toHaveLength(1)
+  })
+
+  it('control — without a failure every request runs its handler exactly once (the instrument can count one)', async () => {
+    const t = backend(ref('flaky'))
+    for (let i = 0; i < 5; i += 1) expect((await post(t, `e${i}`)).status).toBe(200)
+    expect(seen.map((entry) => entry.attempt)).toEqual([undefined, undefined, undefined, undefined, undefined])
+    expect((await hits(t)).map((hit) => hit.attempt)).toEqual([1, 1, 1, 1, 1])
+  })
+})

package/convex/ingest.test.ts

@@ -6,6 +6,7 @@ import {
   INGEST_MAX_BODY_BYTES,
   INGEST_RECEIVER_PATH,
   INGEST_SIGNATURE_HEADER,
+  ingestUploadSha256,
   signedIngestRequest,
 } from '@elytracms/core/ingest'
 import type { IngestHandlerResult, IngestPayload } from '@elytracms/core/ingest'
@@ -186,6 +187,13 @@ async function storeFile(t: ReturnType<typeof backend>, bytes: number, contentTy
   })
 }
 
+/** EC-685: the SHA-256 an upload declares for the zero-filled `bytes` bytes {@link storeFile} stores. */
+async function sha256Of(bytes: number): Promise<string> {
+  const digest = await ingestUploadSha256(new Uint8Array(bytes))
+  if (!digest.ok) throw new Error(digest.message)
+  return digest.sha256
+}
+
 /** Whether stored bytes exist (`storage.get` yields a Blob, which is not a Convex value: answer a boolean). */
 function stored(t: ReturnType<typeof backend>, storageId: string): Promise<boolean> {
   return t.run(async (ctx) => (await ctx.storage.get(storageId as never)) !== null)
@@ -265,7 +273,7 @@ describe('the ingest receiver — dispatch (EC-617)', () => {
   it('an upload the handler accepts gets ONE storage URL and an upload id; one it refuses gets none', async () => {
     env()['ELYTRA_INGEST_SECRET'] = SECRET
     const t = backend()
-    const upload = { kind: 'upload', target: 'contact', field: 'cv', contentType: 'image/png', size: 500 } as const
+    const upload = { kind: 'upload', target: 'contact', field: 'cv', contentType: 'image/png', size: 500, sha256: await sha256Of(500) } as const
     const issued = await signedPost(t, upload)
     expect(issued.status).toBe(200)
     const body = (await issued.json()) as { uploadId: string; uploadUrl: string; expiresInSeconds: number }
@@ -274,23 +282,45 @@ describe('the ingest receiver — dispatch (EC-617)', () => {
     expect(body.expiresInSeconds).toBe(3600)
     expect((await signedPost(t, { ...upload, size: 5000 })).status).toBe(413) // the handler's policy
     expect((await signedPost(t, { ...upload, contentType: 'application/x-msdownload' })).status).toBe(415)
+    // EC-685: the intent records the declared digest (what the claim compares).
+    const intent = await t.run(async (ctx) => (await ctx.db.query('records').collect()).find((row) => row.recordId === body.uploadId))
+    expect((intent!.data as { sha256: string }).sha256).toBe(upload.sha256)
+  })
+
+  it('EC-685 wire: an upload that declares no sha256, or one in another encoding, is a 400 — no intent, no URL', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const base = { kind: 'upload', target: 'contact', field: 'cv', contentType: 'image/png', size: 500 } as const
+    const hex = await sha256Of(500)
+    for (const payload of [base, { ...base, sha256: hex.toUpperCase() }, { ...base, sha256: hex.slice(1) }]) {
+      const raw = JSON.stringify(payload)
+      const answer = await t.fetch(INGEST_RECEIVER_PATH, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', [INGEST_SIGNATURE_HEADER]: await signedIngestRequestRaw(raw) },
+        body: raw,
+      })
+      expect(answer.status, raw).toBe(400) // the receiver's union (payload | probe) reports it at the root; the route's read names `sha256` (core test)
+    }
+    expect(await t.run(async (ctx) => (await ctx.db.query('records').collect()).length)).toBe(0)
+    // Control: the declared lowercase hex is accepted.
+    expect((await signedPost(t, { ...base, sha256: hex })).status).toBe(200)
   })
 
   it('a submission claims its upload: the stored file must match the declaration; a mismatch is refused, never deleted', async () => {
     env()['ELYTRA_INGEST_SECRET'] = SECRET
     const t = backend()
-    const declare = async (contentType: string, size: number) =>
-      ((await (await signedPost(t, { kind: 'upload', target: 'contact', field: 'cv', contentType, size })).json()) as {
+    const declare = async (contentType: string, size: number, bytesOf: number) =>
+      ((await (await signedPost(t, { kind: 'upload', target: 'contact', field: 'cv', contentType, size, sha256: await sha256Of(bytesOf) })).json()) as {
         uploadId: string
       }).uploadId
-    const good = await declare('image/png', 500)
+    const good = await declare('image/png', 500, 400)
     const goodFile = await storeFile(t, 400, 'image/png')
     const ok = await signedPost(t, { ...SUBMISSION, uploads: [{ uploadId: good, storageId: goodFile }] })
     expect(ok.status).toBe(200)
     // A second claim of the same upload is a conflict.
     expect((await signedPost(t, { ...SUBMISSION, uploads: [{ uploadId: good, storageId: goodFile }] })).status).toBe(409)
 
-    const liar = await declare('image/png', 500)
+    const liar = await declare('image/png', 500, 10) // its own bytes: the mismatch is the type
     const wrongType = await storeFile(t, 10, 'text/html')
     expect((await signedPost(t, { ...SUBMISSION, uploads: [{ uploadId: liar, storageId: wrongType }] })).status).toBe(415)
     // EC-671: refused and KEPT — a claim never deletes the id it names (it is the visitor's word).
@@ -301,7 +331,7 @@ describe('the ingest receiver — dispatch (EC-617)', () => {
   it('an upload no submission claims is listed once its life is over (the visible orphan finding)', async () => {
     env()['ELYTRA_INGEST_SECRET'] = SECRET
     const t = backend()
-    await signedPost(t, { kind: 'upload', target: 'contact', field: 'cv', contentType: 'image/png', size: 10 })
+    await signedPost(t, { kind: 'upload', target: 'contact', field: 'cv', contentType: 'image/png', size: 10, sha256: await sha256Of(10) })
     const later = (offsetMs: number) => new Date(Date.parse('2026-10-26T12:00:00.000Z') + offsetMs).toISOString()
     expect(await t.run((ctx) => unclaimedIngestUploads(ctx, 'contact', later(30 * 60 * 1000)))).toEqual([])
     const orphans = await t.run((ctx) => unclaimedIngestUploads(ctx, 'contact', later(2 * 60 * 60 * 1000)))
@@ -318,8 +348,9 @@ describe('the ingest receiver — dispatch (EC-617)', () => {
  */
 describe('the claim binds only this intent’s bytes; release deletes only bound bytes (EC-671)', () => {
   const PNG = { kind: 'upload', target: 'contact', field: 'cv', contentType: 'image/png', size: 500 } as const
-  async function declare(t: ReturnType<typeof backend>): Promise<string> {
-    return ((await (await signedPost(t, PNG)).json()) as { uploadId: string }).uploadId
+  /** An intent declaring a png of up to 500 bytes whose content is the `bytesOf` zero bytes the test then stores (EC-685). */
+  async function declare(t: ReturnType<typeof backend>, bytesOf = 400): Promise<string> {
+    return ((await (await signedPost(t, { ...PNG, sha256: await sha256Of(bytesOf) })).json()) as { uploadId: string }).uploadId
   }
   const claimWith = (t: ReturnType<typeof backend>, uploadId: string, storageId: string) =>
     signedPost(t, { ...SUBMISSION, uploads: [{ uploadId, storageId }] })
@@ -388,7 +419,7 @@ describe('the claim binds only this intent’s bytes; release deletes only bound
   it('(3) a file an asset row references — as its file or as its preview — is refused; control: an unreferenced one is claimed', async () => {
     env()['ELYTRA_INGEST_SECRET'] = SECRET
     const t = backend()
-    const [asFile, asThumb, plain] = [await declare(t), await declare(t), await declare(t)]
+    const [asFile, asThumb, plain] = [await declare(t), await declare(t, 40), await declare(t)]
     const original = await storeFile(t, 400, 'image/png') // all stored AFTER the three intents: check (1) passes
     const preview = await storeFile(t, 40, 'image/png')
     const unreferenced = await storeFile(t, 400, 'image/png')
@@ -414,6 +445,151 @@ describe('the claim binds only this intent’s bytes; release deletes only bound
     expect(await bindings(t)).toEqual([])
   })
 
+  // EC-685 (Codex r4 F20, ordering 2): a fact checked at claim time is not permanent — an
+  // asset may acquire a bound file afterwards. Each delete path re-checks the OTHER owner.
+  async function asEditor(t: ReturnType<typeof backend>) {
+    await t.run(async (ctx) => {
+      await ctx.db.insert('members', { userId: 'user_editor', role: 'admin', createdAt: '2026-10-26T12:00:00.000Z', updatedAt: '2026-10-26T12:00:00.000Z' })
+    })
+    return t.withIdentity({ subject: 'user_editor', issuer: 'https://convex.test' })
+  }
+  const deleteBlob = makeFunctionReference<'mutation', { storageKey: string }, unknown>('assets:deleteBlob')
+
+  it('EC-685: release KEEPS a bound file an asset references now — the binding is spent, the bytes go with the asset', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const [asFile, asThumb, plain] = [await declare(t), await declare(t, 40), await declare(t)]
+    const promoted = await storeFile(t, 400, 'image/png')
+    const preview = await storeFile(t, 40, 'image/png')
+    const unreferenced = await storeFile(t, 400, 'image/png')
+    for (const [uploadId, file] of [[asFile, promoted], [asThumb, preview], [plain, unreferenced]] as const) {
+      expect((await claimWith(t, uploadId, file)).status).toBe(200)
+    }
+    // An editor promotes two of the uploads to an asset (its file and its preview) — after the claims.
+    await insertAsset(t, { storageKey: promoted, thumb: preview })
+    const released = await t.run((ctx) => releaseIngestUploads(ctx, [promoted, preview, unreferenced]))
+    expect(released).toEqual({ deleted: [unreferenced], kept: [promoted, preview] })
+    expect([await stored(t, promoted), await stored(t, preview), await stored(t, unreferenced)]).toEqual([true, true, false])
+    expect(await bindings(t)).toEqual([]) // ownership passed: no binding is left to hold the asset's bytes
+    // …so the asset's own delete now deletes them (control: deleteBlob deletes unbound bytes).
+    const editor = await asEditor(t)
+    expect(await editor.mutation(deleteBlob, { storageKey: promoted })).toEqual({ deleted: true })
+    expect(await stored(t, promoted)).toBe(false)
+  })
+
+  it('EC-685 mirror: assets:deleteBlob KEEPS bytes an ingest binding holds and returns normally; release then deletes them', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const uploadId = await declare(t)
+    const own = await storeFile(t, 400, 'image/png')
+    expect((await claimWith(t, uploadId, own)).status).toBe(200)
+    await insertAsset(t, { storageKey: own }) // promoted to an asset while the submission still holds it
+    const editor = await asEditor(t)
+    expect(await editor.mutation(deleteBlob, { storageKey: own })).toEqual({ deleted: false, heldBy: 'ingest' })
+    expect(await stored(t, own)).toBe(true)
+    expect(await bindings(t)).toEqual([{ storageId: own, uploadId }])
+    // The asset row goes (the studio's `assets:remove`); the submission's release deletes the bytes.
+    await t.run(async (ctx) => {
+      for (const row of await ctx.db.query('assets').collect()) await ctx.db.delete(row._id)
+    })
+    expect(await t.run((ctx) => releaseIngestUploads(ctx, [own]))).toEqual({ deleted: [own], kept: [] })
+    expect(await stored(t, own)).toBe(false)
+  })
+
+  // EC-685 (Codex r4 F20, ordering 1): checks (1)–(3) are eligibility; (4) is causation.
+  async function storeBytes(t: ReturnType<typeof backend>, bytes: Uint8Array<ArrayBuffer>, contentType: string) {
+    return t.run(async (ctx) => {
+      const id = await ctx.storage.store(new Blob([bytes], { type: contentType }))
+      await (ctx.db as unknown as { patch(id: unknown, value: unknown): Promise<void> }).patch(id, { contentType })
+      return id
+    })
+  }
+  const setStoredDigest = (t: ReturnType<typeof backend>, storageId: string, sha256: string) =>
+    t.run(async (ctx) => {
+      await (ctx.db as unknown as { patch(id: unknown, value: unknown): Promise<void> }).patch(storageId, { sha256 })
+    })
+
+  it('(4) EC-685: a file stored after the intent, unbound, no asset’s — but not the DECLARED bytes — is refused, rejected and kept', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const uploadId = await declare(t) // declares 400 zero bytes
+    const other = await storeBytes(t, new Uint8Array(400).fill(7), 'image/png') // same type and size, other bytes
+    const refused = await claimWith(t, uploadId, other)
+    expect(refused.status).toBe(422)
+    // The ONE answer of checks (1)–(4): which one failed is not the visitor's to learn.
+    expect(await refused.json()).toEqual({ error: `Upload “${uploadId}” did not store the file “${other}”.` })
+    expect(await intentState(t, uploadId)).toEqual({ state: 'rejected', storageId: other })
+    expect(await stored(t, other)).toBe(true)
+    expect(await bindings(t)).toEqual([])
+    // Control: the declared bytes, stored after their intent, are claimed.
+    const fresh = await declare(t)
+    const own = await storeFile(t, 400, 'image/png')
+    expect((await claimWith(t, fresh, own)).status).toBe(200)
+  })
+
+  it('EC-685: the comparator reads the stored digest by its FORM — convex-test’s base64 (measured) and hex both match', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const first = await declare(t)
+    const asStored = await storeFile(t, 400, 'image/png')
+    const stamped = await t.run(async (ctx) => ((await ctx.db.system.get(asStored as never)) as { sha256: string }).sha256)
+    expect(stamped).toMatch(/^[A-Za-z0-9+/]{43}=$/) // convex-test 0.0.54 fills `_storage.sha256` with base64 (`blobSha`)
+    expect((await claimWith(t, first, asStored)).status).toBe(200)
+    // The same digest in hex (`storage.getMetadata`'s documented form) reads the same.
+    const second = await declare(t)
+    const asHex = await storeFile(t, 400, 'image/png')
+    await setStoredDigest(t, asHex, (await sha256Of(400)).toUpperCase())
+    expect((await claimWith(t, second, asHex)).status).toBe(200)
+  })
+
+  it('EC-685: a stored digest in NEITHER form is refused visibly with its own reason, never read as a match', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const uploadId = await declare(t)
+    const own = await storeFile(t, 400, 'image/png')
+    // A base64url spelling of the right digest is still neither form: refused, not guessed at.
+    const url = btoa(String.fromCharCode(...Array.from((await sha256Of(400)).match(/../g)!, (pair) => parseInt(pair, 16))))
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '')
+    await setStoredDigest(t, own, url)
+    const refused = await claimWith(t, uploadId, own)
+    expect(refused.status).toBe(422)
+    expect(await refused.json()).toEqual({
+      error: `The deployment's stored digest of “${own}” is in neither form the claim reads (64 hex or 44 base64 characters), so the upload cannot be verified.`,
+    })
+    expect(await intentState(t, uploadId)).toEqual({ state: 'rejected', storageId: own })
+    expect(await bindings(t)).toEqual([])
+  })
+
+  it('LEGACY (EC-685): an intent issued before uploads declared a digest is refused before any write — no crash, the row untouched', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const issuedAt = '2026-10-26T12:00:00.000Z'
+    await t.run(async (ctx) => {
+      // A row as the previous release wrote it: no `sha256` column (the kind now requires one).
+      await ctx.db.insert('records', {
+        kind: 'ingestUpload',
+        recordId: 'upload_legacy',
+        data: { target: 'contact', field: 'cv', contentType: 'image/png', size: 500, state: 'issued', issuedAt },
+        key1: 'contact',
+        key2: 'issued',
+        at: issuedAt,
+        createdAt: issuedAt,
+        updatedAt: issuedAt,
+      })
+    })
+    const file = await storeFile(t, 400, 'image/png')
+    const refused = await claimWith(t, 'upload_legacy', file)
+    expect(refused.status).toBe(422)
+    expect(await refused.json()).toEqual({
+      error: 'Upload “upload_legacy” was issued before uploads declared their SHA-256 — upload the file again.',
+    })
+    expect(await intentState(t, 'upload_legacy')).toEqual({ state: 'issued', storageId: undefined })
+    expect(await bindings(t)).toEqual([])
+    expect(await stored(t, file)).toBe(true)
+  })
+
   it('the binding row is flat — its stored nesting is far inside Convex’s limit', async () => {
     env()['ELYTRA_INGEST_SECRET'] = SECRET
     const t = backend()