@supatype/cli 0.2.1 → 0.3.1

package/src/commands/migrate.ts

@@ -1,3 +1,4 @@
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { join } from "node:path"
 import { loadConfig, loadSchemaAst } from "../config.js"
@@ -149,7 +150,7 @@ export function registerMigrate(program: Command): void {
       const cwd = process.cwd()
 
       await ensureEngine()
-      const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+      const ast = withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config)
       const result = await engineRequest<{ message?: string }>("/push", {
         ast,
         database_url: connection,

package/src/commands/push.ts

@@ -1,3 +1,4 @@
+import { withPublishing } from "../model-versioning.js"
 import type { Command } from "commander"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
@@ -8,6 +9,7 @@ import {
   validateModelValidators,
   writeHooksModule,
 } from "../model-hooks.js"
+import { syncRowCacheEnv } from "../model-cache.js"
 import { adapterEntry, readHookUpload } from "../hook-upload.js"
 import { checkServiceRoleRoutes, serviceRoleProblemLines } from "../service-role-check.js"
 import { fatalError } from "../ui/fatal.js"
@@ -19,6 +21,10 @@ import {
 } from "../project-config.js"
 import { ensureEngine, engineRequest, type DiffResult } from "../engine-client.js"
 import { assertEngineSupportsSchema } from "../engine-floor.js"
+import {
+  modelsWithUnresolvablePreview,
+  unresolvablePreviewMessage,
+} from "../preview-config-check.js"
 import { pinnedVersion } from "../binary-cache.js"
 import { printDiffOperations, printDiffWarnings } from "../diff-output.js"
 import { signJwt } from "../jwt.js"
@@ -27,6 +33,7 @@ import type { ExtractedSchemaAstV2 } from "../schema-ast-v2.js"
 import { ensureFirstAdminUser } from "./admin.js"
 import { withAdminRoles } from "../studio-admin-roles.js"
 import { restoreSystemRelationTargets } from "../restore-system-relation-targets.js"
+import { freeTierCacheNote, seedApiConfigCache } from "../api-config-cache.js"
 import type { SupatypeProjectConfig } from "../project-config.js"
 import {
   resolveTarget,
@@ -71,10 +78,11 @@ export function registerPush(program: Command): void {
       const cwd = process.cwd()
       const config = loadConfig(cwd)
       const pgSchema = schemaPgSchema(cwd)
-      const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+      const ast = withPublishing(loadSchemaAst(schemaPathFromProject(config, cwd), cwd), config)
       assertModelHooksResolve(cwd, config, ast)
       assertServiceRoleGrantsResolve(cwd, config)
       assertEngineSupportsSchema(ast, pinnedVersion("engine", config))
+      assertPreviewAddressesResolve(config)
 
       const linked = loadProjectLink(cwd)
       const useDirect = opts.direct || opts.local || Boolean(opts.connection)
@@ -175,6 +183,7 @@ async function pushViaTarget(
     }
     await generateTypesLocal(ast, config)
     await provisionLocalStorage(ast, config)
+    reportCacheSeeding(cwd, ast)
 
     // Local Studio only: a cloud/self-host push must not advertise the local
     // gateway URL from config, which may not even be running.
@@ -186,6 +195,12 @@ async function pushViaTarget(
   }
 
   info(`Pushed to ${target.mode} (${target.environment}).`)
+  // Cloud only. A self-host control plane has tiers too and they mean nothing there, so the same
+  // sentence would be telling a self-hosted project to upgrade something it already has.
+  if (target.mode === "cloud") {
+    const note = freeTierCacheNote((pushResult as { cache?: { tables?: string[]; honoured?: boolean } }).cache)
+    if (note) info(note)
+  }
   const envUrl = target.link?.environments?.[target.environment]?.apiUrl?.replace(/\/$/, "")
   if (envUrl) {
     plain(`\nProject API: ${envUrl}`)
@@ -239,6 +254,33 @@ async function deployHooksToTarget(
   ).then(() => info(`Deployed ${upload.handlers.length} hook(s)`))
 }
 
+/**
+ * Switch on what the schema newly declares, and say what is still in the way.
+ *
+ * Two things have to be true for a local `.cache({ server: true })` to be served: the schema
+ * declares the table, and the runtime allowlist has it on. A push writes the first, so without
+ * this the second is a trip to Studio that nothing in the output asks for — the symptom being a
+ * BYPASS header and a declaration that appears to do nothing.
+ *
+ * Never an error, and never a rewrite of an entry that already exists. See `seedApiConfigCache`.
+ */
+function reportCacheSeeding(cwd: string, ast: unknown): void {
+  const result = seedApiConfigCache(cwd, ast)
+  if (result === null) return
+
+  if (result.seeded.length > 0) {
+    info(`Server cache enabled for ${result.seeded.join(", ")} in .supatype/api-config.json`)
+  }
+  if (result.ttlIsOff) {
+    // A note rather than a fix. Zero is an off switch someone may have chosen, and a push that
+    // turned caching on project-wide would be overriding a decision rather than filling in a blank.
+    info(
+      `${result.declared.length} table(s) declare a cache, but cache_max_ttl is 0 — nothing is ` +
+        `cached until it is set, under API → REST → Settings or in .supatype/api-config.json.`,
+    )
+  }
+}
+
 /** The generated adapter, flattened to the name handlers were rewritten to import. */
 function readGeneratedAdapter(hooksDir: string): { name: string; source: string } | null {
   const file = join(hooksDir, "_supatype", "hooks.ts")
@@ -254,6 +296,16 @@ async function generateTypesLocal(ast: unknown, config: SupatypeProjectConfig):
   if (hooksPath !== null) info(`Hook handler types written to ${hooksPath}`)
   // The server watches this file, so a changed hook takes effect without a restart.
   if (syncManifestHooks(cwd, ast)) info("Hook map written to .supatype/manifest.json")
+  // The row cache is configured at postmaster start, so this is the one cache setting a push
+  // cannot make take effect on its own.
+  const rowCache = syncRowCacheEnv(cwd, ast)
+  if (rowCache !== null) {
+    info(
+      `Row cache switched ${rowCache} in .env. Recreate the database container for it to take ` +
+        "effect: the image writes pg_keyspace.conf at start, so a running Postgres keeps the " +
+        "setting it booted with.",
+    )
+  }
 
   if (!config.output?.types && !config.output?.client) return
   // The CLI writes these, it does not ask the engine to. Passing types_path and client_path and
@@ -295,6 +347,21 @@ async function writeLocalAdminConfig(ast: unknown, config: SupatypeProjectConfig
   writeFileSync(join(dir, "admin-config.json"), `${JSON.stringify(admin, null, 2)}\n`)
 }
 
+/**
+ * Stop the push when a preview address could never open.
+ *
+ * Refused here rather than left to fail later, because later means in front of whoever was sent the
+ * link, not in front of whoever configured it.
+ */
+function assertPreviewAddressesResolve(config: SupatypeProjectConfig): void {
+  const models = modelsWithUnresolvablePreview(config)
+  if (models.length === 0) return
+  fatalError(unresolvablePreviewMessage(models), [
+    'Give an absolute URL: urlPattern: "https://example.com/preview/{slug}"',
+    'Or set app.mode to "static" or "proxy", if this deployment should serve the app.',
+  ])
+}
+
 /**
  * Stop the push when a declared hook names a function that is not there.
  *

package/src/compose-services.ts

@@ -4,7 +4,8 @@
  * `status` and `logs` each used to carry a hardcoded list of container names.
  * Both lists were wrong: they named containers the compose file does not create
  * (`supatype-postgres`, `supatype-kong`), omitted every service it does create
- * (`server`, `storage`, `functions-worker`, `schema-engine`, `valkey`), and used
+ * (`server`, `storage`, `functions-worker`, `schema-engine`, and `valkey` when the
+ * stack runs one), and used
  * a naming scheme the compose file never applies, since it sets no
  * `container_name` and Docker therefore names containers
  * `<project>-<service>-<n>`.

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"
@@ -20,6 +21,8 @@ import {
   type SupatypeProjectConfig,
 } from "./project-config.js"
 import { syncManifestHooks, writeHooksModule } from "./model-hooks.js"
+import { syncRowCacheEnv } from "./model-cache.js"
+import { anonKeyEnvUpdates } from "./commands/keys.js"
 import { signJwt } from "./jwt.js"
 import { ensureDevDbPort, ensureKongPort } from "./dev-ports.js"
 import { handleComposeProjectRename } from "./compose-rename.js"
@@ -34,6 +37,7 @@ import {
   runDockerCompose,
   schemaEngineImageForPush,
   writeSelfHostCompose,
+  selfHostComposePaths,
   type SelfHostComposePaths,
 } from "./self-host-compose.js"
 import type { DockerBrandOptions } from "./docker-runtime.js"
@@ -287,13 +291,13 @@ export function upsertDevComposeEnv(
     ...seedMissingLocalSecrets(cwd),
     // Project configuration, seeded not overwritten, see seedMissingDatabaseIdentity.
     ...seedMissingDatabaseIdentity(cwd),
-    ANON_KEY: anonKey,
-    SERVICE_ROLE_KEY: serviceRoleKey,
-    PUBLIC_SUPATYPE_ANON_KEY: anonKey,
-    VITE_SUPATYPE_ANON_KEY: anonKey,
-    EXPO_PUBLIC_SUPATYPE_ANON_KEY: anonKey,
-    PUBLIC_SUPATYPE_URL: apiUrl,
-    EXPO_PUBLIC_SUPATYPE_URL: apiUrl,
+    // Shared with `supatype keys --write`, so a front end's prefix cannot be written by one and
+    // forgotten by the other. See `anonKeyEnvUpdates`.
+    //
+    // This list used to live here as well, and the two had already drifted: `dev` wrote
+    // PUBLIC_ and EXPO_PUBLIC_ URLs and no VITE_SUPATYPE_URL, so a Vite app whose `.env` had only
+    // ever been touched by `supatype dev` built against an empty string.
+    ...anonKeyEnvUpdates(anonKey, serviceRoleKey, apiUrl),
     SUPATYPE_KONG_PORT: String(kongPort),
     API_EXTERNAL_URL: apiUrl,
     SITE_URL: apiUrl,
@@ -328,13 +332,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"]
+        : []),
+    ],
   })
 }
 
@@ -583,12 +597,42 @@ async function refreshSchemaArtifacts(
   if (syncManifestHooks(cwd, ast)) {
     console.log("[supatype] Hook and validator maps written to .supatype/manifest.json")
   }
+  // Written before the stack comes up, so a first run with a row cache declared starts with it on
+  // rather than needing a second `supatype dev`.
+  const rowCache = syncRowCacheEnv(cwd, ast)
+  if (rowCache !== null) {
+    console.log(`[supatype] Row cache switched ${rowCache} in .env (pg_keyspace Mode B).`)
+  }
 
   try {
     await ensureEngine()
   } catch (err) {
+    // The host engine is a CDN download and this machine could not complete it. The schema is
+    // already applied, so fall back to the engine in compose rather than giving up: without
+    // admin-config.json Studio reports "No schema has been pushed yet" on a stack whose schema is
+    // entirely live, which reads as a failed push rather than a missing binary.
+    const paths = selfHostComposePaths(cwd)
+    const composeProject = composeProjectName(config.project.name)
+    const wrote = await generateViaComposeEngine(
+      paths,
+      cwd,
+      composeProject,
+      config,
+      ast,
+      adminConfigPath,
+    ).catch(() => false)
+    if (wrote) {
+      console.warn(
+        `[supatype] Host engine unavailable (${(err as Error).message}); used the in-compose ` +
+          "engine instead.",
+      )
+      return
+    }
     console.warn(
-      `[supatype] Host engine unavailable, admin/types not refreshed: ${(err as Error).message}`,
+      `[supatype] Host engine unavailable, admin/types not refreshed: ${(err as Error).message}
+` +
+        "[supatype] Studio will report no schema until this succeeds, even though the schema is " +
+        "applied. Retry with the stack up, or run `supatype push`.",
     )
     return
   }
@@ -635,7 +679,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 +912,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 +934,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 +989,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 +1201,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")
@@ -1322,3 +1366,95 @@ function grantAuthSchemaAccess(
     console.warn("[supatype] Could not grant service_role access to auth.users, Studio relation preview may fail.")
   }
 }
+
+/**
+ * Run one read-only generator in the in-compose schema-engine and return its stdout.
+ *
+ * The same image and the same bind mount the push just used, so if the schema could be applied
+ * this can run. It exists because the host engine is a separate binary fetched from a CDN, and a
+ * machine that cannot fetch it is not a machine that cannot generate: the schema is already
+ * applied, the AST is already on disk, and the container that did it is one `docker compose run`
+ * away.
+ */
+async function runComposeEngineGenerator(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  config: SupatypeProjectConfig,
+  args: readonly string[],
+): Promise<string | null> {
+  const envFile = resolve(cwd, ".env")
+  const composeArgs = ["compose", "--progress", "quiet"]
+  if (composeProject) composeArgs.push("-p", composeProject)
+  composeArgs.push("--project-directory", cwd)
+  composeArgs.push("-f", paths.composePath)
+  if (existsSync(envFile)) composeArgs.push("--env-file", envFile)
+  composeArgs.push(
+    "--profile",
+    "tools",
+    "run",
+    "--rm",
+    "-T",
+    "schema-engine",
+    ...args,
+    "-i",
+    "/project/.supatype/schema.ast.json",
+  )
+
+  const env: NodeJS.ProcessEnv = { ...process.env, COMPOSE_PROGRESS: "quiet" }
+  const engineImage = await schemaEngineImageForPush(config)
+  if (engineImage) env.SUPATYPE_ENGINE_IMAGE = engineImage
+
+  const result = spawnSync("docker", composeArgs, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+    env,
+  })
+  if ((result.status ?? 1) !== 0) return null
+  return String(result.stdout ?? "")
+}
+
+/**
+ * Write `admin-config.json` and the generated types using the in-compose engine.
+ *
+ * The fallback for a host engine that could not be fetched. Without it, a `supatype dev` that
+ * applied the schema perfectly well still left no `admin-config.json`, and Studio reads that file
+ * to decide whether a schema exists: the stack came up, every table was live, the API served them,
+ * and Studio said **"No schema has been pushed yet."** The warning that preceded it named the
+ * download, not the consequence, so nothing connected the two.
+ *
+ * Returns true when the admin config was written, which is the file Studio actually needs.
+ */
+export async function generateViaComposeEngine(
+  paths: SelfHostComposePaths,
+  cwd: string,
+  composeProject: string,
+  config: SupatypeProjectConfig,
+  ast: unknown,
+  adminConfigPath: string,
+): Promise<boolean> {
+  const typesPath = config.output?.types
+  if (typeof typesPath === "string" && typesPath.trim().length > 0) {
+    const out = await runComposeEngineGenerator(paths, cwd, composeProject, config, ["generate"])
+    const marker = out?.indexOf("// Generated by supatype-engine") ?? -1
+    if (out && out.includes("export type")) {
+      const ts = (marker >= 0 ? out.slice(marker) : out).trimStart()
+      const hostPath = join(cwd, typesPath)
+      mkdirSync(dirname(hostPath), { recursive: true })
+      writeFileSync(hostPath, ts)
+      console.log(`[supatype] Types written to ${typesPath} (in-compose engine).`)
+    }
+  }
+
+  const adminOut = await runComposeEngineGenerator(paths, cwd, composeProject, config, ["admin"])
+  if (!adminOut) return false
+  const parsed = parseEngineJsonOutput<unknown>(adminOut)
+  if (parsed === null) return false
+
+  const admin = withAdminRoles(parsed, config)
+  restoreSystemRelationTargets(admin, ast)
+  writeFileSync(adminConfigPath, `${JSON.stringify(admin, null, 2)}\n`)
+  console.log("[supatype] Admin config written to .supatype/admin-config.json (in-compose engine).")
+  return true
+}

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(