@elytracms/studio 0.0.98 → 0.0.100

package/convex/records-column-transform.convex.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 { 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 { defineRecordKind } from '@elytracms/core/persistence'
+import type { AnyRecordKind, RecordColumnSchema } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
+
+/**
+ * EC-694 (Codex round 5 F31), the Convex half — a record column's transform runs ONCE per write,
+ * in the generated `save` mutation's transaction (`defineRecordFunctions(kind).save` →
+ * `saveRecord` → `resolveRecordSave`, the one parse EC-682 keeps on the Convex side), whether the
+ * write comes straight through the adapter's repository or through `operations.records(kind)`.
+ *
+ * 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 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
+ * `ConvexPersistenceAdapter` over convex-test, signed in as an editor member — the probe's
+ * wiring (`tasks/codex-review-2026-10-28-r5/record-transform.convex.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
+type Wrapper = (typeof WRAPPERS)[number]
+
+const exclaimed = (vendor: Vendor, wrapper: Wrapper) => {
+  const inner = vendor.string().transform((value) => `${value}!`)
+  return wrapper === 'optional' ? inner.optional() : wrapper === 'default' ? inner.default('safe!') : inner
+}
+const lengthOf = (vendor: Vendor) => vendor.string().transform((value) => value.length)
+const capitalised = (name: string) => `${name.charAt(0).toUpperCase()}${name.slice(1)}`
+
+/** One kind per case, each in its own Convex module (Convex addresses a kind's functions by module). */
+function kindFor(name: string, fields: Record<string, unknown>): AnyRecordKind {
+  return defineRecordKind({ kind: name, module: `${name}s`, fields: fields as Record<string, RecordColumnSchema> })
+}
+
+const EXCLAIMED = COPIES.flatMap(([copy, vendor]) =>
+  WRAPPERS.map((wrapper) => ({ copy, wrapper, column: exclaimed(vendor, wrapper), kind: kindFor(`${copy}${capitalised(wrapper)}Text`, { text: exclaimed(vendor, wrapper) }) })),
+)
+const LENGTHS = COPIES.map(([copy, vendor]) => ({ copy, column: lengthOf(vendor), kind: kindFor(`${copy}Count`, { count: lengthOf(vendor) }) }))
+const PLAIN = kindFor('plainText', { text: z.string() })
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+  ...Object.fromEntries(
+    [...EXCLAIMED.map((row) => row.kind), ...LENGTHS.map((row) => row.kind), PLAIN].map((kind) => [
+      `./${kind.module}.ts`,
+      async () => defineRecordFunctions(kind),
+    ]),
+  ),
+}
+
+const PROJECT = 'site'
+const STAMP = '2026-10-28T00:00:00.000Z'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(STAMP)
+})
+afterEach(() => vi.useRealTimers())
+
+/** The real client adapter over convex-test, as a signed-in editor; and the operations over it. */
+async function connected() {
+  const t = convexTest(schema, modules)
+  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 client = {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => editor.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => editor.mutation(ref, args ?? {}),
+  } as unknown as ConvexHttpClient
+  const adapter = new ConvexPersistenceAdapter(client, PROJECT)
+  const ops = createOperations({ adapter, collections: () => [], validateDocument: () => [] })
+  return { t, adapter, ops }
+}
+
+describe.each(EXCLAIMED)('EC-694 — Convex, a transforming column of the $copy zod copy, $wrapper', ({ column, kind }) => {
+  it('the operations store what the repository stores (`seed!`, then `edit!`) — the transform runs once', async () => {
+    // Controls (pass with the defect present and absent): the column transforms once, and so
+    // does the repository through the same mutation — the value both paths must agree with.
+    expect((column as unknown as z.ZodType).safeParse('seed')).toMatchObject({ success: true, data: 'seed!' })
+    const { adapter, ops } = await connected()
+    const direct = adapter.records(kind)
+    expect(await direct.save(PROJECT, { id: 'direct', text: 'seed' })).toMatchObject({ text: 'seed!' })
+
+    // The defect row: through the operations, create then edit.
+    const records = ops.records(kind)
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', text: 'seed' })).toMatchObject({ ok: true, value: { text: 'seed!' } })
+    expect((await direct.get(PROJECT, 'viaops')).text).toBe('seed!')
+    expect(await direct.save(PROJECT, { id: 'direct', text: 'edit' })).toMatchObject({ text: 'edit!' })
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', text: 'edit' })).toMatchObject({ ok: true, value: { text: 'edit!' } })
+    expect((await direct.get(PROJECT, 'viaops')).text).toBe('edit!')
+  })
+})
+
+describe.each(LENGTHS)('EC-694 — Convex, a type-changing column of the $copy zod copy', ({ column, kind }) => {
+  it('a value the column accepts is stored through the operations, as through the repository (4)', async () => {
+    expect((column as unknown as z.ZodType).safeParse('seed')).toMatchObject({ success: true, data: 4 })
+    const { adapter, ops } = await connected()
+    const direct = adapter.records(kind)
+    expect(await direct.save(PROJECT, { id: 'direct', count: 'seed' })).toMatchObject({ count: 4 })
+
+    const records = ops.records(kind)
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', count: 'seed' })).toMatchObject({ ok: true, value: { count: 4 } })
+    expect((await direct.get(PROJECT, 'viaops')).count).toBe(4)
+    expect(await records.save({ projectId: PROJECT, id: 'viaops', count: 'edited' })).toMatchObject({ ok: true, value: { count: 6 } })
+  })
+})
+
+describe('EC-694 — Convex, what the operations send', () => {
+  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' } })
+    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([])
+  })
+
+  // A plain column: green before EC-694 too; it fails if the caller's whole input were sent,
+  // because the mutation's argument validator refuses a key it does not declare.
+  it('only the write schema’s keys cross the wire: an undeclared key stays behind (create and edit)', async () => {
+    const { ops } = await connected()
+    const records = ops.records(PLAIN)
+    expect(await records.save({ projectId: PROJECT, id: 'r', text: 'seed', stray: 1 } as never)).toMatchObject({ ok: true, value: { text: 'seed' } })
+    const edited = await records.save({ projectId: PROJECT, id: 'r', text: 'edit', stray: 1 } as never)
+    expect(edited).toMatchObject({ ok: true, value: { text: 'edit', projectId: PROJECT } })
+    expect(edited.ok && 'stray' in edited.value).toBe(false)
+  })
+})

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/schema.ts

@@ -302,7 +302,7 @@ export default defineSchema({
     updatedAt: v.string(),
   })
     .index('by_asset', ['assetId'])
-    // EC-671: an ingest claim refuses a storage id an asset row references (`claimIngestUpload`).
+    // EC-671: an ingest claim refuses a storage id an asset row references (`claimIngestUploads`, EC-695).
     .index('by_storage', ['storageKey'])
     .index('by_thumb_storage', ['thumb.storageKey']),
 

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/addon.d.ts

@@ -14,9 +14,10 @@
  * ## The chrome contract
  *
  * The SHELL draws the top bar, the breadcrumb (its section crumb is the view's `label`;
- * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail with its issues
- * foot (findings contributed with {@link useNavIssues}, or always-on through a view's
- * `useIssues`), the banners and the theme. A VIEW owns the whole scrollable content area
+ * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail, the issues badge
+ * and tray in the header (EC-690: findings contributed with {@link useNavIssues}, or
+ * always-on through a view's `useIssues`; a finding may carry a {@link NoticeLocation} the
+ * tray's "Go to" opens) and the theme. A VIEW owns the whole scrollable content area
  * under it — including its own title header: the shell adds no frame, title or padding.
  * A view reaches the studio through its {@link AppViewContext}: the project, its deep
  * link and search, the operations client (every read and write goes through the one
@@ -55,6 +56,7 @@ export { useSetBreadcrumb } from './components/breadcrumb-context.js';
 export type { BreadcrumbItem } from './components/breadcrumb-context.js';
 export { useNavIssues } from './components/nav-issues-registry.js';
 export type { NavIssue } from './components/nav-issues-registry.js';
+export type { NoticeLocation } from './components/notifications/notice-model.js';
 /** A pane in the document editor's inspector — `defineStudio({ documentPanes: [documentPane({ … })] })`. */
 export { documentPane } from './components/inspector/document-panes.js';
 export type { DocumentPane, DocumentPaneContext } from './components/inspector/document-panes.js';

package/dist/addon.js

@@ -14,9 +14,10 @@
  * ## The chrome contract
  *
  * The SHELL draws the top bar, the breadcrumb (its section crumb is the view's `label`;
- * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail with its issues
- * foot (findings contributed with {@link useNavIssues}, or always-on through a view's
- * `useIssues`), the banners and the theme. A VIEW owns the whole scrollable content area
+ * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail, the issues badge
+ * and tray in the header (EC-690: findings contributed with {@link useNavIssues}, or
+ * always-on through a view's `useIssues`; a finding may carry a {@link NoticeLocation} the
+ * tray's "Go to" opens) and the theme. A VIEW owns the whole scrollable content area
  * under it — including its own title header: the shell adds no frame, title or padding.
  * A view reaches the studio through its {@link AppViewContext}: the project, its deep
  * link and search, the operations client (every read and write goes through the one

package/dist/addon.js.map

@@ -1 +1 @@
-{"version":3,"file":"addon.js","sourceRoot":"","sources":["../src/addon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,0FAA0F;AAE1F,OAAO,EAAE,GAAG,EAAE,MAAM,wCAAwC,CAAA;AAkB5D,2FAA2F;AAE3F,8EAA8E;AAC9E,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,6BAA6B,EAC7B,aAAa,EACb,aAAa,GACd,MAAM,kCAAkC,CAAA;AAEzC,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAEjH,4FAA4F;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAA;AAC5F,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,+BAA+B,CAAA;AAQtC,4FAA4F;AAE5F,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAElE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAElE,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AAG/D,4FAA4F;AAE5F,4GAA4G;AAC5G,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AAGpE,gGAAgG;AAEhG;;;;;GAKG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAA;AACrE,yGAAyG;AACzG,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAChE,6FAA6F;AAC7F,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA","sourcesContent":["/**\n * `@elytracms/studio/addon` — THE public addon API (EC-616, ruling EC-565 § 6b item 2).\n *\n * An addon (`@elytracms/forms`, `@elytracms/analytics`, or your own) is an optional\n * package whose studio half contributes navigation items to a project's\n * `defineStudio({ sidebar })` — a rail bound to a record kind, or a view with its own\n * component — and whose backend half is a record kind in the generic record store\n * (`defineRecordKind` / `adapter.records(kind)` in `@elytracms/core/persistence`, its\n * Convex functions from `defineRecordFunctions` in `@elytracms/studio/convex/\n * record-functions`). Everything an addon's studio code touches is exported HERE; the\n * studio's internals (`lib/*`, `components/*`) are not part of the published package.\n * `@elytracms/studio/ui` stays the primitive set (Button, Panel, Text, …).\n *\n * ## The chrome contract\n *\n * The SHELL draws the top bar, the breadcrumb (its section crumb is the view's `label`;\n * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail with its issues\n * foot (findings contributed with {@link useNavIssues}, or always-on through a view's\n * `useIssues`), the banners and the theme. A VIEW owns the whole scrollable content area\n * under it — including its own title header: the shell adds no frame, title or padding.\n * A view reaches the studio through its {@link AppViewContext}: the project, its deep\n * link and search, the operations client (every read and write goes through the one\n * authorized chokepoint), the query hooks over the one cache, the content locale, and\n * the signed-in user with their role.\n *\n * ## The two navigation items\n *\n * ```tsx\n * import { nav } from '@elytracms/studio/addon'\n * import { submissionRecordKind } from './kinds'\n *\n * // a rail bound to a record kind — the portable list/edit surfaces, no component to write\n * nav.rail(submissionRecordKind, { label: 'Submissions' })\n * // a custom component — the whole content area is yours\n * nav.view({ id: 'forms-stats', label: 'Form stats', render: (ctx) => <Stats ctx={ctx} /> })\n * ```\n */\n\n// --- Navigation items and the view contract --------------------------------------------\n\nexport { nav } from './components/app-views/default-modules'\nexport type {\n  CustomViewConfig,\n  RailViewConfig,\n  BuiltinViewConfig,\n} from './components/app-views/default-modules'\nexport type {\n  AppViewContext,\n  AppViewDeepLink,\n  AppViewModule,\n  AppViewQueryHooks,\n  NavIssuesHook,\n  NavPermission,\n  NavPermissionContext,\n  SidebarNode,\n  SidebarViewNode,\n} from './components/app-views/module'\n\n// --- Rails: a record kind, or your own source -------------------------------------------\n\n/** A record rail's pieces, for an addon composing its own view around one. */\nexport {\n  RECORD_RAIL_CAPABILITIES,\n  RecordRailModule,\n  RecordRailProvider,\n  useRecordCollectionViewSource,\n  useRecordList,\n  useRecordRail,\n} from './components/records/record-rail'\nexport type { RecordRailModuleProps, RecordRailPaths, RecordRailStore } from './components/records/record-rail'\nexport { lensDocumentToRecordWrite, recordLensDef, recordToLensDocument } from './components/records/record-lens'\n\n/** The portable list/edit surfaces over any source, and the scaffold that assembles one. */\nexport { CollectionViewSurface } from './components/collection-view/collection-view-surface'\nexport {\n  assembleRailViewSource,\n  metaBagProjection,\n  normalizeOkResult,\n  useRailViewSource,\n} from './components/rail-view-source'\nexport type { OkResult, RailAdapter } from './components/rail-view-source'\nexport type {\n  CollectionViewCapabilities,\n  CollectionViewSource,\n  FieldAccess,\n} from './lib/collection-view/collection-view-source'\n\n// --- Hooks: the cache, the locale, the breadcrumb, the rail foot -------------------------\n\nexport { useOperationCache, useOperationQuery } from './lib/query'\nexport type { OperationCache, ReadState, UseOperationQueryOptions } from './lib/query'\nexport { useStudioLocale } from './lib/locale'\nexport type { StudioLocale } from './lib/locale'\nexport { useSetBreadcrumb } from './components/breadcrumb-context'\nexport type { BreadcrumbItem } from './components/breadcrumb-context'\nexport { useNavIssues } from './components/nav-issues-registry'\nexport type { NavIssue } from './components/nav-issues-registry'\n\n// --- The document editor: contributed inspector panes (EC-618) ---------------------------\n\n/** A pane in the document editor's inspector — `defineStudio({ documentPanes: [documentPane({ … })] })`. */\nexport { documentPane } from './components/inspector/document-panes'\nexport type { DocumentPane, DocumentPaneContext } from './components/inspector/document-panes'\n\n// --- EC-613 (the forms addon): an own source's edit shell, its list key, the UI language -----\n\n/**\n * The portable edit shell alone (AD-19), with its form-column appendix seam (EC-396): an addon\n * that assembles its own source (`useRailViewSource`) renders one record's detail with\n * read-only sections below the editable fields — the forms inbox shows a submission's answers,\n * files and delivery log there.\n */\nexport { PortableDetailEditor } from './components/cms/detail-editor'\n/** The one query key of a kind's records in a project — patch it after a write (`useOperationCache`). */\nexport { recordListKey } from './components/records/record-rail'\n/** Resolve a `LocalizedString` (`'Text'` or `{ en, de, … }`) in the studio's UI language. */\nexport { useLabel } from './lib/i18n'\n"]}
+{"version":3,"file":"addon.js","sourceRoot":"","sources":["../src/addon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,0FAA0F;AAE1F,OAAO,EAAE,GAAG,EAAE,MAAM,wCAAwC,CAAA;AAkB5D,2FAA2F;AAE3F,8EAA8E;AAC9E,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,6BAA6B,EAC7B,aAAa,EACb,aAAa,GACd,MAAM,kCAAkC,CAAA;AAEzC,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAEjH,4FAA4F;AAC5F,OAAO,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAA;AAC5F,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,+BAA+B,CAAA;AAQtC,4FAA4F;AAE5F,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAElE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAElE,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AAI/D,4FAA4F;AAE5F,4GAA4G;AAC5G,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AAGpE,gGAAgG;AAEhG;;;;;GAKG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAA;AACrE,yGAAyG;AACzG,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAChE,6FAA6F;AAC7F,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA","sourcesContent":["/**\n * `@elytracms/studio/addon` — THE public addon API (EC-616, ruling EC-565 § 6b item 2).\n *\n * An addon (`@elytracms/forms`, `@elytracms/analytics`, or your own) is an optional\n * package whose studio half contributes navigation items to a project's\n * `defineStudio({ sidebar })` — a rail bound to a record kind, or a view with its own\n * component — and whose backend half is a record kind in the generic record store\n * (`defineRecordKind` / `adapter.records(kind)` in `@elytracms/core/persistence`, its\n * Convex functions from `defineRecordFunctions` in `@elytracms/studio/convex/\n * record-functions`). Everything an addon's studio code touches is exported HERE; the\n * studio's internals (`lib/*`, `components/*`) are not part of the published package.\n * `@elytracms/studio/ui` stays the primitive set (Button, Panel, Text, …).\n *\n * ## The chrome contract\n *\n * The SHELL draws the top bar, the breadcrumb (its section crumb is the view's `label`;\n * deeper crumbs are contributed with {@link useSetBreadcrumb}), the rail, the issues badge\n * and tray in the header (EC-690: findings contributed with {@link useNavIssues}, or\n * always-on through a view's `useIssues`; a finding may carry a {@link NoticeLocation} the\n * tray's \"Go to\" opens) and the theme. A VIEW owns the whole scrollable content area\n * under it — including its own title header: the shell adds no frame, title or padding.\n * A view reaches the studio through its {@link AppViewContext}: the project, its deep\n * link and search, the operations client (every read and write goes through the one\n * authorized chokepoint), the query hooks over the one cache, the content locale, and\n * the signed-in user with their role.\n *\n * ## The two navigation items\n *\n * ```tsx\n * import { nav } from '@elytracms/studio/addon'\n * import { submissionRecordKind } from './kinds'\n *\n * // a rail bound to a record kind — the portable list/edit surfaces, no component to write\n * nav.rail(submissionRecordKind, { label: 'Submissions' })\n * // a custom component — the whole content area is yours\n * nav.view({ id: 'forms-stats', label: 'Form stats', render: (ctx) => <Stats ctx={ctx} /> })\n * ```\n */\n\n// --- Navigation items and the view contract --------------------------------------------\n\nexport { nav } from './components/app-views/default-modules'\nexport type {\n  CustomViewConfig,\n  RailViewConfig,\n  BuiltinViewConfig,\n} from './components/app-views/default-modules'\nexport type {\n  AppViewContext,\n  AppViewDeepLink,\n  AppViewModule,\n  AppViewQueryHooks,\n  NavIssuesHook,\n  NavPermission,\n  NavPermissionContext,\n  SidebarNode,\n  SidebarViewNode,\n} from './components/app-views/module'\n\n// --- Rails: a record kind, or your own source -------------------------------------------\n\n/** A record rail's pieces, for an addon composing its own view around one. */\nexport {\n  RECORD_RAIL_CAPABILITIES,\n  RecordRailModule,\n  RecordRailProvider,\n  useRecordCollectionViewSource,\n  useRecordList,\n  useRecordRail,\n} from './components/records/record-rail'\nexport type { RecordRailModuleProps, RecordRailPaths, RecordRailStore } from './components/records/record-rail'\nexport { lensDocumentToRecordWrite, recordLensDef, recordToLensDocument } from './components/records/record-lens'\n\n/** The portable list/edit surfaces over any source, and the scaffold that assembles one. */\nexport { CollectionViewSurface } from './components/collection-view/collection-view-surface'\nexport {\n  assembleRailViewSource,\n  metaBagProjection,\n  normalizeOkResult,\n  useRailViewSource,\n} from './components/rail-view-source'\nexport type { OkResult, RailAdapter } from './components/rail-view-source'\nexport type {\n  CollectionViewCapabilities,\n  CollectionViewSource,\n  FieldAccess,\n} from './lib/collection-view/collection-view-source'\n\n// --- Hooks: the cache, the locale, the breadcrumb, the rail foot -------------------------\n\nexport { useOperationCache, useOperationQuery } from './lib/query'\nexport type { OperationCache, ReadState, UseOperationQueryOptions } from './lib/query'\nexport { useStudioLocale } from './lib/locale'\nexport type { StudioLocale } from './lib/locale'\nexport { useSetBreadcrumb } from './components/breadcrumb-context'\nexport type { BreadcrumbItem } from './components/breadcrumb-context'\nexport { useNavIssues } from './components/nav-issues-registry'\nexport type { NavIssue } from './components/nav-issues-registry'\nexport type { NoticeLocation } from './components/notifications/notice-model'\n\n// --- The document editor: contributed inspector panes (EC-618) ---------------------------\n\n/** A pane in the document editor's inspector — `defineStudio({ documentPanes: [documentPane({ … })] })`. */\nexport { documentPane } from './components/inspector/document-panes'\nexport type { DocumentPane, DocumentPaneContext } from './components/inspector/document-panes'\n\n// --- EC-613 (the forms addon): an own source's edit shell, its list key, the UI language -----\n\n/**\n * The portable edit shell alone (AD-19), with its form-column appendix seam (EC-396): an addon\n * that assembles its own source (`useRailViewSource`) renders one record's detail with\n * read-only sections below the editable fields — the forms inbox shows a submission's answers,\n * files and delivery log there.\n */\nexport { PortableDetailEditor } from './components/cms/detail-editor'\n/** The one query key of a kind's records in a project — patch it after a write (`useOperationCache`). */\nexport { recordListKey } from './components/records/record-rail'\n/** Resolve a `LocalizedString` (`'Text'` or `{ en, de, … }`) in the studio's UI language. */\nexport { useLabel } from './lib/i18n'\n"]}

package/dist/components/app-views/default-modules.d.ts

@@ -108,8 +108,15 @@ export interface CustomViewConfig {
     availabilitySection?: SectionId;
     /** OPTIONAL, default-open nav-permission predicate (EC-240 / AD-18). See {@link BuiltinViewConfig.visible}. */
     visible?: NavPermission;
-    /** Always-on rail-foot findings for this view (EC-616, see `NavIssuesHook`). */
+    /** Always-on findings for the shell's issues tray (EC-616, see `NavIssuesHook`). */
     useIssues?: NavIssuesHook;
+    /**
+     * EC-690 — the record kind this view lists, when it is a custom surface over one (the forms
+     * inbox lists `submission`s): a finding located at a record of that kind
+     * (`{ kind: 'record', recordKind, id? }`) then opens HERE, and reaches whoever can open this
+     * view. A record rail (`nav.rail(kind)`) declares it itself.
+     */
+    recordKind?: string;
 }
 /**
  * Derive a stable, deterministic id from the CMS focus (overridable via `config.id`).
@@ -184,7 +191,7 @@ export interface RailViewConfig extends BuiltinViewConfig {
     /** Narrow the default capabilities (create, edit, remove, bulk delete). */
     capabilities?: Partial<CollectionViewCapabilities>;
     availabilitySection?: SectionId;
-    /** Always-on rail-foot findings for this rail (EC-616, see `NavIssuesHook`). */
+    /** Always-on findings for the shell's issues tray (EC-616, see `NavIssuesHook`). */
     useIssues?: NavIssuesHook;
     /** Copy for the loading / failure states (default: generic catalog copy naming the label). */
     messages?: {
@@ -272,7 +279,7 @@ export interface SidebarIdKeyspace {
      * else passes through untouched, including the merely-ambiguous EC-477 case.
      */
     views: AppViewModule[];
-    /** What was found — visible at the rail foot, never silent. */
+    /** What was found — visible in the issues tray, never silent. */
     issues: CustomizationIssue[];
 }
 /**

package/dist/components/app-views/default-modules.js

@@ -239,6 +239,9 @@ export function railView(kind, config = {}) {
         icon: config.icon ?? Database,
         ...(config.availabilitySection ? { availabilitySection: config.availabilitySection } : {}),
         ...(config.useIssues ? { useIssues: config.useIssues } : {}),
+        // EC-690: a finding located at a record (`{ kind: 'record', recordKind }`) resolves to
+        // the rail listing that kind — whatever view id the consumer gave it.
+        recordKind: kind.kind,
         parsePath: recordDeepLink(kind.idKey),
         render: (ctx) => ctx.search.state && ctx.search.state !== 'working' ? (_jsx(SectionStateView, { state: ctx.search.state, title: label() })) : (_jsx(RecordRailModule, { kind: kind, projectId: ctx.projectId, recordId: ctx.deepLink[kind.idKey] ?? null, schema: schema, paths: paths, capabilities: capabilities, label: label(), ...(config.messages ? { messages: config.messages } : {}) })),
     };
@@ -371,6 +374,7 @@ export function customView(config) {
         ...(config.parsePath ? { parsePath: config.parsePath } : {}),
         ...(config.availabilitySection ? { availabilitySection: config.availabilitySection } : {}),
         ...(config.useIssues ? { useIssues: config.useIssues } : {}),
+        ...(config.recordKind ? { recordKind: config.recordKind } : {}),
     };
 }
 /**
@@ -400,7 +404,7 @@ const SIDEBAR_POINT = 'sidebar';
 /**
  * The catalog keys for the two keyspace findings (EC-478). This module stays pure —
  * it names a key and its identifier values; `lib/persona/labels.ts` resolves them at
- * the render site, so the rail foot localizes as one list.
+ * the render site, so the issues tray localizes as one list.
  */
 const KEYSPACE_KEYS = {
     builtinCollision: 'customization.issue.derivedIdBuiltinCollision',