@elytracms/studio 0.0.93 → 0.0.95

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

@@ -80,7 +80,7 @@ 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)
+    expect(Object.fromEntries(Object.entries(before).map(([id, r]) => [id, assetAlt(r, null)]))).toEqual(READ_BEFORE)
 
     const report = (await t.mutation(liftLegacyAlt, {})) as { scanned: number; lifted: string[] }
     expect(report.scanned).toBe(4)
@@ -94,7 +94,7 @@ describe('EC-587 — assets:liftLegacyAlt moves the legacy column home, once', (
       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)
+    expect(Object.fromEntries(Object.entries(after).map(([id, r]) => [id, assetAlt(r, null)]))).toEqual(READ_BEFORE)
   })
 
   it('is idempotent: a second run lifts nothing and writes nothing', async () => {

package/convex/asset-meta-patch.test.ts

@@ -0,0 +1,218 @@
+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, measureMaxDepth } from '@elytracms/core/cms-core'
+import { InMemoryBlobStorage, InMemoryPersistenceAdapter, PersistenceValidationError, assetAlt } 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 {
+  assetMetaDraft,
+  assetMetaDraftPatch,
+  setAssetMetaField,
+  updateAssetMetadata,
+} from '../src/components/assets/asset-metadata'
+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-634 — an asset's `meta` is written per key, inside the mutation, on BOTH adapters:
+ * two sessions (two adapters over ONE backend — two studio tabs on one deployment) whose
+ * dialog saves interleave keep both keys; a dialog save landing while a file replace is in
+ * flight survives the replace; a not-yet-migrated legacy `alt` column is lifted into the
+ * stored bag by the same transaction. convex-test serialises mutations, so this proves the
+ * per-key MERGE in `assets:upsert`, not Convex's OCC retry (which re-runs the same handler
+ * against the newer row — the merge is what makes that retry correct).
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const PROJECT_ID = 'asset-meta-patch'
+const SESSION_USER_ID = 'user_admin'
+const STAMP = '2026-10-27T00:00:00.000Z'
+
+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 session = () =>
+    new ConvexPersistenceAdapter(
+      {
+        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,
+      PROJECT_ID,
+    ).assets
+  return { t, a: session(), b: session() }
+}
+
+function memoryBackend() {
+  const adapter = new InMemoryPersistenceAdapter()
+  return { a: adapter.assets, b: adapter.assets }
+}
+
+async function seed(assets: AssetRepository, meta: Record<string, unknown>) {
+  await assets.upsertAsset(PROJECT_ID, {
+    id: 'hero',
+    filename: 'hero.jpg',
+    contentType: 'image/jpeg',
+    byteSize: 1,
+    storageKey: 'blob_old',
+    url: 'https://assets.test/old.jpg',
+    meta,
+  })
+}
+
+async function openDialog(assets: AssetRepository) {
+  const opened = assetMetaDraft(await assets.getAsset(PROJECT_ID, 'hero'))
+  let draft = opened
+  return {
+    edit: (key: string, value: unknown) => {
+      draft = setAssetMetaField(draft, { name: key }, null, value)
+    },
+    commit: () => updateAssetMetadata({ assets }, PROJECT_ID, 'hero', assetMetaDraftPatch(opened, draft)),
+  }
+}
+
+/** Two dialogs open on one asset, each edits one key, the commits interleave. */
+async function interleavedDialogs({ a, b }: { a: AssetRepository; b: AssetRepository }) {
+  await seed(a, { alt: 'old alt', credit: 'old credit' })
+  const dialogA = await openDialog(a)
+  const dialogB = await openDialog(b)
+  dialogA.edit('alt', 'A alt')
+  dialogB.edit('credit', 'B credit')
+  expect((await dialogA.commit()).ok).toBe(true)
+  expect((await dialogB.commit()).ok).toBe(true)
+  return (await b.getAsset(PROJECT_ID, 'hero')).meta
+}
+
+const iptcJpeg = new Uint8Array(
+  readFileSync(new URL('../../core/src/cms-core/__fixtures__/embedded-metadata/iptc-xmp.jpg', import.meta.url)),
+)
+
+/** A replace whose read is followed — before its write — by another session's dialog save. */
+async function replaceRacingADialog({ a, b }: { a: AssetRepository; b: AssetRepository }) {
+  await seed(a, { alt: 'old alt', note: 'old note' })
+  const dialogB = await openDialog(b)
+  dialogB.edit('note', 'B note')
+  const racing: AssetRepository = {
+    // B's dialog commits at the worst moment: right before A's replace writes.
+    upsertAsset: async (projectId, input) => {
+      await dialogB.commit()
+      return a.upsertAsset(projectId, input)
+    },
+    getAsset: (projectId, id) => a.getAsset(projectId, id),
+    listAssets: (projectId) => a.listAssets(projectId),
+    removeAsset: (projectId, id) => a.removeAsset(projectId, id),
+    resolveMany: (projectId, ids) => a.resolveMany(projectId, ids),
+    findAsset: (projectId, id) => a.findAsset(projectId, id),
+  }
+  const result = await runUpload(
+    {
+      blobs: new InMemoryBlobStorage(),
+      assets: racing,
+      assetFields: defaultAssetCollection().fields,
+      detectDimensions: async () => ({ width: 8, height: 6 }),
+      generateVariants: async () => ({}),
+    },
+    {
+      projectId: PROJECT_ID,
+      file: {
+        name: 'new.jpg',
+        type: 'image/jpeg',
+        size: iptcJpeg.byteLength,
+        arrayBuffer: async () => iptcJpeg.slice().buffer as ArrayBuffer,
+      },
+      replace: { assetId: 'hero' },
+    },
+  )
+  expect(result.ok).toBe(true)
+  return (await a.getAsset(PROJECT_ID, 'hero')).meta
+}
+
+describe('EC-634 — asset meta is patched per key in the write, on both adapters', () => {
+  it('two sessions’ interleaved dialog saves of different keys keep both (the worst row)', async () => {
+    const expected = { alt: 'A alt', credit: 'B credit' }
+    expect(await interleavedDialogs(memoryBackend())).toEqual(expected)
+    expect(await interleavedDialogs(await convexBackend())).toEqual(expected)
+  })
+
+  it('a dialog save landing just before a replace’s write survives the replace', async () => {
+    const memory = await replaceRacingADialog(memoryBackend())
+    const convex = await replaceRacingADialog(await convexBackend())
+    expect(convex).toEqual(memory)
+    expect(convex).toMatchObject({ alt: 'A harbour at dusk & boats', note: 'B note' })
+  })
+
+  it('a patch lifts a not-yet-migrated legacy alt column into the stored bag, in the same mutation', async () => {
+    const { t, a } = await convexBackend()
+    await t.run(async (ctx) => {
+      await ctx.db.insert('assets', {
+        assetId: 'legacy',
+        filename: 'l.jpg',
+        contentType: 'image/jpeg',
+        byteSize: 1,
+        storageKey: 'k_legacy',
+        alt: 'Column alt',
+        createdAt: STAMP,
+        updatedAt: STAMP,
+      })
+    })
+    // An edit of ANOTHER key: the alt it did not name moves home and is kept.
+    const kept = await a.upsertAsset(PROJECT_ID, { id: 'legacy', metaPatch: { credit: 'Ada' } })
+    expect(kept.meta).toEqual({ alt: 'Column alt', credit: 'Ada' })
+    expect(kept.alt).toBeUndefined()
+    expect(assetAlt(kept, null)).toBe('Column alt')
+    // A clear of the alt stays cleared — no column left to re-surface it (ASSETS D21).
+    const cleared = await a.upsertAsset(PROJECT_ID, { id: 'legacy', metaPatch: { alt: null } })
+    expect(assetAlt(cleared, null)).toBeNull()
+    const row = await t.run((ctx) => ctx.db.query('assets').filter((q) => q.eq(q.field('assetId'), 'legacy')).first())
+    expect(row?.alt).toBeUndefined()
+    expect(row?.meta).toEqual({ credit: 'Ada' })
+  })
+
+  it('EC-632 — per-locale buckets are stored by the real mutation, and the stored row measures its depth', async () => {
+    const { t, a, b } = await convexBackend()
+    await seed(a, { credit: 'Ada' })
+    // Two translators, two sessions, interleaved: both locales are kept.
+    await a.upsertAsset(PROJECT_ID, { id: 'hero', localizedMetaPatch: { de: { alt: 'Hafen' } } })
+    await b.upsertAsset(PROJECT_ID, {
+      id: 'hero',
+      localizedMetaPatch: { en: { alt: 'Harbour', disclosure: { shown: true, badge: { corner: 'tl', tone: 'dark' } } } },
+    })
+    const row = await t.run((ctx) => ctx.db.query('assets').filter((q) => q.eq(q.field('assetId'), 'hero')).first())
+    expect(row?.localizedMeta).toEqual({
+      de: { alt: 'Hafen' },
+      en: { alt: 'Harbour', disclosure: { shown: true, badge: { corner: 'tl', tone: 'dark' } } },
+    })
+    expect(row?.meta).toEqual({ credit: 'Ada' })
+    // The stored Convex document (system fields included): 5 of Convex's 16 levels.
+    expect(measureMaxDepth(row).depth).toBe(5)
+  })
+
+  it('refuses meta and metaPatch together, through the rule (a PersistenceValidationError naming metaPatch)', async () => {
+    const { a } = await convexBackend()
+    await seed(a, { alt: 'x' })
+    await expect(
+      a.upsertAsset(PROJECT_ID, { id: 'hero', meta: { alt: 'y' }, metaPatch: { credit: 'z' } }),
+    ).rejects.toBeInstanceOf(PersistenceValidationError)
+    expect((await a.getAsset(PROJECT_ID, 'hero')).meta).toEqual({ alt: 'x' })
+  })
+})

package/convex/asset-replace-delete-race.test.ts

@@ -0,0 +1,127 @@
+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 { 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-634 follow-on — a replace is an UPDATE of a stored asset, never a create. Session A
+ * replaces the file; session B deletes the asset in the window between A's check and A's
+ * write. The replace used to carry every column a create needs, so it silently RE-CREATED
+ * the asset B had deleted (a colleague's delete undone). Two sessions over ONE backend,
+ * in-memory AND Convex (the real `assets:upsert` over convex-test).
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const PROJECT_ID = 'asset-replace-race'
+const SESSION_USER_ID = 'user_admin'
+
+async function convexSessions() {
+  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 session = () =>
+    new ConvexPersistenceAdapter(
+      {
+        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,
+      PROJECT_ID,
+    ).assets
+  return { a: session(), b: session() }
+}
+
+function memorySessions() {
+  const adapter = new InMemoryPersistenceAdapter()
+  return { a: adapter.assets, b: adapter.assets }
+}
+
+/** A's replace, with B's delete landing right after A checked that the asset exists. */
+async function replaceRacingADelete({ a, b }: { a: AssetRepository; b: AssetRepository }) {
+  await a.upsertAsset(PROJECT_ID, {
+    id: 'hero',
+    filename: 'old.jpg',
+    contentType: 'image/jpeg',
+    byteSize: 1,
+    storageKey: 'blob_old',
+    url: 'https://assets.test/old.jpg',
+  })
+  // B's delete lands immediately before A's write — after anything A checked or read.
+  const racing: AssetRepository = {
+    upsertAsset: async (projectId, input) => {
+      await b.removeAsset(projectId, 'hero')
+      return a.upsertAsset(projectId, input)
+    },
+    getAsset: (projectId, id) => a.getAsset(projectId, id),
+    listAssets: (projectId) => a.listAssets(projectId),
+    removeAsset: (projectId, id) => a.removeAsset(projectId, id),
+    resolveMany: (projectId, ids) => a.resolveMany(projectId, ids),
+    findAsset: (projectId, id) => a.findAsset(projectId, id),
+  }
+  const result = await runUpload(
+    {
+      blobs: new InMemoryBlobStorage(),
+      assets: racing,
+      detectDimensions: async () => ({ width: 8, height: 6 }),
+      generateVariants: async () => ({}),
+    },
+    {
+      projectId: PROJECT_ID,
+      file: { name: 'new.jpg', type: 'image/jpeg', size: 3, arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer },
+      replace: { assetId: 'hero' },
+    },
+  )
+  return { result, stored: await b.findAsset(PROJECT_ID, 'hero') }
+}
+
+describe('EC-634 follow-on — a replace never re-creates an asset another session deleted', () => {
+  for (const [name, backend] of [
+    ['in-memory', async () => memorySessions()],
+    ['Convex', convexSessions],
+  ] as const) {
+    it(`${name}: the replace is refused, visibly, and the delete stands`, async () => {
+      const { result, stored } = await replaceRacingADelete(await backend())
+      expect(stored).toBeUndefined()
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.failure.stage).toBe('confirm')
+        expect(result.failure.message).toContain('hero')
+      }
+    })
+  }
+
+  it('control: without the delete the replace lands (same id, the new file)', async () => {
+    const { a } = memorySessions()
+    await a.upsertAsset(PROJECT_ID, { id: 'hero', filename: 'old.jpg', contentType: 'image/jpeg', byteSize: 1 })
+    const result = await runUpload(
+      { blobs: new InMemoryBlobStorage(), assets: a, detectDimensions: async () => undefined, generateVariants: async () => ({}) },
+      {
+        projectId: PROJECT_ID,
+        file: { name: 'new.jpg', type: 'image/jpeg', size: 3, arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer },
+        replace: { assetId: 'hero' },
+      },
+    )
+    expect(result.ok && result.asset).toMatchObject({ id: 'hero', filename: 'new.jpg' })
+  })
+})

package/convex/assets.ts

@@ -25,8 +25,9 @@ const clearable = <T, F extends string>(validator: Validator<T, 'required', F>)
 /**
  * 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 — and the legacy
- * `alt` column can only be cleared (EC-587: an asset's alt is `meta.alt`). An edit is
+ * the args keeps its stored value, `null` clears it, a value sets it — the legacy
+ * `alt` column can only be cleared (EC-587: an asset's alt is `meta.alt`), and a
+ * `metaPatch` changes `meta` per key against the row read here (EC-634). 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
@@ -65,6 +66,30 @@ export const upsert = mutation({
     lqip: clearable(v.string()),
     /** Schema-driven asset metadata bag (EC-301): alt, copyright, credit, …. `null` clears it. */
     meta: v.optional(v.any()),
+    /**
+     * EC-634 — a per-key change to `meta` (a value sets the key, `null` removes it), applied
+     * by the rule to the row as stored HERE, in this transaction — so an editor's save never
+     * carries a stale copy of a key another session changed. Validated by the rule (an
+     * object of keys, never beside `meta`), as `meta` is.
+     */
+    metaPatch: v.optional(v.any()),
+    /**
+     * EC-632 — the per-locale buckets of the asset collection's `localized: true` fields
+     * (`{ [locale]: { [field]: value } }`): `null` clears them, an object replaces them
+     * whole (a create, an import); an editor sends `localizedMetaPatch` instead.
+     */
+    localizedMeta: v.optional(v.any()),
+    /**
+     * EC-632 — a per-locale, per-key change to those buckets, applied by the rule to the
+     * row as stored HERE (as `metaPatch` is to `meta`). Validated by the rule.
+     */
+    localizedMetaPatch: v.optional(v.any()),
+    /**
+     * EC-634 follow-on — this write only UPDATES a stored asset (a file replace): with the
+     * row gone (deleted by another session) the rule refuses it here, so it never re-creates
+     * what a colleague deleted.
+     */
+    mustExist: v.optional(v.boolean()),
     /**
      * What a CREATE fills in when the write leaves it absent (`assetCreateDefaults`
      * in core). Sent by the adapter because only it knows the project — rows carry

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/contract-parity.test.ts

@@ -4,6 +4,7 @@ import type { ConvexHttpClient } from 'convex/browser'
 import type { FunctionReference } from 'convex/server'
 import { fieldPath, measureMaxDepth, nodePropPath } from '@elytracms/core/cms-core'
 import {
+  CONTRACT_RECORD_KINDS,
   PERSISTENCE_CONTRACT_SCENARIOS,
   publishCurrentDraft,
   replaceAtCurrentRevision,
@@ -12,6 +13,7 @@ import type { ContractContext } from '@elytracms/core/persistence'
 import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
 import type { ReactiveDocumentClient } from '../src/lib/persistence/convex-client'
 import schema from './schema'
+import { defineRecordFunctions } from './record-functions'
 
 /**
  * EC-454 — Convex-side contract parity, restored.
@@ -40,6 +42,11 @@ import schema from './schema'
 const modules = {
   ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
   './_generated/api.ts': async () => ({}),
+  // EC-616: the contract's FIXTURE record kinds, registered as test-only modules exactly as
+  // an addon's convex module registers its kind (one module per kind, named by the kind).
+  ...Object.fromEntries(
+    CONTRACT_RECORD_KINDS.map((kind) => [`./${kind.module}.ts`, async () => defineRecordFunctions(kind)]),
+  ),
 }
 
 /** The config-owned slug this deployment's records are stamped with (EC-179). */