@elytracms/forms 0.0.0-stage → 0.0.95

package/src/convex/forms.convex.test.ts

@@ -0,0 +1,552 @@
+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 { CONVEX_MAX_NESTING_DEPTH, measureMaxDepth } from '@elytracms/core/cms-core'
+import { INGEST_RECEIVER_PATH, signedIngestRequest } from '@elytracms/core/ingest'
+import type { IngestReceiverBody } from '@elytracms/core/ingest'
+import { InMemoryRecordStore } from '@elytracms/core/persistence'
+import type { RecordRepository } from '@elytracms/core/persistence'
+import schema from '../../../studio/convex/schema'
+import { defineStudioHttp } from '../../../studio/convex/http'
+import { ConvexPersistenceAdapter } from '../../../studio/src/lib/persistence/convex-adapter'
+import { createIngestRoute } from '../../../next/src/ingest'
+import * as formsModule from './index'
+import { submissionRecordKind } from '../shared/kind'
+import type { DeliveryEntry, SubmissionRecord } from '../shared/kind'
+import { DELIVERY_MAX_ATTEMPTS, FORMS_DELIVERY_URL_ENV } from '../shared/delivery'
+import { FORMS_HONEYPOT_KEY, FORMS_SOURCE_KEY, FORMS_TARGET_FIELD } from '../shared/submission'
+import { defineFormSource } from '../shared/source'
+import { createFormPostRoute, createFormsDeliveryRoute } from '../next/routes'
+import type { FormMail } from '../next/routes'
+
+/**
+ * EC-613 — the forms addon's Convex half on convex-test, over the ENGINE's schema and receiver
+ * (`defineStudioHttp` with the addon's handler registered, exactly the consumer's `http.ts`
+ * line): the receiver's submissions and uploads, the scheduled delivery per row (fake timers +
+ * `finishAllScheduledFunctions`, the site reached through a stubbed `fetch` that runs the
+ * addon's own delivery route with a fake TRANSPORT — no real timer, no real network), the
+ * retry, the per-recipient log, the editor's retry, the multi-session write, the uploads'
+ * lifecycle, and the kind's contract in both adapters.
+ */
+
+const SECRET = 'ec613-ingest-secret'
+const DELIVERY_URL = 'https://site.test/api/forms'
+const PROJECT_ID = 'forms-test'
+const ADMIN = 'user_admin'
+const T0 = '2026-10-26T12:00:00.000Z'
+
+function env(): Record<string, string | undefined> {
+  return (globalThis as { process: { env: Record<string, string | undefined> } }).process.env
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date(T0))
+  env()['ELYTRA_INGEST_SECRET'] = SECRET
+  env()[FORMS_DELIVERY_URL_ENV] = DELIVERY_URL
+})
+afterEach(() => {
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+  delete env()['ELYTRA_INGEST_SECRET']
+  delete env()[FORMS_DELIVERY_URL_ENV]
+})
+
+// --- The harness: the engine's schema + receiver, the addon's module -----------------------
+
+const silentAuth = { addHttpRoutes: () => {} }
+// convex-test finds the module root by the `_generated` key; the consumer's two files are
+// `forms.ts` (the one re-export line) and `http.ts` (the handler registered).
+const modules = {
+  '/convex/_generated/api.ts': async () => ({}),
+  '/convex/forms.ts': async () => formsModule,
+  '/convex/http.ts': async () => ({
+    default: defineStudioHttp({ auth: silentAuth, ingest: { submission: formsModule.formsIngest } }),
+  }),
+}
+
+async function backend() {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: ADMIN, role: 'admin', createdAt: T0, updatedAt: T0 })
+  })
+  return t
+}
+type Backend = Awaited<ReturnType<typeof backend>>
+
+async function post(t: Backend, body: IngestReceiverBody) {
+  const signed = await signedIngestRequest(body, SECRET)
+  return t.fetch(INGEST_RECEIVER_PATH, { method: 'POST', headers: signed.headers, body: signed.body })
+}
+
+async function rows(t: Backend): Promise<SubmissionRecord[]> {
+  return (await t.run(async (ctx) => (await ctx.db.query('records').collect()).filter((row) => row.kind === 'submission'))).map(
+    (row) => ({ ...(row.data as object), id: row.recordId }) as unknown as SubmissionRecord,
+  )
+}
+
+async function scheduled(t: Backend) {
+  return t.run(async (ctx) =>
+    (await ctx.db.system.query('_scheduled_functions').collect()).map((job) => ({
+      name: job.name,
+      args: job.args[0] as Record<string, unknown>,
+      state: job.state.kind,
+    })),
+  )
+}
+
+/** Store a file as an upload URL would (convex-test records size only; the real upload records the type). */
+async function storeFile(t: Backend, bytes: number, contentType: string): Promise<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
+  })
+}
+
+// --- The site: the addon's delivery route over a fake transport ----------------------------
+
+interface ContactForm {
+  internalId: string
+  title: string
+  recipients: string[]
+  fields: { name: string; label: string }[]
+}
+const contactSource = defineFormSource<ContactForm>({
+  collection: 'form',
+  key: 'internalId',
+  title: (form) => form.title,
+  recipients: (form) => form.recipients,
+  fields: (form) => form.fields,
+})
+const CONTACT = {
+  id: 'form-1',
+  values: {
+    internalId: 'contact',
+    title: 'Contact',
+    recipients: ['shop@example.test', 'owner@example.test'],
+    fields: [{ name: 'email', label: 'E-mail' }, { name: 'message', label: 'Message' }],
+  },
+}
+
+/** The site, reached by the deployment's `fetch`: the delivery route with a scripted transport. */
+function site(script: (mail: FormMail, call: number) => void = () => undefined) {
+  const mails: FormMail[] = []
+  let calls = 0
+  const route = createFormsDeliveryRoute<ContactForm>({
+    secret: SECRET,
+    source: contactSource,
+    forms: async () => [CONTACT],
+    transport: async (mail) => {
+      calls += 1
+      script(mail, calls)
+      mails.push(mail)
+      return { id: `msg_${calls}` }
+    },
+  })
+  const fetches: string[] = []
+  vi.stubGlobal('fetch', async (url: string, init: RequestInit) => {
+    fetches.push(url)
+    return route.POST(new Request(url, init))
+  })
+  return { mails, fetches }
+}
+
+const SUBMISSION = {
+  kind: 'submission',
+  target: 'contact',
+  data: {
+    message: 'Hello, do you deliver?',
+    email: 'ada@example.test',
+    [FORMS_SOURCE_KEY]: 'https://site.test/contact',
+    [FORMS_HONEYPOT_KEY]: '',
+  },
+} as const
+
+const runAll = (t: Backend) => t.finishAllScheduledFunctions(vi.runAllTimers)
+const log = (row: SubmissionRecord): DeliveryEntry[] => row.deliveryLog ?? []
+
+describe('a submission through the receiver (EC-613 on EC-617)', () => {
+  it('lands a row, schedules ONE delivery; drained, the site mails every recipient and the log says so', async () => {
+    const t = await backend()
+    const { mails } = site()
+    const answer = await post(t, SUBMISSION)
+    expect(answer.status).toBe(200)
+    const [row] = await rows(t)
+    expect(row).toMatchObject({
+      form: 'contact',
+      status: 'new',
+      spam: 'clean',
+      deliveryState: 'pending',
+      sourceUrl: 'https://site.test/contact',
+      submittedAt: T0,
+      payload: [
+        { name: 'email', value: 'ada@example.test' },
+        { name: 'message', value: 'Hello, do you deliver?' },
+      ],
+    })
+    expect(await answer.json()).toEqual({ ok: true, id: row!.id })
+    // Control (the critic's): not drained, the delivery is scheduled and has not run.
+    expect(await scheduled(t)).toEqual([{ name: 'forms:deliver', args: { submissionId: row!.id, attempt: 1 }, state: 'pending' }])
+    expect(mails).toEqual([])
+
+    await runAll(t)
+    const [delivered] = await rows(t)
+    expect(delivered!.deliveryState).toBe('sent')
+    expect(log(delivered!).map((line) => [line.to, line.ok, line.id])).toEqual([
+      ['shop@example.test', true, 'msg_1'],
+      ['owner@example.test', true, 'msg_2'],
+    ])
+    expect(mails.map((mail) => mail.to)).toEqual(['shop@example.test', 'owner@example.test'])
+    expect(mails[0]).toMatchObject({
+      subject: 'New submission: Contact',
+      replyTo: 'ada@example.test',
+      form: { key: 'contact', title: 'Contact' },
+    })
+    expect(mails[0]!.text.split('\n').slice(0, 2)).toEqual(['E-mail: ada@example.test', 'Message: Hello, do you deliver?'])
+  })
+
+  it('one recipient fails: only it is retried after a minute; the other is mailed exactly once', async () => {
+    const t = await backend()
+    const { mails } = site((mail, call) => {
+      if (mail.to === 'owner@example.test' && call === 2) throw new Error('451 mailbox busy')
+    })
+    await post(t, SUBMISSION)
+    vi.advanceTimersByTime(0)
+    await t.finishInProgressScheduledFunctions()
+    const [afterFirst] = await rows(t)
+    expect(afterFirst!.deliveryState).toBe('pending')
+    expect(log(afterFirst!).map((line) => [line.to, line.ok, line.error, line.retryAt])).toEqual([
+      ['shop@example.test', true, undefined, undefined],
+      ['owner@example.test', false, '451 mailbox busy', '2026-10-26T12:01:00.000Z'],
+    ])
+    expect((await scheduled(t)).filter((job) => job.state === 'pending')).toEqual([
+      { name: 'forms:deliver', args: { submissionId: afterFirst!.id, attempt: 2 }, state: 'pending' },
+    ])
+
+    await runAll(t)
+    const [done] = await rows(t)
+    expect(done!.deliveryState).toBe('sent')
+    expect(mails.filter((mail) => mail.to === 'shop@example.test')).toHaveLength(1)
+    expect(mails.filter((mail) => mail.to === 'owner@example.test')).toHaveLength(1)
+  })
+
+  it('a site that stays down: every attempt logged, then FAILED — a visible issue on a row that exists', async () => {
+    const t = await backend()
+    let tries = 0
+    vi.stubGlobal('fetch', async () => {
+      tries += 1
+      throw new TypeError('fetch failed: ECONNREFUSED')
+    })
+    await post(t, SUBMISSION)
+    await runAll(t)
+    const [row] = await rows(t)
+    expect(tries).toBe(DELIVERY_MAX_ATTEMPTS)
+    expect(row!.deliveryState).toBe('failed')
+    expect(log(row!).map((line) => line.attempt)).toEqual([1, 2, 3, 4, 5])
+    expect(log(row!).every((line) => !line.ok && /ECONNREFUSED/.test(line.error ?? ''))).toBe(true)
+    expect(log(row!).at(-1)!.retryAt).toBeUndefined()
+  })
+
+  it('no delivery route configured → failed at once, naming the variable; nothing is fetched', async () => {
+    delete env()[FORMS_DELIVERY_URL_ENV]
+    const t = await backend()
+    const { fetches } = site()
+    await post(t, SUBMISSION)
+    await runAll(t)
+    const [row] = await rows(t)
+    expect(row!.deliveryState).toBe('failed')
+    expect(log(row!)[0]!.error).toMatch(/ELYTRA_FORMS_DELIVERY_URL/)
+    expect(fetches).toEqual([])
+  })
+
+  it('a form the site does not know → 404 → failed, not retried (content, not the network)', async () => {
+    const t = await backend()
+    const { fetches } = site()
+    await post(t, { ...SUBMISSION, target: 'retired-form' })
+    await runAll(t)
+    const [row] = await rows(t)
+    expect(row!.deliveryState).toBe('failed')
+    expect(log(row!)[0]!.error).toMatch(/HTTP 404: No published form “retired-form”/)
+    expect(fetches).toHaveLength(1)
+  })
+
+  it('a filled honeypot: the visitor gets the same 200, the row is kept as spam, nothing is delivered', async () => {
+    const t = await backend()
+    const { fetches } = site()
+    const answer = await post(t, { ...SUBMISSION, data: { ...SUBMISSION.data, [FORMS_HONEYPOT_KEY]: 'http://buy.test' } })
+    expect(answer.status).toBe(200)
+    const [row] = await rows(t)
+    expect(row).toMatchObject({ spam: 'honeypot', status: 'spam', deliveryState: 'skipped' })
+    expect(await scheduled(t)).toEqual([])
+    await runAll(t)
+    expect(fetches).toEqual([])
+  })
+
+  it('an invalid payload is refused 422 with its issues, and nothing is stored or scheduled', async () => {
+    const t = await backend()
+    const answer = await post(t, { kind: 'submission', target: 'contact', data: { nested: { no: 1 } } })
+    expect(answer.status).toBe(422)
+    expect(await answer.json()).toMatchObject({ issues: [{ path: ['data', 'nested'] }] })
+    expect(await rows(t)).toEqual([])
+    expect(await scheduled(t)).toEqual([])
+  })
+
+  it('the stored row measures far below Convex’s 16-level ceiling', async () => {
+    const t = await backend()
+    site()
+    await post(t, { ...SUBMISSION, data: { ...SUBMISSION.data, topics: ['a', 'b'] } })
+    await runAll(t)
+    const stored = await t.run(async (ctx) => (await ctx.db.query('records').collect()).find((row) => row.kind === 'submission'))
+    const { _id: _ignored, _creationTime: _time, ...document } = stored as Record<string, unknown>
+    expect(measureMaxDepth(document).depth).toBeLessThanOrEqual(6)
+    expect(measureMaxDepth(document).depth).toBeLessThan(CONVEX_MAX_NESTING_DEPTH)
+  })
+})
+
+// --- The studio's writes ---------------------------------------------------------------------
+
+function adapterClient(t: Backend): ConvexHttpClient {
+  const asAdmin = t.withIdentity({ subject: ADMIN, issuer: 'https://convex.test' })
+  return {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => asAdmin.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => asAdmin.mutation(ref, args ?? {}),
+  } as unknown as ConvexHttpClient
+}
+
+describe('the editor’s writes (the kind’s save)', () => {
+  it('a retry: moving a failed row INTO pending schedules a new run; a save that keeps the state schedules nothing', async () => {
+    delete env()[FORMS_DELIVERY_URL_ENV]
+    const t = await backend()
+    await post(t, SUBMISSION)
+    await runAll(t)
+    const [failed] = await rows(t)
+    expect(failed!.deliveryState).toBe('failed')
+
+    env()[FORMS_DELIVERY_URL_ENV] = DELIVERY_URL
+    const { mails } = site()
+    const repo = new ConvexPersistenceAdapter(adapterClient(t), PROJECT_ID).records(submissionRecordKind)
+    await repo.save(PROJECT_ID, { id: failed!.id, status: 'open' })
+    expect((await scheduled(t)).filter((job) => job.state === 'pending')).toEqual([])
+    await repo.save(PROJECT_ID, { id: failed!.id, deliveryState: 'pending' })
+    expect((await scheduled(t)).filter((job) => job.state === 'pending')).toEqual([
+      { name: 'forms:deliver', args: { submissionId: failed!.id, attempt: 1 }, state: 'pending' },
+    ])
+    await runAll(t)
+    const [sent] = await rows(t)
+    expect(sent).toMatchObject({ deliveryState: 'sent', status: 'open' })
+    expect(mails).toHaveLength(2)
+  })
+
+  it('multi-session: an editor’s change and the delivery’s log merge per column — and the stale whole-record write (control) is what would clobber it', async () => {
+    const t = await backend()
+    site()
+    await post(t, SUBMISSION)
+    const repo = new ConvexPersistenceAdapter(adapterClient(t), PROJECT_ID).records(submissionRecordKind)
+    const [loaded] = await rows(t)
+    // The editor's view is loaded while the delivery is still pending…
+    const editorsView = await repo.get(PROJECT_ID, loaded!.id)
+    expect(editorsView.deliveryState).toBe('pending')
+    // …the delivery runs and logs…
+    await runAll(t)
+    // …and the inbox saves ONLY the column the editor changed.
+    await repo.save(PROJECT_ID, { id: loaded!.id, status: 'done', assignee: 'Grace' })
+    const [merged] = await rows(t)
+    expect(merged).toMatchObject({ status: 'done', assignee: 'Grace', deliveryState: 'sent' })
+    expect(log(merged!)).toHaveLength(2)
+
+    // Control: the same edit sent as the WHOLE record the editor loaded (the generic rail's
+    // write, `lensDocumentToRecordWrite`) puts the stale `pending` back over the delivered row
+    // — and so schedules a SECOND delivery (duplicate mail). Which is why the inbox never sends it.
+    const { id: _id, projectId: _p, createdAt: _c, updatedAt: _u, ...stale } = editorsView
+    await repo.save(PROJECT_ID, { ...stale, id: loaded!.id, status: 'done' })
+    const [clobbered] = await rows(t)
+    expect(clobbered!.deliveryState).toBe('pending')
+    expect((await scheduled(t)).filter((job) => job.state === 'pending')).toEqual([
+      { name: 'forms:deliver', args: { submissionId: loaded!.id, attempt: 1 }, state: 'pending' },
+    ])
+  })
+})
+
+// --- Uploads -----------------------------------------------------------------------------------
+
+async function declareUpload(t: Backend, contentType: string, size: number, field = 'cv') {
+  const answer = await post(t, { kind: 'upload', target: 'contact', field, contentType, size })
+  return { status: answer.status, body: (await answer.json()) as { uploadId?: string; uploadUrl?: string } }
+}
+
+describe('uploads, claimed by the submission', () => {
+  it('a claimed file is on the row (name, type, size, URL), its URL reaches the mail; removing the row deletes it', async () => {
+    const t = await backend()
+    const { mails } = site()
+    const { status, body } = await declareUpload(t, 'application/pdf', 900)
+    expect(status).toBe(200)
+    expect(typeof body.uploadUrl).toBe('string')
+    const storageId = await storeFile(t, 800, 'application/pdf')
+    const answer = await post(t, {
+      ...SUBMISSION,
+      data: { ...SUBMISSION.data, cv: 'lebenslauf.pdf' },
+      uploads: [{ uploadId: body.uploadId!, storageId }],
+    })
+    expect(answer.status).toBe(200)
+    const [row] = await rows(t)
+    expect(row!.files).toEqual([
+      { field: 'cv', name: 'lebenslauf.pdf', storageId, contentType: 'application/pdf', size: 800, url: expect.any(String) },
+    ])
+    await runAll(t)
+    expect(mails[0]!.attachments).toEqual([
+      { filename: 'lebenslauf.pdf', contentType: 'application/pdf', size: 800, url: row!.files![0]!.url },
+    ])
+
+    const repo = new ConvexPersistenceAdapter(adapterClient(t), PROJECT_ID).records(submissionRecordKind)
+    await repo.remove(PROJECT_ID, row!.id)
+    expect(await rows(t)).toEqual([])
+    expect(await t.run((ctx) => ctx.storage.get(storageId as never))).toBeNull()
+  })
+
+  it('a claim that fails refuses the submission AND deletes the files it had already claimed', async () => {
+    const t = await backend()
+    site()
+    const good = await declareUpload(t, 'image/png', 500, 'photo')
+    const goodFile = await storeFile(t, 400, 'image/png')
+    const liar = await declareUpload(t, 'image/png', 500, 'photo')
+    const wrongType = await storeFile(t, 10, 'text/html')
+    const answer = await post(t, {
+      ...SUBMISSION,
+      uploads: [
+        { uploadId: good.body.uploadId!, storageId: goodFile },
+        { uploadId: liar.body.uploadId!, storageId: wrongType },
+      ],
+    })
+    expect(answer.status).toBe(415)
+    expect(await rows(t)).toEqual([])
+    expect(await t.run((ctx) => ctx.storage.get(goodFile as never))).toBeNull() // claimed, then released
+    expect(await t.run((ctx) => ctx.storage.get(wrongType as never))).toBeNull() // EC-617's claim deletes a mismatch
+    expect(await scheduled(t)).toEqual([])
+  })
+
+  it('the forms upload policy refuses what a browser would run (HTML, SVG) and anything over 10 MiB', async () => {
+    const t = await backend()
+    expect((await declareUpload(t, 'text/html', 10)).status).toBe(415)
+    expect((await declareUpload(t, 'image/svg+xml', 10)).status).toBe(415)
+    expect((await declareUpload(t, 'application/pdf', 10)).status).toBe(200) // control
+  })
+
+  it('unclaimed uploads past their life are listed for the developer (their bytes cannot be located)', async () => {
+    const t = await backend()
+    await declareUpload(t, 'application/pdf', 10)
+    const unclaimed = makeFunctionReference<'query', Record<string, never>, unknown>('forms:unclaimedUploads')
+    const query = t.query as unknown as (ref: unknown, args: Record<string, never>) => Promise<unknown>
+    const read = () => query(unclaimed, {})
+    expect(await read()).toMatchObject({ count: 0 })
+    vi.setSystemTime(new Date(Date.parse(T0) + 2 * 60 * 60 * 1000))
+    expect(await read()).toMatchObject({
+      count: 1,
+      uploads: [{ form: 'contact', field: 'cv' }],
+    })
+  })
+})
+
+// --- End to end: the site's no-JS form post → the ingest route → the receiver --------------------
+
+describe('the site’s form post, end to end', () => {
+  it('a multipart post with a file → 303 ?form=ok, the row carries the file, the delivery mails it', async () => {
+    const t = await backend()
+    const viaReceiver = (async (url: string, init: RequestInit) => t.fetch(new URL(url).pathname, init)) as unknown as typeof fetch
+    const ingest = createIngestRoute({ secret: SECRET, siteUrl: 'https://happy-otter-123.convex.site', fetchImpl: viaReceiver })
+    // The bytes' destination: the issued storage URL (convex-test stores them directly).
+    const storeBytes = (async (_url: string, init: RequestInit) => {
+      const blob = init.body as Blob
+      const storageId = await storeFile(t, blob.size, String(new Headers(init.headers).get('content-type')))
+      return Response.json({ storageId })
+    }) as unknown as typeof fetch
+    const formPost = createFormPostRoute({ ingest, fetchImpl: storeBytes })
+
+    const form = new FormData()
+    form.set(FORMS_TARGET_FIELD, 'contact')
+    form.set('email', 'ada@example.test')
+    form.set('message', 'Please call back.')
+    form.set('website', '')
+    form.set('cv', new File([new Uint8Array(300)], 'cv.pdf', { type: 'application/pdf' }))
+    const answer = await formPost.POST(
+      new Request('https://site.test/api/form', {
+        method: 'POST',
+        headers: { origin: 'https://site.test', referer: 'https://site.test/contact' },
+        body: form,
+      }),
+    )
+    expect(answer.status).toBe(303)
+    expect(answer.headers.get('location')).toBe('https://site.test/contact?form=ok')
+    const [row] = await rows(t)
+    expect(row).toMatchObject({
+      form: 'contact',
+      sourceUrl: 'https://site.test/contact',
+      payload: [
+        { name: 'cv', value: 'cv.pdf' },
+        { name: 'email', value: 'ada@example.test' },
+        { name: 'message', value: 'Please call back.' },
+      ],
+      files: [{ field: 'cv', name: 'cv.pdf', contentType: 'application/pdf', size: 300 }],
+    })
+
+    const { mails } = site()
+    await runAll(t)
+    expect(mails.map((mail) => mail.attachments.map((file) => file.filename))).toEqual([['cv.pdf'], ['cv.pdf']])
+
+    // Control: a post naming no form is refused before anything is sent.
+    const bare = new FormData()
+    bare.set('email', 'x@example.test')
+    const refused = await formPost.POST(new Request('https://site.test/api/form', { method: 'POST', body: bare }))
+    expect(refused.headers.get('location')).toBe('https://site.test/?form=invalid')
+    expect(await rows(t)).toHaveLength(1)
+  })
+})
+
+// --- The kind's contract in both adapters --------------------------------------------------------
+
+async function contract(repo: RecordRepository<typeof submissionRecordKind>) {
+  const base = { payload: [{ name: 'email', value: 'a@x.test' }], spam: 'clean' as const, deliveryState: 'sent' as const }
+  await repo.save(PROJECT_ID, { ...base, id: 'submission_a', form: 'contact', submittedAt: '2026-10-01T00:00:00.000Z' })
+  await repo.save(PROJECT_ID, { ...base, id: 'submission_b', form: 'jobs', submittedAt: '2026-10-02T00:00:00.000Z' })
+  await repo.save(PROJECT_ID, { ...base, id: 'submission_c', form: 'contact', status: 'done', submittedAt: '2026-10-03T00:00:00.000Z' })
+  const ids = (list: readonly { id: string }[]) => list.map((record) => record.id)
+  const edited = await repo.save(PROJECT_ID, { id: 'submission_a', notes: 'called back' })
+  const removedThen = async () => {
+    await repo.remove(PROJECT_ID, 'submission_b')
+    return ids(await repo.list(PROJECT_ID))
+  }
+  return {
+    all: ids(await repo.list(PROJECT_ID)),
+    newestFirst: ids(await repo.list(PROJECT_ID, { order: 'desc' })),
+    byForm: ids(await repo.list(PROJECT_ID, { where: { form: 'contact' } })),
+    byStatus: ids(await repo.list(PROJECT_ID, { where: { status: 'new' } })),
+    byBoth: ids(await repo.list(PROJECT_ID, { where: { form: 'contact', status: 'done' } })),
+    edited: { status: edited.status, notes: edited.notes, payload: edited.payload },
+    unknownKey: await repo.list(PROJECT_ID, { where: { assignee: 'x' } }).then(
+      () => 'accepted',
+      (error: Error) => error.name,
+    ),
+    afterRemove: await removedThen(),
+  }
+}
+
+describe('the submission kind’s contract — the same answers in both adapters', () => {
+  it('in memory and on Convex: create defaults, per-column edit, the two key slots, time order, remove', async () => {
+    const memory = await contract(new InMemoryRecordStore().records(submissionRecordKind))
+    const t = await backend()
+    const convex = await contract(new ConvexPersistenceAdapter(adapterClient(t), PROJECT_ID).records(submissionRecordKind))
+    expect(memory).toEqual({
+      all: ['submission_a', 'submission_b', 'submission_c'],
+      newestFirst: ['submission_c', 'submission_b', 'submission_a'],
+      byForm: ['submission_a', 'submission_c'],
+      byStatus: ['submission_a', 'submission_b'],
+      byBoth: ['submission_c'],
+      edited: { status: 'new', notes: 'called back', payload: [{ name: 'email', value: 'a@x.test' }] },
+      unknownKey: 'PersistenceValidationError',
+      afterRemove: ['submission_a', 'submission_c'],
+    })
+    expect(convex).toEqual(memory)
+  })
+})