@elytracms/studio 0.0.92 → 0.0.94

package/convex/record-functions.ts

@@ -0,0 +1,325 @@
+import { ConvexError, v } from 'convex/values'
+import type { GenericId } from 'convex/values'
+import type { RegisteredMutation, RegisteredQuery } from 'convex/server'
+import {
+  PersistenceValidationError,
+  matchesRecordQuery,
+  orderRecords,
+  recordSlots,
+  recordWireRow,
+  resolveRecordQuery,
+  resolveRecordSave,
+} from '@elytracms/core/persistence'
+import type {
+  AnyRecordKind,
+  IndexedRecord,
+  RecordColumns,
+  RecordQuery,
+  RecordWireRow,
+  ResolvedRecordQuery,
+} from '@elytracms/core/persistence'
+import { mutation, query } from './functions'
+import type { MutationCtx, QueryCtx } from './functions'
+import { requireCapability } from './guard'
+
+/**
+ * EC-616 — the Convex half of the generic record store: ONE implementation, instantiated
+ * per record kind. A kind's module is one line,
+ *
+ * ```ts
+ * // an addon's convex module (and the engine's own kinds) — the same way
+ * export const { save, get, list, remove } = defineRecordFunctions(submissionRecordKind)
+ * ```
+ *
+ * and reaches a deployment through the consumer's one re-export line for that module
+ * (`convex/forms.ts`: `export * from '@elytracms/forms/convex'`), so the functions are
+ * addressed `<module>:save` (the kind declares its `module`). The engine never imports a
+ * kind it did not declare: an addon's convex module brings its own declaration.
+ *
+ * This file registers NO functions itself — it is a factory, imported by the modules
+ * that do (`./record-functions` is not a consumer re-export).
+ *
+ * **The wire is the kind's own:** `save` takes the kind's `idKey` (`redirectId`) and its
+ * columns flat (plus `meta`, or a per-key `metaPatch`) (each `v.optional(v.any())` — the kind's zod schema is the one validator,
+ * run below, never a hand-mirrored Convex copy), plus `createdAt`/`updatedAt`; every
+ * function returns rows flat (`recordWireRow`). A kind's columns are therefore its
+ * Convex argument names — `defineRecordKind` refuses the names that would collide.
+ *
+ * **The write** is the EC-577 rule (`resolveRecordSave`, shared with the in-memory store),
+ * inside this transaction: absent keeps, `null` clears an optional column, a value sets,
+ * no stored record → a complete create or a `validation` `ConvexError` (the client maps
+ * it to `PersistenceValidationError`). ONE `db.patch` or ONE `db.insert` into `records`,
+ * so the write-chokepoint trigger fires once per save. Access is the kind's (`access`,
+ * default `content.read` / `content.write`), checked first.
+ */
+
+type RecordDoc = {
+  _id: GenericId<'records'>
+  kind: string
+  recordId: string
+  data: RecordColumns
+  key1?: string
+  key2?: string
+  at: string
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * TOLERANT READ (marked; EC-616's redirect move, the EC-587 precedent): a kind whose rows
+ * used to live in a table of their own declares where, so a deployment whose functions
+ * moved but whose migration has not run yet serves exactly what it served before — no
+ * gap. Reads union the legacy rows a record does not shadow; a save of a legacy-only id
+ * lifts it (the record is created from the legacy columns, the legacy row deleted, one
+ * transaction); a remove deletes both. Writes NEVER go to the legacy table. Removed with
+ * the legacy table once its migration is reported run on every deployment (a gated item).
+ */
+export interface LegacyRecordSource {
+  /** The legacy row for one id: its columns and stamps, and a handle to delete it. */
+  find(ctx: QueryCtx | MutationCtx, recordId: string): Promise<LegacyRecord | null>
+  /** Every legacy row (the tables are small editorial sets: read whole). */
+  list(ctx: QueryCtx | MutationCtx): Promise<LegacyRecord[]>
+  /** Delete one legacy row (after its record exists). */
+  remove(ctx: MutationCtx, record: LegacyRecord): Promise<void>
+}
+
+export interface LegacyRecord {
+  recordId: string
+  columns: RecordColumns
+  createdAt: string
+  updatedAt: string
+  /** The legacy row's own id, opaque to the factory. */
+  handle: unknown
+}
+
+/** A `PersistenceValidationError` from the shared rule, as the `ConvexError` the client maps back. */
+function asConvexValidation(error: unknown): unknown {
+  if (!(error instanceof PersistenceValidationError)) return error
+  return new ConvexError({ code: 'validation', message: error.message, issues: [...error.issues] })
+}
+
+function rethrowAsConvex<T>(work: () => T): T {
+  try {
+    return work()
+  } catch (error) {
+    throw asConvexValidation(error)
+  }
+}
+
+/** One stored record of a kind by id (`by_kind_record`). */
+export async function findRecordDoc(
+  ctx: QueryCtx | MutationCtx,
+  kind: AnyRecordKind,
+  recordId: string,
+): Promise<RecordDoc | null> {
+  return (await ctx.db
+    .query('records')
+    .withIndex('by_kind_record', (q) => q.eq('kind', kind.kind).eq('recordId', recordId))
+    .first()) as RecordDoc | null
+}
+
+/** A stored row as the kind's wire row. */
+export function recordDocWire(kind: AnyRecordKind, doc: RecordDoc): RecordWireRow {
+  return recordWireRow(kind, doc.recordId, doc.data, doc.createdAt, doc.updatedAt)
+}
+
+/**
+ * The rows of one kind a resolved query selects, straight from the index the query
+ * resolved to: its equalities, its time range, `.order('desc')` and `.take(limit)` —
+ * which break ties exactly as `orderRecords` does (insertion order). An unbounded list
+ * of an `orderBy` kind is read in index order and ordered by the shared function.
+ */
+export async function queryRecordDocs(
+  ctx: QueryCtx | MutationCtx,
+  kind: AnyRecordKind,
+  resolved: ResolvedRecordQuery,
+): Promise<RecordDoc[]> {
+  // The index range builder is typed per index; the four shapes share `kind` + `at`.
+  type Range = {
+    eq(field: string, value: string): Range
+    gte(field: string, value: string): Range
+    lt(field: string, value: string): Range
+  }
+  const range = (q: Range): Range => {
+    let r = q.eq('kind', kind.kind)
+    if (resolved.index === 'by_kind_key1' || resolved.index === 'by_kind_keys') r = r.eq('key1', resolved.key1!)
+    if (resolved.index === 'by_kind_key2' || resolved.index === 'by_kind_keys') r = r.eq('key2', resolved.key2!)
+    if (resolved.since !== undefined) r = r.gte('at', resolved.since)
+    if (resolved.before !== undefined) r = r.lt('at', resolved.before)
+    return r
+  }
+  const byColumn = kind.orderBy !== undefined && resolved.limit === undefined
+  const indexed = ctx.db.query('records').withIndex(resolved.index, range as never)
+  const read = !byColumn && resolved.order === 'desc' ? indexed.order('desc') : indexed
+  const docs = (resolved.limit !== undefined ? await read.take(resolved.limit) : await read.collect()) as RecordDoc[]
+  if (!byColumn) return docs
+  return orderRecords(kind, docs.map(indexedDoc), resolved).map((entry) => entry.doc)
+}
+
+function indexedDoc(doc: RecordDoc): IndexedRecord & { doc: RecordDoc } {
+  return { id: doc.recordId, slots: { ...doc }, columns: doc.data, doc }
+}
+
+/**
+ * The wire rows of one kind for a query — the records, plus (while a legacy source is
+ * declared) the legacy rows no record shadows, matched and ordered by the SAME pure
+ * functions the in-memory store uses. The one list reader: the kind's `list` and any
+ * server-side reader of the kind (the delivery snapshot) go through it.
+ */
+export async function listRecordWire(
+  ctx: QueryCtx | MutationCtx,
+  kind: AnyRecordKind,
+  resolved: ResolvedRecordQuery,
+  legacy?: LegacyRecordSource,
+): Promise<RecordWireRow[]> {
+  if (!legacy) return (await queryRecordDocs(ctx, kind, resolved)).map((doc) => recordDocWire(kind, doc))
+  // TOLERANT READ (marked): the union is read unbounded and ordered once, here.
+  const { limit: _limit, ...unbounded } = resolved
+  const docs = await queryRecordDocs(ctx, kind, { ...unbounded, order: 'asc' })
+  const shadowed = new Set(docs.map((doc) => doc.recordId))
+  const legacyRows = (await legacy.list(ctx))
+    .filter((row) => !shadowed.has(row.recordId))
+    .map((row) => ({
+      id: row.recordId,
+      slots: recordSlots(kind, row.columns, row.createdAt),
+      columns: row.columns,
+      wire: recordWireRow(kind, row.recordId, row.columns, row.createdAt, row.updatedAt),
+    }))
+    .filter((row) => matchesRecordQuery(row, resolved))
+  // Legacy rows predate every record, so they lead in insertion order.
+  const union = [...legacyRows, ...docs.map((doc) => ({ ...indexedDoc(doc), wire: recordDocWire(kind, doc) }))]
+  return orderRecords(kind, union, resolved).map((row) => row.wire)
+}
+
+/** One record's wire row by id — the record, else (while declared) its legacy row. */
+export async function getRecordWire(
+  ctx: QueryCtx | MutationCtx,
+  kind: AnyRecordKind,
+  recordId: string,
+  legacy?: LegacyRecordSource,
+): Promise<RecordWireRow | null> {
+  const doc = await findRecordDoc(ctx, kind, recordId)
+  if (doc) return recordDocWire(kind, doc)
+  const old = legacy ? await legacy.find(ctx, recordId) : null // TOLERANT READ (marked)
+  return old ? recordWireRow(kind, old.recordId, old.columns, old.createdAt, old.updatedAt) : null
+}
+
+/**
+ * Save one record of a kind (the shared write path — the kind's `save` mutation and an
+ * addon's internal ingest mutation both call it). Returns the stored wire row.
+ */
+export async function saveRecord(
+  ctx: MutationCtx,
+  kind: AnyRecordKind,
+  recordId: string,
+  write: Readonly<Record<string, unknown>>,
+  stamps: { createdAt: string; updatedAt: string },
+  legacy?: LegacyRecordSource,
+): Promise<RecordWireRow> {
+  const existing = await findRecordDoc(ctx, kind, recordId)
+  // TOLERANT READ (marked): a legacy-only record is edited from its legacy columns.
+  const lifted = !existing && legacy ? await legacy.find(ctx, recordId) : null
+  const stored = existing?.data ?? lifted?.columns
+  const columns = rethrowAsConvex(() => resolveRecordSave(kind, recordId, stored, write))
+  const createdAt = existing?.createdAt ?? lifted?.createdAt ?? stamps.createdAt
+  const slots = recordSlots(kind, columns, createdAt)
+  if (existing) {
+    // `key1`/`key2` are always written: an edit that empties a key unsets its slot.
+    await ctx.db.patch(existing._id, {
+      data: columns,
+      key1: slots.key1,
+      key2: slots.key2,
+      at: slots.at,
+      updatedAt: stamps.updatedAt,
+    })
+  } else {
+    await ctx.db.insert('records', {
+      kind: kind.kind,
+      recordId,
+      data: columns,
+      ...(slots.key1 !== undefined ? { key1: slots.key1 } : {}),
+      ...(slots.key2 !== undefined ? { key2: slots.key2 } : {}),
+      at: slots.at,
+      createdAt,
+      updatedAt: stamps.updatedAt,
+    })
+    if (lifted && legacy) await legacy.remove(ctx, lifted)
+  }
+  return recordWireRow(kind, recordId, columns, createdAt, stamps.updatedAt)
+}
+
+/** The registered functions of one record kind (the module's exports). */
+export interface RecordFunctions {
+  save: RegisteredMutation<'public', Record<string, unknown>, Promise<RecordWireRow>>
+  get: RegisteredQuery<'public', Record<string, unknown>, Promise<RecordWireRow | null>>
+  list: RegisteredQuery<'public', RecordQuery & Record<string, unknown>, Promise<RecordWireRow[]>>
+  remove: RegisteredMutation<'public', Record<string, unknown>, Promise<void>>
+}
+
+export interface RecordFunctionsOptions {
+  /** TOLERANT READ (marked) — see {@link LegacyRecordSource}. Only a kind that moved declares one. */
+  legacy?: LegacyRecordSource
+}
+
+/** The public CRUD functions of one record kind — see the module header. */
+export function defineRecordFunctions(kind: AnyRecordKind, options: RecordFunctionsOptions = {}): RecordFunctions {
+  const { legacy } = options
+  const idArg = { [kind.idKey]: v.string() }
+  const columnArgs = Object.fromEntries(
+    [...Object.keys(kind.fields), 'meta', 'metaPatch'].map((column) => [column, v.optional(v.any())]),
+  )
+
+  const save = mutation({
+    args: { ...idArg, ...columnArgs, createdAt: v.string(), updatedAt: v.string() },
+    handler: async (ctx, args: Record<string, unknown>) => {
+      await requireCapability(ctx, kind.access.write)
+      const { [kind.idKey]: recordId, createdAt, updatedAt, ...write } = args
+      return saveRecord(
+        ctx,
+        kind,
+        recordId as string,
+        write,
+        { createdAt: createdAt as string, updatedAt: updatedAt as string },
+        legacy,
+      )
+    },
+  })
+
+  const get = query({
+    args: idArg,
+    handler: async (ctx, args: Record<string, unknown>) => {
+      await requireCapability(ctx, kind.access.read)
+      return getRecordWire(ctx, kind, args[kind.idKey] as string, legacy)
+    },
+  })
+
+  const list = query({
+    args: {
+      where: v.optional(v.record(v.string(), v.string())),
+      since: v.optional(v.string()),
+      before: v.optional(v.string()),
+      order: v.optional(v.union(v.literal('asc'), v.literal('desc'))),
+      limit: v.optional(v.number()),
+    },
+    handler: async (ctx, args: RecordQuery) => {
+      await requireCapability(ctx, kind.access.read)
+      const resolved = rethrowAsConvex(() => resolveRecordQuery(kind, args))
+      return listRecordWire(ctx, kind, resolved, legacy)
+    },
+  })
+
+  const remove = mutation({
+    args: idArg,
+    handler: async (ctx, args: Record<string, unknown>) => {
+      await requireCapability(ctx, kind.access.write)
+      const recordId = args[kind.idKey] as string
+      const doc = await findRecordDoc(ctx, kind, recordId)
+      if (doc) await ctx.db.delete(doc._id)
+      // TOLERANT READ (marked): a legacy row of the same id goes too, or it would resurface.
+      const old = legacy ? await legacy.find(ctx, recordId) : null
+      if (old && legacy) await legacy.remove(ctx, old)
+    },
+  })
+
+  return { save, get, list, remove }
+}

package/convex/records.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { z } from 'zod'
+import { CONVEX_MAX_NESTING_DEPTH, measureMaxDepth } from '@elytracms/core/cms-core'
+import { CONTRACT_NOTE_KIND, defineRecordKind, recordRowDepth } from '@elytracms/core/persistence'
+import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
+
+/**
+ * EC-616 — the Convex record store beyond the shared contract scenarios (those run in
+ * `contract-parity.test.ts`): the stored row's nesting depth against Convex's 16-level
+ * ceiling (convex-test does NOT enforce it, so the row is measured here), the kind's
+ * wire (its columns are its argument names, nothing else is accepted), and access (the
+ * kind's capabilities, checked before anything is read or written).
+ */
+
+/** A kind whose writes need administration — proves `access` is the kind's, not a constant. */
+const ADMIN_NOTE_KIND = defineRecordKind({
+  kind: 'adminNote',
+  module: 'adminNotes',
+  fields: { text: z.string().min(1) },
+  access: { read: 'content.read', write: 'project.administer' },
+})
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+  [`./${CONTRACT_NOTE_KIND.module}.ts`]: async () => defineRecordFunctions(CONTRACT_NOTE_KIND),
+  [`./${ADMIN_NOTE_KIND.module}.ts`]: async () => defineRecordFunctions(ADMIN_NOTE_KIND),
+}
+
+const saveNote = makeFunctionReference<'mutation'>('contractNotes:save')
+const listNotes = makeFunctionReference<'query'>('contractNotes:list')
+const getNote = makeFunctionReference<'query'>('contractNotes:get')
+const saveAdminNote = makeFunctionReference<'mutation'>('adminNotes:save')
+
+const STAMP = '2026-10-26T00:00:00.000Z'
+
+async function backendWith(members: Array<{ userId: string; role: string }>) {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    for (const member of members) {
+      await ctx.db.insert('members', { ...member, createdAt: STAMP, updatedAt: STAMP })
+    }
+  })
+  const as = (userId: string) => t.withIdentity({ subject: userId, issuer: 'https://convex.test' })
+  return { t, as }
+}
+
+/** A meta value whose stored row measures exactly `rowDepth`. */
+function metaForRowDepth(rowDepth: number): Record<string, unknown> {
+  // row (1) → data (2) → meta (3) → … : the bag itself sits at row depth 3.
+  let value: Record<string, unknown> = { leaf: true }
+  for (let depth = 3; depth < rowDepth; depth++) value = { nested: value }
+  return value
+}
+
+describe('the records row and Convex’s stored-depth ceiling (EC-616)', () => {
+  it('a record at the ceiling is stored, and its stored row measures ≤ 16', async () => {
+    const { t, as } = await backendWith([{ userId: 'editor', role: 'editor' }])
+    const meta = metaForRowDepth(CONVEX_MAX_NESTING_DEPTH)
+    expect(recordRowDepth({ topic: 't', postedAt: STAMP, meta })).toBe(CONVEX_MAX_NESTING_DEPTH)
+
+    await as('editor').mutation(saveNote, {
+      contractNoteId: 'deepest',
+      topic: 't',
+      postedAt: STAMP,
+      meta,
+      createdAt: STAMP,
+      updatedAt: STAMP,
+    })
+    const stored = await t.run(async (ctx) =>
+      ctx.db
+        .query('records')
+        .withIndex('by_kind_record', (q) => q.eq('kind', 'contractNote').eq('recordId', 'deepest'))
+        .unique(),
+    )
+    expect(stored).not.toBeNull()
+    // Measured on the WHOLE stored document (system fields included) — what Convex measures.
+    expect(measureMaxDepth(stored).depth).toBe(CONVEX_MAX_NESTING_DEPTH)
+  })
+
+  it('one level deeper is refused with a validation error, and nothing is stored', async () => {
+    const { t, as } = await backendWith([{ userId: 'editor', role: 'editor' }])
+    await expect(
+      as('editor').mutation(saveNote, {
+        contractNoteId: 'too_deep',
+        topic: 't',
+        postedAt: STAMP,
+        meta: metaForRowDepth(CONVEX_MAX_NESTING_DEPTH + 1),
+        createdAt: STAMP,
+        updatedAt: STAMP,
+      }),
+    ).rejects.toThrow(/nests 17 levels deep/)
+    expect(await t.run(async (ctx) => (await ctx.db.query('records').collect()).length)).toBe(0)
+  })
+})
+
+describe('a kind’s wire is its own declaration (EC-616)', () => {
+  it('accepts exactly the id key, the columns, meta and the stamps — an unknown argument is refused', async () => {
+    const { as } = await backendWith([{ userId: 'editor', role: 'editor' }])
+    await expect(
+      as('editor').mutation(saveNote, {
+        contractNoteId: 'n',
+        topic: 't',
+        postedAt: STAMP,
+        bogus: 1,
+        createdAt: STAMP,
+        updatedAt: STAMP,
+      }),
+    ).rejects.toThrow(/bogus/)
+    // Control: the same call without the stray argument is stored and returns its wire row.
+    const row = await as('editor').mutation(saveNote, {
+      contractNoteId: 'n',
+      topic: 't',
+      postedAt: STAMP,
+      createdAt: STAMP,
+      updatedAt: STAMP,
+    })
+    expect(row).toEqual({
+      contractNoteId: 'n',
+      topic: 't',
+      status: 'open',
+      postedAt: STAMP,
+      createdAt: STAMP,
+      updatedAt: STAMP,
+    })
+    expect(await as('editor').query(getNote, { contractNoteId: 'n' })).toEqual(row)
+  })
+})
+
+describe('access is the kind’s, checked first (EC-616)', () => {
+  it('a viewer reads and cannot write; a non-member cannot read', async () => {
+    const { as } = await backendWith([
+      { userId: 'editor', role: 'editor' },
+      { userId: 'viewer', role: 'viewer' },
+    ])
+    await as('editor').mutation(saveNote, { contractNoteId: 'n', topic: 't', postedAt: STAMP, createdAt: STAMP, updatedAt: STAMP })
+    expect(await as('viewer').query(listNotes, {})).toHaveLength(1)
+    await expect(
+      as('viewer').mutation(saveNote, { contractNoteId: 'v', topic: 't', postedAt: STAMP, createdAt: STAMP, updatedAt: STAMP }),
+    ).rejects.toThrow(/unauthorized|forbidden|capability/i)
+    await expect(as('stranger').query(listNotes, {})).rejects.toThrow(/unauthorized|forbidden|member/i)
+  })
+
+  it('a kind that declares administration refuses an editor and admits an admin', async () => {
+    const { as } = await backendWith([
+      { userId: 'editor', role: 'editor' },
+      { userId: 'admin', role: 'admin' },
+    ])
+    const write = { adminNoteId: 'a', text: 'x', createdAt: STAMP, updatedAt: STAMP }
+    await expect(as('editor').mutation(saveAdminNote, write)).rejects.toThrow(/unauthorized|forbidden|capability/i)
+    await expect(as('admin').mutation(saveAdminNote, write)).resolves.toMatchObject({ adminNoteId: 'a', text: 'x' })
+  })
+})

package/convex/redirect-migration.test.ts

@@ -0,0 +1,205 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import schema from './schema'
+
+// convex-test fires `runAfter(0)` on a REAL timer; fake timers keep any scheduled
+// revalidation queued (rows written, the `webhooks:deliver` fetch never fired).
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/**
+ * EC-616 — the redirect move from the `redirects` table into `records` (kind `redirect`)
+ * is a STORED-DATA move (Konditorei and Naturkinder hold real redirects), done the EC-587
+ * way: writes to the new home, a marked tolerant read of the old one, an idempotent
+ * per-deployment migration. These run the REAL functions on convex-test over legacy rows
+ * inserted as a pre-EC-616 deployment holds them, and pin "no gap": a deployment with the
+ * new functions pushed and the migration NOT yet run serves exactly what it served before.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const listRedirects = makeFunctionReference<'query'>('redirects:list')
+const getRedirect = makeFunctionReference<'query'>('redirects:get')
+const saveRedirect = makeFunctionReference<'mutation'>('redirects:save')
+const removeRedirect = makeFunctionReference<'mutation'>('redirects:remove')
+const migrateLegacy = makeFunctionReference<'mutation'>('redirects:migrateLegacy')
+const snapshot = makeFunctionReference<'query'>('delivery:snapshot')
+
+const STAMP = '2026-08-01T00:00:00.000Z'
+const LATER = '2026-10-26T00:00:00.000Z'
+
+/** Rows as a pre-EC-616 deployment stores them in the legacy `redirects` table. */
+const LEGACY = [
+  { redirectId: 'r_spring', from: '/spring', to: '/offers', permanent: true, enabled: true },
+  { redirectId: 'r_paused', from: '/paused', to: '/x', permanent: false, enabled: false, meta: { note: 'later' } },
+  { redirectId: 'r_blog', from: '/blog-old', to: '/blog', permanent: true, enabled: true },
+  // Stored before EC-577 refused it: a meta key naming a column. The current schema
+  // refuses this row as a create, so the migration must REPORT it, never drop it.
+  { redirectId: 'r_shadow', from: '/shadow', to: '/real', permanent: true, enabled: true, meta: { to: '/fake' } },
+] as const
+
+async function legacyDeployment(configuredRevalidation = false) {
+  const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env
+  if (configuredRevalidation) {
+    env['CANVAS_REVALIDATE_ENDPOINT'] = 'https://host.invalid/api/revalidate'
+    env['CANVAS_REVALIDATE_SECRET'] = 'ec616-secret'
+  }
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: 'editor', role: 'editor', createdAt: STAMP, updatedAt: STAMP })
+    for (const row of LEGACY) await ctx.db.insert('redirects', { ...row, createdAt: STAMP, updatedAt: STAMP })
+  })
+  const asEditor = t.withIdentity({ subject: 'editor', issuer: 'https://convex.test' })
+  return { t, asEditor }
+}
+
+afterEach(() => {
+  const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env
+  delete env['CANVAS_REVALIDATE_ENDPOINT']
+  delete env['CANVAS_REVALIDATE_SECRET']
+})
+
+/** What the pre-EC-616 functions returned for the legacy rows: each row flat, ordered by `from`. */
+const SERVED_BEFORE = [...LEGACY]
+  .sort((a, b) => (a.from < b.from ? -1 : 1))
+  .map((row) => ({ ...row, createdAt: STAMP, updatedAt: STAMP }))
+
+/** What the pre-EC-616 snapshot served: the enabled rows as routing records. */
+const LIVE_BEFORE = LEGACY.filter((row) => row.enabled).map((row) => ({
+  id: row.redirectId,
+  from: row.from,
+  to: row.to,
+  permanent: row.permanent,
+}))
+
+const byId = (a: { id: string }, b: { id: string }) => (a.id < b.id ? -1 : 1)
+
+async function counts(t: Awaited<ReturnType<typeof legacyDeployment>>['t']) {
+  return t.run(async (ctx) => ({
+    legacy: (await ctx.db.query('redirects').collect()).length,
+    records: (await ctx.db.query('records').collect()).filter((row) => row.kind === 'redirect').length,
+  }))
+}
+
+describe('the redirect move: no gap before the migration runs (EC-616)', () => {
+  it('list, get and the delivery snapshot serve the legacy rows exactly as before', async () => {
+    const { asEditor } = await legacyDeployment()
+    expect(await asEditor.query(listRedirects, {})).toEqual(SERVED_BEFORE)
+    expect(await asEditor.query(getRedirect, { redirectId: 'r_paused' })).toEqual(
+      SERVED_BEFORE.find((row) => row.redirectId === 'r_paused'),
+    )
+    const served = (await asEditor.query(snapshot, { projectId: 'demo' })) as { redirects: { id: string }[] }
+    expect([...served.redirects].sort(byId)).toEqual([...LIVE_BEFORE].sort(byId))
+  })
+
+  it('a save of a legacy-only redirect lifts it: an edit, not a create; the legacy row goes', async () => {
+    const { t, asEditor } = await legacyDeployment()
+    // An edit that leaves `enabled`/`permanent` absent keeps the STORED (legacy) values.
+    const saved = await asEditor.mutation(saveRedirect, {
+      redirectId: 'r_paused',
+      to: '/y',
+      createdAt: LATER,
+      updatedAt: LATER,
+    })
+    expect(saved).toEqual({
+      redirectId: 'r_paused',
+      from: '/paused',
+      to: '/y',
+      permanent: false,
+      enabled: false,
+      meta: { note: 'later' },
+      createdAt: STAMP,
+      updatedAt: LATER,
+    })
+    expect(await counts(t)).toEqual({ legacy: 3, records: 1 })
+    expect((await asEditor.query(listRedirects, {})) as unknown[]).toHaveLength(4)
+  })
+
+  it('a remove of a legacy-only redirect deletes it (it never resurfaces)', async () => {
+    const { t, asEditor } = await legacyDeployment()
+    await asEditor.mutation(removeRedirect, { redirectId: 'r_blog' })
+    expect(await asEditor.query(getRedirect, { redirectId: 'r_blog' })).toBeNull()
+    expect(await counts(t)).toEqual({ legacy: 3, records: 0 })
+  })
+})
+
+describe('redirects:migrateLegacy (EC-616)', () => {
+  it('moves every valid legacy row, reports the refused one, and serves the same set after', async () => {
+    const { t, asEditor } = await legacyDeployment()
+    const first = await t.mutation(migrateLegacy, {})
+    expect(first).toEqual({
+      scanned: 4,
+      moved: 3,
+      shadowed: 0,
+      refused: [{ redirectId: 'r_shadow', message: expect.stringMatching(/meta may not use a column name/) }],
+      movedIds: ['r_blog', 'r_paused', 'r_spring'],
+    })
+    expect(await counts(t)).toEqual({ legacy: 1, records: 3 })
+    // The served set is unchanged by the move — the refused row still serves (tolerant read).
+    expect(await asEditor.query(listRedirects, {})).toEqual(SERVED_BEFORE)
+    const served = (await asEditor.query(snapshot, { projectId: 'demo' })) as { redirects: { id: string }[] }
+    expect([...served.redirects].sort(byId)).toEqual([...LIVE_BEFORE].sort(byId))
+  })
+
+  it('is idempotent: a second run moves nothing', async () => {
+    const { t } = await legacyDeployment()
+    await t.mutation(migrateLegacy, {})
+    expect(await t.mutation(migrateLegacy, {})).toMatchObject({ scanned: 1, moved: 0, shadowed: 0 })
+    expect(await counts(t)).toEqual({ legacy: 1, records: 3 })
+  })
+
+  it('drops a legacy row a record already shadows (a save lifted it meanwhile)', async () => {
+    const { t, asEditor } = await legacyDeployment()
+    // Simulate the race the transaction cannot have: a record and its legacy row both present.
+    await t.run(async (ctx) => {
+      await ctx.db.insert('redirects', {
+        redirectId: 'r_twice',
+        from: '/twice',
+        to: '/a',
+        permanent: true,
+        enabled: true,
+        createdAt: STAMP,
+        updatedAt: STAMP,
+      })
+    })
+    await asEditor.mutation(saveRedirect, { redirectId: 'r_twice', from: '/twice', to: '/b', createdAt: LATER, updatedAt: LATER })
+    await t.run(async (ctx) => {
+      await ctx.db.insert('redirects', {
+        redirectId: 'r_twice',
+        from: '/twice',
+        to: '/a',
+        permanent: true,
+        enabled: true,
+        createdAt: STAMP,
+        updatedAt: STAMP,
+      })
+    })
+    // The record wins every read while both exist…
+    expect(await asEditor.query(getRedirect, { redirectId: 'r_twice' })).toMatchObject({ to: '/b' })
+    // …and the migration drops the shadowed legacy row instead of overwriting the record.
+    expect(await t.mutation(migrateLegacy, {})).toMatchObject({ shadowed: 1 })
+    expect(await asEditor.query(getRedirect, { redirectId: 'r_twice' })).toMatchObject({ to: '/b' })
+  })
+
+  it('schedules no revalidation: the served set is identical before and after', async () => {
+    const { t } = await legacyDeployment(true)
+    await t.mutation(migrateLegacy, {})
+    const scheduled = await t.run(async (ctx) => ctx.db.system.query('_scheduled_functions').collect())
+    expect(scheduled).toEqual([])
+  })
+
+  it('control: a redirect SAVE on the same configured deployment does schedule one', async () => {
+    const { t, asEditor } = await legacyDeployment(true)
+    await asEditor.mutation(saveRedirect, { redirectId: 'r_new', from: '/n', to: '/m', createdAt: LATER, updatedAt: LATER })
+    const scheduled = await t.run(async (ctx) => ctx.db.system.query('_scheduled_functions').collect())
+    expect(scheduled.map((row) => (row.args as [{ event: unknown }])[0].event)).toEqual([{ kind: 'redirects' }])
+  })
+})