@elytracms/studio 0.0.96 → 0.0.98

package/convex/fixtureAccounts.ts

@@ -0,0 +1,298 @@
+import { createAccount, modifyAccountCredentials } from '@convex-dev/auth/server'
+import { internalActionGeneric, makeFunctionReference } from 'convex/server'
+import type { AnyDataModel, GenericMutationCtx } from 'convex/server'
+import { v } from 'convex/values'
+import type { GenericId } from 'convex/values'
+import { DEV_USERS, DEV_USER_ROLES, classifyInviteSignup, normalizeInviteEmail } from '@elytracms/core/persistence'
+import { gateSessionCreation } from './auth'
+import { assertDeclaredRole, recordAuthorityAudit } from './authority'
+import { internalMutation } from './functions'
+import type { MutationCtx } from './functions'
+import { purgeOrphanCredentials } from './invites'
+
+/**
+ * EC-672 — fixture accounts for the two DEMO deployments (owner-ratified 2026-10-28: both
+ * demo deployments are agent-owned, re-seedable fixtures). Provisions the seed's dev users
+ * (`DEV_USER_ROLES`: admin, editor, viewer — the same three the playground signs in as) as
+ * real Convex Auth accounts, so an agent's connected studio and `elytra seed --drop` can sign
+ * in, and two browsers are two users.
+ *
+ * **Confined structurally, not by a check.** No consumer deployment has these functions: a
+ * Convex deployment runs only what its own `convex/` directory exports, and only the in-repo
+ * demo (`apps/demo/studio/convex/fixtureAccounts.ts`) re-exports this module — the
+ * `create-elytra` template and both kits re-export nothing of it, which
+ * `packages/create-elytra/test/template-fixture-accounts.test.js` pins. Belt and braces, every
+ * function here refuses unless the deployment carries `ELYTRA_FIXTURE_ACCOUNTS=1` (set on the
+ * two demo deployments only).
+ *
+ * **The password is a per-deployment secret**, `ELYTRA_FIXTURE_PASSWORD`, read from the
+ * deployment env — never a literal in this repo. The playground's `LOCAL_DEV_CREDENTIALS`
+ * ship in the published studio and are shown on the playground sign-in screen, so a real
+ * account carrying one of them would have a publicly known password (critic-on-plan,
+ * wave-0098). The owner sets the secret once per deployment from a generator piped straight
+ * into `npx convex env set`; the agent studio's connected mode and `pnpm demo:reseed` read it
+ * with `npx convex env get` into a child process env, never printed.
+ *
+ * **Through the provider's own path, so the role/invite gate applies.** Per account:
+ *
+ * 1. `prepare` (one transaction) does what an admin's invite does (`invites:create`): it
+ *    refuses a role the deployed policy does not declare (`assertDeclaredRole`), purges
+ *    member-less credentials for the email (EC-358 — an invite never adopts pre-existing
+ *    credentials; a crashed earlier run's half-made account is one), and writes the invite
+ *    when the deployment's own decision (`classifyInviteSignup`) would otherwise reject the
+ *    sign-up. It is the invite's equivalent because it is INTERNAL: only a holder of the
+ *    deployment's admin key (the CLI, the dashboard) can run it — strictly above
+ *    `project.administer`, the capability `invites:create` requires.
+ * 2. `createAccount` (Convex Auth) — exactly the call the Password provider's `signUp` flow
+ *    makes — creates the account; the engine's account-creation gate
+ *    (`afterUserCreatedOrUpdated` → `gateAccountCreation`) runs inside it and reads that
+ *    invite, unmodified. An existing account whose secret matches is returned untouched (the
+ *    library's own idempotency); one whose secret differs means the owner rotated the
+ *    deployment secret, and `modifyAccountCredentials` follows it.
+ * 3. `settle` grants the membership by the gate every sign-in runs (`gateSessionCreation`:
+ *    bootstrap on an empty deployment, grant + consume the invite otherwise), restores a
+ *    drifted fixture role (audited), and drops a leftover invite for the email.
+ *
+ * Idempotent: a second run creates, rotates, grants and writes nothing — every account
+ * reports `unchanged`. Creating no session, it never signs anyone in.
+ *
+ * Run from the demo studio dir (the reseed script does it for you):
+ * `CONVEX_DEPLOYMENT=dev:<name> npx convex run fixtureAccounts:provision`.
+ */
+
+/** The deployment env flag every function here requires, exactly `'1'`. */
+export const FIXTURE_ACCOUNTS_FLAG = 'ELYTRA_FIXTURE_ACCOUNTS'
+/** The deployment env var holding the fixture accounts' password (a per-deployment secret). */
+export const FIXTURE_PASSWORD_ENV = 'ELYTRA_FIXTURE_PASSWORD'
+/**
+ * The secret's minimum length. Above the Password provider's own 8 (which `createAccount`
+ * does not apply — only the provider's `signUp` flow validates): this password guards an
+ * admin on a deployment behind a public site, so a short one is a misconfiguration, refused.
+ */
+export const FIXTURE_PASSWORD_MIN_LENGTH = 16
+/** The provider the accounts belong to — the studio's default `Password` (`defineStudioAuth`). */
+const PROVIDER = 'password'
+/** The audit actor of a fixture role restore (no studio user performs it). */
+const AUDIT_ACTOR = 'fixture-accounts'
+
+/** Where the demo re-exports this module (`convex/fixtureAccounts.ts`); the action's sub-calls. */
+const prepareRef = makeFunctionReference<'mutation', { email: string; role: string }, PrepareOutcome>(
+  'fixtureAccounts:prepare',
+)
+const settleRef = makeFunctionReference<'mutation', { email: string; role: string }, SettleOutcome>(
+  'fixtureAccounts:settle',
+)
+
+type Env = Record<string, string | undefined>
+
+/** One fixture account: a seeded dev user's email and role. */
+export interface FixtureAccount {
+  readonly email: string
+  readonly role: string
+}
+
+/**
+ * The fixture accounts, from the seed's ONE declaration of its dev users and their roles
+ * (`DEV_USER_ROLES` → `DEV_USERS`), in that order — admin first, so on an empty deployment
+ * the admin is the bootstrap principal. The agent scripts select an account by the same
+ * role table, so there is no second list to drift.
+ */
+export function fixtureAccountList(): FixtureAccount[] {
+  const users = Object.values(DEV_USERS)
+  return DEV_USER_ROLES.map(({ userId, role }) => {
+    const user = users.find((candidate) => candidate.id === userId)
+    if (!user) throw new Error(`fixture-accounts: DEV_USER_ROLES names ${userId}, which DEV_USERS does not declare`)
+    return { email: normalizeInviteEmail(user.email), role }
+  })
+}
+
+/** Refuse unless this deployment opted in. Every function here calls it first. */
+export function assertFixtureAccountsEnabled(env: Env): void {
+  if (env[FIXTURE_ACCOUNTS_FLAG] !== '1') {
+    throw new Error(
+      `fixture-accounts: refused — this deployment does not carry ${FIXTURE_ACCOUNTS_FLAG}=1. Fixture accounts exist only on the two demo deployments; nothing was written.`,
+    )
+  }
+}
+
+/** The fixture password from the deployment env, or a refusal naming what is missing (never the value). */
+export function readFixturePassword(env: Env): string {
+  assertFixtureAccountsEnabled(env)
+  const password = env[FIXTURE_PASSWORD_ENV]
+  if (password === undefined || password === '') {
+    throw new Error(
+      `fixture-accounts: refused — ${FIXTURE_PASSWORD_ENV} is not set on this deployment. The owner sets it once, generated and piped (never typed): \`sh -c 'openssl rand -base64 24 | xargs npx convex env set ${FIXTURE_PASSWORD_ENV}'\` with the deployment inline. Nothing was written.`,
+    )
+  }
+  if (password.length < FIXTURE_PASSWORD_MIN_LENGTH) {
+    throw new Error(
+      `fixture-accounts: refused — ${FIXTURE_PASSWORD_ENV} is shorter than ${FIXTURE_PASSWORD_MIN_LENGTH} characters. Nothing was written.`,
+    )
+  }
+  return password
+}
+
+/** What `prepare` found and did for one account. */
+export interface PrepareOutcome {
+  /** Member-less credentials for the email that were purged (EC-358). */
+  readonly purgedOrphans: number
+  /** Whether a password account for the email exists after the purge. */
+  readonly accountExists: boolean
+  /** The invite step: written / role corrected / already right / not needed (a member, or the bootstrap principal). */
+  readonly invite: 'written' | 'updated' | 'present' | 'not-needed'
+}
+
+/** What `settle` did for one account. */
+export interface SettleOutcome {
+  readonly membership: 'bootstrapped' | 'granted' | 'unchanged' | 'role-restored'
+  /** A leftover invite for the email that was removed (the account is a member now). */
+  readonly inviteRemoved: boolean
+}
+
+/** One account's line in the `provision` report. */
+export interface ProvisionedAccount extends FixtureAccount {
+  readonly account: 'created' | 'unchanged' | 'password-rotated'
+  readonly membership: SettleOutcome['membership']
+  readonly invite: PrepareOutcome['invite']
+  readonly purgedOrphans: number
+}
+
+async function findPasswordAccount(ctx: Pick<MutationCtx, 'db'>, email: string) {
+  return ctx.db
+    .query('authAccounts')
+    .withIndex('providerAndAccountId', (q) => q.eq('provider', PROVIDER).eq('providerAccountId', email))
+    .unique()
+}
+
+async function findMember(ctx: Pick<MutationCtx, 'db'>, userId: string) {
+  return ctx.db
+    .query('members')
+    .withIndex('by_user', (q) => q.eq('userId', userId))
+    .first()
+}
+
+async function findInvite(ctx: Pick<MutationCtx, 'db'>, email: string) {
+  return ctx.db
+    .query('invites')
+    .withIndex('by_email', (q) => q.eq('email', email))
+    .first()
+}
+
+const accountArgs = { email: v.string(), role: v.string() }
+
+/** Step 1 — the admin-invite equivalent (see the module doc). Internal: admin key only. */
+export const prepare = internalMutation({
+  args: accountArgs,
+  handler: async (ctx, args): Promise<PrepareOutcome> => {
+    assertFixtureAccountsEnabled(process.env)
+    assertDeclaredRole(args.role)
+    const email = normalizeInviteEmail(args.email)
+    const purgedOrphans = await purgeOrphanCredentials(ctx, email)
+    const account = await findPasswordAccount(ctx, email)
+    const member = account ? await findMember(ctx, String(account.userId)) : null
+    if (member) return { purgedOrphans, accountExists: true, invite: 'not-needed' }
+
+    const invite = await findInvite(ctx, email)
+    const decision = classifyInviteSignup({
+      hasAnyMember: (await ctx.db.query('members').first()) !== null,
+      existingRole: null,
+      invite: invite ? { role: invite.role } : null,
+    })
+    const now = new Date().toISOString()
+    if (decision.kind === 'bootstrap-admin') {
+      return { purgedOrphans, accountExists: account !== null, invite: 'not-needed' }
+    }
+    if (invite && invite.role === args.role) {
+      return { purgedOrphans, accountExists: account !== null, invite: 'present' }
+    }
+    if (invite) {
+      await ctx.db.patch(invite._id, { role: args.role, updatedAt: now })
+      return { purgedOrphans, accountExists: account !== null, invite: 'updated' }
+    }
+    await ctx.db.insert('invites', { email, role: args.role, createdAt: now, updatedAt: now })
+    return { purgedOrphans, accountExists: account !== null, invite: 'written' }
+  },
+})
+
+/** Step 3 — grant by the sign-in gate, restore a drifted role, drop a leftover invite. Internal. */
+export const settle = internalMutation({
+  args: accountArgs,
+  handler: async (ctx, args): Promise<SettleOutcome> => {
+    assertFixtureAccountsEnabled(process.env)
+    const email = normalizeInviteEmail(args.email)
+    const account = await findPasswordAccount(ctx, email)
+    if (!account) throw new Error(`fixture-accounts: no password account for ${email} after createAccount`)
+    const userId = String(account.userId)
+    const before = await findMember(ctx, userId)
+    const anyMemberBefore = before !== null || (await ctx.db.query('members').first()) !== null
+
+    // The gate every sign-in runs (EC-324): bootstrap / grant + consume / existing / reject.
+    await gateSessionCreation(ctx as unknown as GenericMutationCtx<AnyDataModel>, {
+      userId: account.userId as GenericId<'users'>,
+    })
+    const member = await findMember(ctx, userId)
+    if (!member) throw new Error(`fixture-accounts: ${email} is not a member after the sign-in gate`)
+
+    let membership: SettleOutcome['membership'] = before ? 'unchanged' : anyMemberBefore ? 'granted' : 'bootstrapped'
+    if (member.role !== args.role) {
+      assertDeclaredRole(args.role)
+      await ctx.db.patch(member._id, { role: args.role, updatedAt: new Date().toISOString() })
+      await recordAuthorityAudit(ctx, {
+        actorId: AUDIT_ACTOR,
+        targetUserId: userId,
+        op: 'members.set',
+        outcome: 'allowed',
+        rolesGranted: [args.role],
+        detail: `fixture role restored (was ${member.role})`,
+      })
+      membership = 'role-restored'
+    }
+
+    const leftover = await findInvite(ctx, email)
+    if (leftover) await ctx.db.delete(leftover._id)
+    return { membership, inviteRemoved: leftover !== null }
+  },
+})
+
+/**
+ * `fixtureAccounts:provision` — the one entry point: provisions every fixture account
+ * (prepare → `createAccount` → settle) and returns the per-account report. Never logs or
+ * returns the password. Internal: admin key only.
+ */
+export const provision = internalActionGeneric({
+  args: {},
+  handler: async (ctx): Promise<{ accounts: ProvisionedAccount[] }> => {
+    const password = readFixturePassword(process.env)
+    const accounts: ProvisionedAccount[] = []
+    for (const fixture of fixtureAccountList()) {
+      const prepared = await ctx.runMutation(prepareRef, { email: fixture.email, role: fixture.role })
+      let outcome: ProvisionedAccount['account'] = prepared.accountExists ? 'unchanged' : 'created'
+      try {
+        // The Password provider's own sign-up call — the account-creation gate runs inside it.
+        await createAccount(ctx, {
+          provider: PROVIDER,
+          account: { id: fixture.email, secret: password },
+          profile: { email: fixture.email },
+        })
+      } catch (error) {
+        // The library's "secret differs" signal on an EXISTING account (never on a new one).
+        const message = error instanceof Error ? error.message : String(error)
+        if (!prepared.accountExists || !/already exists/.test(message)) throw error
+        await modifyAccountCredentials(ctx, {
+          provider: PROVIDER,
+          account: { id: fixture.email, secret: password },
+        })
+        outcome = 'password-rotated'
+      }
+      const settled = await ctx.runMutation(settleRef, { email: fixture.email, role: fixture.role })
+      accounts.push({
+        ...fixture,
+        account: outcome,
+        membership: settled.membership,
+        invite: prepared.invite,
+        purgedOrphans: prepared.purgedOrphans,
+      })
+    }
+    return { accounts }
+  },
+})

package/convex/incarnation.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import type { FunctionReference } from 'convex/server'
+import { fieldPath, measureMaxDepth } from '@elytracms/core/cms-core'
+import { createChangesets, 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-669 — the Codex review's F21 counterexample on Convex (round 3, `races.convex.test.ts`),
+ * copied and INVERTED, plus the critic-on-plan's version cases: the real `cms:*` handlers,
+ * schema and triggers under convex-test, driven by the production operations over the
+ * production `ConvexPersistenceAdapter`. Deleting (`cms:deleteDocument`) or clearing
+ * (`cms:clearDocuments`) an identity records the revision and version it reached
+ * (`documentFloors`); a later create of the same `collection:id` starts above both, so a
+ * token the old lifetime minted names nothing in the new one. No wire change.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const projectId = 'incarnation'
+const ref = { collection: 'post', id: 'p' }
+const collections = () => [{ id: 'post', kind: 'document' as const, fields: [{ name: 'title', type: 'text' as const }] }]
+
+async function world() {
+  const t = convexTest(schema, modules)
+  const stamp = '2026-10-28T00:00:00Z'
+  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, projectId)
+  const options = { adapter, collections, validateDocument: () => [] }
+  const ops = createOperations(options)
+  const changesets = createChangesets(options)
+  const put = (title: string) =>
+    ops.documents.replace({ projectId, document: { ...ref, values: { title } }, precondition: { ifAbsent: true } })
+  return { t, adapter, ops, changesets, put }
+}
+
+it('F21 Convex: a recreated identity refuses a previous incarnation’s authoring revision', async () => {
+  const { adapter, ops, put } = await world()
+  expect((await put('old')).ok).toBe(true)
+  expect((await ops.documents.patch({ projectId, ref, baseRevision: 1, patches: [{ op: 'set', path: fieldPath('title'), value: 'B' }] })).ok).toBe(true)
+  const stale = () => ops.documents.patch({ projectId, ref, baseRevision: 1, patches: [{ op: 'set', path: fieldPath('title'), value: 'STALE' }] })
+  expect((await stale()).ok).toBe(false) // known-positive control (kept as written)
+  expect((await ops.documents.delete({ projectId, ref })).ok).toBe(true)
+  expect((await put('NEW')).ok).toBe(true)
+  // Inverted: the new lifetime starts above revision 2, and the stale patch refuses.
+  expect((await adapter.cms.getDocument(projectId, ref)).revision).toBe(3)
+  expect((await stale()).ok).toBe(false)
+  expect((await adapter.cms.getDocument(projectId, ref)).document.values.title).toBe('NEW')
+})
+
+describe('EC-669 Convex — revisions and versions are monotonic per identity across both removal mutations', () => {
+  it('control: a fresh identity still starts at revision 1 and version 1', async () => {
+    const { adapter, ops, put } = await world()
+    expect((await put('first')).ok).toBe(true)
+    expect((await adapter.cms.getDocument(projectId, ref)).revision).toBe(1)
+    expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true)
+    expect((await adapter.cms.getDocument(projectId, ref)).publishedVersion).toBe(1)
+  })
+
+  for (const removal of ['delete', 'clear'] as const) {
+    it(`${removal}: stale revision and version tokens of the old lifetime refuse on the new one`, async () => {
+      const { adapter, ops, put } = await world()
+      expect((await put('old v1')).ok).toBe(true)
+      expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true) // r2, v1
+      const removed = removal === 'delete' ? await ops.documents.delete({ projectId, ref }) : await ops.documents.clear({ projectId })
+      expect(removed.ok).toBe(true)
+      expect((await put('new')).ok).toBe(true)
+      expect((await adapter.cms.getDocument(projectId, ref)).revision).toBe(3)
+      expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true)
+      const reborn = await adapter.cms.getDocument(projectId, ref)
+      expect(reborn.publishedVersion).toBe(2)
+      expect((await ops.documents.replace({ projectId, document: { ...ref, values: { title: 'STALE' } }, precondition: { revision: 1 } })).ok).toBe(false)
+      expect((await ops.documents.publish({ projectId, ref, expectedRevision: 2 })).ok).toBe(false)
+      expect((await ops.documents.delete({ projectId, ref, precondition: { revision: 2 } })).ok).toBe(false)
+      const pinned = await ops.documents.pinVersion({ projectId, ref, version: 1 })
+      expect(pinned.ok).toBe(false)
+      if (!pinned.ok) expect(pinned.error.code).toBe('not-found')
+      const restored = await ops.documents.restore({ projectId, ref, version: 1 })
+      expect(restored.ok).toBe(false)
+      if (!restored.ok) expect(restored.error.code).toBe('not-found')
+      const after = await adapter.cms.getDocument(projectId, ref)
+      expect(after.revision).toBe(reborn.revision)
+      expect(after.publishedVersion).toBe(2)
+      expect(after.document.values.title).toBe('new')
+    })
+  }
+
+  it('the floor holds across repeated lifetimes, and a second removal raises it', async () => {
+    const { t, adapter, ops, put } = await world()
+    expect((await put('one')).ok).toBe(true)
+    expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true) // r2, v1
+    expect((await ops.documents.delete({ projectId, ref })).ok).toBe(true)
+    expect((await put('two')).ok).toBe(true) // r3
+    expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true) // r4, v2
+    expect((await ops.documents.clear({ projectId })).ok).toBe(true)
+    expect((await put('three')).ok).toBe(true)
+    expect((await adapter.cms.getDocument(projectId, ref)).revision).toBe(5)
+    expect((await ops.documents.publish({ projectId, ref })).ok).toBe(true)
+    expect((await adapter.cms.getDocument(projectId, ref)).publishedVersion).toBe(3)
+    // One floor row per identity, raised in place (never a row per removal).
+    const floors = await t.run((ctx) => ctx.db.query('documentFloors').collect())
+    expect(floors.map(({ collection, docId, revision, version }) => ({ collection, docId, revision, version }))).toEqual([
+      { collection: 'post', docId: 'p', revision: 4, version: 2 },
+    ])
+    // A new stored shape stays inside Convex's 16-level cap (flat scalars).
+    expect(measureMaxDepth(floors[0]).depth).toBeLessThanOrEqual(16)
+  })
+
+  it('a changeset that re-creates a removed identity records a REMOVE inverse, and its revert removes it', async () => {
+    const { adapter, ops, changesets, put } = await world()
+    expect((await put('old')).ok).toBe(true)
+    expect((await ops.documents.delete({ projectId, ref })).ok).toBe(true)
+    const applied = await changesets.apply(
+      changesets.create({
+        title: 're-create',
+        steps: [{ operation: 'documents.replace', input: { projectId, document: { ...ref, values: { title: 'again' } }, precondition: { ifAbsent: true } } }],
+      }),
+    )
+    expect(applied.ok).toBe(true)
+    if (!applied.ok) throw new Error(applied.error.message)
+    expect(applied.value.receipts).toEqual([
+      expect.objectContaining({ beforeRevision: null, afterRevision: 2, inverse: { kind: 'remove' } }),
+    ])
+    expect((await changesets.revert(applied.value)).ok).toBe(true)
+    expect(await adapter.cms.findDocument(projectId, ref)).toBeUndefined()
+  })
+})

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])
+  })
+})