@elytracms/studio 0.0.99 → 0.0.101

package/convex/analytics-cost.test.ts

@@ -485,7 +485,7 @@ function pick<T>(random: () => number, weighted: readonly (readonly [T, number])
 }
 
 const SLUGS = [
-  'sommerfest-im-garten-der-konditorei',
+  'sommerfest-im-garten-der-stadthalle',
   'unsere-torten-fuer-hochzeiten',
   'ueber-uns',
   'kontakt-und-anfahrt',

package/convex/cms.ts

@@ -12,9 +12,9 @@ import {
   unfoldValue,
 } from '@elytracms/core/cms-core'
 import type { CmsDocument, DocumentPatch, PatchLogKind, ReplacePrecondition } from '@elytracms/core/cms-core'
-import { isPinnableVersion } from '@elytracms/core/persistence'
+import { isPinnableVersion, planVersionKindStamps } from '@elytracms/core/persistence'
 import type { DocumentVersionKind } from '@elytracms/core/persistence'
-import { mutation, query } from './functions'
+import { internalMutation, mutation, query } from './functions'
 import type { MutationCtx, QueryCtx } from './functions'
 import { requireCapability } from './guard'
 import { assertWithinWriteLimits } from './write-limits'
@@ -866,6 +866,33 @@ export const listAllDocumentVersions = query({
   },
 })
 
+/**
+ * EC-707 — the EC-585 kind stamping: every version row recorded before EC-585 (no `kind`)
+ * gets the kind `isPinnableVersion` already reads it as — `label: 'published'` → `'publish'`,
+ * anything else → `'snapshot'` (core `planVersionKindStamps`, the same inference) — so
+ * pinnability is unchanged for every row, and once every deployment reads 0 kind-less rows
+ * the tolerant branch and the optional `kind` can go (EC-707's deletions). Idempotent: a
+ * second run stamps 0; a row that names a kind is never touched; nothing but `kind` is written.
+ *
+ * Internal: an admin runs it from the CLI, once per deployment — `npx convex run
+ * cms:stampVersionKinds` (no args) → `{ scanned, stamped }`; `pnpm demo:reseed` runs it twice.
+ * ONE transaction at a documented bound (`VERSION_KIND_STAMP_BOUND`: 4096 rows / 4 MiB of
+ * rewritten rows, half of Convex's per-transaction write limits): it reads every version row,
+ * as `listAllDocumentVersions` already does for delivery, and above the bound it throws
+ * before writing anything — a refusal is whole, never a partial stamping. `documentVersions`
+ * has no write-chokepoint trigger, so the stamp schedules no revalidation (delivery reads the
+ * same pins before and after).
+ */
+export const stampVersionKinds = internalMutation({
+  args: {},
+  handler: async (ctx) => {
+    const rows = await ctx.db.query('documentVersions').collect()
+    const stamps = planVersionKindStamps(rows)
+    for (const { row, kind } of stamps) await ctx.db.patch(row._id, { kind })
+    return { scanned: rows.length, stamped: stamps.length }
+  },
+})
+
 /**
  * Pin an EXISTING version live (EC-224 `pinVersion`, changeset revert). Pin integrity is
  * enforced here, in the transaction: the version must exist for THIS document

package/convex/records-column-transform.convex.test.ts

@@ -21,7 +21,8 @@ import { defineRecordFunctions } from './record-functions'
  * Before: the operations parsed the write and sent the PARSED values over the wire, where the
  * mutation parsed them again — `seed!!` stored with `ok: true`, and a type-changing column
  * (`string → length`) refused. Measured red on the wave base 21678336: 12 of 12. Now the
- * operations judge the columns and send the caller's values as sent.
+ * operations send the values as sent (EC-694), and judge no column themselves (EC-702): the
+ * mutation is the one executor, and its refusal arrives located (`records-one-write.convex.test.ts`).
  *
  * The three copies are real zod releases (the engine's own 4.4.3; the aliased devDependencies
  * `zod-copy-older` 4.1.13 and `zod-copy-newer` 4.6.7). The client is the real
@@ -126,11 +127,12 @@ describe.each(LENGTHS)('EC-694 — Convex, a type-changing column of the $copy z
 })
 
 describe('EC-694 — Convex, what the operations send', () => {
-  it('a refused value is the operation’s own refusal: no mutation runs, nothing stored', async () => {
+  it('a refused value is the mutation’s located refusal, through the operation (EC-702): nothing stored', async () => {
     const { t, ops } = await connected()
     const kind = EXCLAIMED[0]!.kind
     const refused = await ops.records(kind).save({ projectId: PROJECT, id: 'refused', text: 42 as never })
-    expect(refused).toMatchObject({ ok: false, error: { code: 'validation', message: `Input for “${kind.module}.save” is invalid.` } })
+    expect(refused).toMatchObject({ ok: false, error: { code: 'validation' } })
+    expect(!refused.ok && refused.error.code === 'validation' && refused.error.issues.map((issue) => issue.path)).toEqual([['text']])
     expect(await t.run(async (ctx) => ctx.db.query('records').collect())).toEqual([])
   })
 

package/convex/records-one-write.convex.test.ts

@@ -0,0 +1,218 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import { getFunctionName } from 'convex/server'
+import type { FunctionReference } from 'convex/server'
+import { z } from 'zod'
+import { z as newerZod } from 'zod-copy-newer'
+import { z as olderZod } from 'zod-copy-older'
+import { createOperations } from '@elytracms/core/operations'
+import type { AuthorizationHook, OperationEvent } from '@elytracms/core/operations'
+import { PersistenceValidationError, defineRecordKind } from '@elytracms/core/persistence'
+import type { AnyRecordKind, RecordColumnSchema } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter, UNCARRIABLE_VALUE } from '../src/lib/persistence/convex-adapter'
+import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
+
+/**
+ * EC-702 (Codex round 6 F31 residual + F32), the Convex half — a record save through
+ * `operations.records(kind)` is ONE write: captured when the call starts, authorized as captured,
+ * executed exactly as authorized, and parsed ONCE, in the kind's `save` mutation
+ * (`defineRecordFunctions(kind).save` → `resolveRecordSave`).
+ *
+ * Measured red on the wave base 85b983de through this file's as-written copy of
+ * `codex-review-2026-10-28-r6/record-raw-contracts.ts` (22 of 22 on Convex): a save authorized as
+ * `allowed` stored `forbidden`; a transform ran twice; a mutating normaliser stored `seed!!`.
+ *
+ * The client is the real `ConvexPersistenceAdapter` over convex-test, signed in as an editor
+ * member (the probe's wiring), with the kind's functions in the kind's module. The in-memory half
+ * is `core/src/operations/records-one-write.test.ts`.
+ */
+
+type Vendor = typeof z
+const COPIES = [
+  ['own', z],
+  ['older', olderZod as unknown as Vendor],
+  ['newer', newerZod as unknown as Vendor],
+] as const
+const WRAPPERS = ['required', 'optional', 'default'] as const
+const FORMS = ['custom transform', 'preprocess'] as const
+type Wrapper = (typeof WRAPPERS)[number]
+type Form = (typeof FORMS)[number]
+
+const PROJECT = 'site'
+const STAMP = '2026-10-29T00:00:00.000Z'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(STAMP)
+})
+afterEach(() => vi.useRealTimers())
+
+function kindOf(fields: Record<string, unknown>): AnyRecordKind {
+  return defineRecordKind({
+    kind: 'reviewTransform',
+    module: 'reviewTransforms',
+    fields: fields as Record<string, RecordColumnSchema>,
+  })
+}
+
+/** The real client adapter over convex-test, signed in as an editor; the operations over it. */
+async function connected(fields: Record<string, unknown>, authorize?: AuthorizationHook) {
+  const kind = kindOf(fields)
+  const t = convexTest(schema, {
+    './_generated/api.ts': async () => ({}),
+    [`./${kind.module}.ts`]: async () => defineRecordFunctions(kind),
+  })
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: 'editor', role: 'editor', createdAt: STAMP, updatedAt: STAMP })
+  })
+  const editor = t.withIdentity({ subject: 'editor', issuer: 'https://convex.test' })
+  const calls: string[] = []
+  const client = {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => editor.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => {
+      calls.push(getFunctionName(ref))
+      return editor.mutation(ref, args ?? {})
+    },
+  } as unknown as ConvexHttpClient
+  const adapter = new ConvexPersistenceAdapter(client, PROJECT)
+  const ops = createOperations({ adapter, collections: () => [], validateDocument: () => [], ...(authorize ? { authorize } : {}) })
+  const events: OperationEvent[] = []
+  ops.events.subscribe((event) => events.push(event))
+  return { t, direct: adapter.records(kind), records: ops.records(kind), events, calls }
+}
+
+function normalising(vendor: Vendor, form: Form, wrapper: Wrapper) {
+  const normalize = (value: { text: string }) => {
+    value.text += '!'
+    return value
+  }
+  const isText = (value: unknown) => typeof value === 'object' && value !== null && typeof (value as { text?: unknown }).text === 'string'
+  const inner =
+    form === 'custom transform'
+      ? vendor.custom<{ text: string }>(isText).transform(normalize)
+      : vendor.preprocess((value) => (isText(value) ? normalize(value as { text: string }) : value), vendor.object({ text: vendor.string() }))
+  return wrapper === 'optional' ? inner.optional() : wrapper === 'default' ? inner.default({ text: 'safe' }) : inner
+}
+
+const pathsOf = (result: { ok: boolean; error?: unknown }) =>
+  !result.ok && (result.error as { code: string }).code === 'validation'
+    ? (result.error as { issues: { path?: unknown }[] }).issues.map((issue) => issue.path)
+    : undefined
+
+describe('EC-702 — F32 on Convex: the write authorized is the write executed', () => {
+  it('a caller that rewrites its input while authorization awaits changes nothing: the authorized write is stored, never the denied one', async () => {
+    const decisions: string[] = []
+    let reached!: () => void
+    let resume!: () => void
+    const atHook = new Promise<void>((resolve) => (reached = resolve))
+    const gate = new Promise<void>((resolve) => (resume = resolve))
+    const { direct, records } = await connected({ text: z.string() }, async (request) => {
+      const id = (request.input as { id: string }).id
+      decisions.push(id)
+      if (id === 'allowed') {
+        reached()
+        await gate
+      }
+      return id === 'allowed' ? { allow: true } : { allow: false, reason: `“${id}” is not yours.` }
+    })
+    // Positive control: this hook denies a direct save to `forbidden`.
+    expect(await records.save({ projectId: PROJECT, id: 'forbidden', text: 'denied' })).toMatchObject({ ok: false, error: { code: 'unauthorized' } })
+    expect(await direct.find(PROJECT, 'forbidden')).toBeUndefined()
+
+    const input = { projectId: PROJECT, id: 'allowed', text: 'original' }
+    const pending = records.save(input)
+    await atHook
+    input.id = 'forbidden'
+    input.text = 'changed after parse'
+    resume()
+    expect(await pending).toMatchObject({ ok: true, value: { id: 'allowed', text: 'original' } })
+    expect(decisions).toEqual(['forbidden', 'allowed'])
+    expect(await direct.get(PROJECT, 'allowed')).toMatchObject({ text: 'original' })
+    expect(await direct.find(PROJECT, 'forbidden')).toBeUndefined()
+  })
+})
+
+describe('EC-702 — F31 on Convex: a column transform runs once per write, in the mutation', () => {
+  it.each(WRAPPERS)('%s: the counter reads 1 per write through the operations, as through the repository (create and edit)', async (wrapper) => {
+    let calls = 0
+    const inner = z.string().transform((value) => `${value}:${++calls}`)
+    const column = wrapper === 'optional' ? inner.optional() : wrapper === 'default' ? inner.default('safe') : inner
+    const { direct, records } = await connected({ text: column })
+    calls = 0
+    expect(await direct.save(PROJECT, { id: 'direct', text: 'seed' })).toMatchObject({ text: 'seed:1' })
+    expect(calls).toBe(1)
+    calls = 0
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', text: 'seed' })).toMatchObject({ ok: true, value: { text: 'seed:1' } })
+    expect(calls).toBe(1)
+    calls = 0
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', text: 'edit' })).toMatchObject({ ok: true, value: { text: 'edit:1' } })
+    expect(calls).toBe(1)
+  })
+
+  for (const [copy, vendor] of COPIES) {
+    for (const form of FORMS) {
+      it.each(WRAPPERS)(`${copy} zod, ${form}, %s: a mutating normaliser stores \`seed!\` then \`edit!\` through the operations, as through the repository`, async (wrapper) => {
+        const { direct, records } = await connected({ payload: normalising(vendor, form, wrapper) })
+        expect(await direct.save(PROJECT, { id: 'direct', payload: { text: 'seed' } })).toMatchObject({ payload: { text: 'seed!' } })
+        expect(await direct.save(PROJECT, { id: 'direct', payload: { text: 'edit' } })).toMatchObject({ payload: { text: 'edit!' } })
+        expect(await records.save({ projectId: PROJECT, id: 'viaops', payload: { text: 'seed' } })).toMatchObject({ ok: true, value: { payload: { text: 'seed!' } } })
+        expect(await records.save({ projectId: PROJECT, id: 'viaops', payload: { text: 'edit' } })).toMatchObject({ ok: true, value: { payload: { text: 'edit!' } } })
+        expect((await direct.get(PROJECT, 'viaops')).payload).toEqual({ text: 'edit!' })
+      })
+    }
+  }
+})
+
+describe('EC-702 — the store is the one judge of a column, located (Convex)', () => {
+  it('a value the column refuses (a number for `z.string()`) is the operation’s located `validation` failure, after authorization (`failed`) — the mutation refused it, nothing stored', async () => {
+    const { t, records, events, calls } = await connected({ text: z.string() })
+    const refused = await records.save({ projectId: PROJECT, id: 'refused', text: 42 as never })
+    expect(refused).toMatchObject({ ok: false, error: { code: 'validation' } })
+    expect(pathsOf(refused)).toEqual([['text']])
+    expect(events.map((event) => event.status)).toEqual(['failed'])
+    // The server judged it: one mutation ran, and its transaction stored nothing.
+    expect(calls).toEqual(['reviewTransforms:save'])
+    expect(await t.run(async (ctx) => ctx.db.query('records').collect())).toEqual([])
+  })
+
+  it('a `Date` in a `z.string()` column — a value the wire cannot carry — is refused located at `[text]`, before any request', async () => {
+    const { t, records, events, calls } = await connected({ text: z.string() })
+    const refused = await records.save({ projectId: PROJECT, id: 'dated', text: new Date(0) as never })
+    expect(refused).toMatchObject({ ok: false, error: { code: 'validation' } })
+    expect(pathsOf(refused)).toEqual([['text']])
+    expect(!refused.ok && refused.error.code === 'validation' && refused.error.issues[0]!.code).toBe(UNCARRIABLE_VALUE)
+    expect(events.map((event) => event.status)).toEqual(['failed'])
+    expect(calls).toEqual([])
+    expect(await t.run(async (ctx) => ctx.db.query('records').collect())).toEqual([])
+  })
+
+  it('the repository itself refuses an uncarriable value as a located `PersistenceValidationError` — at the deepest value or key that fails', async () => {
+    const { direct, calls } = await connected({ payload: z.unknown() })
+    const cases: [unknown, (string | number)[]][] = [
+      [new Date(0), ['payload']],
+      [{ nested: { when: new Date(0) } }, ['payload', 'nested', 'when']],
+      [{ list: ['a', new Map()] }, ['payload', 'list', 1]],
+      [{ nested: { $junk: 1 } }, ['payload', 'nested', '$junk']],
+      [{ ['ü']: 1 }, ['payload', 'ü']],
+      [[1, undefined], ['payload', 1]],
+    ]
+    for (const [payload, path] of cases) {
+      const error = await direct.save(PROJECT, { id: 'r', payload }).then(
+        () => undefined,
+        (thrown: unknown) => thrown,
+      )
+      expect(error).toBeInstanceOf(PersistenceValidationError)
+      expect((error as PersistenceValidationError).issues.map((issue) => [issue.code, issue.path])).toEqual([[UNCARRIABLE_VALUE, path]])
+    }
+    expect(calls).toEqual([])
+  })
+
+  it('control: a carriable value crosses and is stored', async () => {
+    const { direct } = await connected({ payload: z.unknown() })
+    expect(await direct.save(PROJECT, { id: 'r', payload: { nested: { when: '1970-01-01', n: 1n, list: [1, null] } } })).toMatchObject({
+      payload: { nested: { when: '1970-01-01', list: [1, null] } },
+    })
+  })
+})

package/convex/redirect-migration.test.ts

@@ -14,7 +14,7 @@ afterEach(() => {
 
 /**
  * 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
+ * is a STORED-DATA move (both production consumers 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

package/convex/redirects.ts

@@ -22,7 +22,7 @@ import { recordEntryFromWire } from '@elytracms/core/persistence'
  * `export * from '@elytracms/studio/convex/redirects'` line are unchanged. Content-gated
  * (a viewer reads, an editor writes), NOT admin-only — redirects are content.
  *
- * ## The move from the `redirects` table (stored data — KON and NK hold real redirects)
+ * ## The move from the `redirects` table (stored data — both production consumers hold real redirects)
  *
  * The EC-587 precedent, with no gap:
  *
@@ -92,7 +92,7 @@ export async function loadRedirectEntries(ctx: QueryCtx, projectId: string): Pro
  * identical before and after by construction (the tolerant read), so the move needs no
  * revalidation — through the triggers it would schedule two sweeps per row (an insert
  * into `records`, a delete from `redirects`). One transaction: Convex bounds it at 8192
- * written rows, far above any editorial redirect set (KON's import holds 192).
+ * written rows, far above any editorial redirect set (a production site's import holds 192).
  */
 export const migrateLegacy = (internalMutationGeneric as MutationBuilder<DataModel, 'internal'>)({
   args: {},

package/convex/shared-capture.convex.test.ts

@@ -0,0 +1,165 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import { getFunctionName } from 'convex/server'
+import type { FunctionReference } from 'convex/server'
+import { z } from 'zod'
+import { UNCOPYABLE_VALUE, createOperations } from '@elytracms/core/operations'
+import type { AuthorizationHook, OperationEvent, OperationIssue } from '@elytracms/core/operations'
+import { defineRecordKind } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter, UNCARRIABLE_VALUE } from '../src/lib/persistence/convex-adapter'
+import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
+
+/**
+ * EC-713 (Codex round 7 F32 residual), the Convex half — Codex's 24 shared/private cases through
+ * `operations.records(kind)` over the real `ConvexPersistenceAdapter` (convex-test, signed-in
+ * editor). This project runs in the edge runtime, whose `structuredClone` shares a
+ * `SharedArrayBuffer` too (measured, wave-0102): the capture's walk of the clone is what refuses it.
+ *
+ * Before (measured on the wave base 188e35bf): a shared input was captured, AUTHORIZED, and only then
+ * refused by the record repository's wire check (`uncarriable-value`, `failed`) — so Codex called it
+ * no Convex bypass, but authorization had judged memory the caller could still change. Now it is the
+ * capture's `uncopyable-value` (`rejected`) before any step: the hook never sees it, no mutation runs.
+ * The private controls keep their outcome: an `ArrayBuffer` crosses the wire and the authorized byte
+ * is stored; a typed array, a `DataView` or a `Map` is still the wire's located refusal.
+ *
+ * The in-memory half is `core/src/operations/shared-capture.test.ts`.
+ */
+
+type Binary = ArrayBuffer | SharedArrayBuffer | Uint8Array | DataView
+type Segment = string | number
+
+const PROJECT = 'site'
+const STAMP = '2026-10-31T00:00:00.000Z'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(STAMP)
+})
+afterEach(() => vi.useRealTimers())
+
+const byteOf = (value: Binary): number =>
+  value instanceof Uint8Array ? Number(value[0]) : value instanceof DataView ? value.getUint8(0) : Number(new Uint8Array(value)[0])
+
+const PLACES = [
+  { name: 'column', put: (v: Binary): unknown => v, get: (v: unknown) => v as Binary, path: ['value'] as Segment[] },
+  {
+    name: 'object',
+    put: (v: Binary): unknown => ({ nested: { bytes: v } }),
+    get: (v: unknown) => (v as { nested: { bytes: Binary } }).nested.bytes,
+    path: ['value', 'nested', 'bytes'] as Segment[],
+  },
+  { name: 'list', put: (v: Binary): unknown => [v], get: (v: unknown) => (v as Binary[])[0]!, path: ['value', 0] as Segment[] },
+  {
+    name: 'map',
+    put: (v: Binary): unknown => new Map([['bytes', v]]),
+    get: (v: unknown) => (v as Map<string, Binary>).get('bytes')!,
+    path: ['value'] as Segment[],
+  },
+] as const
+const SHAPES = ['buffer', 'uint8', 'dataView'] as const
+
+function issuesOf(result: { ok: boolean; error?: unknown }): readonly OperationIssue[] {
+  return !result.ok && (result.error as { code: string }).code === 'validation' ? (result.error as { issues: readonly OperationIssue[] }).issues : []
+}
+
+/** The real client adapter over convex-test, signed in as an editor; the operations over it. */
+async function connected(read: (value: unknown) => number, authorize: AuthorizationHook) {
+  const kind = defineRecordKind({ kind: 'byte', module: 'bytes', fields: { value: z.unknown().transform(read) } })
+  const t = convexTest(schema, {
+    './_generated/api.ts': async () => ({}),
+    [`./${kind.module}.ts`]: async () => defineRecordFunctions(kind),
+  })
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: 'editor', role: 'editor', createdAt: STAMP, updatedAt: STAMP })
+  })
+  const editor = t.withIdentity({ subject: 'editor', issuer: 'https://convex.test' })
+  const calls: string[] = []
+  const client = {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => editor.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => {
+      calls.push(getFunctionName(ref))
+      return editor.mutation(ref, args ?? {})
+    },
+  } as unknown as ConvexHttpClient
+  const adapter = new ConvexPersistenceAdapter(client, PROJECT)
+  const ops = createOperations({ adapter, collections: () => [], validateDocument: () => [], authorize })
+  const events: OperationEvent[] = []
+  ops.events.subscribe((event) => events.push(event))
+  return { t, direct: adapter.records(kind), records: ops.records(kind), events, calls }
+}
+
+describe('EC-713 — Codex round 7 F32 residual on Convex: shared memory is refused at the capture, before authorization', () => {
+  for (const shape of SHAPES)
+    for (const place of PLACES)
+      for (const shared of [false, true]) {
+        // What the wire carries (Convex's own `convexToJson`): an `ArrayBuffer`, in a column, an object or a list.
+        const carriable = shape === 'buffer' && place.name !== 'map'
+        const label = shared
+          ? 'shared: `uncopyable-value` before authorization, no mutation'
+          : carriable
+            ? 'private control: the authorized 1 is stored'
+            : 'private control: still the wire’s located refusal, after authorization'
+        it(`${shape}/${place.name}/${label}`, async () => {
+          const read = (v: unknown) => byteOf(place.get(v))
+          let reached!: () => void
+          let resume!: () => void
+          const atHook = new Promise<void>((resolve) => (reached = resolve))
+          const gate = new Promise<void>((resolve) => (resume = resolve))
+          const judged: number[] = []
+          const { t, records, events, calls } = await connected(read, async (request) => {
+            const value = read((request.input as { value: unknown }).value)
+            judged.push(value)
+            if (value !== 1) return { allow: false, reason: 'only byte 1' }
+            reached()
+            await gate
+            return { allow: true }
+          })
+          const carry = (buffer: ArrayBuffer | SharedArrayBuffer) =>
+            place.put(shape === 'buffer' ? buffer : shape === 'uint8' ? new Uint8Array(buffer) : new DataView(buffer))
+
+          // The instrument: the hook denies byte 9, before any request.
+          const denied = new ArrayBuffer(1)
+          new Uint8Array(denied)[0] = 9
+          expect(await records.save({ projectId: PROJECT, id: 'denied', value: carry(denied) })).toMatchObject({
+            ok: false,
+            error: { code: 'unauthorized' },
+          })
+
+          const buffer = shared ? new SharedArrayBuffer(1) : new ArrayBuffer(1)
+          new Uint8Array(buffer)[0] = 1
+          const pending = records.save({ projectId: PROJECT, id: 'r', value: carry(buffer) })
+          const first = await Promise.race([pending.then(() => 'returned' as const), atHook.then(() => 'authorizing' as const)])
+          if (first === 'authorizing') {
+            new Uint8Array(buffer)[0] = 9
+            resume()
+          }
+          const result = await pending
+          const issues = issuesOf(result)
+          const stored = await t.run(async (ctx) => ctx.db.query('records').collect())
+
+          if (shared) {
+            expect(issues.map((issue) => [issue.code, issue.path])).toEqual([[UNCOPYABLE_VALUE, place.path]])
+            expect(issues[0]!.message).toContain('shared memory')
+            expect(judged).toEqual([9])
+            expect(events.map((event) => event.status)).toEqual(['denied', 'rejected'])
+            expect(calls).toEqual([])
+            expect(stored).toEqual([])
+            return
+          }
+          expect(first).toBe('authorizing')
+          expect(judged).toEqual([9, 1])
+          if (carriable) {
+            expect(result).toMatchObject({ ok: true, value: { id: 'r', value: 1 } })
+            expect(calls).toEqual(['bytes:save'])
+            expect(stored).toHaveLength(1)
+            return
+          }
+          expect(issues.map((issue) => [issue.code, issue.path?.[0]])).toEqual([[UNCARRIABLE_VALUE, 'value']])
+          expect(events.map((event) => event.status)).toEqual(['denied', 'failed'])
+          expect(calls).toEqual([])
+          expect(stored).toEqual([])
+        })
+      }
+})

package/convex/version-kind-stamping.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { foldDocument } from '@elytracms/core/cms-core'
+import type { CmsDocument } from '@elytracms/core/cms-core'
+import { VERSION_KIND_STAMP_BOUND, isPinnableVersion, scanStoredShapes } from '@elytracms/core/persistence'
+import schema from './schema'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/**
+ * EC-707 — the EC-585 kind stamping, the REAL internal mutation (`cms:stampVersionKinds`,
+ * the line an admin runs with `npx convex run`) on convex-test's backend: planted kind-less
+ * rows of each label are stamped with exactly the kind `isPinnableVersion` reads them as,
+ * a row that names a kind is untouched, pinnability is unchanged for every row, a second
+ * run stamps 0, and above the documented bound the run refuses whole.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+const stampVersionKinds = makeFunctionReference<'mutation'>('cms:stampVersionKinds')
+
+const STAMP = '2026-10-29T00:00:00.000Z'
+const snapshot = (id: string) =>
+  foldDocument({ collection: 'page', id, values: { title: id } } as unknown as CmsDocument)
+
+/** The planted rows: kind-less of each label, and two that name a kind. */
+const PLANTED = [
+  { docId: 'a', version: 1, label: 'published' },
+  { docId: 'a', version: 2, label: 'pre-restore' },
+  { docId: 'a', version: 3, label: 'AI snapshot' },
+  { docId: 'b', version: 1 },
+  { docId: 'b', version: 2, label: 'published', kind: 'snapshot' as const },
+  { docId: 'b', version: 3, label: 'pre-restore', kind: 'publish' as const },
+]
+
+async function plant(
+  rows: ReadonlyArray<{ docId: string; version: number; label?: string; kind?: 'publish' | 'snapshot' }>,
+) {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    for (const row of rows) {
+      await ctx.db.insert('documentVersions', {
+        collection: 'page',
+        snapshot: snapshot(row.docId),
+        createdAt: STAMP,
+        ...row,
+      })
+    }
+  })
+  return t
+}
+
+const stored = (t: Awaited<ReturnType<typeof plant>>) =>
+  t.run(async (ctx) =>
+    (await ctx.db.query('documentVersions').collect()).sort((x, y) =>
+      x.docId + x.version < y.docId + y.version ? -1 : 1,
+    ),
+  )
+
+describe('EC-707 — cms:stampVersionKinds stamps what isPinnableVersion infers, once', () => {
+  it('stamps every kind-less row by its label, leaves a kinded row alone, keeps pinnability; a second run stamps 0', async () => {
+    const t = await plant(PLANTED)
+    const before = await stored(t)
+    expect(before.filter((row) => row.kind === undefined)).toHaveLength(4)
+
+    expect(await t.mutation(stampVersionKinds, {})).toEqual({ scanned: 6, stamped: 4 })
+    const after = await stored(t)
+    expect(after.map((row) => `${row.docId}@v${row.version} ${row.kind}`)).toEqual([
+      'a@v1 publish',
+      'a@v2 snapshot',
+      'a@v3 snapshot',
+      'b@v1 snapshot',
+      'b@v2 snapshot', // named a kind: untouched (its label says published, its kind wins)
+      'b@v3 publish',
+    ])
+    // The migration preserves meaning: every row pins exactly as it did kind-less.
+    expect(after.map(isPinnableVersion)).toEqual(before.map(isPinnableVersion))
+    // Nothing but `kind` was written: label, snapshot (still folded), createdAt as planted.
+    for (const [index, row] of after.entries()) {
+      const { kind: _k, ...rest } = row
+      const { kind: _b, ...was } = before[index]!
+      expect(rest).toEqual(was)
+    }
+    // The at-rest scan now reads 0 kind-less rows here.
+    const scan = scanStoredShapes({ cmsDocuments: [], documentVersions: after }, { collections: [] })
+    expect(scan.byShape['kind-less-version']).toBe(0)
+
+    expect(await t.mutation(stampVersionKinds, {})).toEqual({ scanned: 6, stamped: 0 })
+  })
+
+  it('CONTROL: before the stamping the at-rest scan counts the kind-less rows (the scan can see them)', async () => {
+    const t = await plant(PLANTED)
+    const scan = scanStoredShapes({ cmsDocuments: [], documentVersions: await stored(t) }, { collections: [] })
+    expect(scan.byShape['kind-less-version']).toBe(4)
+  })
+
+  it('refuses WHOLE above the documented row bound — nothing stamped', async () => {
+    const rows = Array.from({ length: VERSION_KIND_STAMP_BOUND.rows + 1 }, (_, index) => ({
+      docId: 'c',
+      version: index + 1,
+      label: 'published',
+    }))
+    const t = await plant(rows)
+    await expect(t.mutation(stampVersionKinds, {})).rejects.toThrow(
+      /exceed the one-transaction stamping bound of 4096 — nothing was stamped/,
+    )
+    const after = await stored(t)
+    expect(after.every((row) => row.kind === undefined)).toBe(true)
+  }, 60_000)
+})

package/dist/components/ai/ai-chat-panel-lazy.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { Suspense, lazy } from 'react';
 import { Text } from '@elytracms/studio/ui';
 import { translate } from '../../lib/i18n/index.js';
+import { LazySurfaceBoundary } from '../load-failure.js';
 /**
  * Lazy boundary for the AI chat panel (EC-199, EC-331/EC-334 bundle discipline). The
  * panel and everything it imports — `useChat` + the AI SDK (`ai` / `@ai-sdk/react`),
@@ -12,10 +13,14 @@ import { translate } from '../../lib/i18n/index.js';
  * `version-compare-lazy` / `rich-text/lazy`.
  */
 const AiChatPanelImpl = lazy(() => import('./ai-chat-panel.js').then((module) => ({ default: module.AiChatPanel })));
+/** The panel's aside — shared by the loading state and a failed load (EC-717). */
+function AiPanelFrame({ children }) {
+    return (_jsx("aside", { className: "flex h-full min-h-0 w-[360px] shrink-0 flex-col border-l border-border bg-card", children: children }));
+}
 function AiPanelFallback() {
-    return (_jsx("aside", { className: "flex h-full min-h-0 w-[360px] shrink-0 flex-col border-l border-border bg-card", children: _jsx("div", { className: "grid min-h-0 flex-1 place-items-center p-6", children: _jsx(Text, { size: "sm", tone: "muted", children: translate('ai.panel.loading') }) }) }));
+    return (_jsx(AiPanelFrame, { children: _jsx("div", { className: "grid min-h-0 flex-1 place-items-center p-6", children: _jsx(Text, { size: "sm", tone: "muted", children: translate('ai.panel.loading') }) }) }));
 }
 export function AiChatPanel() {
-    return (_jsx(Suspense, { fallback: _jsx(AiPanelFallback, {}), children: _jsx(AiChatPanelImpl, {}) }));
+    return (_jsx(LazySurfaceBoundary, { frame: (notice) => _jsx(AiPanelFrame, { children: notice }), children: _jsx(Suspense, { fallback: _jsx(AiPanelFallback, {}), children: _jsx(AiChatPanelImpl, {}) }) }));
 }
 //# sourceMappingURL=ai-chat-panel-lazy.js.map

package/dist/components/ai/ai-chat-panel-lazy.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-chat-panel-lazy.js","sourceRoot":"","sources":["../../../src/components/ai/ai-chat-panel-lazy.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAChC,MAAM,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAC9E,CAAA;AAED,SAAS,eAAe;IACtB,OAAO,CACL,gBAAO,SAAS,EAAC,gFAAgF,YAC/F,cAAK,SAAS,EAAC,4CAA4C,YACzD,KAAC,IAAI,IAAC,IAAI,EAAC,IAAI,EAAC,IAAI,EAAC,OAAO,YACzB,SAAS,CAAC,kBAAkB,CAAC,GACzB,GACH,GACA,CACT,CAAA;AACH,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,CACL,KAAC,QAAQ,IAAC,QAAQ,EAAE,KAAC,eAAe,KAAG,YACrC,KAAC,eAAe,KAAG,GACV,CACZ,CAAA;AACH,CAAC","sourcesContent":["import { Suspense, lazy } from 'react'\nimport { Text } from '@elytracms/studio/ui'\nimport { translate } from '../../lib/i18n'\n\n/**\n * Lazy boundary for the AI chat panel (EC-199, EC-331/EC-334 bundle discipline). The\n * panel and everything it imports — `useChat` + the AI SDK (`ai` / `@ai-sdk/react`),\n * the client tool executor, `applyContentWithShape`, the provider adapters — load\n * ONLY when a configured studio actually opens the panel. An unconfigured studio never\n * renders the toggle, never mounts this, and so pulls none of the AI chunk onto the CMS\n * critical path (pinned by the `lib/ai` bundle test). Same pattern as\n * `version-compare-lazy` / `rich-text/lazy`.\n */\nconst AiChatPanelImpl = lazy(() =>\n  import('./ai-chat-panel').then((module) => ({ default: module.AiChatPanel })),\n)\n\nfunction AiPanelFallback() {\n  return (\n    <aside className=\"flex h-full min-h-0 w-[360px] shrink-0 flex-col border-l border-border bg-card\">\n      <div className=\"grid min-h-0 flex-1 place-items-center p-6\">\n        <Text size=\"sm\" tone=\"muted\">\n          {translate('ai.panel.loading')}\n        </Text>\n      </div>\n    </aside>\n  )\n}\n\nexport function AiChatPanel() {\n  return (\n    <Suspense fallback={<AiPanelFallback />}>\n      <AiChatPanelImpl />\n    </Suspense>\n  )\n}\n"]}
+{"version":3,"file":"ai-chat-panel-lazy.js","sourceRoot":"","sources":["../../../src/components/ai/ai-chat-panel-lazy.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD;;;;;;;;GAQG;AACH,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAChC,MAAM,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAC9E,CAAA;AAED,kFAAkF;AAClF,SAAS,YAAY,CAAC,EAAE,QAAQ,EAA2B;IACzD,OAAO,CACL,gBAAO,SAAS,EAAC,gFAAgF,YAC9F,QAAQ,GACH,CACT,CAAA;AACH,CAAC;AAED,SAAS,eAAe;IACtB,OAAO,CACL,KAAC,YAAY,cACX,cAAK,SAAS,EAAC,4CAA4C,YACzD,KAAC,IAAI,IAAC,IAAI,EAAC,IAAI,EAAC,IAAI,EAAC,OAAO,YACzB,SAAS,CAAC,kBAAkB,CAAC,GACzB,GACH,GACO,CAChB,CAAA;AACH,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,CACL,KAAC,mBAAmB,IAAC,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,KAAC,YAAY,cAAE,MAAM,GAAgB,YAC3E,KAAC,QAAQ,IAAC,QAAQ,EAAE,KAAC,eAAe,KAAG,YACrC,KAAC,eAAe,KAAG,GACV,GACS,CACvB,CAAA;AACH,CAAC","sourcesContent":["import { Suspense, lazy } from 'react'\nimport type { ReactNode } from 'react'\nimport { Text } from '@elytracms/studio/ui'\nimport { translate } from '../../lib/i18n'\nimport { LazySurfaceBoundary } from '../load-failure'\n\n/**\n * Lazy boundary for the AI chat panel (EC-199, EC-331/EC-334 bundle discipline). The\n * panel and everything it imports — `useChat` + the AI SDK (`ai` / `@ai-sdk/react`),\n * the client tool executor, `applyContentWithShape`, the provider adapters — load\n * ONLY when a configured studio actually opens the panel. An unconfigured studio never\n * renders the toggle, never mounts this, and so pulls none of the AI chunk onto the CMS\n * critical path (pinned by the `lib/ai` bundle test). Same pattern as\n * `version-compare-lazy` / `rich-text/lazy`.\n */\nconst AiChatPanelImpl = lazy(() =>\n  import('./ai-chat-panel').then((module) => ({ default: module.AiChatPanel })),\n)\n\n/** The panel's aside — shared by the loading state and a failed load (EC-717). */\nfunction AiPanelFrame({ children }: { children: ReactNode }) {\n  return (\n    <aside className=\"flex h-full min-h-0 w-[360px] shrink-0 flex-col border-l border-border bg-card\">\n      {children}\n    </aside>\n  )\n}\n\nfunction AiPanelFallback() {\n  return (\n    <AiPanelFrame>\n      <div className=\"grid min-h-0 flex-1 place-items-center p-6\">\n        <Text size=\"sm\" tone=\"muted\">\n          {translate('ai.panel.loading')}\n        </Text>\n      </div>\n    </AiPanelFrame>\n  )\n}\n\nexport function AiChatPanel() {\n  return (\n    <LazySurfaceBoundary frame={(notice) => <AiPanelFrame>{notice}</AiPanelFrame>}>\n      <Suspense fallback={<AiPanelFallback />}>\n        <AiChatPanelImpl />\n      </Suspense>\n    </LazySurfaceBoundary>\n  )\n}\n"]}