@elytracms/studio 0.0.92 → 0.0.94

package/convex/asset-alt-migration.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { measureMaxDepth } from '@elytracms/core/cms-core'
+import { InMemoryAssetRepository, assetAlt, liftLegacyAssetAlts } from '@elytracms/core/persistence'
+import type { AssetRecord } from '@elytracms/core/persistence'
+import schema from './schema'
+
+// convex-test fires a `runAfter(0)` on a REAL timer; fake timers keep the scheduled
+// revalidations queued (rows written, the `webhooks:deliver` fetch never fired).
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/**
+ * EC-587 — the one-shot migration of the legacy `alt` column into `meta.alt`, its one
+ * home: the REAL internal mutation (`assets:liftLegacyAlt`, the line the operator runs
+ * with `npx convex run`) on convex-test's backend, and the in-memory runner
+ * (`liftLegacyAssetAlts`) held to the same expectations over the same rows.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const liftLegacyAlt = makeFunctionReference<'mutation'>('assets:liftLegacyAlt')
+
+const STAMP = '2026-10-26T00:00:00.000Z'
+
+/** The four shapes a stored asset row can hold its alt in. */
+const ROWS = [
+  { assetId: 'column_only', alt: 'Harbour' },
+  { assetId: 'both', alt: 'stale column', meta: { alt: 'Meta wins', credit: 'Ada' } },
+  { assetId: 'meta_only', meta: { alt: 'Already home' } },
+  { assetId: 'none', meta: { credit: 'Jo' } },
+] as const
+
+function row(input: (typeof ROWS)[number]) {
+  return {
+    filename: `${input.assetId}.jpg`,
+    contentType: 'image/jpeg',
+    byteSize: 1,
+    storageKey: `k_${input.assetId}`,
+    createdAt: STAMP,
+    updatedAt: STAMP,
+    ...input,
+  }
+}
+
+/** What every reader sees BEFORE the lift — the migration must not change it. */
+const READ_BEFORE = { column_only: 'Harbour', both: 'Meta wins', meta_only: 'Already home', none: null }
+
+const EXPECTED_META = {
+  column_only: { alt: 'Harbour' },
+  both: { alt: 'Meta wins', credit: 'Ada' },
+  meta_only: { alt: 'Already home' },
+  none: { credit: 'Jo' },
+}
+
+async function seededBackend() {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    for (const input of ROWS) await ctx.db.insert('assets', row(input) as never)
+  })
+  return t
+}
+
+async function storedRows(t: Awaited<ReturnType<typeof seededBackend>>) {
+  return t.run(async (ctx) => {
+    const rows = await ctx.db.query('assets').collect()
+    return Object.fromEntries(rows.map((r) => [r.assetId, { alt: r.alt, meta: r.meta }]))
+  })
+}
+
+describe('EC-587 — assets:liftLegacyAlt moves the legacy column home, once', () => {
+  it('lifts the column into meta.alt (meta.alt wins when both), unsets it, and keeps every alt reading', async () => {
+    const t = await seededBackend()
+    const before = await storedRows(t)
+    expect(Object.fromEntries(Object.entries(before).map(([id, r]) => [id, assetAlt(r)]))).toEqual(READ_BEFORE)
+
+    const report = (await t.mutation(liftLegacyAlt, {})) as { scanned: number; lifted: string[] }
+    expect(report.scanned).toBe(4)
+    expect([...report.lifted].sort()).toEqual(['both', 'column_only'])
+
+    const after = await storedRows(t)
+    for (const [id, stored] of Object.entries(after)) {
+      expect(stored.alt, `${id}: the column is gone`).toBeUndefined()
+      expect(stored.meta, `${id}: meta`).toEqual(EXPECTED_META[id as keyof typeof EXPECTED_META])
+      // convex-test enforces no nesting depth — the stored shape asserts it itself.
+      expect(measureMaxDepth(stored.meta).depth).toBeLessThanOrEqual(16)
+    }
+    // The lift changes no reading: every alt is what it was.
+    expect(Object.fromEntries(Object.entries(after).map(([id, r]) => [id, assetAlt(r)]))).toEqual(READ_BEFORE)
+  })
+
+  it('is idempotent: a second run lifts nothing and writes nothing', async () => {
+    const t = await seededBackend()
+    await t.mutation(liftLegacyAlt, {})
+    const once = await storedRows(t)
+    const scheduledAfterFirst = await t.run(async (ctx) => (await ctx.db.system.query('_scheduled_functions').collect()).length)
+    const again = (await t.mutation(liftLegacyAlt, {})) as { scanned: number; lifted: string[] }
+    expect(again).toEqual({ scanned: 4, lifted: [] })
+    expect(await storedRows(t)).toEqual(once)
+    const scheduledAfterSecond = await t.run(async (ctx) => (await ctx.db.system.query('_scheduled_functions').collect()).length)
+    expect(scheduledAfterSecond).toBe(scheduledAfterFirst)
+  })
+
+  it('the in-memory runner does the same to the same rows (the playground / headless equivalent)', async () => {
+    const records: AssetRecord[] = ROWS.map((input) => {
+      const { assetId, ...rest } = row(input)
+      return { ...rest, id: assetId, projectId: 'p' } as AssetRecord
+    })
+    const repo = new InMemoryAssetRepository({ seed: records })
+    const report = await liftLegacyAssetAlts(repo, 'p')
+    expect(report.scanned).toBe(4)
+    expect([...report.lifted].sort()).toEqual(['both', 'column_only'])
+    const after = await repo.listAssets('p')
+    expect(Object.fromEntries(after.map((r) => [r.id, { alt: r.alt, meta: r.meta }]))).toEqual(
+      Object.fromEntries(Object.entries(EXPECTED_META).map(([id, meta]) => [id, { alt: undefined, meta }])),
+    )
+    expect((await liftLegacyAssetAlts(repo, 'p')).lifted).toEqual([])
+  })
+})

package/convex/asset-replace.test.ts

@@ -0,0 +1,168 @@
+import { readFileSync } from 'node:fs'
+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 { defaultAssetCollection } from '@elytracms/core/cms-core'
+import { InMemoryBlobStorage, InMemoryPersistenceAdapter } from '@elytracms/core/persistence'
+import type { AssetRepository } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import { runUpload } from '../src/lib/assets/upload'
+import schema from './schema'
+
+// convex-test fires a `runAfter(0)` on a REAL timer; fake timers keep the scheduled
+// revalidation queued (its row written, the `webhooks:deliver` fetch never fired).
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/**
+ * EC-568 — "replace works in both persistence modes, same id, derived data regenerated
+ * through the upload path" and "verify the revalidation covers a replace, do not assume".
+ * The REAL `runUpload` (replace mode) against the in-memory adapter and against the
+ * Convex adapter over convex-test (the real `assets:upsert` through the real trigger
+ * wrapper); the replace's revalidation is read off `_scheduled_functions`, as
+ * `asset-revalidate.test.ts` does (its redirect write is that file's known-positive
+ * control for the instrument).
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const PROJECT_ID = 'asset-replace'
+const SESSION_USER_ID = 'user_admin'
+
+async function convexBackend() {
+  const t = convexTest(schema, modules)
+  const now = new Date().toISOString()
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: SESSION_USER_ID, role: 'admin', createdAt: now, updatedAt: now })
+  })
+  const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+  const client = {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => asAdmin.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => asAdmin.mutation(ref, args ?? {}),
+  } as unknown as ConvexHttpClient
+  return { t, adapter: new ConvexPersistenceAdapter(client, PROJECT_ID) }
+}
+
+function withRevalidationEnv<T>(run: () => Promise<T>): Promise<T> {
+  const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env
+  const keys = ['CANVAS_REVALIDATE_ENDPOINT', 'CANVAS_REVALIDATE_SECRET'] as const
+  const previous = keys.map((key) => env[key])
+  env['CANVAS_REVALIDATE_ENDPOINT'] = 'https://host.invalid/api/revalidate'
+  env['CANVAS_REVALIDATE_SECRET'] = 'ec568-secret'
+  return run().finally(() => {
+    keys.forEach((key, index) => {
+      const value = previous[index]
+      if (value === undefined) delete env[key]
+      else env[key] = value
+    })
+  })
+}
+
+const iptcJpeg = new Uint8Array(
+  readFileSync(new URL('../../core/src/cms-core/__fixtures__/embedded-metadata/iptc-xmp.jpg', import.meta.url)),
+)
+const newFile = {
+  name: 'new.jpg',
+  type: 'image/jpeg',
+  size: iptcJpeg.byteLength,
+  arrayBuffer: async () => iptcJpeg.slice().buffer as ArrayBuffer,
+}
+
+async function seedHero(assets: AssetRepository) {
+  await assets.upsertAsset(PROJECT_ID, {
+    id: 'hero',
+    filename: 'old.jpg',
+    contentType: 'image/jpeg',
+    byteSize: 10,
+    width: 4000,
+    height: 3000,
+    storageKey: 'blob_old',
+    url: 'https://assets.test/old.jpg',
+    focalPoint: { x: 0.2, y: 0.8 },
+    thumb: { storageKey: 'blob_thumb_old', url: 'https://assets.test/old-t.webp', width: 480, height: 360 },
+    lqip: 'data:image/webp;base64,OLD',
+    meta: { alt: 'Editor alt', note: 'kept' },
+  })
+}
+
+/** Replace hero's file through THE upload path; the comparable record after it. */
+async function replaceHero(assets: AssetRepository) {
+  await seedHero(assets)
+  const result = await runUpload(
+    {
+      blobs: new InMemoryBlobStorage(),
+      assets,
+      assetFields: defaultAssetCollection().fields,
+      detectDimensions: async () => ({ width: 8, height: 6 }),
+      generateVariants: async () => ({ lqip: 'data:image/webp;base64,NEW' }),
+    },
+    { projectId: PROJECT_ID, file: newFile, replace: { assetId: 'hero' } },
+  )
+  expect(result.ok).toBe(true)
+  const after = await assets.getAsset(PROJECT_ID, 'hero')
+  return {
+    ids: (await assets.listAssets(PROJECT_ID)).map((a) => a.id),
+    filename: after.filename,
+    byteSize: after.byteSize,
+    storageKey: after.storageKey,
+    width: after.width,
+    height: after.height,
+    thumb: after.thumb ?? null,
+    lqip: after.lqip ?? null,
+    focalPoint: after.focalPoint ?? null,
+    meta: after.meta,
+  }
+}
+
+describe('EC-568 — a file replace means the same thing on both adapters', () => {
+  it('same id; new bytes and every derived column regenerated (or cleared); meta overridden per key; focal kept', async () => {
+    const memory = await replaceHero(new InMemoryPersistenceAdapter().assets)
+    const convex = await replaceHero((await convexBackend()).adapter.assets)
+    const expected = {
+      ids: ['hero'],
+      filename: 'new.jpg',
+      byteSize: iptcJpeg.byteLength,
+      storageKey: 'blob-1',
+      width: 8,
+      height: 6,
+      thumb: null,
+      lqip: 'data:image/webp;base64,NEW',
+      focalPoint: { x: 0.2, y: 0.8 },
+      meta: {
+        alt: 'A harbour at dusk & boats',
+        note: 'kept',
+        credit: 'Ana Credit (XMP)',
+        copyright: '© 2026 Example (XMP)',
+      },
+    }
+    expect({ memory, convex }).toEqual({ memory: expected, convex: expected })
+  })
+
+  it('the replace reaches the live site: it schedules the asset revalidation (kind asset, the asset id)', async () => {
+    await withRevalidationEnv(async () => {
+      const { t, adapter } = await convexBackend()
+      await seedHero(adapter.assets) // a create schedules nothing (EC-579)
+      const scheduled = async () =>
+        t.run(async (ctx) =>
+          (await ctx.db.system.query('_scheduled_functions').collect())
+            .filter((row) => row.name.startsWith('webhooks'))
+            .map((row) => (row.args as [{ event?: unknown }])[0]?.event),
+        )
+      expect(await scheduled()).toEqual([])
+      const result = await runUpload(
+        { blobs: new InMemoryBlobStorage(), assets: adapter.assets, assetFields: defaultAssetCollection().fields },
+        { projectId: PROJECT_ID, file: newFile, replace: { assetId: 'hero' } },
+      )
+      expect(result.ok).toBe(true)
+      expect(await scheduled()).toEqual([{ kind: 'asset', id: 'hero' }])
+    })
+  })
+})

package/convex/asset-revalidate.test.ts

@@ -101,7 +101,7 @@ const assetArgs = {
   byteSize: 1,
   storageKey: 'placeholder',
   url: 'https://assets.invalid/photo.png',
-  alt: 'old',
+  meta: { alt: 'old' },
   createdAt: STAMP,
   updatedAt: STAMP,
 }
@@ -128,13 +128,13 @@ describe('EC-579 — the write chokepoint revalidates on every asset edit', () =
       await asAdmin.mutation(upsertAsset, assetArgs)
       expect(await scheduledRevalidations(t)).toHaveLength(1)
 
-      await asAdmin.mutation(upsertAsset, { ...assetArgs, alt: 'new' })
+      await asAdmin.mutation(upsertAsset, { ...assetArgs, meta: { alt: 'new' } })
 
       // The edit IS live output: the published snapshot already serves it.
       const snapshot = (await t.query(deliverySnapshot, { projectId: 'ec579' })) as {
-        assets: { alt?: string }[]
+        assets: { meta?: { alt?: string } }[]
       }
-      expect(snapshot.assets[0]?.alt).toBe('new')
+      expect(snapshot.assets[0]?.meta?.alt).toBe('new')
 
       expect(await scheduledRevalidations(t)).toEqual([{ kind: 'redirects' }, ASSET_EVENT])
     })
@@ -179,13 +179,13 @@ describe('EC-579 — the write chokepoint revalidates on every asset edit', () =
       const t = await freshBackend()
       const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
       await asAdmin.mutation(upsertAsset, assetArgs)
-      await asAdmin.mutation(upsertAsset, { ...assetArgs, alt: 'new' })
+      await asAdmin.mutation(upsertAsset, { ...assetArgs, meta: { alt: 'new' } })
       // The first test is the known-positive control: the same edit on the same
       // harness DOES schedule when the scope is configured.
       expect(await scheduledRevalidations(t)).toEqual([])
       // The write itself still happened — silence is at the webhook, not the save.
       expect(
-        await t.run(async (ctx) => (await ctx.db.query('assets').first())?.alt),
+        await t.run(async (ctx) => (await ctx.db.query('assets').first())?.meta?.alt),
       ).toBe('new')
     })
   })

package/convex/assets.ts

@@ -1,9 +1,9 @@
 import { ConvexError, v } from 'convex/values'
 import type { GenericId, Validator } from 'convex/values'
 import type { DocumentByName, WithoutSystemFields } from 'convex/server'
-import { assetRowSchema, rejectedWriteMessage, resolveRecordWrite } from '@elytracms/core/persistence'
+import { liftLegacyAlt as legacyAltLift, rejectedWriteMessage, resolveAssetWrite } from '@elytracms/core/persistence'
 import type { DataModel } from './functions'
-import { mutation, query } from './functions'
+import { internalMutation, mutation, query } from './functions'
 import { requireCapability } from './guard'
 
 /**
@@ -23,9 +23,10 @@ const clearable = <T, F extends string>(validator: Validator<T, 'required', F>)
   v.optional(v.union(v.null(), validator))
 
 /**
- * Write one asset (EC-577). The ONE write rule (`resolveRecordWrite`, shared with
+ * Write one asset (EC-577). The ONE write rule (`resolveAssetWrite`, shared with
  * the in-memory adapter) runs here, inside the transaction: a column absent from
- * the args keeps its stored value, `null` clears it, a value sets it. An edit is
+ * the args keeps its stored value, `null` clears it, a value sets it — and the legacy
+ * `alt` column can only be cleared (EC-587: an asset's alt is `meta.alt`). An edit is
  * ONE `db.patch` — the rule's store patch, where a cleared column is `undefined`,
  * which `db.patch` removes — so the write-chokepoint triggers fire once. No stored
  * asset → ONE `db.insert` of the complete row (the `defaults` fill what the write
@@ -41,6 +42,12 @@ export const upsert = mutation({
     storageKey: v.optional(v.string()),
     width: clearable(v.number()),
     height: clearable(v.number()),
+    /**
+     * LEGACY column (EC-587): accepted on the wire only so a write that still sets it
+     * is refused BY THE RULE with a message naming `meta.alt` (not a bare validator
+     * error); `null` clears it. Dropped with the column once `liftLegacyAlt` ran on
+     * every deployment.
+     */
     alt: clearable(v.string()),
     title: clearable(v.string()),
     url: clearable(v.string()),
@@ -73,7 +80,7 @@ export const upsert = mutation({
       .query('assets')
       .withIndex('by_asset', (q) => q.eq('assetId', assetId))
       .first()
-    const resolved = resolveRecordWrite(assetRowSchema, existing ?? undefined, write, defaults ?? {})
+    const resolved = resolveAssetWrite(existing ?? undefined, write, defaults ?? {})
     if (!resolved.ok) {
       throw new ConvexError({
         code: 'validation',
@@ -91,6 +98,35 @@ export const upsert = mutation({
   },
 })
 
+/**
+ * EC-587 — the one-shot migration of the legacy `alt` column: every asset row holding
+ * it gets the value lifted into `meta.alt` (unless `meta` already carries an `alt`
+ * key, which wins — it is what every reader already reads) and the column unset, by
+ * the ONE pure rule (core `liftLegacyAlt`, shared with the in-memory runner
+ * `liftLegacyAssetAlts`). Idempotent: a second run lifts nothing.
+ *
+ * Internal: run by an admin from the CLI, never by a client —
+ * `npx convex run assets:liftLegacyAlt` (no args). Each lifted row is one `db.patch`
+ * through the write-chokepoint triggers, so it schedules the asset's revalidation like
+ * any asset edit (the delivered alt is unchanged by the lift; the sweep is harmless).
+ * One transaction: Convex bounds it at 8192 written rows, far above any v1 library —
+ * documented, not paginated (as `cms:clearDocuments`).
+ */
+export const liftLegacyAlt = internalMutation({
+  args: {},
+  handler: async (ctx) => {
+    const rows = await ctx.db.query('assets').collect()
+    const lifted: string[] = []
+    for (const row of rows) {
+      const patch = legacyAltLift(row)
+      if (!patch) continue
+      await ctx.db.patch(row._id, patch as Partial<AssetDoc>)
+      lifted.push(row.assetId)
+    }
+    return { scanned: rows.length, lifted }
+  },
+})
+
 export const get = query({
   args: { assetId: v.string() },
   handler: async (ctx, args) => {

package/convex/auth.ts

@@ -4,8 +4,9 @@ import { actionGeneric } from 'convex/server'
 import type { AnyDataModel, GenericMutationCtx } from 'convex/server'
 import { ConvexError, v } from 'convex/values'
 import type { GenericId } from 'convex/values'
-import { classifyInviteSignup, normalizeInviteEmail } from '@elytracms/core/persistence'
+import { bootstrapRole, classifyInviteSignup, normalizeInviteEmail } from '@elytracms/core/persistence'
 import type { InviteSignupDecision } from '@elytracms/core/persistence'
+import { deployedRolePolicy } from './roles'
 
 /** The provider list `convexAuth` accepts, derived from its own signature. */
 type ConvexAuthProviders = Parameters<typeof convexAuth>[0]['providers']
@@ -210,7 +211,9 @@ export async function gateSessionCreation(
     case 'bootstrap-admin':
       await ctx.db.insert('members', {
         userId: args.userId,
-        role: 'admin',
+        // EC-605: the deployed policy's strongest role (which the policy rules require
+        // to grant `project.administer`) — `admin` under the default policy.
+        role: bootstrapRole(deployedRolePolicy()),
         createdAt: now,
         updatedAt: now,
       })

package/convex/authority.ts

@@ -1,12 +1,14 @@
 import { checkAuthorityFloor } from '@elytracms/core/operations'
 import {
   buildAuthorityAuditEntry,
-  defaultRolePolicy,
+  isKnownRole,
+  policyRoleIds,
   roleGrantsCapability,
 } from '@elytracms/core/persistence'
 import type { AuthorityAuditOutcome, ProjectRole } from '@elytracms/core/persistence'
 import type { MutationCtx } from './functions'
 import { memberRole, type GuardCtx } from './guard'
+import { deployedRolePolicy } from './roles'
 
 /**
  * The engine integrity FLOOR at the Convex trust boundary (EC-240 / AD-18 tenet
@@ -16,9 +18,10 @@ import { memberRole, type GuardCtx } from './guard'
  * invariants on authority-mutating handlers (`members:set`, `members:remove` —
  * and therefore `users.save`/`users.remove`, which delegate to them):
  *
- * - **(a) assign only roles you hold** — future-proofs the boundary for when
- *   policy opens member-management to non-admins; today an administrator can
- *   grant any role, so this never fires under the default policy.
+ * - **(a) assign only roles you hold** — never fires under the default policy (the
+ *   only administrator, `admin`, is the strongest role); under a declared policy
+ *   with an administering role below the strongest (EC-605) it is what stops that
+ *   role granting — or inviting someone into (`invites:create`) — a rank above its own.
  * - **(b) the last admin can't be removed or demoted** — the hole this closes:
  *   before EC-240 the handlers did a blind upsert/delete, so an admin could
  *   remove the sole admin and lock everyone out (the empty-table bootstrap in
@@ -27,28 +30,32 @@ import { memberRole, type GuardCtx } from './guard'
  * The decision logic is the ONE shared `checkAuthorityFloor` primitive that the
  * engine resolver also calls — this file only supplies the primitives it reads
  * from `ctx.db`, so client and server can never drift. Denials throw
- * `unauthorized: …`, matching the guard convention.
+ * `unauthorized: …`, matching the guard convention. The policy is the deployment's
+ * (EC-605, `deployedRolePolicy`) — the one `requireCapability` granted by.
  */
 export async function assertAuthorityFloor(
   ctx: GuardCtx,
   params: {
     /** The caller (already `requireCapability('project.administer')`-checked). */
     readonly callerId: string
-    /** The member whose role/membership this op changes. */
-    readonly targetUserId: string
+    /**
+     * The member whose role/membership this op changes; absent for an invite (EC-605 —
+     * it grants a role to someone who is not a member yet, so only (a) can apply).
+     */
+    readonly targetUserId?: string
     /** Roles this op grants the target (empty for a pure removal). */
     readonly rolesGranted: readonly ProjectRole[]
     /** True when the op removes the membership entirely. */
     readonly removesMembership: boolean
   },
 ): Promise<void> {
+  const policy = deployedRolePolicy()
   const callerRole = await memberRole(ctx, params.callerId)
-  const targetRole = await memberRole(ctx, params.targetUserId)
+  const targetRole = params.targetUserId !== undefined ? await memberRole(ctx, params.targetUserId) : null
   const members = await ctx.db.query('members').collect()
   // "admin" generalizes to "grants project.administer" (EC-240c) — the same
   // policy the engine resolver uses, so client and server can never drift.
-  const isAdministrator = (role: string) =>
-    roleGrantsCapability(role, 'project.administer', defaultRolePolicy)
+  const isAdministrator = (role: string) => roleGrantsCapability(role, 'project.administer', policy)
   const adminCount = members.filter((m) => isAdministrator(m.role)).length
 
   const decision = checkAuthorityFloor(
@@ -59,11 +66,28 @@ export async function assertAuthorityFloor(
       removesMembership: params.removesMembership,
       adminCount,
     },
-    defaultRolePolicy,
+    policy,
   )
   if (!decision.allow) throw new Error(`unauthorized: ${decision.reason}`)
 }
 
+/**
+ * EC-605 — refuse a role the deployed policy does not declare, at the WRITE (a member's
+ * role, an invite's role), visibly: `invalid-role: …` naming the declared set. The
+ * studio validates against the project's config first; this is the trust boundary's own
+ * check, so a hand-crafted client or a drifted deployment can never store a role nobody
+ * can enforce (an unknown role grants nothing — it would fail closed on every read,
+ * silently).
+ */
+export function assertDeclaredRole(role: string): void {
+  const policy = deployedRolePolicy()
+  if (!isKnownRole(role, policy)) {
+    throw new Error(
+      `invalid-role: role "${role}" is not declared in this deployment's role policy (declared: ${policyRoleIds(policy).join(', ')}). Declare it in elytra.config.ts \`roles\` and re-provision (\`elytra init\`), or pick a declared role.`,
+    )
+  }
+}
+
 /**
  * Append one {@link buildAuthorityAuditEntry} row to the `authorityAudit` table
  * (EC-240 H-tail item 6). Called at the floor chokepoint (`members:set` /

package/convex/cms.ts

@@ -10,6 +10,8 @@ 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 type { DocumentVersionKind } from '@elytracms/core/persistence'
 import { mutation, query } from './functions'
 import type { MutationCtx, QueryCtx } from './functions'
 import { requireCapability } from './guard'
@@ -454,10 +456,15 @@ export const clearDocuments = mutation({
   },
 })
 
-/** Insert the next monotonic version row of a document (folded); returns it. */
+/**
+ * Insert the next monotonic version row of a document (folded); returns it. `kind` is the
+ * mutation that records it (EC-585) — decided HERE, never taken from a client argument, so
+ * a `content.write` caller cannot mint a pinnable row through `saveDocumentVersion`.
+ */
 async function insertVersion(
   ctx: MutationCtx,
   args: { collection: string; docId: string; snapshot: unknown; label?: string; origin?: string; createdAt: string },
+  kind: DocumentVersionKind,
 ) {
   // EC-302: versions are appended monotonically, so the latest-created row holds the
   // highest version — read just that one instead of the whole history.
@@ -475,6 +482,7 @@ async function insertVersion(
     snapshot: foldDocument(args.snapshot as CmsDocument),
     ...(args.label ? { label: args.label } : {}),
     ...(args.origin ? { origin: args.origin } : {}),
+    kind,
     createdAt: args.createdAt,
   })
   return (await ctx.db.get(id))!
@@ -484,7 +492,8 @@ async function insertVersion(
  * Document version history (EC-224): append-only snapshots in `documentVersions`; the
  * live one is pinned by `cmsDocuments.publishedVersion`. Version numbers are 1-based,
  * monotonic per document. Used by the pre-restore snapshot and `documents.snapshot`;
- * publish records its version inside `publishDocument` (one step).
+ * publish records its version inside `publishDocument` (one step). A row written here is
+ * a `'snapshot'` (EC-585): a restore point `publishDocumentVersion` refuses to pin.
  */
 export const saveDocumentVersion = mutation({
   args: {
@@ -498,7 +507,7 @@ export const saveDocumentVersion = mutation({
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.write') // EC-150
     assertWithinWriteLimits(args.snapshot, 'snapshot') // EC-304 B-4
-    const row = await insertVersion(ctx, args)
+    const row = await insertVersion(ctx, args, 'snapshot')
     return withUnfoldedSnapshot(row)
   },
 })
@@ -534,7 +543,7 @@ export const publishDocument = mutation({
       label: args.label ?? 'published',
       ...(args.origin ? { origin: args.origin } : {}),
       createdAt: args.at,
-    })
+    }, 'publish')
     const revision = existing.revision + 1
     // EC-595 retention: compact the log behind the PREVIOUS publish (one cycle kept).
     const previousPublish = (await logAfter(ctx, args.collection, args.docId, 0))
@@ -636,10 +645,15 @@ export const listAllDocumentVersions = query({
 /**
  * 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
- * (`missing-version` otherwise). The changed flag is DERIVED against the pinned snapshot
- * (a pin of an older version against a newer draft reads `true` — Codex P05's sibling),
- * the revision bumps, a `pin` row is logged. EC-585 reroutes this through the one
- * publish operation (Wave 4).
+ * (`missing-version` otherwise) and must have been recorded by `publishDocument`
+ * (`not-pinnable` otherwise — EC-585: a `saveDocumentVersion` row was never validated, so
+ * an editor calling this mutation directly cannot put one live; Codex P03). The changed
+ * flag is DERIVED against the pinned snapshot (a pin of an older version against a newer
+ * draft reads `true` — Codex P05's sibling), the revision bumps, a `pin` row is logged.
+ *
+ * Server-side trust (EC-565 1e, owner-ratified): the checks here are DATA-ONLY — revision,
+ * pin integrity, authority. Schema validation stays the client gate (`documents.publish`
+ * runs it, with the hidden-clear, before `publishDocument` records the row this pins).
  */
 export const publishDocumentVersion = mutation({
   args: {
@@ -654,9 +668,9 @@ export const publishDocumentVersion = mutation({
     const actor = await requireCapability(ctx, 'content.write') // EC-150
     const doc = await draftRow(ctx, args.collection, args.docId)
     if (!doc) return { status: 'missing' as const }
-    if (!(await versionRow(ctx, args.collection, args.docId, args.version))) {
-      return { status: 'missing-version' as const }
-    }
+    const target = await versionRow(ctx, args.collection, args.docId, args.version)
+    if (!target) return { status: 'missing-version' as const }
+    if (!isPinnableVersion(target)) return { status: 'not-pinnable' as const }
     const revision = doc.revision + 1
     const patch = {
       revision,