@elytracms/studio 0.0.92 → 0.0.94

package/convex/redirect-revalidate.test.ts

@@ -135,8 +135,12 @@ describe('EC-510 — the write chokepoint revalidates on every redirect write',
       // is the gate working rather than the instrument being blind.
       expect(await scheduledRevalidations(t)).toEqual([])
       // The write itself still happened — silence is at the webhook, not the save.
+      // EC-616: a redirect is stored as a `records` row of kind `redirect` now.
       expect(
-        await t.run(async (ctx) => (await ctx.db.query('redirects').collect()).length),
+        await t.run(
+          async (ctx) =>
+            (await ctx.db.query('records').collect()).filter((row) => row.kind === 'redirect').length,
+        ),
       ).toBe(1)
     })
   })

package/convex/redirects.ts

@@ -1,92 +1,133 @@
-import { ConvexError, v } from 'convex/values'
-import type { DocumentByName, WithoutSystemFields } from 'convex/server'
-import { redirectRowSchema, rejectedWriteMessage, resolveRecordWrite } from '@elytracms/core/persistence'
-import type { DataModel } from './functions'
-import { mutation, query } from './functions'
-import { requireCapability } from './guard'
-
-type RedirectDoc = DocumentByName<DataModel, 'redirects'>
+import { internalMutationGeneric } from 'convex/server'
+import type { MutationBuilder } from 'convex/server'
+import {
+  PersistenceValidationError,
+  recordColumnsOf,
+  recordSlots,
+  redirectRecordKind,
+  resolveRecordQuery,
+  resolveRecordSave,
+} from '@elytracms/core/persistence'
+import type { RedirectEntry } from '@elytracms/core/persistence'
+import type { DataModel, MutationCtx, QueryCtx } from './functions'
+import { defineRecordFunctions, findRecordDoc, listRecordWire } from './record-functions'
+import type { LegacyRecord, LegacyRecordSource } from './record-functions'
+import { recordEntryFromWire } from '@elytracms/core/persistence'
 
 /**
- * Editorial redirects persistence (EC-303). Redirects are data an editor owns —
- * saved+enabled entries go live dynamically (no deploy) via the delivery
- * snapshot. Reachable only through the app's `ConvexRedirectRepository` adapter.
- * Content-gated (a viewer reads, an editor writes), NOT admin-only — redirects
- * are content, not administration.
+ * Editorial redirects persistence (EC-303) — since EC-616 the redirect RECORD KIND over
+ * the generic record store (`redirectRecordKind`, one `records` row per redirect). The
+ * functions keep their names and wire (`redirects:save/get/list/remove`, `redirectId` +
+ * the columns flat), so the studio's adapter and every consumer's
+ * `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 EC-587 precedent, with no gap:
+ *
+ * - **writes go to `records`** (kind `redirect`); nothing writes the legacy table again;
+ * - **reads union the legacy rows no record shadows** — the TOLERANT READ below, marked:
+ *   a deployment with these functions pushed and the migration NOT yet run serves the
+ *   same redirects it served before (`list`, `get`, the delivery snapshot);
+ * - a save of a legacy-only redirect lifts it (record from its columns, legacy row
+ *   deleted, one transaction); a remove deletes both;
+ * - **`redirects:migrateLegacy`** moves every legacy row in one idempotent internal
+ *   mutation and reports counts — run per deployment (both consumers + the prod harness:
+ *   owner-run); the legacy table and this tolerant read are dropped together once it is
+ *   reported run everywhere (a gated item, like EC-587's alt column).
  */
 
-/**
- * Create or modify a redirect (EC-577). The ONE write rule (`resolveRecordWrite`,
- * shared with the in-memory adapter) runs here, inside the transaction: a column
- * absent from the args keeps its stored value — `permanent`/`enabled` included,
- * whose defaults (the record schema's `.default(true)`) apply only when this save
- * creates the redirect — `null` clears the optional `meta` bag, a value sets. ONE
- * `db.patch` or ONE `db.insert`, so the EC-510 revalidation trigger fires once.
- */
-export const save = mutation({
-  args: {
-    redirectId: v.string(),
-    from: v.optional(v.string()),
-    to: v.optional(v.string()),
-    permanent: v.optional(v.boolean()),
-    enabled: v.optional(v.boolean()),
-    // Schema-driven additive-field bag (EC-311 Tier 2): present replaces the bag,
-    // `null` clears it, absent keeps it.
-    meta: v.optional(v.any()),
-    createdAt: v.string(),
-    updatedAt: v.string(),
-  },
-  handler: async (ctx, { redirectId, createdAt, updatedAt, ...write }) => {
-    await requireCapability(ctx, 'content.write')
-    const existing = await ctx.db
-      .query('redirects')
-      .withIndex('by_redirect', (q) => q.eq('redirectId', redirectId))
-      .first()
-    const resolved = resolveRecordWrite(redirectRowSchema, existing ?? undefined, write)
-    if (!resolved.ok) {
-      throw new ConvexError({
-        code: 'validation',
-        message: rejectedWriteMessage('redirect', redirectId, resolved.issues),
-        issues: resolved.issues,
-      })
-    }
-    if (existing) {
-      await ctx.db.patch(existing._id, { ...(resolved.patch as Partial<RedirectDoc>), updatedAt })
-      return ctx.db.get(existing._id)
-    }
-    const row: WithoutSystemFields<RedirectDoc> = { ...resolved.row, redirectId, createdAt, updatedAt }
-    const id = await ctx.db.insert('redirects', row)
-    return ctx.db.get(id)
-  },
-})
+type LegacyRedirectDoc = DataModel['redirects']['document']
 
-export const get = query({
-  args: { redirectId: v.string() },
-  handler: async (ctx, args) => {
-    await requireCapability(ctx, 'content.read')
-    return ctx.db
+/** TOLERANT READ (marked) — the legacy `redirects` table as the kind's legacy source. */
+const legacyRedirects: LegacyRecordSource = {
+  find: async (ctx, recordId) => {
+    const row = await ctx.db
       .query('redirects')
-      .withIndex('by_redirect', (q) => q.eq('redirectId', args.redirectId))
+      .withIndex('by_redirect', (q) => q.eq('redirectId', recordId))
       .first()
+    return row ? legacyRecord(row) : null
   },
-})
+  list: async (ctx) => (await ctx.db.query('redirects').withIndex('by_redirect').collect()).map(legacyRecord),
+  remove: async (ctx, record) => {
+    await ctx.db.delete(record.handle as LegacyRedirectDoc['_id'])
+  },
+}
+
+function legacyRecord(row: LegacyRedirectDoc): LegacyRecord {
+  return {
+    recordId: row.redirectId,
+    columns: recordColumnsOf(redirectRecordKind, row),
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    handle: row._id,
+  }
+}
 
-export const list = query({
+export const { save, get, list, remove } = defineRecordFunctions(redirectRecordKind, { legacy: legacyRedirects })
+
+/**
+ * Every stored redirect of this deployment (records + the tolerant legacy read), ordered
+ * by `from` — the ONE server-side reader; the delivery snapshot projects it through
+ * `liveRedirectRecords` (EC-590 / EC-627: one enabled-redirect reader).
+ */
+export async function loadRedirectEntries(ctx: QueryCtx, projectId: string): Promise<RedirectEntry[]> {
+  const rows = await listRecordWire(ctx, redirectRecordKind, resolveRecordQuery(redirectRecordKind), legacyRedirects)
+  return rows.map((row) => recordEntryFromWire(redirectRecordKind, row, projectId))
+}
+
+/**
+ * EC-616 — move every legacy `redirects` row into `records` (kind `redirect`), the
+ * redirect move's migration. Per row: a record of the same id already exists (a save
+ * lifted it, or an earlier run) → the legacy row is dropped as shadowed; otherwise the
+ * row's columns are written as a record CREATE through the one rule (`resolveRecordSave`
+ * — a legacy row the current schema refuses is REPORTED and left where it is, still
+ * served by the tolerant read, never dropped silently) and the legacy row deleted.
+ * Idempotent: a second run scans nothing.
+ *
+ * Internal: an admin runs it from the CLI, once per deployment —
+ * `npx convex run redirects:migrateLegacy` (no args). Built on the RAW internal-mutation
+ * builder, deliberately outside the write-chokepoint triggers: the served redirect set is
+ * 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).
+ */
+export const migrateLegacy = (internalMutationGeneric as MutationBuilder<DataModel, 'internal'>)({
   args: {},
   handler: async (ctx) => {
-    await requireCapability(ctx, 'content.read')
-    return ctx.db.query('redirects').withIndex('by_redirect').collect()
-  },
-})
-
-export const remove = mutation({
-  args: { redirectId: v.string() },
-  handler: async (ctx, args) => {
-    await requireCapability(ctx, 'content.write')
-    const existing = await ctx.db
-      .query('redirects')
-      .withIndex('by_redirect', (q) => q.eq('redirectId', args.redirectId))
-      .first()
-    if (existing) await ctx.db.delete(existing._id)
+    const legacy = await ctx.db.query('redirects').withIndex('by_redirect').collect()
+    const moved: string[] = []
+    const shadowed: string[] = []
+    const refused: Array<{ redirectId: string; message: string }> = []
+    for (const row of legacy) {
+      const record = legacyRecord(row)
+      if (await findRecordDoc(ctx as unknown as MutationCtx, redirectRecordKind, record.recordId)) {
+        await ctx.db.delete(row._id)
+        shadowed.push(record.recordId)
+        continue
+      }
+      let columns: Record<string, unknown>
+      try {
+        columns = resolveRecordSave(redirectRecordKind, record.recordId, undefined, record.columns)
+      } catch (error) {
+        if (!(error instanceof PersistenceValidationError)) throw error
+        refused.push({ redirectId: record.recordId, message: error.message })
+        continue
+      }
+      const slots = recordSlots(redirectRecordKind, columns, record.createdAt)
+      await ctx.db.insert('records', {
+        kind: redirectRecordKind.kind,
+        recordId: record.recordId,
+        data: columns,
+        at: slots.at,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+      })
+      await ctx.db.delete(row._id)
+      moved.push(record.recordId)
+    }
+    return { scanned: legacy.length, moved: moved.length, shadowed: shadowed.length, refused, movedIds: moved }
   },
 })

package/convex/role-policy.test.ts

@@ -0,0 +1,315 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import { makeFunctionReference } from 'convex/server'
+import type { FunctionReference } from 'convex/server'
+import type { GenericId } from 'convex/values'
+import {
+  ROLE_POLICY_ENV,
+  defaultRolePolicy,
+  rolePolicyFingerprint,
+  serializeRolePolicy,
+} from '@elytracms/core/persistence'
+import type { RolePolicy } from '@elytracms/core/persistence'
+import { resolveProject } from '@elytracms/core/studio-core'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import { gateSessionCreation } from './auth'
+import { requireCapability } from './guard'
+import { deployedRolePolicy } from './roles'
+import schema from './schema'
+
+/**
+ * EC-605 — the Convex trust boundary reads the project's role policy from the copy the
+ * CLI provisions into `ELYTRA_ROLE_POLICY`, and only that copy.
+ *
+ * The REAL `members` / `invites` / `roles` handlers and the REAL guard + integrity floor
+ * run on convex-test's in-memory backend; the env is stubbed per test (set, unset,
+ * malformed). Two member rows hold DIFFERENT custom roles, so a decision that silently
+ * fell back to the default policy (where both roles are unknown) is visible.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const ISSUER = 'https://convex.test'
+
+/** The fourth-role proof: a `reviewer` that reads, between viewer and editor. */
+const FOUR_ROLE: RolePolicy = {
+  roles: [
+    { id: 'viewer', label: 'Viewer', capabilities: ['content.read'] },
+    { id: 'reviewer', label: 'Reviewer', capabilities: ['content.read'] },
+    { id: 'editor', label: 'Editor', capabilities: ['content.read', 'content.write'] },
+    { id: 'admin', label: 'Admin', capabilities: ['content.read', 'content.write', 'project.administer'] },
+  ],
+}
+
+/** An administering role BELOW the strongest — what the floor's rank invariant guards. */
+const RANKED: RolePolicy = {
+  roles: [
+    { id: 'author', capabilities: ['content.read', 'content.write'] },
+    { id: 'manager', capabilities: ['content.read', 'content.write', 'project.administer'] },
+    { id: 'owner', capabilities: ['content.read', 'content.write', 'project.administer'] },
+  ],
+}
+
+const membersSet = makeFunctionReference<'mutation'>('members:set')
+const membersList = makeFunctionReference<'query'>('members:list')
+const invitesCreate = makeFunctionReference<'mutation'>('invites:create')
+const fingerprintQuery = makeFunctionReference<'query'>('roles:fingerprint')
+
+const NOW = '2026-10-26T00:00:00.000Z'
+
+async function backendWith(rows: Array<{ userId: string; role: string }>) {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    for (const row of rows) {
+      await ctx.db.insert('members', { ...row, createdAt: NOW, updatedAt: NOW })
+    }
+  })
+  return t
+}
+
+const as = (t: ReturnType<typeof convexTest>, userId: string) =>
+  t.withIdentity({ subject: userId, issuer: ISSUER })
+
+/** Run the guard itself as `userId` — the one primitive every engine handler gates on. */
+async function canDo(
+  t: ReturnType<typeof convexTest>,
+  userId: string,
+  capability: 'content.read' | 'content.write' | 'project.administer',
+): Promise<boolean> {
+  try {
+    await as(t, userId).run((ctx) => requireCapability(ctx, capability))
+    return true
+  } catch {
+    return false
+  }
+}
+
+beforeEach(() => {
+  vi.unstubAllEnvs()
+})
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+describe('the deployed role policy (EC-605) — absent → the default, byte-identical', () => {
+  it('reads the default policy when ELYTRA_ROLE_POLICY is unset or blank', () => {
+    expect(deployedRolePolicy({})).toBe(defaultRolePolicy)
+    expect(deployedRolePolicy({ [ROLE_POLICY_ENV]: '  ' })).toBe(defaultRolePolicy)
+  })
+
+  it('keeps the historical tiers with no env: viewer reads, editor writes, admin administers', async () => {
+    const t = await backendWith([
+      { userId: 'u_viewer', role: 'viewer' },
+      { userId: 'u_editor', role: 'editor' },
+      { userId: 'u_admin', role: 'admin' },
+    ])
+    expect(await canDo(t, 'u_viewer', 'content.read')).toBe(true)
+    expect(await canDo(t, 'u_viewer', 'content.write')).toBe(false)
+    expect(await canDo(t, 'u_editor', 'content.write')).toBe(true)
+    expect(await canDo(t, 'u_editor', 'project.administer')).toBe(false)
+    expect(await canDo(t, 'u_admin', 'project.administer')).toBe(true)
+  })
+
+  it('refuses to store a role the default policy does not declare (members:set, invites:create)', async () => {
+    const t = await backendWith([{ userId: 'u_admin', role: 'admin' }])
+    await expect(
+      as(t, 'u_admin').mutation(membersSet, { userId: 'u_x', role: 'reviewer', createdAt: NOW, updatedAt: NOW }),
+    ).rejects.toThrow(/invalid-role: role "reviewer" is not declared/)
+    await expect(
+      as(t, 'u_admin').mutation(invitesCreate, {
+        email: 'x@example.com',
+        role: 'reviewer',
+        createdAt: NOW,
+        updatedAt: NOW,
+      }),
+    ).rejects.toThrow(/invalid-role/)
+    // Control: a declared role is stored.
+    const stored = await as(t, 'u_admin').mutation(membersSet, {
+      userId: 'u_x',
+      role: 'editor',
+      createdAt: NOW,
+      updatedAt: NOW,
+    })
+    expect(stored).toMatchObject({ userId: 'u_x', role: 'editor' })
+  })
+
+  it('answers the default fingerprint, sourced from the default', async () => {
+    const t = convexTest(schema, modules)
+    expect(await t.query(fingerprintQuery, {})).toEqual({
+      status: 'ok',
+      fingerprint: rolePolicyFingerprint(defaultRolePolicy),
+      source: 'default',
+    })
+  })
+})
+
+describe('a provisioned four-role policy — honoured by the guard with two custom-role members', () => {
+  beforeEach(() => {
+    vi.stubEnv(ROLE_POLICY_ENV, serializeRolePolicy(FOUR_ROLE))
+  })
+
+  it('stores the custom role (members:set) and the guard grants by it', async () => {
+    const t = await backendWith([{ userId: 'u_admin', role: 'admin' }])
+    for (const [userId, role] of [
+      ['u_reviewer', 'reviewer'],
+      ['u_editor', 'editor'],
+    ] as const) {
+      const stored = await as(t, 'u_admin').mutation(membersSet, { userId, role, createdAt: NOW, updatedAt: NOW })
+      expect(stored).toMatchObject({ userId, role })
+    }
+    // The reviewer reads (a real handler) but cannot write; the editor writes.
+    expect(await as(t, 'u_reviewer').query(membersList, {})).toHaveLength(3)
+    expect(await canDo(t, 'u_reviewer', 'content.read')).toBe(true)
+    expect(await canDo(t, 'u_reviewer', 'content.write')).toBe(false)
+    expect(await canDo(t, 'u_editor', 'content.write')).toBe(true)
+    expect(await canDo(t, 'u_editor', 'project.administer')).toBe(false)
+  })
+
+  it('control: without the env the same reviewer row grants NOTHING (unknown role fails closed)', async () => {
+    vi.unstubAllEnvs()
+    const t = await backendWith([{ userId: 'u_reviewer', role: 'reviewer' }])
+    expect(await canDo(t, 'u_reviewer', 'content.read')).toBe(false)
+  })
+
+  it('answers the provisioned policy’s fingerprint, sourced from the env', async () => {
+    const t = convexTest(schema, modules)
+    expect(await t.query(fingerprintQuery, {})).toEqual({
+      status: 'ok',
+      fingerprint: rolePolicyFingerprint(FOUR_ROLE),
+      source: 'env',
+    })
+    expect(rolePolicyFingerprint(FOUR_ROLE)).not.toBe(rolePolicyFingerprint(defaultRolePolicy))
+  })
+
+  it('stores a custom role through the production adapter unchanged (no silent viewer floor)', async () => {
+    const t = await backendWith([{ userId: 'u_admin', role: 'admin' }])
+    const asAdmin = as(t, 'u_admin')
+    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
+    // users:get joins the auth `users` row; give the member an identity row first.
+    const userId = await t.run(async (ctx) => {
+      const id = await ctx.db.insert('users', { email: 'rev@example.com' })
+      return String(id)
+    })
+    const adapter = new ConvexPersistenceAdapter(client, 'role-policy')
+    await adapter.users.saveUser('role-policy', { id: userId, roles: ['reviewer'] })
+    const row = await t.run((ctx) =>
+      ctx.db
+        .query('members')
+        .withIndex('by_user', (q) => q.eq('userId', userId))
+        .first(),
+    )
+    expect(row?.role).toBe('reviewer')
+  })
+})
+
+describe('the integrity floor under a ranked custom policy (an administering role below the strongest)', () => {
+  beforeEach(() => {
+    vi.stubEnv(ROLE_POLICY_ENV, serializeRolePolicy(RANKED))
+  })
+
+  it('a manager assigns roles up to its own rank, never above (members:set and invites:create)', async () => {
+    const t = await backendWith([
+      { userId: 'u_owner', role: 'owner' },
+      { userId: 'u_manager', role: 'manager' },
+    ])
+    const manager = as(t, 'u_manager')
+    await expect(
+      manager.mutation(membersSet, { userId: 'u_new', role: 'author', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'author' })
+    await expect(
+      manager.mutation(membersSet, { userId: 'u_new', role: 'manager', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'manager' })
+    await expect(
+      manager.mutation(membersSet, { userId: 'u_new', role: 'owner', createdAt: NOW, updatedAt: NOW }),
+    ).rejects.toThrow(/cannot assign the “owner” role/)
+    await expect(
+      manager.mutation(invitesCreate, { email: 'boss@example.com', role: 'owner', createdAt: NOW, updatedAt: NOW }),
+    ).rejects.toThrow(/cannot assign the “owner” role/)
+    // Control: the owner (strongest) may invite an owner.
+    await expect(
+      as(t, 'u_owner').mutation(invitesCreate, { email: 'boss@example.com', role: 'owner', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'owner' })
+  })
+
+  it('counts every administering role for "the last administrator" — demoting one of two is allowed, the last is not', async () => {
+    const t = await backendWith([
+      { userId: 'u_owner', role: 'owner' },
+      { userId: 'u_manager', role: 'manager' },
+    ])
+    // Two administrators: the owner demotes the manager to author.
+    await expect(
+      as(t, 'u_owner').mutation(membersSet, { userId: 'u_manager', role: 'author', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'author' })
+    // Now the owner is the last administrator: demoting themselves is refused.
+    await expect(
+      as(t, 'u_owner').mutation(membersSet, { userId: 'u_owner', role: 'manager', createdAt: NOW, updatedAt: NOW }),
+    ).resolves.toMatchObject({ role: 'manager' })
+    await expect(
+      as(t, 'u_owner').mutation(membersSet, { userId: 'u_owner', role: 'author', createdAt: NOW, updatedAt: NOW }),
+    ).rejects.toThrow(/last admin/)
+  })
+
+  it('bootstraps the first user into the strongest role (owner), not a literal "admin"', async () => {
+    const t = convexTest(schema, modules)
+    const userId = await t.run((ctx) => ctx.db.insert('users', { email: 'first@example.com' }))
+    await t.run((ctx) => gateSessionCreation(ctx as never, { userId: userId as GenericId<'users'> }))
+    const row = await t.run((ctx) => ctx.db.query('members').first())
+    expect(row?.role).toBe('owner')
+  })
+})
+
+describe('a malformed or invalid deployed copy throws — never a silent default', () => {
+  it('every guarded function fails, naming ELYTRA_ROLE_POLICY', async () => {
+    vi.stubEnv(ROLE_POLICY_ENV, '{not json')
+    const t = await backendWith([{ userId: 'u_admin', role: 'admin' }])
+    await expect(as(t, 'u_admin').query(membersList, {})).rejects.toThrow(/ELYTRA_ROLE_POLICY is not valid JSON/)
+  })
+
+  it('an invalid policy (no administering role) is refused with the located rule', () => {
+    const invalid = JSON.stringify({ v: 1, roles: [{ id: 'viewer', capabilities: ['content.read'] }] })
+    expect(() => deployedRolePolicy({ [ROLE_POLICY_ENV]: invalid })).toThrow(/No role grants “project.administer”/)
+  })
+
+  it('the fingerprint query answers `invalid` with the reason instead of throwing', async () => {
+    vi.stubEnv(ROLE_POLICY_ENV, '{"v":2,"roles":[]}')
+    const t = convexTest(schema, modules)
+    const answer = (await t.query(fingerprintQuery, {})) as { status: string; detail: string }
+    expect(answer.status).toBe('invalid')
+    expect(answer.detail).toMatch(/ELYTRA_ROLE_POLICY is not a serialised role policy/)
+  })
+
+  it('a changed env is read on the next call (the parse is cached per string, not per process)', () => {
+    const four = serializeRolePolicy(FOUR_ROLE)
+    expect(deployedRolePolicy({ [ROLE_POLICY_ENV]: four }).roles.map((r) => r.id)).toContain('reviewer')
+    expect(deployedRolePolicy({ [ROLE_POLICY_ENV]: serializeRolePolicy(RANKED) }).roles.map((r) => r.id)).toEqual([
+      'author',
+      'manager',
+      'owner',
+    ])
+  })
+})
+
+describe('one declaration, two readers — the config entry reaches the guard through the provisioned copy', () => {
+  it('resolveProject → serializeRolePolicy → ELYTRA_ROLE_POLICY → the guard grants the declared reviewer', async () => {
+    const resolved = resolveProject({
+      name: 'Acme',
+      slug: 'acme',
+      locales: { default: 'en', locales: ['en'] },
+      roles: FOUR_ROLE.roles.map((role) => ({ ...role, capabilities: [...role.capabilities] })),
+    })
+    expect(resolved.ok).toBe(true)
+    if (!resolved.ok) return
+    vi.stubEnv(ROLE_POLICY_ENV, serializeRolePolicy(resolved.project.roles!))
+    const t = await backendWith([{ userId: 'u_reviewer', role: 'reviewer' }])
+    expect(await canDo(t, 'u_reviewer', 'content.read')).toBe(true)
+    expect(await canDo(t, 'u_reviewer', 'content.write')).toBe(false)
+  })
+})

package/convex/roles.ts

@@ -0,0 +1,83 @@
+import {
+  ROLE_POLICY_ENV,
+  defaultRolePolicy,
+  parseRolePolicy,
+  rolePolicyFingerprint,
+} from '@elytracms/core/persistence'
+import type { RolePolicy } from '@elytracms/core/persistence'
+import { query } from './functions'
+
+/**
+ * The role policy this deployment ENFORCES (EC-605) — the Convex trust boundary's
+ * reader of the project's `roles` declaration.
+ *
+ * Convex functions cannot import `elytra.config.ts`, and the nine engine modules that
+ * gate on a capability import `./guard` inside the package, so the declaration reaches
+ * the deployment as a serialised copy in its env: `ELYTRA_ROLE_POLICY`, provisioned by
+ * the `elytra` CLI from the resolved project (`elytra init`, and `elytra build` before
+ * every Convex deploy). `guard.ts`, `authority.ts`, `members.ts`, `invites.ts` and the
+ * first-user bootstrap (`auth.ts`) all read it through {@link deployedRolePolicy}.
+ *
+ * - **Absent (or blank)** → the shipped default policy, byte-identical to before EC-605.
+ * - **Present but malformed or invalid** → THROWS, naming every reason
+ *   (`parseRolePolicy`): every guarded function then fails loudly rather than enforcing
+ *   a policy nobody declared. Never a silent default.
+ *
+ * The env is read per CALL (a provisioned change takes effect without a redeploy) and
+ * the parse is cached per serialised string, so the steady state costs one string
+ * comparison.
+ *
+ * The public {@link fingerprint} query is how a drift between this copy and the config
+ * becomes visible: `elytra doctor` and the studio compare it with the config's own
+ * fingerprint. Consumers reach it through a one-line re-export (`convex/roles.ts`); the
+ * readers above work without it.
+ */
+
+let cached: { readonly serialized: string; readonly policy: RolePolicy } | undefined
+
+/** The deployment env, reached via `globalThis` so this module needs no Node types at runtime. */
+function deploymentEnv(): Record<string, string | undefined> {
+  return (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+}
+
+/**
+ * The deployed role policy: the parsed `ELYTRA_ROLE_POLICY`, or the default when it is
+ * unset. Throws on a malformed or invalid value (see the module comment). `env` is
+ * injectable for tests.
+ */
+export function deployedRolePolicy(env: Record<string, string | undefined> = deploymentEnv()): RolePolicy {
+  const serialized = env[ROLE_POLICY_ENV]
+  if (serialized === undefined || serialized.trim() === '') return defaultRolePolicy
+  if (cached?.serialized === serialized) return cached.policy
+  const policy = parseRolePolicy(serialized)
+  cached = { serialized, policy }
+  return policy
+}
+
+/** What {@link fingerprint} answers — the deployed policy's identity, never its content. */
+export type DeployedRolePolicyFingerprint =
+  | { readonly status: 'ok'; readonly fingerprint: string; readonly source: 'env' | 'default' }
+  | { readonly status: 'invalid'; readonly detail: string }
+
+/**
+ * PUBLIC, unauthenticated: the fingerprint of the role policy this deployment enforces
+ * (`rolePolicyFingerprint` — 16 hex chars over ids, rank and capabilities; labels and
+ * the policy itself never leave the deployment) and whether it comes from
+ * `ELYTRA_ROLE_POLICY` or the default. `elytra doctor` reads it without a session (the
+ * doctor's env rule — names only, values never printed — stands: this is not a value),
+ * and the studio reads it at boot. A malformed or invalid deployed copy answers
+ * `invalid` with the located reasons instead of throwing, so the drift check can say
+ * exactly what is wrong.
+ */
+export const fingerprint = query({
+  args: {},
+  handler: async (): Promise<DeployedRolePolicyFingerprint> => {
+    const env = deploymentEnv()
+    const source = env[ROLE_POLICY_ENV]?.trim() ? 'env' : 'default'
+    try {
+      return { status: 'ok', fingerprint: rolePolicyFingerprint(deployedRolePolicy(env)), source }
+    } catch (error) {
+      return { status: 'invalid', detail: error instanceof Error ? error.message : String(error) }
+    }
+  },
+})