@elytracms/studio 0.0.92 → 0.0.94

package/convex/contract-parity.test.ts

@@ -3,11 +3,17 @@ import { convexTest } from 'convex-test'
 import type { ConvexHttpClient } from 'convex/browser'
 import type { FunctionReference } from 'convex/server'
 import { fieldPath, measureMaxDepth, nodePropPath } from '@elytracms/core/cms-core'
-import { PERSISTENCE_CONTRACT_SCENARIOS, replaceAtCurrentRevision } from '@elytracms/core/persistence'
+import {
+  CONTRACT_RECORD_KINDS,
+  PERSISTENCE_CONTRACT_SCENARIOS,
+  publishCurrentDraft,
+  replaceAtCurrentRevision,
+} from '@elytracms/core/persistence'
 import type { ContractContext } from '@elytracms/core/persistence'
 import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
 import type { ReactiveDocumentClient } from '../src/lib/persistence/convex-client'
 import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
 
 /**
  * EC-454 — Convex-side contract parity, restored.
@@ -36,6 +42,11 @@ import schema from './schema'
 const modules = {
   ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
   './_generated/api.ts': async () => ({}),
+  // EC-616: the contract's FIXTURE record kinds, registered as test-only modules exactly as
+  // an addon's convex module registers its kind (one module per kind, named by the kind).
+  ...Object.fromEntries(
+    CONTRACT_RECORD_KINDS.map((kind) => [`./${kind.module}.ts`, async () => defineRecordFunctions(kind)]),
+  ),
 }
 
 /** The config-owned slug this deployment's records are stamped with (EC-179). */
@@ -190,8 +201,7 @@ describe('EC-286 write-chokepoint triggers (Convex-only: in-transaction referenc
     )
 
     // Pinning a version re-runs maintenance: published rows mirror the draft rows.
-    const v = await adapter.cms.saveDocumentVersion(projectId, doc, { label: 'published' })
-    await adapter.cms.publishDocumentVersion(projectId, ref, v.version)
+    await publishCurrentDraft(adapter.cms, projectId, ref)
     expect(
       (await adapter.references.outbound(projectId, source, { variant: 'published' })).length,
     ).toBe(2)
@@ -266,6 +276,18 @@ describe('EC-260 fold-at-rest (Convex-only: the stored form respects the depth c
     })
     expect(atRest).toBeDefined()
     expect(measureMaxDepth(atRest).depth).toBeLessThanOrEqual(16) // folded at rest
+
+    // EC-585: the publish step's version row now carries `kind` — a top-level scalar
+    // beside the folded snapshot, so the WHOLE stored row stays within the cap.
+    await publishCurrentDraft(adapter.cms, PROJECT_ID, { collection: doc.collection, id: doc.id })
+    const versionRow = await t.run(async (ctx) =>
+      ctx.db
+        .query('documentVersions')
+        .withIndex('by_doc_version', (q) => q.eq('collection', doc.collection).eq('docId', doc.id).eq('version', 1))
+        .unique(),
+    )
+    expect(versionRow?.kind).toBe('publish')
+    expect(measureMaxDepth(versionRow).depth).toBeLessThanOrEqual(16)
   })
 })
 

package/convex/delivery.ts

@@ -1,12 +1,14 @@
 import { v } from 'convex/values'
-import { DRAFT_PERSPECTIVE, DRAFT_VARIANT, unfoldValue, variantOf } from '@elytracms/core/cms-core'
+import { DRAFT_PERSPECTIVE, DRAFT_VARIANT, liveRedirectRecords, unfoldValue, variantOf } from '@elytracms/core/cms-core'
 import type { Perspective } from '@elytracms/core/cms-core'
 import { assetRecordFromRow, deliveryAssetRecord } from '@elytracms/core/persistence'
+import { constantTimeEquals } from '@elytracms/core/revalidation'
 import type { AssetRecord } from '@elytracms/core/persistence'
 import studioPackage from '../package.json'
 import { query } from './functions'
 import type { QueryCtx } from './functions'
 import { requireCapability } from './guard'
+import { loadRedirectEntries } from './redirects'
 
 // EC-207: routes/redirects are config-sourced (authored in elytra.config.ts and
 // resolved by studio-core), NOT backend data. The delivery snapshot no longer
@@ -156,13 +158,12 @@ export async function loadSnapshot(
 
   const assets = await loadDeliveryAssets(ctx, projectId)
 
-  // Editorial redirects (EC-303): only ENABLED entries serve — a disabled redirect
-  // is stored but never live, in either perspective. Projected to the routing
-  // `RedirectRecord` shape the router/`resolvePage` consume.
-  const redirectRows = await ctx.db.query('redirects').withIndex('by_redirect').collect()
-  const redirects = redirectRows
-    .filter((row) => row.enabled)
-    .map((row) => ({ id: row.redirectId, from: row.from, to: row.to, permanent: row.permanent }))
+  // Editorial redirects (EC-303): only ENABLED entries serve — a disabled redirect is
+  // stored but never live, in either perspective. EC-616: read through the redirect
+  // kind's one server-side reader (records + the marked legacy tolerant read) and
+  // projected by the ONE enabled-redirect reader, `liveRedirectRecords` (EC-590 / EC-627 —
+  // this was the last hand-built copy on Convex).
+  const redirects = liveRedirectRecords(await loadRedirectEntries(ctx, projectId))
 
   return {
     projectId,
@@ -214,7 +215,9 @@ export const draftSnapshot = query({
     if (expected === undefined || expected.length === 0) {
       throw new Error('unauthorized: draft preview is not configured on this deployment')
     }
-    if (args.token !== expected) {
+    // EC-617: the one timing-safe comparison (`constantTimeEquals`, the MAC-compare the
+    // revalidation and ingest verifiers rest on) — never a string `!==`.
+    if (!(await constantTimeEquals(args.token, expected))) {
       throw new Error('unauthorized: invalid draft preview token')
     }
     return loadSnapshot(ctx, { projectId: args.projectId }, DRAFT_PERSPECTIVE)

package/convex/document-revalidate.test.ts

@@ -39,8 +39,7 @@ const modules = {
 
 const replaceDocument = makeFunctionReference<'mutation'>('cms:replaceDocument')
 const getDocument = makeFunctionReference<'query'>('cms:getDocument')
-const saveVersion = makeFunctionReference<'mutation'>('cms:saveDocumentVersion')
-const publishVersion = makeFunctionReference<'mutation'>('cms:publishDocumentVersion')
+const publishDocument = makeFunctionReference<'mutation'>('cms:publishDocument')
 const unpublishDocument = makeFunctionReference<'mutation'>('cms:unpublishDocument')
 const deleteDocument = makeFunctionReference<'mutation'>('cms:deleteDocument')
 const deliverySnapshot = makeFunctionReference<'query'>('delivery:snapshot')
@@ -104,19 +103,18 @@ async function saveDraft({ asAdmin }: Backend, collection: string, id: string, v
   })
 }
 
+/**
+ * Publish `values` the way the one publish operation does (EC-585): the draft holds them,
+ * then the one-step `publishDocument` records a publish-kind version and pins it.
+ */
 async function publish(backend: Backend, collection: string, id: string, values: Record<string, unknown>) {
-  const version = (await backend.asAdmin.mutation(saveVersion, {
+  await saveDraft(backend, collection, id, values)
+  const current = (await backend.asAdmin.query(getDocument, { collection, docId: id })) as { revision: number }
+  await backend.asAdmin.mutation(publishDocument, {
     collection,
     docId: id,
-    snapshot: doc(collection, id, values),
-    createdAt: STAMP,
-  })) as { version: number }
-  await backend.asAdmin.mutation(publishVersion, {
-    collection,
-    docId: id,
-    version: version.version,
-    updatedAt: STAMP,
-    publishedAt: STAMP,
+    expectedRevision: current.revision,
+    at: STAMP,
   })
 }
 

package/convex/guard.ts

@@ -1,7 +1,8 @@
 import { getAuthUserId } from '@convex-dev/auth/server'
-import { defaultRolePolicy, roleGrantsCapability } from '@elytracms/core/persistence'
+import { roleGrantsCapability } from '@elytracms/core/persistence'
 import type { OperationCapabilityId, ProjectRole, RolePolicy } from '@elytracms/core/persistence'
 import type { QueryCtx } from './functions'
+import { deployedRolePolicy } from './roles'
 
 /**
  * Server-side authorization guards (EC-150). The operations chokepoint in the
@@ -18,9 +19,10 @@ import type { QueryCtx } from './functions'
  * imported here rather than re-declared. Handlers gate on CAPABILITIES
  * (`content.read` / `content.write` / `project.administer`), not literal roles
  * (EC-240c), so a project's custom role set enforces server-side by the same
- * policy the operations layer uses. The Convex trust boundary reads the shipped
- * {@link defaultRolePolicy}; a project overriding roles injects its policy (the
- * documented follow-up seam).
+ * policy the operations layer uses. EC-605: the policy is the project's `roles`
+ * declaration as DEPLOYED — the copy the `elytra` CLI provisions into
+ * `ELYTRA_ROLE_POLICY` (`./roles` `deployedRolePolicy`: the default when unset, a
+ * thrown, located error when malformed — never a silent default).
  *
  * Failures throw plain `Error('unauthorized: …')` — Convex transports the
  * message; the app's adapters normalize thrown backend errors onto the
@@ -78,13 +80,13 @@ export async function memberRole(ctx: GuardCtx, userId: string): Promise<Project
  * This is the ONE role-enforcement primitive at the trust boundary — every
  * handler gates on a capability rather than a literal role, so a project's
  * custom role set is honoured by the shared policy. `policy` defaults to the
- * shipped {@link defaultRolePolicy}; the override seam (a project injecting its
- * own policy) is the documented follow-up.
+ * deployment's policy (EC-605, {@link deployedRolePolicy}); the parameter stays for a
+ * caller that must judge against another (tests).
  */
 export async function requireCapability(
   ctx: GuardCtx,
   capability: OperationCapabilityId,
-  policy: RolePolicy = defaultRolePolicy,
+  policy: RolePolicy = deployedRolePolicy(),
 ): Promise<string> {
   const userId = await requireUserId(ctx)
   const actual = await memberRole(ctx, userId)

package/convex/http-routes.test.ts

@@ -33,9 +33,20 @@ function routeTable(http: HttpRouter): string[] {
     .sort()
 }
 
-describe('defineStudioHttp — the engine registers no HTTP routes of its own (EC-481)', () => {
-  it('contributes an EMPTY route table beyond what the injected auth registers', () => {
-    expect(routeTable(defineStudioHttp({ auth: silentAuth }))).toEqual([])
+/** EC-617: the engine's ONE route — the public-ingest receiver, an exact path (the EC-481 bar: a real client, a narrow prefix). */
+const ENGINE_ROUTES = ['POST /elytra/ingest']
+
+describe('defineStudioHttp — the engine registers exactly one HTTP route of its own (EC-481 → EC-617)', () => {
+  it('contributes ONLY the ingest receiver beyond what the injected auth registers', () => {
+    expect(routeTable(defineStudioHttp({ auth: silentAuth }))).toEqual(ENGINE_ROUTES)
+  })
+
+  it('the receiver is an EXACT path, POST only — it claims no prefix', () => {
+    const http = defineStudioHttp({ auth: silentAuth })
+    expect(http.lookup('/elytra/ingest', 'POST')).not.toBeNull()
+    expect(http.lookup('/elytra/ingest/anything', 'POST')).toBeNull()
+    expect(http.lookup('/elytra/', 'POST')).toBeNull()
+    expect(http.lookup('/elytra/ingest', 'GET')).toBeNull()
   })
 
   it('control: the recorder DOES see routes, so the empty result above is real', () => {
@@ -45,10 +56,9 @@ describe('defineStudioHttp — the engine registers no HTTP routes of its own (E
         http.route({ pathPrefix: '/api/auth/callback/', method: 'POST', handler })
       },
     }
-    expect(routeTable(defineStudioHttp({ auth }))).toEqual([
-      'GET /.well-known/jwks.json',
-      'POST /api/auth/callback/*',
-    ])
+    expect(routeTable(defineStudioHttp({ auth }))).toEqual(
+      ['GET /.well-known/jwks.json', 'POST /api/auth/callback/*', ...ENGINE_ROUTES].sort(),
+    )
   })
 
   it('passes the auth routes through untouched — nothing is added, dropped, or reordered', () => {
@@ -61,7 +71,7 @@ describe('defineStudioHttp — the engine registers no HTTP routes of its own (E
         }
       },
     }
-    expect(routeTable(defineStudioHttp({ auth }))).toEqual([...registered].sort())
+    expect(routeTable(defineStudioHttp({ auth }))).toEqual([...registered, ...ENGINE_ROUTES].sort())
   })
 })
 

package/convex/http.ts

@@ -1,5 +1,8 @@
 import { httpRouter } from 'convex/server'
 import type { HttpRouter } from 'convex/server'
+import { INGEST_RECEIVER_PATH } from '@elytracms/core/ingest'
+import { ingestReceiver } from './ingest'
+import type { IngestHandlers } from './ingest'
 
 /** The slice of the Convex Auth object the studio's HTTP routes need. */
 interface AuthHttpRoutes {
@@ -8,33 +11,36 @@ interface AuthHttpRoutes {
 
 /**
  * EC-252 — the studio's HTTP routes as a factory. Pure engine infra ships in the
- * package; only the consumer's `auth` (provider choice) is injected. The consumer's
- * `convex/http.ts` is a two-liner:
+ * package; only the consumer's `auth` (provider choice) and — since EC-617 — its ingest
+ * handlers are injected. The consumer's `convex/http.ts`:
  *
  * ```ts
  * import { auth } from './auth'
  * export default defineStudioHttp({ auth })
+ * // with an addon that handles ingest payloads (one import, one entry):
+ * // import { formsIngest } from '@elytracms/forms/convex'
+ * // export default defineStudioHttp({ auth, ingest: { submission: formsIngest } })
  * ```
  *
- * ## The engine registers NO HTTP routes of its own (EC-481)
+ * ## The engine registers exactly ONE route of its own (EC-481 → EC-617)
  *
- * Everything on this router comes from Convex Auth's `addHttpRoutes` — the JWT
- * discovery endpoints (`/.well-known/*`, EC-150) and, only when a consumer supplies
- * an OAuth provider, `/api/auth/signin/*` + `/api/auth/callback/*`.
+ * Everything else on this router comes from Convex Auth's `addHttpRoutes` — the JWT
+ * discovery endpoints (`/.well-known/*`, EC-150) and, only when a consumer supplies an
+ * OAuth provider, `/api/auth/signin/*` + `/api/auth/callback/*`.
  *
- * The engine used to add one more: `GET /api/projects/*`, the EC-157 Bearer-token
- * registry-sync endpoint backing `builder typegen`/`builder check`. EC-470 deleted
- * that CLI and with it the endpoint's only client; the handler had in any case
- * answered with config-owned placeholders since EC-287 retired the project graph
- * (`project: null`, `collections: []`). EC-481 removed the route and its handler
- * together rather than leave a Bearer-authenticated surface serving stub data on
- * every deployment. `http-routes.test.ts` pins that shut.
- *
- * A future engine-owned HTTP surface is fine — but it needs a real client and a
- * narrower prefix than `/api/projects/`.
+ * EC-481 removed the engine's former `GET /api/projects/*` (a Bearer-authenticated
+ * registry-sync endpoint with no client left) and set the bar for any future one: "a
+ * real client and a narrower prefix". EC-617's public-ingest RECEIVER is that route:
+ * `POST /elytra/ingest` — an EXACT path, not a prefix; its client is the site's
+ * `createIngestRoute` (`@elytracms/next`), which signs every payload with the
+ * server-held secret, and `elytra doctor`'s probe. It is mounted on every deployment,
+ * with or without handlers: closed (401) until `ELYTRA_INGEST_SECRET` is set, and a
+ * payload kind with no registered handler is refused visibly (422), never dropped.
+ * `http-routes.test.ts` pins the table.
  */
-export function defineStudioHttp({ auth }: { auth: AuthHttpRoutes }): HttpRouter {
+export function defineStudioHttp({ auth, ingest }: { auth: AuthHttpRoutes; ingest?: IngestHandlers }): HttpRouter {
   const http = httpRouter()
   auth.addHttpRoutes(http)
+  http.route({ path: INGEST_RECEIVER_PATH, method: 'POST', handler: ingestReceiver(ingest) })
   return http
 }

package/convex/ingest.test.ts

@@ -0,0 +1,326 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { z } from 'zod'
+import {
+  INGEST_MAX_BODY_BYTES,
+  INGEST_RECEIVER_PATH,
+  INGEST_SIGNATURE_HEADER,
+  signedIngestRequest,
+} from '@elytracms/core/ingest'
+import type { IngestHandlerResult, IngestPayload } from '@elytracms/core/ingest'
+import { defineRecordKind } from '@elytracms/core/persistence'
+import schema from './schema'
+import { internalMutation } from './functions'
+import { defineStudioHttp } from './http'
+import { claimIngestUpload, ingestHandlerArgs, parseIngestPayload, recordIngestUpload, unclaimedIngestUploads } from './ingest'
+import type { IngestHandlerRef } from './ingest'
+import { saveRecord } from './record-functions'
+import { createIngestRoute } from '../../next/src/ingest'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date('2026-10-26T12:00:00.000Z'))
+})
+afterEach(() => {
+  vi.useRealTimers()
+  delete env()['ELYTRA_INGEST_SECRET']
+  delete env()['DRAFT_PREVIEW_TOKEN']
+})
+
+/**
+ * EC-617 — the ONE inbound receiver (`POST /elytra/ingest`, `defineStudioHttp`), on
+ * convex-test with a project-registered handler (a test module standing in for an addon's
+ * `./convex` entry): 401 unconfigured / unsigned / wrong secret, 413, 400, the probe, a
+ * kind with NO handler refused visibly (422 — EC-618's gate), a handler's write and its
+ * refusal relayed, the upload URL issued after the handler accepted, and the claim checks.
+ * Then the site's route (`createIngestRoute`) driven END TO END into this receiver.
+ *
+ * convex-test runs `crypto.subtle` under edge-runtime; that the Convex default runtime has
+ * it too is the operator's dev-deployment check (the revalidation signer already runs there).
+ */
+
+const SECRET = 'ec617-shared-secret'
+function env(): Record<string, string | undefined> {
+  return (globalThis as { process: { env: Record<string, string | undefined> } }).process.env
+}
+
+/** The submission an addon would declare (forms, EC-613) — here a test kind. */
+const testSubmissionKind = defineRecordKind({
+  kind: 'testSubmission',
+  module: 'testIngest',
+  keys: ['form'],
+  fields: {
+    form: z.string().min(1),
+    values: z.record(z.string(), z.unknown()),
+    files: z.array(z.string()).optional(),
+  },
+})
+
+/** The addon's handler module: one internal mutation, the shape `IngestHandlerRef` names. */
+const testIngestModule = {
+  handle: internalMutation({
+    args: ingestHandlerArgs,
+    handler: async (ctx, args): Promise<IngestHandlerResult> => {
+      const payload: IngestPayload = parseIngestPayload(args.payload)
+      if (payload.kind === 'upload') {
+        return recordIngestUpload(ctx, payload, args.receivedAt, { maxBytes: 1000, contentTypes: ['image/*'] })
+      }
+      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)
+      }
+      const id = `sub_${(await ctx.db.query('records').collect()).length + 1}`
+      await saveRecord(
+        ctx,
+        testSubmissionKind,
+        id,
+        { form: payload.target, values: payload.data, ...(files.length ? { files } : {}) },
+        { createdAt: args.receivedAt, updatedAt: args.receivedAt },
+      )
+      return { ok: true, id }
+    },
+  }),
+}
+
+const handle = makeFunctionReference<'mutation'>('testIngest:handle') as unknown as IngestHandlerRef
+const silentAuth = { addHttpRoutes: () => {} }
+
+function backend(handlers: Parameters<typeof defineStudioHttp>[0]['ingest'] = { submission: handle }) {
+  return convexTest(schema, {
+    ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+    './_generated/api.ts': async () => ({}),
+    './testIngest.ts': async () => testIngestModule,
+    './http.ts': async () => ({ default: defineStudioHttp({ auth: silentAuth, ingest: handlers }) }),
+  })
+}
+
+async function signedPost(t: ReturnType<typeof backend>, body: Parameters<typeof signedIngestRequest>[0], secret = SECRET) {
+  const signed = await signedIngestRequest(body, secret)
+  return t.fetch(INGEST_RECEIVER_PATH, { method: 'POST', headers: signed.headers, body: signed.body })
+}
+
+const SUBMISSION = { kind: 'submission', target: 'contact', data: { email: 'ada@example.test' } } as const
+
+describe('the ingest receiver — refusals (EC-617)', () => {
+  it('401 { configured: false } while ELYTRA_INGEST_SECRET is unset — even for a signed body', async () => {
+    const t = backend()
+    const response = await signedPost(t, SUBMISSION)
+    expect(response.status).toBe(401)
+    expect(await response.json()).toMatchObject({ configured: false })
+  })
+
+  it('401 unsigned, or signed with another secret; control: the right secret is accepted', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const unsigned = await t.fetch(INGEST_RECEIVER_PATH, { method: 'POST', body: JSON.stringify(SUBMISSION) })
+    expect(unsigned.status).toBe(401)
+    expect((await signedPost(t, SUBMISSION, 'wrong-secret')).status).toBe(401)
+    expect((await signedPost(t, SUBMISSION)).status).toBe(200)
+  })
+
+  it('413 over the body cap', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const big = JSON.stringify({ ...SUBMISSION, data: { note: 'x'.repeat(INGEST_MAX_BODY_BYTES) } })
+    const response = await t.fetch(INGEST_RECEIVER_PATH, { method: 'POST', body: big })
+    expect(response.status).toBe(413)
+  })
+
+  it('400 for a signed body that is not an ingest payload', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const raw = JSON.stringify({ kind: 'submission' })
+    const { headers } = await signedIngestRequest({ kind: 'probe' }, SECRET) // headers for another body…
+    const badShape = await t.fetch(INGEST_RECEIVER_PATH, {
+      method: 'POST',
+      headers: { ...headers, [INGEST_SIGNATURE_HEADER]: (await signedIngestRequestRaw(raw)) },
+      body: raw,
+    })
+    expect(badShape.status).toBe(400)
+  })
+
+  it('the doctor’s signed probe answers 200 and dispatches nothing', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const response = await signedPost(t, { kind: 'probe' })
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ ok: true, probe: true })
+    expect(await t.run(async (ctx) => (await ctx.db.query('records').collect()).length)).toBe(0)
+  })
+
+  it('a kind with NO registered handler is refused visibly (422), never dropped — an event without analytics', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const response = await signedPost(t, { kind: 'event', data: { page: '/' } })
+    expect(response.status).toBe(422)
+    expect(await response.json()).toMatchObject({ kind: 'event', handled: false })
+    // …and with NO handlers at all, a submission is refused the same way.
+    const bare = backend({})
+    expect((await signedPost(bare, SUBMISSION)).status).toBe(422)
+  })
+})
+
+/**
+ * Store a file as an upload URL would: Convex records the uploader's Content-Type on the
+ * `_storage` row; convex-test 0.0.54's `storage.store` records only size + sha256, so the
+ * harness sets the type the real upload would have carried.
+ */
+async function storeFile(t: ReturnType<typeof backend>, bytes: number, contentType: string) {
+  return t.run(async (ctx) => {
+    const id = await ctx.storage.store(new Blob([new Uint8Array(bytes)], { type: contentType }))
+    await (ctx.db as unknown as { patch(id: unknown, value: unknown): Promise<void> }).patch(id, { contentType })
+    return id
+  })
+}
+
+/** Sign an arbitrary raw body (for the invalid-shape case the typed builder refuses to build). */
+async function signedIngestRequestRaw(raw: string): Promise<string> {
+  const { signRevalidationBody } = await import('@elytracms/core/revalidation')
+  return signRevalidationBody(raw, SECRET)
+}
+
+describe('the key rule: a payload Convex cannot carry is a 400, never a failed mutation (EC-617)', () => {
+  /** POST a raw body signed with the right secret (the typed builder would refuse it). */
+  async function postRaw(t: ReturnType<typeof backend>, payload: unknown) {
+    const raw = JSON.stringify(payload)
+    return t.fetch(INGEST_RECEIVER_PATH, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', [INGEST_SIGNATURE_HEADER]: await signedIngestRequestRaw(raw) },
+      body: raw,
+    })
+  }
+
+  it('refuses a `$`-led key, a non-ASCII key and a nested one with 400 naming the key; nothing is dispatched', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    for (const data of [{ $honeypot: '' }, { straße: 'Hauptstraße 1' }, { address: { 'straße': 'x' } }]) {
+      const response = await postRaw(t, { ...SUBMISSION, data })
+      expect(response.status, JSON.stringify(data)).toBe(400)
+      const body = (await response.json()) as { issues: { path: (string | number)[]; message: string }[] }
+      expect(body.issues[0]!.path[0]).toBe('data')
+      expect(body.issues[0]!.message).toMatch(/field name/i)
+    }
+    expect(await t.run(async (ctx) => (await ctx.db.query('records').collect()).length)).toBe(0)
+  })
+
+  it('refuses data nested deeper than Convex arguments carry, with 400', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    let deep: Record<string, unknown> = { leaf: 1 }
+    for (let level = 0; level < 80; level++) deep = { n: deep }
+    expect((await postRaw(t, { ...SUBMISSION, data: deep })).status).toBe(400)
+  })
+
+  it('control: printable-ASCII keys (spaces, dashes, dots included) reach the handler', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const response = await postRaw(t, { ...SUBMISSION, data: { 'first name': 'Ada', 'e-mail': 'a@b.c', 'a.b': 1, honeypot$: '' } })
+    expect(response.status).toBe(200)
+  })
+})
+
+describe('the ingest receiver — dispatch (EC-617)', () => {
+  it('a submission reaches the project’s handler, which writes a record; its refusal is relayed', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const accepted = await signedPost(t, SUBMISSION)
+    expect(accepted.status).toBe(200)
+    expect(await accepted.json()).toEqual({ ok: true, id: 'sub_1' })
+    const stored = await t.run(async (ctx) => (await ctx.db.query('records').collect()).filter((r) => r.kind === 'testSubmission'))
+    expect(stored.map((row) => [row.recordId, row.key1, row.data])).toEqual([
+      ['sub_1', 'contact', { form: 'contact', values: { email: 'ada@example.test' } }],
+    ])
+    const refused = await signedPost(t, { ...SUBMISSION, target: 'closed' })
+    expect(refused.status).toBe(404)
+    expect(await refused.json()).toEqual({ error: 'No form “closed”.' })
+  })
+
+  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 issued = await signedPost(t, upload)
+    expect(issued.status).toBe(200)
+    const body = (await issued.json()) as { uploadId: string; uploadUrl: string; expiresInSeconds: number }
+    expect(body.uploadId).toMatch(/^upload_/)
+    expect(typeof body.uploadUrl).toBe('string')
+    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)
+  })
+
+  it('a submission claims its upload: the stored file must match the declaration; a mismatch is 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 {
+        uploadId: string
+      }).uploadId
+    const good = await declare('image/png', 500)
+    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 wrongType = await storeFile(t, 10, 'text/html')
+    expect((await signedPost(t, { ...SUBMISSION, uploads: [{ uploadId: liar, storageId: wrongType }] })).status).toBe(415)
+    expect(await t.run((ctx) => ctx.storage.get(wrongType))).toBeNull() // deleted, never kept
+  })
+
+  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 })
+    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)))
+    expect(orphans.map((orphan) => orphan.field)).toEqual(['cv'])
+  })
+})
+
+describe('the site’s route → the receiver, end to end (EC-617)', () => {
+  it('a visitor’s submission through createIngestRoute lands a record; a mismatched site secret is a 502', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const viaReceiver = (async (url: string, init: RequestInit) =>
+      t.fetch(new URL(url).pathname, init as RequestInit)) as unknown as typeof fetch
+    const site = createIngestRoute({ secret: SECRET, siteUrl: 'https://happy-otter-123.convex.site', fetchImpl: viaReceiver })
+    const visitor = new Request('https://example.test/api/ingest', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', origin: 'https://example.test' },
+      body: JSON.stringify(SUBMISSION),
+    })
+    const answer = await site.POST(visitor)
+    expect(answer.status).toBe(200)
+    expect(await answer.json()).toEqual({ ok: true, id: 'sub_1' })
+
+    const misconfigured = createIngestRoute({ secret: 'not-the-same', siteUrl: 'https://happy-otter-123.convex.site', fetchImpl: viaReceiver })
+    const rejected = await misconfigured.POST(
+      new Request('https://example.test/api/ingest', { method: 'POST', body: JSON.stringify(SUBMISSION) }),
+    )
+    expect(rejected.status).toBe(502)
+  })
+})
+
+describe('draftSnapshot’s token check is the timing-safe helper (EC-617)', () => {
+  const draftSnapshot = makeFunctionReference<'query'>('delivery:draftSnapshot')
+
+  it('the right token reads; a wrong, a prefix or an empty token is unauthorized; unset closes it', async () => {
+    const t = backend()
+    await expect(t.query(draftSnapshot, { projectId: 'demo', token: 'x' })).rejects.toThrow(/not configured/)
+    env()['DRAFT_PREVIEW_TOKEN'] = 'preview-token-123'
+    await expect(t.query(draftSnapshot, { projectId: 'demo', token: 'preview-token-123' })).resolves.toMatchObject({
+      perspective: { variant: 'draft' },
+    })
+    for (const token of ['preview-token-124', 'preview-token-12', '', 'preview-token-1234']) {
+      await expect(t.query(draftSnapshot, { projectId: 'demo', token })).rejects.toThrow(/invalid draft preview token/)
+    }
+  })
+})