@elytracms/studio 0.0.93 → 0.0.95

package/convex/delivery-redirects.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import type { FunctionReference } from 'convex/server'
+import type { ConvexHttpClient } from 'convex/browser'
+// The host's two readers, from their own modules — the package index also loads the React
+// delivery kit, which the edge-runtime environment cannot evaluate.
+import { assembleLiveSource } from '../../next/src/host-content'
+import { createContentSnapshot } from '../../next/src/snapshot'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import schema from './schema'
+
+/**
+ * The delivery snapshot's redirect strand, end to end: rows stored in the deployment's
+ * `records` table (kind `redirect`) → the REAL `delivery:snapshot` query (convex-test) →
+ * the REAL host loader (`assembleLiveSource`, `@elytracms/next`).
+ *
+ * EC-628 (Codex F04, `tasks/codex-review-2026-10-27/backend.convex.test.ts` "F04 upstream"):
+ * the record store's open data bag accepts drift the normal CRUD refuses (a dashboard edit,
+ * an older writer). Before, an enabled row with `to: 42` was SERVED by the snapshot and
+ * vanished in the host with zero issues, and a switch that is not a boolean was decided by
+ * truthiness (`'false'` served, a missing switch silently paused). Now the snapshot reads
+ * every stored redirect through the one rule (`readLiveRedirects`): what it cannot read is
+ * withheld and reported on the snapshot's `redirectIssues` strand, which the host carries
+ * into its `sourceIssues` and onto the 404 at the redirect's `from`.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+const snapshot = makeFunctionReference<'query'>('delivery:snapshot')
+
+const AT = '2026-10-27T12:00:00.000Z'
+const LOCALES = { default: 'en', locales: ['en'] }
+
+/** Insert redirect rows as the record store holds them — raw, as drift reaches it. */
+async function deploymentWith(rows: ReadonlyArray<{ id: string; data: Record<string, unknown> }>) {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    for (const row of rows) {
+      await ctx.db.insert('records', { kind: 'redirect', recordId: row.id, data: row.data, at: AT, createdAt: AT, updatedAt: AT })
+    }
+  })
+  return t
+}
+
+const redirect = (id: string, data: Record<string, unknown> = {}) => ({
+  id,
+  data: { from: `/${id}`, to: '/target', permanent: true, enabled: true, ...data },
+})
+
+describe('EC-628 — the snapshot names every stored redirect it cannot serve', () => {
+  it('drift is withheld and reported upstream, then located by the host (F04 + disabled-state drift)', async () => {
+    const t = await deploymentWith([
+      redirect('good'),
+      redirect('bad', { to: 42 }), // F04's row
+      redirect('paused', { enabled: false }), // a paused redirect: not live, not a finding
+      redirect('string-off', { enabled: 'false' }), // truthy: was SERVED before
+      { id: 'no-switch', data: { from: '/no-switch', to: '/target', permanent: true } }, // falsy: was silently paused
+    ])
+    const payload = (await t.query(snapshot, { projectId: 'site' })) as {
+      redirects: unknown[]
+      redirectIssues: Array<{ code: string; path: unknown[] }>
+    }
+    expect(payload.redirects).toEqual([{ id: 'good', from: '/good', to: '/target', permanent: true }])
+    expect(payload.redirectIssues.map((issue) => [issue.code, issue.path])).toEqual([
+      ['invalid-redirect', ['redirects', 'bad']],
+      ['invalid-redirect', ['redirects', 'no-switch']],
+      ['invalid-redirect', ['redirects', 'string-off']],
+    ])
+
+    const client = assembleLiveSource(payload as never, { locales: LOCALES, collections: [], routes: [] }, 'published').client({
+      perspective: 'published',
+    })
+    // Control: the readable redirect traverses the whole pipeline, with no issue.
+    expect(client.resolvePage('/good').status).toBe('redirect')
+    expect(client.resolvePage('/good').issues).toEqual([])
+    expect(client.sourceIssues.map((issue) => issue.path[1])).toEqual(['bad', 'no-switch', 'string-off'])
+    for (const path of ['/bad', '/string-off', '/no-switch']) {
+      const result = client.resolvePage(path)
+      expect(result.status).toBe('notFound')
+      expect(result.issues.map((issue) => issue.code)).toEqual(['invalid-redirect'])
+    }
+    // The paused redirect is a 404 with nothing to say — pausing is not drift.
+    expect(client.resolvePage('/paused').status).toBe('notFound')
+    expect(client.resolvePage('/paused').issues).toEqual([])
+  })
+})
+
+/**
+ * EC-627 — "which redirects are live" is decided by ONE reader on every side. The same
+ * stored set is read (1) by the Convex delivery snapshot (`delivery:snapshot`, through
+ * `readLiveRedirects`) and assembled by the host's live loader, and (2) by the host's OTHER
+ * reader, `createContentSnapshot` (`next/src/snapshot.ts`, `readLiveRedirects` over
+ * `adapter.records(redirectRecordKind).list`) — through the REAL `ConvexPersistenceAdapter`
+ * over the same convex-test deployment, so both sides read the very same stored rows.
+ *
+ * The set holds what a hand-built copy of the rule gets wrong: a paused redirect (a copy that
+ * forgets the switch serves it), a switch that is not a boolean (a truthy copy serves
+ * `'false'`), a duplicate `from` (`/old` and `/old/` — the lower id applies on both sides)
+ * and an editorial `meta` bag (never on the routing record). Measured: replacing either
+ * side's call with a hand-built `.filter((r) => r.enabled)` projection turns this red.
+ */
+describe('EC-627 — the Convex snapshot and the host adapter snapshot serve one live set', () => {
+  const STORED = [
+    redirect('a', { meta: { note: 'editorial only' } }),
+    redirect('paused', { enabled: false }),
+    redirect('string-off', { enabled: 'false' }),
+    { id: 'dup-1', data: { from: '/old', to: '/one', permanent: true, enabled: true } },
+    { id: 'dup-2', data: { from: '/old/', to: '/two', permanent: false, enabled: true } },
+  ]
+  const PATHS = ['/a', '/paused', '/string-off', '/old', '/old/']
+
+  /** The decision a reader makes per URL: what a visitor gets. */
+  const outcomes = (client: { resolvePage(url: string): { status: string; redirect: unknown } }) =>
+    PATHS.map((path) => {
+      const result = client.resolvePage(path)
+      return { path, status: result.status, redirect: result.redirect }
+    })
+
+  it('the same stored set yields the same live set through both readers', async () => {
+    const t = await deploymentWith(STORED)
+    await t.run(async (ctx) => {
+      await ctx.db.insert('members', { userId: 'admin', role: 'admin', createdAt: AT, updatedAt: AT })
+    })
+
+    // (1) the deployment's public snapshot → the host's live loader
+    const payload = await t.query(snapshot, { projectId: 'site' })
+    const viaSnapshot = assembleLiveSource(payload as never, { locales: LOCALES, collections: [], routes: [] }, 'published')
+      .client({ perspective: 'published' })
+
+    // (2) the host's adapter reader over the same deployment
+    const asAdmin = t.withIdentity({ subject: 'admin', issuer: 'https://convex.test' })
+    const adapter = 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,
+      'site',
+    )
+    const viaAdapter = (await createContentSnapshot(adapter, 'site', { locales: LOCALES, collections: [], routes: [] }))
+      .client({ perspective: 'published' })
+
+    // The instrument can tell outcomes apart — pinned explicitly, not only compared.
+    expect(outcomes(viaSnapshot)).toEqual([
+      { path: '/a', status: 'redirect', redirect: { target: '/target', permanent: true } },
+      { path: '/paused', status: 'notFound', redirect: null },
+      { path: '/string-off', status: 'notFound', redirect: null },
+      { path: '/old', status: 'redirect', redirect: { target: '/one', permanent: true } },
+      { path: '/old/', status: 'redirect', redirect: { target: '/one', permanent: true } },
+    ])
+    expect(outcomes(viaAdapter)).toEqual(outcomes(viaSnapshot))
+    // The duplicate is one issue, the same on both sides (the router's one redirect set).
+    const duplicates = (issues: readonly { code: string; path: readonly unknown[] }[]) =>
+      issues.filter((issue) => issue.code === 'invalid-redirect').map((issue) => issue.path)
+    expect(duplicates(viaSnapshot.routerIssues)).toEqual([['redirects', 'dup-2']])
+    expect(duplicates(viaAdapter.routerIssues)).toEqual(duplicates(viaSnapshot.routerIssues))
+
+    // EC-628 (the adapter snapshot): the drifted row is NAMED on both sides, not only withheld —
+    // on the source and on the 404 at its `from`. (Before, the adapter path withheld it silently.)
+    const sourcePaths = (client: typeof viaSnapshot) => client.sourceIssues.map((issue) => [issue.code, issue.path])
+    expect(sourcePaths(viaSnapshot)).toEqual([['invalid-redirect', ['redirects', 'string-off']]])
+    expect(sourcePaths(viaAdapter)).toEqual(sourcePaths(viaSnapshot))
+    expect(viaAdapter.resolvePage('/string-off').issues.map((issue) => issue.code)).toEqual(['invalid-redirect'])
+  })
+})

package/convex/delivery.ts

@@ -1,12 +1,14 @@
 import { v } from 'convex/values'
-import { DRAFT_PERSPECTIVE, DRAFT_VARIANT, unfoldValue, variantOf } from '@elytracms/core/cms-core'
+import { DRAFT_PERSPECTIVE, DRAFT_VARIANT, readLiveRedirects, unfoldValue, variantOf } from '@elytracms/core/cms-core'
 import type { Perspective } from '@elytracms/core/cms-core'
 import { assetRecordFromRow, deliveryAssetRecord } from '@elytracms/core/persistence'
+import { constantTimeEquals } from '@elytracms/core/revalidation'
 import type { AssetRecord } from '@elytracms/core/persistence'
 import studioPackage from '../package.json'
 import { query } from './functions'
 import type { QueryCtx } from './functions'
 import { requireCapability } from './guard'
+import { loadRedirectEntries } from './redirects'
 
 // EC-207: routes/redirects are config-sourced (authored in elytra.config.ts and
 // resolved by studio-core), NOT backend data. The delivery snapshot no longer
@@ -75,6 +77,12 @@ interface DeliverySnapshot {
    * infra redirects stay native (`next.config`/`vercel`), evaluated before these.
    */
   redirects: unknown[]
+  /**
+   * EC-628 — one `invalid-redirect` issue per stored redirect the live rule withheld because
+   * it could not read it (id, `from` and the kind of fault — never the target or a value).
+   * Paused redirects are not here: pausing is not drift.
+   */
+  redirectIssues: unknown[]
 }
 
 /**
@@ -156,20 +164,23 @@ export async function loadSnapshot(
 
   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
-  // `RedirectRecord` shape the router/`resolvePage` consume.
-  const redirectRows = await ctx.db.query('redirects').withIndex('by_redirect').collect()
-  const redirects = redirectRows
-    .filter((row) => row.enabled)
-    .map((row) => ({ id: row.redirectId, from: row.from, to: row.to, permanent: row.permanent }))
+  // Editorial redirects (EC-303): only ENABLED entries serve — a disabled redirect is
+  // stored but never live, in either perspective. EC-616: read through the redirect
+  // kind's one server-side reader (records + the marked legacy tolerant read) and
+  // decided by the ONE live-redirect rule, `readLiveRedirects` (EC-590 / EC-627 — this
+  // was the last hand-built copy on Convex). EC-628: a stored redirect the rule cannot
+  // read (a non-boolean switch, a non-string `to`) is withheld AND reported — the host
+  // carries `redirectIssues` into its source issues — instead of being served or dropped
+  // by truthiness. The record kind's own read, not the project schema (EC-585 1e).
+  const live = readLiveRedirects(await loadRedirectEntries(ctx, projectId))
 
   return {
     projectId,
     perspective,
     documents,
     assets,
-    redirects,
+    redirects: live.redirects,
+    redirectIssues: live.issues,
   }
 }
 
@@ -214,7 +225,9 @@ export const draftSnapshot = query({
     if (expected === undefined || expected.length === 0) {
       throw new Error('unauthorized: draft preview is not configured on this deployment')
     }
-    if (args.token !== expected) {
+    // EC-617: the one timing-safe comparison (`constantTimeEquals`, the MAC-compare the
+    // revalidation and ingest verifiers rest on) — never a string `!==`.
+    if (!(await constantTimeEquals(args.token, expected))) {
       throw new Error('unauthorized: invalid draft preview token')
     }
     return loadSnapshot(ctx, { projectId: args.projectId }, DRAFT_PERSPECTIVE)

package/convex/guard.ts

@@ -1,7 +1,8 @@
 import { getAuthUserId } from '@convex-dev/auth/server'
-import { defaultRolePolicy, roleGrantsCapability } from '@elytracms/core/persistence'
+import { roleGrantsCapability } from '@elytracms/core/persistence'
 import type { OperationCapabilityId, ProjectRole, RolePolicy } from '@elytracms/core/persistence'
 import type { QueryCtx } from './functions'
+import { deployedRolePolicy } from './roles'
 
 /**
  * Server-side authorization guards (EC-150). The operations chokepoint in the
@@ -18,9 +19,10 @@ import type { QueryCtx } from './functions'
  * imported here rather than re-declared. Handlers gate on CAPABILITIES
  * (`content.read` / `content.write` / `project.administer`), not literal roles
  * (EC-240c), so a project's custom role set enforces server-side by the same
- * policy the operations layer uses. The Convex trust boundary reads the shipped
- * {@link defaultRolePolicy}; a project overriding roles injects its policy (the
- * documented follow-up seam).
+ * policy the operations layer uses. EC-605: the policy is the project's `roles`
+ * declaration as DEPLOYED — the copy the `elytra` CLI provisions into
+ * `ELYTRA_ROLE_POLICY` (`./roles` `deployedRolePolicy`: the default when unset, a
+ * thrown, located error when malformed — never a silent default).
  *
  * Failures throw plain `Error('unauthorized: …')` — Convex transports the
  * message; the app's adapters normalize thrown backend errors onto the
@@ -78,13 +80,13 @@ export async function memberRole(ctx: GuardCtx, userId: string): Promise<Project
  * This is the ONE role-enforcement primitive at the trust boundary — every
  * handler gates on a capability rather than a literal role, so a project's
  * custom role set is honoured by the shared policy. `policy` defaults to the
- * shipped {@link defaultRolePolicy}; the override seam (a project injecting its
- * own policy) is the documented follow-up.
+ * deployment's policy (EC-605, {@link deployedRolePolicy}); the parameter stays for a
+ * caller that must judge against another (tests).
  */
 export async function requireCapability(
   ctx: GuardCtx,
   capability: OperationCapabilityId,
-  policy: RolePolicy = defaultRolePolicy,
+  policy: RolePolicy = deployedRolePolicy(),
 ): Promise<string> {
   const userId = await requireUserId(ctx)
   const actual = await memberRole(ctx, userId)

package/convex/http-routes.test.ts

@@ -33,9 +33,20 @@ function routeTable(http: HttpRouter): string[] {
     .sort()
 }
 
-describe('defineStudioHttp — the engine registers no HTTP routes of its own (EC-481)', () => {
-  it('contributes an EMPTY route table beyond what the injected auth registers', () => {
-    expect(routeTable(defineStudioHttp({ auth: silentAuth }))).toEqual([])
+/** EC-617: the engine's ONE route — the public-ingest receiver, an exact path (the EC-481 bar: a real client, a narrow prefix). */
+const ENGINE_ROUTES = ['POST /elytra/ingest']
+
+describe('defineStudioHttp — the engine registers exactly one HTTP route of its own (EC-481 → EC-617)', () => {
+  it('contributes ONLY the ingest receiver beyond what the injected auth registers', () => {
+    expect(routeTable(defineStudioHttp({ auth: silentAuth }))).toEqual(ENGINE_ROUTES)
+  })
+
+  it('the receiver is an EXACT path, POST only — it claims no prefix', () => {
+    const http = defineStudioHttp({ auth: silentAuth })
+    expect(http.lookup('/elytra/ingest', 'POST')).not.toBeNull()
+    expect(http.lookup('/elytra/ingest/anything', 'POST')).toBeNull()
+    expect(http.lookup('/elytra/', 'POST')).toBeNull()
+    expect(http.lookup('/elytra/ingest', 'GET')).toBeNull()
   })
 
   it('control: the recorder DOES see routes, so the empty result above is real', () => {
@@ -45,10 +56,9 @@ describe('defineStudioHttp — the engine registers no HTTP routes of its own (E
         http.route({ pathPrefix: '/api/auth/callback/', method: 'POST', handler })
       },
     }
-    expect(routeTable(defineStudioHttp({ auth }))).toEqual([
-      'GET /.well-known/jwks.json',
-      'POST /api/auth/callback/*',
-    ])
+    expect(routeTable(defineStudioHttp({ auth }))).toEqual(
+      ['GET /.well-known/jwks.json', 'POST /api/auth/callback/*', ...ENGINE_ROUTES].sort(),
+    )
   })
 
   it('passes the auth routes through untouched — nothing is added, dropped, or reordered', () => {
@@ -61,7 +71,7 @@ describe('defineStudioHttp — the engine registers no HTTP routes of its own (E
         }
       },
     }
-    expect(routeTable(defineStudioHttp({ auth }))).toEqual([...registered].sort())
+    expect(routeTable(defineStudioHttp({ auth }))).toEqual([...registered, ...ENGINE_ROUTES].sort())
   })
 })
 

package/convex/http.ts

@@ -1,5 +1,8 @@
 import { httpRouter } from 'convex/server'
 import type { HttpRouter } from 'convex/server'
+import { INGEST_RECEIVER_PATH } from '@elytracms/core/ingest'
+import { ingestReceiver } from './ingest'
+import type { IngestHandlers } from './ingest'
 
 /** The slice of the Convex Auth object the studio's HTTP routes need. */
 interface AuthHttpRoutes {
@@ -8,33 +11,36 @@ interface AuthHttpRoutes {
 
 /**
  * EC-252 — the studio's HTTP routes as a factory. Pure engine infra ships in the
- * package; only the consumer's `auth` (provider choice) is injected. The consumer's
- * `convex/http.ts` is a two-liner:
+ * package; only the consumer's `auth` (provider choice) and — since EC-617 — its ingest
+ * handlers are injected. The consumer's `convex/http.ts`:
  *
  * ```ts
  * import { auth } from './auth'
  * export default defineStudioHttp({ auth })
+ * // with an addon that handles ingest payloads (one import, one entry):
+ * // import { formsIngest } from '@elytracms/forms/convex'
+ * // export default defineStudioHttp({ auth, ingest: { submission: formsIngest } })
  * ```
  *
- * ## The engine registers NO HTTP routes of its own (EC-481)
+ * ## The engine registers exactly ONE route of its own (EC-481 → EC-617)
  *
- * Everything on this router comes from Convex Auth's `addHttpRoutes` — the JWT
- * discovery endpoints (`/.well-known/*`, EC-150) and, only when a consumer supplies
- * an OAuth provider, `/api/auth/signin/*` + `/api/auth/callback/*`.
+ * Everything else on this router comes from Convex Auth's `addHttpRoutes` — the JWT
+ * discovery endpoints (`/.well-known/*`, EC-150) and, only when a consumer supplies an
+ * OAuth provider, `/api/auth/signin/*` + `/api/auth/callback/*`.
  *
- * The engine used to add one more: `GET /api/projects/*`, the EC-157 Bearer-token
- * registry-sync endpoint backing `builder typegen`/`builder check`. EC-470 deleted
- * that CLI and with it the endpoint's only client; the handler had in any case
- * answered with config-owned placeholders since EC-287 retired the project graph
- * (`project: null`, `collections: []`). EC-481 removed the route and its handler
- * together rather than leave a Bearer-authenticated surface serving stub data on
- * every deployment. `http-routes.test.ts` pins that shut.
- *
- * A future engine-owned HTTP surface is fine — but it needs a real client and a
- * narrower prefix than `/api/projects/`.
+ * EC-481 removed the engine's former `GET /api/projects/*` (a Bearer-authenticated
+ * registry-sync endpoint with no client left) and set the bar for any future one: "a
+ * real client and a narrower prefix". EC-617's public-ingest RECEIVER is that route:
+ * `POST /elytra/ingest` — an EXACT path, not a prefix; its client is the site's
+ * `createIngestRoute` (`@elytracms/next`), which signs every payload with the
+ * server-held secret, and `elytra doctor`'s probe. It is mounted on every deployment,
+ * with or without handlers: closed (401) until `ELYTRA_INGEST_SECRET` is set, and a
+ * payload kind with no registered handler is refused visibly (422), never dropped.
+ * `http-routes.test.ts` pins the table.
  */
-export function defineStudioHttp({ auth }: { auth: AuthHttpRoutes }): HttpRouter {
+export function defineStudioHttp({ auth, ingest }: { auth: AuthHttpRoutes; ingest?: IngestHandlers }): HttpRouter {
   const http = httpRouter()
   auth.addHttpRoutes(http)
+  http.route({ path: INGEST_RECEIVER_PATH, method: 'POST', handler: ingestReceiver(ingest) })
   return http
 }