@supatype/cli 0.2.1 → 0.3.1

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,122 @@
+/**
+ * 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 { readEnvValue, upsertEnvFile } from "./env-file.js"
+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
+}
+
+// ─── Row cache enablement ────────────────────────────────────────────────────
+
+/** The two env names the Postgres image reads to turn Mode B on. */
+export const ROWCACHE_DECODE_ENV = "SUPATYPE_KEYSPACE_ROWCACHE_DECODE"
+export const ROWCACHE_READTHROUGH_ENV = "SUPATYPE_KEYSPACE_ROWCACHE_READTHROUGH"
+
+/** Whether any model declares `cache: { rows: true }`. */
+export function declaresRowCache(ast: unknown): boolean {
+  return Object.values(manifestCache(ast)).some((entry) => entry.rows === true)
+}
+
+/**
+ * Keep the row cache's two switches in `.env` matching what the schema declares.
+ *
+ * `cache: { rows: true }` registers a table with the row cache, and registration alone serves
+ * nothing: Mode B needs `pg_keyspace.rowcache_decode` for the invalidation worker and
+ * `rowcache_readthrough` to fill on a primary-key miss. Both are written by the image's entrypoint
+ * from these variables, before any server starts, so they cannot be switched at runtime and cannot
+ * be decided by the compose file alone: only a push knows whether any model declares `rows`.
+ *
+ * Without this the stack came up with the row-cache segment reserved, the tables registered, both
+ * switches off and nothing anywhere saying so. Studio's panel was the only thing that reported it,
+ * and it reported it as an operator's missing configuration rather than as a push that had not
+ * finished the job.
+ *
+ * Written to `.env` rather than baked into the compose file for the same reason `SUPATYPE_KONG_PORT`
+ * is: `self-host compose render` runs with no AST in hand, so a value the compose file hardcoded
+ * would be whatever the last render guessed.
+ *
+ * Returns the new state when it changed, and null when it did not. A change needs the database
+ * container recreated, which the caller is the one that can say.
+ */
+export function syncRowCacheEnv(cwd: string, ast: unknown): "on" | "off" | null {
+  const want = declaresRowCache(ast)
+  const value = want ? "1" : "0"
+
+  const current = readEnvValue(cwd, ROWCACHE_DECODE_ENV, "")
+  const currentThrough = readEnvValue(cwd, ROWCACHE_READTHROUGH_ENV, "")
+  if (current === value && currentThrough === value) return null
+
+  upsertEnvFile(cwd, {
+    [ROWCACHE_DECODE_ENV]: value,
+    [ROWCACHE_READTHROUGH_ENV]: value,
+  })
+  return want ? "on" : "off"
+}

package/src/model-hooks.ts

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { join, relative } from "node:path"
 import { generateHooksModule } from "./hooks-generator.js"
+import { manifestCache } from "./model-cache.js"
 
 export interface DeclaredHook {
   model: string
@@ -25,6 +26,8 @@ export function declaredHooks(ast: unknown): DeclaredHook[] {
 
   const out: DeclaredHook[] = []
   for (const model of models) {
+    // Guarded before the optional chains, not by them: see manifestHooks.
+    if (typeof model !== "object" || model === null) continue
     const shaped = model as {
       name?: string
       annotations?: { platform?: { hooks?: Record<string, unknown> } }
@@ -132,6 +135,10 @@ export function manifestHooks(ast: unknown): Record<string, Record<string, Manif
 
   const out: Record<string, Record<string, ManifestHookEntry>> = {}
   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 {
       annotations?: {
         db?: { tableName?: string }
@@ -179,6 +186,8 @@ export function declaredValidators(ast: unknown): DeclaredValidator[] {
 
   const out: DeclaredValidator[] = []
   for (const model of models) {
+    // Guarded before the optional chains, not by them: see manifestHooks.
+    if (typeof model !== "object" || model === null) continue
     const shaped = model as {
       name?: string
       annotations?: { platform?: { validate?: Record<string, unknown> } }
@@ -210,6 +219,10 @@ export function manifestValidators(ast: unknown): Record<string, Record<string,
 
   const out: Record<string, Record<string, ManifestHookEntry>> = {}
   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 {
       annotations?: {
         db?: { tableName?: string }
@@ -281,6 +294,11 @@ export const DEFAULT_HOOK_TIMEOUT_MS = 2000
  * the worse half of that: the schema says the field is checked, and no error appears anywhere,
  * because the write simply succeeds.
  *
+ * `cache` is here for a third reason of the same kind: the declaration is a ceiling the server
+ * enforces, and a manifest carrying a stale one lets a table be cached that the schema has since
+ * stopped permitting — or stops one the schema now allows, which is merely slow rather than wrong.
+ * The first of those is why it is written at push and not left to drift.
+ *
  * **Only updates a manifest that is already there.** Creating one from scratch here would be a
  * hazard: `functions_enabled` is a plain bool on the server's side, so a manifest carrying only
  * hooks would read as functions *disabled*, the exact defect this repo fixed a commit ago, arriving
@@ -302,7 +320,8 @@ export function syncManifestHooks(cwd: string, ast: unknown): boolean {
 
   const changedHooks = applyManifestMap(parsed, "hooks", manifestHooks(ast))
   const changedValidators = applyManifestMap(parsed, "validators", manifestValidators(ast))
-  if (!changedHooks && !changedValidators) return false
+  const changedCache = applyManifestMap(parsed, "cache", manifestCache(ast))
+  if (!changedHooks && !changedValidators && !changedCache) return false
 
   writeFileSync(manifestPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8")
   return true
@@ -315,10 +334,15 @@ export function syncManifestHooks(cwd: string, ast: unknown): boolean {
  * when it decides whether the manifest predates the feature, and an empty object left behind by a
  * schema that no longer declares any is not the same statement.
  */
+/**
+ * `Record<string, unknown>` rather than a hook map: this never looks inside a value, it compares
+ * the serialised form and swaps it. It was typed to hooks only because hooks were the first caller,
+ * and that narrowness is what a third key would otherwise have had to work around.
+ */
 function applyManifestMap(
   manifest: Record<string, unknown>,
   key: string,
-  map: Record<string, Record<string, ManifestHookEntry>>,
+  map: Record<string, unknown>,
 ): boolean {
   const next = JSON.stringify(map)
   if (next === JSON.stringify(manifest[key] ?? {})) return false

package/src/model-versioning.ts

@@ -0,0 +1,167 @@
+/**
+ * Which models keep drafts and version history, read from the extracted schema.
+ *
+ * The answer shapes things decided before any database exists: whether `PGRST_DB_SCHEMA` names the
+ * generated `draft` schema, and whether the push refuses a model that also masks a column. So it is
+ * read from the AST rather than asked of Postgres, the same way
+ * [`field-masking-tier`](./field-masking-tier.ts) decides the masking tier offline.
+ *
+ * Shaped loosely on purpose: the CLI's AST carries `options` as an opaque record, and nothing here
+ * needs more than "is `versions` present, and what did it ask for".
+ */
+
+import { existsSync } from "node:fs"
+import { loadSchemaAst } from "./config.js"
+import type { SupatypeProjectConfig } from "./project-config.js"
+import type { ExtractedSchemaAstV2 } from "./schema-ast-v2.js"
+import { draftVisibilityRoles, previewLimits, schemaPathFromProject } from "./project-config.js"
+
+/** Versions kept per record when the model states no retention. */
+export const DEFAULT_VERSIONS_KEPT = 20
+
+/** What a model's `versions` declaration resolves to. */
+export type VersionsOptions = {
+  /** Editing writes a draft version rather than the live row. */
+  drafts: boolean
+  /** Versions kept per record, oldest pruned beyond it. */
+  keep: number
+}
+
+/** One versioned model, as the callers of this module need it. */
+export type VersionedModel = {
+  /** The model's declared name, for an error message that names what the author wrote. */
+  name: string
+  /** Its table, which is what `<table>_versions` and `draft.<table>` are named after. */
+  tableName: string
+  options: VersionsOptions
+}
+
+type LooseModel = {
+  name?: unknown
+  options?: Record<string, unknown>
+  annotations?: { db?: { tableName?: unknown }; platform?: { access?: Record<string, unknown> } }
+}
+
+/**
+ * Normalise a `versions` value from the AST.
+ *
+ * `true` is shorthand for `{ drafts: true }` with the default retention, and a non-positive or
+ * unparseable `keep` falls back to the default rather than to "keep nothing": pruning to zero would
+ * delete the draft the author is editing.
+ */
+export function resolveVersionsOptions(raw: unknown): VersionsOptions | undefined {
+  if (raw === true) return { drafts: true, keep: DEFAULT_VERSIONS_KEPT }
+  if (typeof raw !== "object" || raw === null) return undefined
+  const record = raw as { drafts?: unknown; keep?: unknown }
+  const keep =
+    typeof record.keep === "number" && Number.isFinite(record.keep) && record.keep >= 1
+      ? Math.floor(record.keep)
+      : DEFAULT_VERSIONS_KEPT
+  return { drafts: record.drafts !== false, keep }
+}
+
+/** Every model in the schema that declares `versions`, in declaration order. */
+export function versionedModels(ast: unknown): VersionedModel[] {
+  const models = (ast as { models?: unknown[] } | null)?.models
+  if (!Array.isArray(models)) return []
+
+  const out: VersionedModel[] = []
+  for (const entry of models) {
+    const model = entry as LooseModel | null
+    if (model === null || typeof model !== "object") continue
+    const options = resolveVersionsOptions(model.options?.["versions"])
+    if (options === undefined) continue
+    const name = typeof model.name === "string" ? model.name : ""
+    const tableName = model.annotations?.db?.tableName
+    out.push({
+      name,
+      tableName: typeof tableName === "string" ? tableName : name,
+      options,
+    })
+  }
+  return out
+}
+
+/** Whether anything in the schema is versioned, which is what exposes the `draft` schema. */
+export function schemaHasVersionedModels(ast: unknown): boolean {
+  return versionedModels(ast).length > 0
+}
+
+/**
+ * Models declaring both `versions` and per-column rules, which cannot both be enforced.
+ *
+ * A version snapshot is opaque `jsonb`. `supatype_mask` is driven by security labels on a specific
+ * table's column and rewrites references to *that* column, and the view tier puts the masking
+ * expression in a view over the real columns: neither can see inside a snapshot. So a masked value
+ * sits in plain sight in the versions table for anyone able to read it, and the push refuses rather
+ * than applying a schema whose restrictions have a hole in them.
+ *
+ * Per model, and that matters: under the view tier the managed schema comes off the exposed list but
+ * the API roles keep their privileges on the base tables, so a `security_invoker` view in an exposed
+ * schema — which is exactly what `draft.<table>` is — reaches past the `api` layer. A project may
+ * hold a masked model and a versioned model at once; one model may not be both.
+ */
+export function modelsWithVersionsAndFieldRules(ast: unknown): string[] {
+  const models = (ast as { models?: unknown[] } | null)?.models
+  if (!Array.isArray(models)) return []
+
+  const out: string[] = []
+  for (const entry of models) {
+    const model = entry as LooseModel | null
+    if (model === null || typeof model !== "object") continue
+    if (resolveVersionsOptions(model.options?.["versions"]) === undefined) continue
+    const fields = model.annotations?.platform?.access?.["fields"]
+    if (typeof fields !== "object" || fields === null || Object.keys(fields).length === 0) continue
+    out.push(typeof model.name === "string" ? model.name : "(unnamed model)")
+  }
+  return out
+}
+
+/**
+ * Whether this project on disk has any versioned model.
+ *
+ * A schema that fails to load reads as "no versioned models", the narrower answer: deciding the
+ * exposed-schema list is the wrong moment to report a syntax error, and `push` and `dev` do it
+ * properly moments later with the file and line. Narrower rather than wider on purpose, since the
+ * failure mode of guessing wrong here is exposing a schema of drafts.
+ */
+export function projectHasVersionedModels(cwd: string, config: SupatypeProjectConfig): boolean {
+  try {
+    const schemaPath = schemaPathFromProject(config, cwd)
+    if (!existsSync(schemaPath)) return false
+    return schemaHasVersionedModels(loadSchemaAst(schemaPath, cwd))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The AST with this project's publishing settings attached, when anything is versioned.
+ *
+ * The engine compiles draft visibility into the generated policies, and it **refuses** a push whose
+ * schema has versioned models and carries no settings rather than applying a default. That refusal
+ * is the reason this is safe to add at a handful of call sites instead of somewhere unmissable: a
+ * path that forgets fails loudly at push time, naming what is missing, rather than quietly
+ * narrowing or widening who can read unpublished content.
+ *
+ * Returns the AST untouched for a project with no versioned model, so nothing else grows a key it
+ * has no use for.
+ */
+export function withPublishing(
+  ast: ExtractedSchemaAstV2,
+  config: SupatypeProjectConfig,
+): ExtractedSchemaAstV2 {
+  if (!schemaHasVersionedModels(ast)) return ast
+
+  const limits = previewLimits(config)
+  return {
+    ...ast,
+    publishing: {
+      draftVisibility: draftVisibilityRoles(config),
+      previewDefaultTtl: limits.defaultTtl,
+      previewMaxRecordTtl: limits.maxRecordTtl,
+      previewMaxProjectTtl: limits.maxProjectTtl,
+      previewAllowProjectScope: limits.allowProjectScope,
+    },
+  }
+}