@supatype/cli 0.2.0 → 0.3.0

package/src/dev-compose.ts

@@ -2,6 +2,7 @@
  * `supatype dev` when `provider: docker`, full self-host Compose stack (Kong gateway).
  */
 
+import { withPublishing } from "./model-versioning.js"
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
@@ -328,13 +329,23 @@ export function upsertDevComposeEnv(
     (key) => !(wantsLocalServer && key === "SUPATYPE_SERVER_IMAGE"),
   )
   const removeImageKeys = managedImageKeys.filter((key) => !(key in imagePins))
+  // The server refuses to start when *any* retired name is in scope, and it reads the project's
+  // config files into its environment before checking, so a `.env` this CLI wrote under the old
+  // spelling is fatal to a stack that has otherwise been upgraded. Only the key this file used to
+  // write is removed: an operator's own GOTRUE_ variable is theirs, and the server's error names it
+  // and its replacement precisely enough to fix by hand.
+  const retiredKeys = ["GOTRUE_MAILER_AUTOCONFIRM"]
   upsertEnvFile(cwd, updates, {
     removeManaged: removeImageKeys,
     managed: managedImageKeys,
     // A local image left in `.env` after the project stopped asking for one would keep pointing
     // compose at a stale build, and it carries no marker for `removeManaged` to act on.
-    ...(!wantsLocalServer &&
-      !("SUPATYPE_SERVER_IMAGE" in imagePins) && { remove: ["SUPATYPE_SERVER_IMAGE"] }),
+    remove: [
+      ...retiredKeys,
+      ...(!wantsLocalServer && !("SUPATYPE_SERVER_IMAGE" in imagePins)
+        ? ["SUPATYPE_SERVER_IMAGE"]
+        : []),
+    ],
   })
 }
 
@@ -635,7 +646,7 @@ async function runComposeSchemaPush(
   schemaPath: string,
   composeProject: string,
 ): Promise<void> {
-  const ast = loadSchemaAst(schemaPath, cwd)
+  const ast = withPublishing(loadSchemaAst(schemaPath, cwd), config)
   const astJson = JSON.stringify(ast)
 
   const supatypeDir = join(cwd, ".supatype")
@@ -868,7 +879,7 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
     const brand = { intro: "Schema diff" }
     await ensureDockerDbPublishedForHostEngine(cwd, config, brand)
     const schemaPath = schemaPathFromProject(config, cwd)
-    const ast = loadSchemaAst(schemaPath, cwd)
+    const ast = withPublishing(loadSchemaAst(schemaPath, cwd), config)
     await ensureEngine()
     return engineRequest<DiffResult>("/diff", {
       ast,
@@ -890,7 +901,7 @@ export async function diffSchemaDocker(cwd: string, config: SupatypeProjectConfi
   await startComposeDatabase(config, paths, cwd, project, diffBrand)
 
   const schemaPath = schemaPathFromProject(config, cwd)
-  const ast = loadSchemaAst(schemaPath, cwd)
+  const ast = withPublishing(loadSchemaAst(schemaPath, cwd), config)
 
   const supatypeDir = join(cwd, ".supatype")
   mkdirSync(supatypeDir, { recursive: true })
@@ -945,7 +956,7 @@ export async function pushSchemaDocker(cwd: string, config: SupatypeProjectConfi
   await startComposeDatabase(config, paths, cwd, project, pushBrand)
 
   const schemaPath = schemaPathFromProject(config, cwd)
-  const ast = loadSchemaAst(schemaPath, cwd)
+  const ast = withPublishing(loadSchemaAst(schemaPath, cwd), config)
   await runComposeSchemaPush(cwd, config, paths, schemaPath, project)
 
   const upGateway = runDockerCompose(paths.composePath, ["up", "-d"], cwd, project, {
@@ -1157,7 +1168,7 @@ export async function runDevCompose(cwd: string, config: SupatypeProjectConfig,
     startedAt: new Date().toISOString(),
   })
 
-  const ast = loadSchemaAst(schemaPath, cwd)
+  const ast = withPublishing(loadSchemaAst(schemaPath, cwd), config)
   await provisionDockerStorageBuckets(ast, kongPort, serviceRoleKey)
 
   const pidDir = join(homedir(), ".supatype", "projects", config.project.name, "pid")

package/src/engine-floor.ts

@@ -27,6 +27,15 @@ import type { ExtractedSchemaAstV2, ModelAstV2 } from "./schema-ast-v2.js"
 /** First engine release that creates the `_supatype` constraint helpers (schema-engine v0.2.0). */
 export const ENGINE_MIN_FOR_BOUNDS = "0.2.0"
 
+/**
+ * First engine release that emits the drafts and publishing layer (schema-engine v0.3.0).
+ *
+ * The failure this guards is silent rather than loud, which is why it is worth a check of its own:
+ * an older engine does not reject `versions`, it ignores the key. The push succeeds, the model has
+ * no snapshot table, and Studio saves drafts into nothing.
+ */
+export const ENGINE_MIN_FOR_VERSIONS = "0.3.0"
+
 /**
  * Compare two dotted versions numerically. Returns <0, 0 or >0.
  *
@@ -80,8 +89,55 @@ export function boundsRequiringHelpers(ast: ExtractedSchemaAstV2): string[] {
   return [...fieldsWithBounds(ast.models), ...modelsWithConstraints(ast.models)]
 }
 
+/** Models declaring `versions`, which needs a whole layer only a new enough engine emits. */
+export function modelsRequiringVersions(ast: ExtractedSchemaAstV2): string[] {
+  return ast.models
+    .filter((model) => model.options["versions"] !== undefined)
+    .map((model) => model.name)
+}
+
 /**
- * Refuse a push whose schema needs helpers this engine does not create.
+ * One thing a schema can declare that an older engine cannot apply.
+ *
+ * A table rather than a second copy of the check, because there will be a third: every feature that
+ * puts something in the database which only the engine creates lands here, and the shape of the
+ * refusal should not be rewritten each time.
+ */
+interface EngineRequirement {
+  /** First engine release that can apply it. */
+  since: string
+  /** What in this schema needs it, named so the message can point at it. */
+  declaredBy: (ast: ExtractedSchemaAstV2) => string[]
+  /** What the author wrote. */
+  feature: string
+  /** What happens if it is applied anyway, in the words the failure would use. */
+  consequence: string
+}
+
+const ENGINE_REQUIREMENTS: EngineRequirement[] = [
+  {
+    since: ENGINE_MIN_FOR_BOUNDS,
+    declaredBy: boundsRequiringHelpers,
+    feature: "bounds",
+    consequence:
+      `Bounds compile to CHECK constraints that call helpers in the _supatype schema, and only ` +
+      `engine ${ENGINE_MIN_FOR_BOUNDS}+ creates them. Applying this would fail inside Postgres ` +
+      `with "function _supatype.richtext_text(jsonb) does not exist".`,
+  },
+  {
+    since: ENGINE_MIN_FOR_VERSIONS,
+    declaredBy: modelsRequiringVersions,
+    feature: "`versions`",
+    consequence:
+      `Only engine ${ENGINE_MIN_FOR_VERSIONS}+ emits the snapshot tables, the draft views and the ` +
+      `publish functions. An older engine ignores the declaration and applies the rest, so the ` +
+      `push reports success and you get a model with no history, no drafts and an editor that ` +
+      `saves into nothing. That silence is the reason this refuses.`,
+  },
+]
+
+/**
+ * Refuse a push whose schema needs something this engine cannot apply.
  *
  * Takes the pin from `versions.engine`, or undefined when unpinned. See the note above on why
  * that is the right source rather than the binary's own `--version`.
@@ -93,21 +149,22 @@ export function assertEngineSupportsSchema(
   // Unpinned resolves to latest, and `local` points at a build whose version the config does not
   // know. Neither can be compared, and neither is the case that breaks.
   if (pinnedEngineVersion === undefined || pinnedEngineVersion === "local") return
-  if (compareVersions(pinnedEngineVersion, ENGINE_MIN_FOR_BOUNDS) >= 0) return
 
-  const needed = boundsRequiringHelpers(ast)
-  if (needed.length === 0) return
+  for (const requirement of ENGINE_REQUIREMENTS) {
+    if (compareVersions(pinnedEngineVersion, requirement.since) >= 0) continue
 
-  const shown = needed.slice(0, 3).join(", ")
-  const more = needed.length > 3 ? `, and ${needed.length - 3} more` : ""
-  throw new Error(
-    `This schema declares bounds that need schema-engine ${ENGINE_MIN_FOR_BOUNDS} or newer, ` +
-      `and this project pins ${pinnedEngineVersion}.\n\n` +
-      `  Declared on: ${shown}${more}\n\n` +
-      `Bounds compile to CHECK constraints that call helpers in the _supatype schema, and only ` +
-      `engine ${ENGINE_MIN_FOR_BOUNDS}+ creates them. Applying this would fail inside Postgres ` +
-      `with "function _supatype.richtext_text(jsonb) does not exist".\n\n` +
-      `Raise or remove the pin in supatype.config.ts:\n` +
-      `  versions: { engine: "${ENGINE_MIN_FOR_BOUNDS}" }   // or omit it to track latest`,
-  )
+    const needed = requirement.declaredBy(ast)
+    if (needed.length === 0) continue
+
+    const shown = needed.slice(0, 3).join(", ")
+    const more = needed.length > 3 ? `, and ${needed.length - 3} more` : ""
+    throw new Error(
+      `This schema declares ${requirement.feature}, which needs schema-engine ` +
+        `${requirement.since} or newer, and this project pins ${pinnedEngineVersion}.\n\n` +
+        `  Declared on: ${shown}${more}\n\n` +
+        `${requirement.consequence}\n\n` +
+        `Raise or remove the pin in supatype.config.ts:\n` +
+        `  versions: { engine: "${requirement.since}" }   // or omit it to track latest`,
+    )
+  }
 }

package/src/functions-deno-types.ts

@@ -76,6 +76,44 @@ declare namespace Deno {
 }
 
 /** `functions/tsconfig.json`: owns function files so the app config can exclude them. */
+/**
+ * The context type, as a module a function can import.
+ *
+ * Not an ambient declaration. `functions/deno.d.ts` is read by tsserver and by the tsconfig in this
+ * directory, but `deno check` builds its own type graph and does not look at either, so a function
+ * naming an ambient type fails the check the runtime itself would run. An import works in both.
+ */
+export function functionsContextModuleSource(): string {
+  return `/**
+ * What a function is told about the call it is serving.
+ *
+ * Handed to the handler as its second argument. Per-invocation values used to be injected into the
+ * process environment and read with Deno.env.get, which is global: two concurrent calls saw each
+ * other's configuration, including a service-role key granted to one route and not another. The
+ * worker therefore held a lock across every handler and ran one invocation at a time.
+ *
+ * Passing them in removes the global, so functions run concurrently.
+ *
+ * Regenerated by the CLI. Edits are overwritten.
+ */
+export interface FunctionContext {
+  /** Unique to this invocation. Every log line it writes carries the same value. */
+  readonly executionId: string
+  /** The function or hook route being served. */
+  readonly functionName: string
+  /** The project's API base URL, reachable from inside the function. */
+  readonly url: string
+  readonly anonKey: string
+  /** Present only when the project granted this route the service role. */
+  readonly serviceRoleKey?: string
+  readonly dbUrl?: string
+  readonly region: string
+  /** Values from .env and .env.<function>.local. */
+  readonly env: Readonly<Record<string, string>>
+}
+`
+}
+
 export function functionsTsConfigSource(): string {
   return `{
   "compilerOptions": {
@@ -97,6 +135,7 @@ export function functionsTsConfigSource(): string {
 
 export type FunctionsDenoTypesResult = {
   wroteDenoDts: boolean
+  wroteContextModule: boolean
   wroteTsconfig: boolean
   rootExclude: "updated" | "already" | "missing" | "manual"
   hints: string[]
@@ -121,6 +160,14 @@ export function ensureFunctionsDenoTypes(
     wroteDenoDts = true
   }
 
+  // Always rewritten, unlike the other two: this one is a contract the runtime enforces, so a stale
+  // copy is a type error in the user's editor rather than a missing convenience.
+  const contextDir = join(functionsDir, "_shared")
+  const contextPath = join(contextDir, "context.ts")
+  mkdirSync(contextDir, { recursive: true })
+  writeFileSync(contextPath, functionsContextModuleSource(), "utf8")
+  const wroteContextModule = true
+
   let wroteTsconfig = false
   if (!existsSync(tsconfigPath)) {
     writeFileSync(tsconfigPath, functionsTsConfigSource(), "utf8")
@@ -141,7 +188,7 @@ export function ensureFunctionsDenoTypes(
     )
   }
 
-  return { wroteDenoDts, wroteTsconfig, rootExclude, hints }
+  return { wroteDenoDts, wroteContextModule, wroteTsconfig, rootExclude, hints }
 }
 
 function ensureRootTsconfigExcludesFunctions(

package/src/functions-router-gen.ts

@@ -59,9 +59,28 @@ export function generateFunctionsRouterSource(
   const routes = fns.map((fn, i) => `  "${fn.name}": handler_${i},`)
 
   return `// Auto-generated: do not edit (regenerated by supatype dev / functions serve)
+import { AsyncLocalStorage } from "node:async_hooks"
 ${imports.join("\n")}
 
-const handlers: Record<string, (req: Request) => Response | Promise<Response>> = {
+/**
+ * What a function is told about the call it is serving.
+ *
+ * Passed as the second argument rather than injected into the process environment, so
+ * invocations do not have to
+ * be serialised to keep one call's configuration out of another's.
+ */
+interface FunctionContext {
+  readonly executionId: string
+  readonly functionName: string
+  readonly url: string
+  readonly anonKey: string
+  readonly serviceRoleKey?: string
+  readonly dbUrl?: string
+  readonly region: string
+  readonly env: Readonly<Record<string, string>>
+}
+
+const handlers: Record<string, (req: Request, ctx: FunctionContext) => Response | Promise<Response>> = {
 ${routes.join("\n")}
 }
 
@@ -71,17 +90,57 @@ const normalizedFunctionsDir = functionsDir.endsWith("/") ? functionsDir.slice(0
 const sharedEnvPath = Deno.env.get("SUPATYPE_SHARED_ENV_FILE")
   ?? (normalizedFunctionsDir ? normalizedFunctionsDir + "/.env.local" : "")
 
-let envLock: Promise<void> = Promise.resolve()
+// Nothing per-invocation is written to Deno.env, so invocations run concurrently.
+//
+// This used to hold a lock across the whole handler because the config was delivered by mutating
+// the process environment, which is global: two concurrent calls would read each other's values.
+// The lock made the router run one invocation at a time, so a function waiting on a slow API
+// blocked every other function locally, and the deployed worker had the same lock, so local
+// behaved exactly like production and the serialisation was invisible.
+const invocationStore = new AsyncLocalStorage<{ executionId: string; functionName: string }>()
+
+const realConsole = {
+  debug: console.debug.bind(console),
+  info: console.info.bind(console),
+  log: console.log.bind(console),
+  warn: console.warn.bind(console),
+  error: console.error.bind(console),
+}
+
+function projectRef(): string {
+  return (Deno.env.get("SUPATYPE_PROJECT_REF") ?? "").trim() || "unknown"
+}
 
-async function withEnvLock<T>(run: () => Promise<T>): Promise<T> {
-  const prev = envLock
-  let release: () => void = () => {}
-  envLock = new Promise<void>(resolve => { release = resolve })
-  await prev
+function emit(level: string, message: string, extra: Record<string, unknown> = {}): void {
+  const current = invocationStore.getStore()
+  const line = {
+    timestamp: new Date().toISOString(),
+    level,
+    service: "functions-worker",
+    project_ref: projectRef(),
+    ...(current ? { request_id: current.executionId, function: current.functionName } : {}),
+    message,
+    ...extra,
+  }
+  const write = level === "error" ? realConsole.error : realConsole.log
+  write(JSON.stringify(line))
+}
+
+function formatArg(value: unknown): string {
+  if (typeof value === "string") return value
+  if (value instanceof Error) return value.stack ?? value.name + ": " + value.message
   try {
-    return await run()
-  } finally {
-    release()
+    return JSON.stringify(value) ?? String(value)
+  } catch {
+    return String(value)
+  }
+}
+
+// A function's own console output, structured and attributed to the call that wrote it. Captured
+// before any handler runs so nothing it logs escapes unlabelled.
+for (const [method, level] of [["debug", "debug"], ["info", "info"], ["log", "info"], ["warn", "warn"], ["error", "error"]] as const) {
+  console[method] = (...args: unknown[]): void => {
+    emit(level, args.map(formatArg).join(" "))
   }
 }
 
@@ -90,12 +149,17 @@ async function readEnvFile(path: string): Promise<Record<string, string>> {
   try {
     const text = await Deno.readTextFile(path)
     const out: Record<string, string> = {}
-    for (const line of text.split("\\n")) {
-      const trimmed = line.trim()
-      if (!trimmed || trimmed.startsWith("#")) continue
-      const eq = trimmed.indexOf("=")
+    for (const raw of text.split("\\n")) {
+      const line = raw.trim()
+      if (!line || line.startsWith("#")) continue
+      const eq = line.indexOf("=")
       if (eq <= 0) continue
-      out[trimmed.slice(0, eq)] = trimmed.slice(eq + 1)
+      const key = line.slice(0, eq).trim()
+      let value = line.slice(eq + 1).trim()
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1)
+      }
+      out[key] = value
     }
     return out
   } catch {
@@ -106,32 +170,16 @@ async function readEnvFile(path: string): Promise<Record<string, string>> {
 async function scopedEnvForFunction(fnName: string): Promise<Record<string, string>> {
   const shared = await readEnvFile(sharedEnvPath)
   if (!normalizedFunctionsDir) return shared
-  const fnPath = normalizedFunctionsDir + "/.env." + fnName + ".local"
-  const fnVars = await readEnvFile(fnPath)
+  const fnVars = await readEnvFile(normalizedFunctionsDir + "/.env." + fnName + ".local")
   return { ...shared, ...fnVars }
 }
 
-async function runWithScopedEnv<T>(fnName: string, run: () => Promise<T>): Promise<T> {
-  return withEnvLock(async () => {
-    const scoped = await scopedEnvForFunction(fnName)
-    const prev = new Map<string, string | undefined>()
-    for (const [k, v] of Object.entries(scoped)) {
-      prev.set(k, Deno.env.get(k))
-      Deno.env.set(k, v)
-    }
-    try {
-      return await run()
-    } finally {
-      for (const k of Object.keys(scoped)) {
-        const old = prev.get(k)
-        if (old === undefined) Deno.env.delete(k)
-        else Deno.env.set(k, old)
-      }
-    }
-  })
-}
-
-Deno.serve({ port }, async (req: Request): Promise<Response> => {
+Deno.serve({
+  port,
+  onListen: ({ hostname, port: bound }) => {
+    emit("info", "functions router listening on http://" + hostname + ":" + bound)
+  },
+}, async (req: Request): Promise<Response> => {
   const url = new URL(req.url)
   const pathParts = url.pathname
     .replace(/^\\/functions\\/v1\\/?/, "")
@@ -142,58 +190,42 @@ Deno.serve({ port }, async (req: Request): Promise<Response> => {
   if (!fnName || !handlers[fnName]) {
     return new Response(JSON.stringify({
       error: "not_found",
-      message: fnName ? \`Function "\${fnName}" not found\` : "No function specified",
+      message: fnName ? 'Function "' + fnName + '" not found' : "No function specified",
       available: Object.keys(handlers),
     }), { status: 404, headers: { "Content-Type": "application/json" } })
   }
 
-  try {
-    const start = performance.now()
-    const response = await runWithScopedEnv(fnName, async () => {
-      const prev = new Map<string, string | undefined>()
-      const setScoped = (key: string, value: string | undefined) => {
-        if (value === undefined || value.length === 0) return
-        prev.set(key, Deno.env.get(key))
-        Deno.env.set(key, value)
-      }
+  const anonKey = Deno.env.get("SUPATYPE_ANON_KEY") ?? ""
+  const serviceRoleKey = Deno.env.get("SUPATYPE_SERVICE_ROLE_KEY")
+  const dbUrl = Deno.env.get("SUPATYPE_DB_URL") ?? Deno.env.get("DATABASE_URL")
+  const context: FunctionContext = {
+    executionId: crypto.randomUUID(),
+    functionName: fnName,
+    url: Deno.env.get("SUPATYPE_URL") ?? "",
+    anonKey,
+    ...(serviceRoleKey ? { serviceRoleKey } : {}),
+    ...(dbUrl ? { dbUrl } : {}),
+    region: Deno.env.get("SUPATYPE_REGION") ?? "local",
+    env: await scopedEnvForFunction(fnName),
+  }
 
-      // Supatype runtime defaults available to every invocation.
-      const supatypeUrl = Deno.env.get("SUPATYPE_URL")
-      const supatypeAnon = Deno.env.get("SUPATYPE_ANON_KEY")
-      const supatypeServiceRole = Deno.env.get("SUPATYPE_SERVICE_ROLE_KEY")
-      const supatypeDbUrl = Deno.env.get("SUPATYPE_DB_URL") ?? Deno.env.get("DATABASE_URL")
-      const supatypeJwks = Deno.env.get("SUPATYPE_JWKS")
-
-      setScoped("SUPATYPE_URL", supatypeUrl)
-      setScoped("SUPATYPE_ANON_KEY", supatypeAnon)
-      setScoped("SUPATYPE_SERVICE_ROLE_KEY", supatypeServiceRole)
-      setScoped("SUPATYPE_DB_URL", supatypeDbUrl)
-      setScoped("SUPATYPE_JWKS", supatypeJwks)
-      if (!Deno.env.get("SUPATYPE_PUBLISHABLE_KEYS") && supatypeAnon) {
-        setScoped("SUPATYPE_PUBLISHABLE_KEYS", JSON.stringify({ anon: supatypeAnon }))
-      }
-      if (!Deno.env.get("SUPATYPE_SECRET_KEYS") && supatypeServiceRole) {
-        setScoped("SUPATYPE_SECRET_KEYS", JSON.stringify({ service_role: supatypeServiceRole }))
-      }
+  const start = performance.now()
 
-      setScoped("SUPATYPE_REGION", Deno.env.get("SUPATYPE_REGION") ?? "local")
-      setScoped("SUPATYPE_EXECUTION_ID", crypto.randomUUID())
-      setScoped("DENO_DEPLOYMENT_ID", Deno.env.get("DENO_DEPLOYMENT_ID") ?? "local-dev")
-
-      try {
-        return await handlers[fnName]!(req)
-      } finally {
-        for (const [key, old] of prev.entries()) {
-          if (old === undefined) Deno.env.delete(key)
-          else Deno.env.set(key, old)
-        }
-      }
+  try {
+    const response = await invocationStore.run(
+      { executionId: context.executionId, functionName: fnName },
+      async () => handlers[fnName]!(req, context),
+    )
+    emit("info", req.method + " /functions/v1/" + fnName + " -> " + response.status, {
+      status: response.status,
+      duration_ms: Number((performance.now() - start).toFixed(1)),
     })
-    const duration = (performance.now() - start).toFixed(1)
-    console.log(\`\${req.method} /functions/v1/\${fnName} → \${response.status} (\${duration}ms)\`)
     return response
   } catch (err) {
-    console.error(\`Error in function "\${fnName}":\`, err)
+    emit("error", err instanceof Error ? err.message : "Unknown error", {
+      status: 500,
+      duration_ms: Number((performance.now() - start).toFixed(1)),
+    })
     return new Response(JSON.stringify({
       error: "function_error",
       message: err instanceof Error ? err.message : "Unknown error",

package/src/kong-config.ts

@@ -19,7 +19,7 @@ export interface KongDeclarativeOptions {
   /** See {@link RuntimeRouteOptions.studioStripPath}. */
   studioStripPath?: boolean | undefined
   /**
-   * When set, append a global Kong `acme` plugin (Let's Encrypt) with Redis/Valkey
+   * When set, append a global Kong `acme` plugin (Let's Encrypt) with RESP
    * storage so the self-host gateway provisions and renews TLS automatically.
    */
   acme?: { email: string; domain: string; redisHost: string } | undefined

package/src/model-cache.ts

@@ -0,0 +1,74 @@
+/**
+ * Lift each model's `cache` declaration into the shape the route manifest carries.
+ *
+ * Keyed by **table**, like `hooks` and `validators`, because that is what a REST path carries — the
+ * model name never reaches the wire.
+ *
+ * ## Why the manifest and not the AST
+ *
+ * `supatype push` writes the declaration into `annotations.platform.cache` too, and the server does
+ * not read it there. The schema engine writes `_supatype.schema_state.ast_snapshot` as
+ * `serde_json::to_value(&ast)` — its own parsed struct, re-serialised — and its
+ * `PlatformModelAnnotations` knows only `access` and `searchFields`. An unknown key is not an error
+ * to serde; it is silently dropped. So a declaration left to ride the AST would vanish between here
+ * and the server with nothing anywhere reporting it.
+ *
+ * `hooks` has always taken this route for the same reason. Plan §13.1 said otherwise and said to
+ * verify before relying on it; this is the verified path.
+ */
+import type { ModelCacheAst } from "./schema-ast-v2.js"
+
+/** One table's cache declaration, as the manifest carries it. */
+export interface ManifestCacheEntry {
+  enabled?: boolean
+  maxTtl?: number
+  public?: boolean
+  rows?: boolean
+}
+
+interface ShapedModel {
+  annotations?: {
+    db?: { tableName?: string }
+    platform?: { cache?: ModelCacheAst }
+  }
+}
+
+/**
+ * Every model's cache declaration, keyed by table name.
+ *
+ * A model that declared nothing is absent rather than present-and-empty. The distinction is
+ * load-bearing: the declaration is a ceiling, so "no entry" means *nothing may cache this table*,
+ * and an empty entry would read as "declared, permitting nothing" — the same outcome by a route
+ * that looks like a bug.
+ */
+export function manifestCache(ast: unknown): Record<string, ManifestCacheEntry> {
+  const models = (ast as { models?: unknown[] })?.models
+  if (!Array.isArray(models)) return {}
+
+  const out: Record<string, ManifestCacheEntry> = {}
+  for (const model of models) {
+    // Guarded before the optional chains, not by them: `x?.y` protects against `x.y` being
+    // nullish, not against `x` itself being null — so a malformed entry in the models array would
+    // throw a TypeError out of `supatype push` rather than being skipped.
+    if (typeof model !== "object" || model === null) continue
+    const shaped = model as ShapedModel
+    const table = shaped.annotations?.db?.tableName
+    const cache = shaped.annotations?.platform?.cache
+    if (typeof table !== "string" || table.length === 0) continue
+    if (typeof cache !== "object" || cache === null) continue
+
+    const entry: ManifestCacheEntry = {}
+    // Copied key by key rather than spread, so a field added to the AST shape has to be added here
+    // deliberately. The manifest is a wire format read by another process; silently widening it is
+    // how the two ends stop agreeing about what a field means.
+    if (typeof cache.enabled === "boolean") entry.enabled = cache.enabled
+    if (typeof cache.public === "boolean") entry.public = cache.public
+    if (typeof cache.rows === "boolean") entry.rows = cache.rows
+    if (typeof cache.maxTtl === "number" && Number.isFinite(cache.maxTtl) && cache.maxTtl >= 0) {
+      entry.maxTtl = cache.maxTtl
+    }
+
+    if (Object.keys(entry).length > 0) out[table] = entry
+  }
+  return out
+}