@elytracms/studio 0.0.95 → 0.0.97

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.test.ts

@@ -13,7 +13,15 @@ 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 { CONVEX_MAX_NESTING_DEPTH, measureMaxDepth } from '@elytracms/core/cms-core'
+import {
+  claimIngestUpload,
+  ingestHandlerArgs,
+  parseIngestPayload,
+  recordIngestUpload,
+  releaseIngestUploads,
+  unclaimedIngestUploads,
+} from './ingest'
 import type { IngestHandlerRef } from './ingest'
 import { saveRecord } from './record-functions'
 import { createIngestRoute } from '../../next/src/ingest'
@@ -178,6 +186,20 @@ async function storeFile(t: ReturnType<typeof backend>, bytes: number, contentTy
   })
 }
 
+/** 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)
+}
+
+/** An upload intent's claim columns, as stored. */
+function intentState(t: ReturnType<typeof backend>, uploadId: string) {
+  return t.run(async (ctx) => {
+    const row = (await ctx.db.query('records').collect()).find((r) => r.kind === 'ingestUpload' && r.recordId === uploadId)
+    const data = row?.data as { state?: string; storageId?: string } | undefined
+    return { state: data?.state, storageId: data?.storageId }
+  })
+}
+
 /** 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')
@@ -254,7 +276,7 @@ describe('the ingest receiver — dispatch (EC-617)', () => {
     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 () => {
+  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) =>
@@ -271,7 +293,9 @@ describe('the ingest receiver — dispatch (EC-617)', () => {
     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
+    // EC-671: refused and KEPT — a claim never deletes the id it names (it is the visitor's word).
+    expect(await stored(t, wrongType)).toBe(true)
+    expect(await intentState(t, liar)).toEqual({ state: 'rejected', storageId: wrongType })
   })
 
   it('an upload no submission claims is listed once its life is over (the visible orphan finding)', async () => {
@@ -285,6 +309,124 @@ describe('the ingest receiver — dispatch (EC-617)', () => {
   })
 })
 
+/**
+ * EC-671 — a claim binds only bytes the deployment's own facts say are this intent's, each
+ * check isolated (the others pass by construction) beside a control the same harness claims;
+ * and `releaseIngestUploads` deletes only what a claim bound. The forms addon's end-to-end
+ * probe (its rollback and removal, the attacker's harvest) is
+ * `packages/forms/src/convex/claim-ownership.convex.test.ts`.
+ */
+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
+  }
+  const claimWith = (t: ReturnType<typeof backend>, uploadId: string, storageId: string) =>
+    signedPost(t, { ...SUBMISSION, uploads: [{ uploadId, storageId }] })
+  async function insertAsset(t: ReturnType<typeof backend>, files: { storageKey: string; thumb?: string }) {
+    await t.run(async (ctx) => {
+      await ctx.db.insert('assets', {
+        assetId: `asset_${files.storageKey}`,
+        filename: 'hero.png',
+        contentType: 'image/png',
+        byteSize: 400,
+        storageKey: files.storageKey,
+        ...(files.thumb ? { thumb: { storageKey: files.thumb, url: 'https://cdn.invalid/t', width: 1, height: 1 } } : {}),
+        createdAt: '2026-10-26T12:00:00.000Z',
+        updatedAt: '2026-10-26T12:00:00.000Z',
+      })
+    })
+  }
+  const bindings = (t: ReturnType<typeof backend>) =>
+    t.run(async (ctx) =>
+      (await ctx.db.query('records').collect())
+        .filter((row) => row.kind === 'ingestBinding')
+        .map((row) => ({ storageId: row.recordId, uploadId: (row.data as { uploadId: string }).uploadId })),
+    )
+
+  it('(1) a file stored BEFORE the intent — in the same millisecond — is refused, rejected and kept; one stored after is claimed', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const earlier = await storeFile(t, 400, 'image/png') // the fake clock does not move: one millisecond for all
+    const uploadId = await declare(t)
+    // Why the rule reads the intent ROW's `_creationTime`, not `issuedAt`: in this millisecond
+    // the earlier file is NOT before `issuedAt` (the HTTP action's clock, ms grain) — that
+    // comparison would have admitted it. Both `_creationTime`s are the deployment's stamps.
+    const facts = await t.run(async (ctx) => {
+      const intent = (await ctx.db.query('records').collect()).find((row) => row.recordId === uploadId)!
+      const file = (await ctx.db.system.get(earlier as never)) as { _creationTime: number }
+      return { file: file._creationTime, issuedAt: Date.parse((intent.data as { issuedAt: string }).issuedAt), intent: intent._creationTime }
+    })
+    expect(facts.file).toBeGreaterThanOrEqual(facts.issuedAt)
+    expect(facts.file).toBeLessThan(facts.intent)
+    const refused = await claimWith(t, uploadId, earlier)
+    expect(refused.status).toBe(422)
+    expect(await refused.json()).toEqual({ error: `Upload “${uploadId}” did not store the file “${earlier}”.` })
+    expect(await intentState(t, uploadId)).toEqual({ state: 'rejected', storageId: earlier })
+    expect(await stored(t, earlier)).toBe(true)
+    expect(await bindings(t)).toEqual([])
+    // Control: a file stored after its intent is claimed and bound.
+    const fresh = await declare(t)
+    const own = await storeFile(t, 400, 'image/png')
+    expect((await claimWith(t, fresh, own)).status).toBe(200)
+    expect(await bindings(t)).toEqual([{ storageId: own, uploadId: fresh }])
+  })
+
+  it('(2) a file another claim bound is refused for a second intent issued before it was stored', async () => {
+    env()['ELYTRA_INGEST_SECRET'] = SECRET
+    const t = backend()
+    const first = await declare(t)
+    const second = await declare(t) // issued BEFORE the file, so check (1) passes for it too
+    const file = await storeFile(t, 400, 'image/png')
+    expect((await claimWith(t, first, file)).status).toBe(200) // control: the first claim binds it
+    expect((await claimWith(t, second, file)).status).toBe(422)
+    expect(await intentState(t, second)).toEqual({ state: 'rejected', storageId: file })
+    expect(await bindings(t)).toEqual([{ storageId: file, uploadId: first }])
+    expect(await stored(t, file)).toBe(true)
+  })
+
+  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 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')
+    await insertAsset(t, { storageKey: original, thumb: preview })
+    expect((await claimWith(t, asFile, original)).status).toBe(422)
+    expect((await claimWith(t, asThumb, preview)).status).toBe(422)
+    expect((await claimWith(t, plain, unreferenced)).status).toBe(200)
+    expect(await bindings(t)).toEqual([{ storageId: unreferenced, uploadId: plain }])
+    expect([await stored(t, original), await stored(t, preview)]).toEqual([true, true])
+  })
+
+  it('releaseIngestUploads deletes a bound file and its binding, keeps an unbound one (an asset’s), and dedupes', 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)
+    const assetFile = await storeFile(t, 400, 'image/png')
+    await insertAsset(t, { storageKey: assetFile })
+    const released = await t.run((ctx) => releaseIngestUploads(ctx, [own, assetFile, own]))
+    expect(released).toEqual({ deleted: [own], kept: [assetFile] })
+    expect([await stored(t, own), await stored(t, assetFile)]).toEqual([false, true])
+    expect(await bindings(t)).toEqual([])
+  })
+
+  it('the binding row is flat — its stored nesting is far inside Convex’s limit', 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)
+    const row = await t.run(async (ctx) => (await ctx.db.query('records').collect()).find((r) => r.kind === 'ingestBinding')!)
+    expect(row.data).toEqual({ uploadId, target: 'contact', boundAt: '2026-10-26T12:00:00.000Z' })
+    expect(measureMaxDepth(row).depth).toBe(2) // the row object → `data` → its string columns
+    expect(measureMaxDepth(row).depth).toBeLessThanOrEqual(CONVEX_MAX_NESTING_DEPTH)
+  })
+})
+
 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