@elytracms/studio 0.0.86 → 0.0.87

package/convex/asset-revalidate.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import schema from './schema'
+
+/**
+ * EC-579 (no-owner-call carve-out) — an asset edit must reach the live site.
+ *
+ * An asset row rides the delivery wire field by field (`delivery.ts`: url, alt,
+ * dimensions, focal point, lqip, the `meta` bag), so editing one changes
+ * published output with no draft/published split to gate on. Before this ticket
+ * the EC-286 write chokepoint registered `cmsDocuments` and `redirects` but not
+ * `assets`, so on the Convex path an alt/focal-point/re-upload edit reached the
+ * host by no server-side path (EC-566 M5, measured by the Codex review as P07).
+ *
+ * Same harness as `redirect-revalidate.test.ts`: the REAL `assets:upsert` /
+ * `assets:remove` mutations through the REAL `functions.ts` trigger wrapper on
+ * `convex-test`'s in-memory backend, asserting on the `_scheduled_functions`
+ * system table — the observable `scheduleRevalidate` produces. A redirect write
+ * is the known-positive control that this instrument sees a revalidation at all.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const saveRedirect = makeFunctionReference<'mutation'>('redirects:save')
+const upsertAsset = makeFunctionReference<'mutation'>('assets:upsert')
+const removeAsset = makeFunctionReference<'mutation'>('assets:remove')
+const deliverySnapshot = makeFunctionReference<'query'>('delivery:snapshot')
+
+const SESSION_USER_ID = 'user_admin'
+const SCOPE = 'ec579-scope'
+const SWEEP = [`p:${SCOPE}:project`]
+
+async function freshBackend() {
+  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,
+    })
+  })
+  return t
+}
+
+/** The scheduled `webhooks:deliver` calls, in order, as `{event, tags}`. */
+async function scheduledRevalidations(
+  t: Awaited<ReturnType<typeof freshBackend>>,
+): Promise<{ event: unknown; tags: unknown }[]> {
+  return t.run(async (ctx) => {
+    const rows = await ctx.db.system.query('_scheduled_functions').collect()
+    return rows
+      .filter((row) => row.name.startsWith('webhooks'))
+      .map((row) => {
+        const [args] = row.args as [{ event?: unknown; tags?: unknown }]
+        return { event: args?.event, tags: args?.tags }
+      })
+  })
+}
+
+function withScope<T>(scope: string | undefined, run: () => Promise<T>): Promise<T> {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process
+    ?.env
+  const previous = env?.['CANVAS_PROJECT_SCOPE']
+  if (env) {
+    if (scope === undefined) delete env['CANVAS_PROJECT_SCOPE']
+    else env['CANVAS_PROJECT_SCOPE'] = scope
+  }
+  return run().finally(() => {
+    if (!env) return
+    if (previous === undefined) delete env['CANVAS_PROJECT_SCOPE']
+    else env['CANVAS_PROJECT_SCOPE'] = previous
+  })
+}
+
+const STAMP = '2026-09-26T00:00:00.000Z'
+
+const assetArgs = {
+  assetId: 'asset_ec579_1',
+  filename: 'photo.png',
+  contentType: 'image/png',
+  byteSize: 1,
+  storageKey: 'placeholder',
+  url: 'https://assets.invalid/photo.png',
+  alt: 'old',
+  createdAt: STAMP,
+  updatedAt: STAMP,
+}
+
+describe('EC-579 — the write chokepoint revalidates on every asset edit', () => {
+  it('an alt edit schedules a project sweep; the create before it schedules nothing', async () => {
+    await withScope(SCOPE, async () => {
+      const t = await freshBackend()
+      const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+
+      // Known-positive control: the same instrument DOES see a revalidation.
+      await asAdmin.mutation(saveRedirect, {
+        redirectId: 'redirect_ec579_1',
+        from: '/old',
+        to: '/new',
+        permanent: true,
+        enabled: true,
+        createdAt: STAMP,
+        updatedAt: STAMP,
+      })
+      expect(await scheduledRevalidations(t)).toHaveLength(1)
+
+      // A brand-new asset is on no page yet, so its create invalidates nothing —
+      // the same rule the browser dispatcher applies (`webhooks/tags.ts`).
+      await asAdmin.mutation(upsertAsset, assetArgs)
+      expect(await scheduledRevalidations(t)).toHaveLength(1)
+
+      await asAdmin.mutation(upsertAsset, { ...assetArgs, alt: 'new' })
+
+      // The edit IS live output: the published snapshot already serves it.
+      const snapshot = (await t.query(deliverySnapshot, { projectId: SCOPE })) as {
+        assets: { alt?: string }[]
+      }
+      expect(snapshot.assets[0]?.alt).toBe('new')
+
+      expect(await scheduledRevalidations(t)).toEqual([
+        { event: 'redirects.save', tags: SWEEP },
+        { event: 'assets.upsert', tags: SWEEP },
+      ])
+    })
+  })
+
+  it('schedules a sweep on a focal-point edit, a meta edit, a re-upload, and a delete', async () => {
+    await withScope(SCOPE, async () => {
+      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, focalPoint: { x: 0.2, y: 0.8 } })
+      await asAdmin.mutation(upsertAsset, { ...assetArgs, meta: { alt: 'meta alt', credit: 'Jo' } })
+      // A replace keeps the id and swaps the bytes (EC-568's case).
+      await asAdmin.mutation(upsertAsset, {
+        ...assetArgs,
+        storageKey: 'placeholder-2',
+        url: 'https://assets.invalid/photo-2.png',
+        byteSize: 2,
+      })
+      await asAdmin.mutation(removeAsset, { assetId: assetArgs.assetId })
+
+      // The sweep, never an `asset:<id>` tag: a page does not carry the tag for an
+      // asset it reads through a document asset FIELD (`next/src/route-core.ts`,
+      // `scopeAssetsToPage`), so a per-asset tag would miss exactly those pages.
+      expect(await scheduledRevalidations(t)).toEqual([
+        { event: 'assets.upsert', tags: SWEEP },
+        { event: 'assets.upsert', tags: SWEEP },
+        { event: 'assets.upsert', tags: SWEEP },
+        { event: 'assets.remove', tags: SWEEP },
+      ])
+    })
+  })
+
+  it('removing an asset that does not exist writes nothing and schedules nothing', async () => {
+    await withScope(SCOPE, async () => {
+      const t = await freshBackend()
+      const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+      await asAdmin.mutation(removeAsset, { assetId: 'asset_never_existed' })
+      expect(await scheduledRevalidations(t)).toEqual([])
+    })
+  })
+
+  it('stays a silent no-op on a deployment with no CANVAS_PROJECT_SCOPE', async () => {
+    await withScope(undefined, async () => {
+      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' })
+      // 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),
+      ).toBe('new')
+    })
+  })
+})

package/convex/assets.ts

@@ -1,5 +1,8 @@
-import { v } from 'convex/values'
-import type { GenericId } from 'convex/values'
+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 type { DataModel } from './functions'
 import { mutation, query } from './functions'
 import { requireCapability } from './guard'
 
@@ -13,21 +16,37 @@ import { requireCapability } from './guard'
 /** Convex storage ids arrive as plain strings over the wire; rebrand for the typed API. */
 const asStorageId = (storageKey: string) => storageKey as GenericId<'_storage'>
 
+type AssetDoc = DocumentByName<DataModel, 'assets'>
+
+/** An optional column on the wire (EC-577): absent keeps, `null` clears, a value sets. */
+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
+ * 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
+ * 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
+ * left absent), or a `validation` `ConvexError` naming what is missing; a partial
+ * row is never stored.
+ */
 export const upsert = mutation({
   args: {
     assetId: v.string(),
-    filename: v.string(),
-    contentType: v.string(),
-    byteSize: v.number(),
-    width: v.optional(v.number()),
-    height: v.optional(v.number()),
-    alt: v.optional(v.string()),
-    title: v.optional(v.string()),
-    storageKey: v.string(),
-    url: v.optional(v.string()),
-    focalPoint: v.optional(v.object({ x: v.number(), y: v.number() })),
+    filename: v.optional(v.string()),
+    contentType: v.optional(v.string()),
+    byteSize: v.optional(v.number()),
+    storageKey: v.optional(v.string()),
+    width: clearable(v.number()),
+    height: clearable(v.number()),
+    alt: clearable(v.string()),
+    title: clearable(v.string()),
+    url: clearable(v.string()),
+    focalPoint: clearable(v.object({ x: v.number(), y: v.number() })),
     /** Downscaled editorial preview variant (EC-400) — a second stored blob. */
-    thumb: v.optional(
+    thumb: clearable(
       v.object({
         storageKey: v.string(),
         url: v.string(),
@@ -36,23 +55,38 @@ export const upsert = mutation({
       }),
     ),
     /** Delivery LQIP blur-placeholder data URI (EC-420) — rides the delivery wire. */
-    lqip: v.optional(v.string()),
-    /** Schema-driven asset metadata bag (EC-301): alt, copyright, credit, …. */
+    lqip: clearable(v.string()),
+    /** Schema-driven asset metadata bag (EC-301): alt, copyright, credit, …. `null` clears it. */
     meta: v.optional(v.any()),
+    /**
+     * 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
+     * none (EC-179). Ignored on an edit.
+     */
+    defaults: v.optional(v.object({ storageKey: v.string() })),
     createdAt: v.string(),
     updatedAt: v.string(),
   },
-  handler: async (ctx, args) => {
+  handler: async (ctx, { assetId, defaults, createdAt, updatedAt, ...write }) => {
     await requireCapability(ctx, 'content.write') // EC-150
     const existing = await ctx.db
       .query('assets')
-      .withIndex('by_asset', (q) => q.eq('assetId', args.assetId))
+      .withIndex('by_asset', (q) => q.eq('assetId', assetId))
       .first()
+    const resolved = resolveRecordWrite(assetRowSchema, existing ?? undefined, write, defaults ?? {})
+    if (!resolved.ok) {
+      throw new ConvexError({
+        code: 'validation',
+        message: rejectedWriteMessage('asset', assetId, resolved.issues),
+        issues: resolved.issues,
+      })
+    }
     if (existing) {
-      await ctx.db.patch(existing._id, { ...args, createdAt: existing.createdAt })
+      await ctx.db.patch(existing._id, { ...(resolved.patch as Partial<AssetDoc>), updatedAt })
       return ctx.db.get(existing._id)
     }
-    const id = await ctx.db.insert('assets', args)
+    const row: WithoutSystemFields<AssetDoc> = { ...resolved.row, assetId, createdAt, updatedAt }
+    const id = await ctx.db.insert('assets', row)
     return ctx.db.get(id)
   },
 })

package/convex/cms.ts

@@ -153,6 +153,28 @@ export const deleteDocument = mutation({
   },
 })
 
+/**
+ * EC-576: drop every document and every version snapshot of the deployment — the
+ * explicit drop a seeder runs before writing a known world. One transaction, so a
+ * seed never observes a half-cleared store. Administration, not a content write:
+ * it requires `project.administer`. Each row delete still passes through the EC-286
+ * write-chokepoint trigger, which drops the reference-index rows and schedules the
+ * host sweep for the published ones — a seeder re-publishes afterwards anyway.
+ *
+ * Convex bounds one transaction at 8192 written documents (its documented limit);
+ * a store past that size fails loudly here rather than clearing half. That is far
+ * above any v1 deployment (the largest measured, Konditorei, holds 331 rows across
+ * both tables), so it is documented, not paginated.
+ */
+export const clearDocuments = mutation({
+  args: {},
+  handler: async (ctx) => {
+    await requireCapability(ctx, 'project.administer')
+    for (const row of await ctx.db.query('cmsDocuments').collect()) await ctx.db.delete(row._id)
+    for (const row of await ctx.db.query('documentVersions').collect()) await ctx.db.delete(row._id)
+  },
+})
+
 /**
  * Document version history (EC-224) — the document analogue of `graphs:*`.
  * Append-only snapshots in `documentVersions`; the live one is pinned by

package/convex/delivery.ts

@@ -1,7 +1,7 @@
 import { v } from 'convex/values'
 import { unfoldValue } from '@elytracms/core/cms-core'
-import { dataSourceSchema } from '@elytracms/core/data-binding'
-import { safeParseTotal } from '@elytracms/core/project-graph'
+import { assetRecordFromRow, deliveryAssetRecord } from '@elytracms/core/persistence'
+import type { AssetRecord } from '@elytracms/core/persistence'
 import studioPackage from '../package.json'
 import { query } from './functions'
 import type { QueryCtx } from './functions'
@@ -37,6 +37,15 @@ import { requireCapability } from './guard'
  *   (EC-183/EC-207, AD-11) — the host reads them from its own config, not this
  *   snapshot. EC-287: there is no project graph — layouts/structure are code.
  *
+ * EC-574: the snapshot used to carry a `sources` strand — the data-binding
+ * subsystem's persisted `cms-data-sources` rows, projected from EVERY stored row
+ * including drafts (the wave-0089 finding: draft rows reached the public
+ * snapshot, and nothing revalidated it). The subsystem is deleted, so the strand
+ * is gone with it; a deployment that still holds `cms-data-sources` rows serves
+ * them like any other document of a collection its config does not declare
+ * (unpinned, so never on the public snapshot; on the draft snapshot as a plain
+ * document the host's content client reports as `unknown-collection`).
+ *
  * `draftSnapshot` is the draft-perspective equivalent (all stored document rows
  * including drafts) and is gated by the deployment env var `DRAFT_PREVIEW_TOKEN`
  * — set via `npx convex env set`. A missing or
@@ -48,19 +57,6 @@ import { requireCapability } from './guard'
 interface DeliverySnapshot {
   projectId: string
   perspective: 'published' | 'draft'
-  /**
-   * Data-source definitions the published graph's bindings reference (EC-166
-   * delivery): the builder persists its provisioned sources (per-section
-   * queries, per-template "current document" sources, provider refs) as
-   * documents in the `cms-data-sources` system collection; this surfaces them
-   * in the structural `CanvasDataSource` shape (`kind`/`id`/`label`/`config`)
-   * the host's payload materialization consumes. Sources are config, not
-   * content — perspective rules don't apply — but exposure is deliberate:
-   * only cms-kind query configs and provider-backed refs are returned (a
-   * rest-kind source's headers stay inside the deployment), and the captured
-   * sample/schema envelope (builder preview state) is not delivery data.
-   */
-  sources: unknown[]
   /** Stored document rows visible in the perspective (published: pinned versions only). */
   documents: unknown[]
   /** Asset metadata in the delivery `AssetRecord` shape (with serve URLs). */
@@ -75,67 +71,32 @@ interface DeliverySnapshot {
   redirects: unknown[]
 }
 
-/** One document per persisted source — must match the studio's sources-store. */
-const DATA_SOURCES_COLLECTION = 'cms-data-sources'
-
-/** The functionRef namespace marking a convex-kind source as provider-backed. */
-const PROVIDER_FUNCTION_PREFIX = 'provider:'
-
 /**
- * Map the persisted `cms-data-sources` documents to the delivery `sources`
- * array. Each record's `config` field carries the FULL canonical
- * `@elytracms/core/data-binding` source, JSON-serialized; it is validated against
- * `dataSourceSchema` (malformed records drop out, never crash the snapshot)
- * and then deliberately projected to the structural delivery envelope:
+ * The delivery-shaped asset records of this deployment (EC-577, D13/F24) — the
+ * ONE row → record projection the Convex delivery route reads. (A second route,
+ * the EC-145 `createContent` kit, read it too until EC-574 deleted the kit; before
+ * EC-577 each route copied the row field by field, and the kit's copy had lost
+ * `lqip`, so the same asset blurred up on the snapshot path and not through the
+ * kit.) The columns come from the core
+ * record schema (`assetRecordFromRow`), and the delivery cut (no editorial `thumb`
+ * or library `title`) from `deliveryAssetRecord`.
  *
- * - `cms`-kind sources pass with their full query config (collection,
- *   documentId, filter/sort/limit, locale) — exactly what
- *   `materializeSourcePayloads` replays through `listDocuments`;
- * - `convex`-kind sources pass only when provider-backed
- *   (`functionRef: provider:<id>`) — a provider ref names project code, it
- *   carries no secret;
- * - `rest`-kind sources never leave the deployment (their headers could hold
- *   credentials), and the captured sample/schema envelope (builder preview
- *   state, not delivery config) is stripped for every kind.
+ * `projectId`: rows carry none (single-tenant, EC-179); the host still parses
+ * delivery assets with one (the constant slug from the args, EC-179 §4).
  *
- * EC-304 B-1: this runs on the PUBLIC `delivery:snapshot` read path, so it must
- * NEVER throw — a hostile `cms-data-sources` row whose `values.config` decodes to a
- * multi-thousand-deep JSON payload would overflow the recursive `dataSourceSchema`
- * and make a plain `.safeParse` THROW a `RangeError`, escaping `loadSnapshot` and
- * 500-ing the public query for every page of the live site. Both parses here degrade
- * instead: `JSON.parse` is already `try`/`catch`-guarded, and `safeParseTotal`
- * turns the schema-side stack overflow into the ordinary `!success` skip below.
- * (Exported for the EC-304 regression pin.)
+ * URL: the stored serve URL when available (EC-151), else a live storage lookup
+ * for older rows. Seeded rows carry a placeholder storage key that is not a real
+ * storage id — `getUrl` throws on those, so degrade to "no URL" instead of
+ * failing the whole read (the host renders its explicit unresolved fallback).
  */
-export function dataSourcesFromSystemCollection(documents: unknown[]): unknown[] {
-  const sources: unknown[] = []
-  for (const document of documents) {
-    if (typeof document !== 'object' || document === null) continue
-    const row = document as { collection?: unknown; id?: unknown; values?: unknown }
-    if (row.collection !== DATA_SOURCES_COLLECTION) continue
-    const values = (typeof row.values === 'object' && row.values !== null ? row.values : {}) as {
-      config?: unknown
-    }
-    if (typeof values.config !== 'string') continue
-    let raw: unknown
-    try {
-      raw = JSON.parse(values.config)
-    } catch {
-      continue
-    }
-    const parsed = safeParseTotal(dataSourceSchema, raw)
-    if (!parsed.success) continue
-    const source = parsed.data
-    if (source.kind === 'rest') continue
-    if (
-      source.kind === 'convex' &&
-      !source.config.functionRef.startsWith(PROVIDER_FUNCTION_PREFIX)
-    ) {
-      continue
-    }
-    sources.push({ kind: source.kind, id: source.id, label: source.label, config: source.config })
+export async function loadDeliveryAssets(ctx: QueryCtx, projectId: string): Promise<AssetRecord[]> {
+  const rows = await ctx.db.query('assets').withIndex('by_asset').collect()
+  const assets: AssetRecord[] = []
+  for (const row of rows) {
+    const url = row.url ?? (await ctx.storage.getUrl(row.storageKey).catch(() => null)) ?? undefined
+    assets.push(deliveryAssetRecord(assetRecordFromRow(row, projectId), url))
   }
-  return sources
+  return assets
 }
 
 export async function loadSnapshot(
@@ -180,50 +141,7 @@ export async function loadSnapshot(
     }
   }
 
-  const assetRows = await ctx.db.query('assets').withIndex('by_asset').collect()
-  const assets: unknown[] = []
-  for (const row of assetRows) {
-    // Same URL convention as the EC-145 content kit: stored serve URL when
-    // available (EC-151), else a live storage lookup for older rows. Seeded
-    // rows carry a placeholder storage key that is not a real storage id —
-    // `getUrl` throws on those, so degrade to "no URL" instead of failing
-    // the whole snapshot (the host renders its explicit unresolved fallback).
-    const url = row.url ?? (await ctx.storage.getUrl(row.storageKey).catch(() => null)) ?? undefined
-    assets.push({
-      id: row.assetId,
-      // Wire-compat: the host still parses delivery assets with `projectId`
-      // (the constant slug from the snapshot args) until the host drops it (EC-179 §4).
-      projectId,
-      filename: row.filename,
-      contentType: row.contentType,
-      byteSize: row.byteSize,
-      ...(row.width !== undefined ? { width: row.width } : {}),
-      ...(row.height !== undefined ? { height: row.height } : {}),
-      ...(row.alt !== undefined ? { alt: row.alt } : {}),
-      // EC-301: thread focalPoint (EC-230) + the schema-driven metadata bag into
-      // the delivery snapshot — both were omitted here, dropping a studio-set
-      // hotspot/metadata on the LIVE path.
-      ...(row.focalPoint !== undefined ? { focalPoint: row.focalPoint } : {}),
-      // EC-420 (AD-2): the LQIP blur placeholder is DELIVERY data, so it ships on
-      // the wire (the EC-368 image seam turns it into a next/image blurDataURL).
-      // The editorial `thumb` (EC-400) is deliberately NOT projected — it stays
-      // in the studio, per the EC-311 additive-metadata invariant.
-      ...(row.lqip !== undefined ? { lqip: row.lqip } : {}),
-      ...(row.meta !== undefined ? { meta: row.meta } : {}),
-      storageKey: row.storageKey,
-      ...(url !== undefined ? { url } : {}),
-      createdAt: row.createdAt,
-      updatedAt: row.updatedAt,
-    })
-  }
-
-  // LIVE-mode data sources: the builder's persisted source records, projected
-  // to the delivery envelope (config only — see the helper's exposure rules).
-  // Sources are project *config*, not perspective-gated content, so they are
-  // extracted from every stored row (independent of publish state) — published
-  // bindings must always resolve their definitions, even when the defining
-  // `cms-data-sources` row is not itself "published".
-  const sources = dataSourcesFromSystemCollection(documentRows.map(unfoldDraft))
+  const assets = await loadDeliveryAssets(ctx, projectId)
 
   // Editorial redirects (EC-303): only ENABLED entries serve — a disabled redirect
   // is stored but never live, in either perspective. Projected to the routing
@@ -236,7 +154,6 @@ export async function loadSnapshot(
   return {
     projectId,
     perspective,
-    sources,
     documents,
     assets,
     redirects,

package/convex/functions.ts

@@ -39,9 +39,9 @@ export const action = actionGeneric
 /**
  * EC-286: every mutation runs through the write-chokepoint triggers (`triggers.ts`)
  * via `customCtx(triggers.wrapDB)`, so reference-index maintenance and host
- * revalidation derive by construction on any `cmsDocuments` write — no mutation
- * calls a derivation helper by hand. (EC-287 retired the graph publish path, so
- * `cmsDocuments` is the single trigger.)
+ * revalidation derive by construction on every write to a registered table — no
+ * mutation calls a derivation helper by hand. `triggers.ts` is the one place that
+ * says which tables those are.
  */
 export const mutation = customMutation(
   mutationGeneric as MutationBuilder<DataModel, 'public'>,