@palbase/backend 33.0.2 → 34.1.0

package/dist/bin/palbase-backend.js

@@ -3,17 +3,19 @@ import {
   BootRefused,
   createApp,
   loadConfig
-} from "../chunk-C6COAB3E.js";
-import "../chunk-WWUG2QXF.js";
-import "../chunk-TVCCR6SO.js";
-import "../chunk-XOX6RFPZ.js";
-import "../chunk-SI4KGEM3.js";
+} from "../chunk-XZPDPYVY.js";
+import "../chunk-X2UYIXDS.js";
+import "../chunk-GHNC2UHS.js";
+import "../chunk-YO5GYM73.js";
+import "../chunk-PRH45NZU.js";
+import "../chunk-P7MGSAFT.js";
 import {
   getRegisteredControllers
-} from "../chunk-AAT5G7KY.js";
+} from "../chunk-JJW3L62T.js";
+import "../chunk-UMESJJRS.js";
 import {
   __name
-} from "../chunk-KATPXCJ5.js";
+} from "../chunk-VXPNPVAG.js";
 
 // src/bin/palbase-backend.ts
 import { readdir } from "fs/promises";

package/dist/bin/palbase-backend.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/bin/palbase-backend.ts"],"sourcesContent":["#!/usr/bin/env bun\n/**\n * palbase-backend — run this project's backend.\n *\n *   npm run dev        →  palbase-backend dev     (reloads on change)\n *   npm start          →  palbase-backend serve\n *\n * There is no scaffolding step and no server file to write. The project IS the\n * backend: every `controllers/*.controller.ts` is imported, which is what\n * registers it, and the engine is built around whatever registered.\n *\n * It is the same engine the deployed runtime builds — not a development\n * stand-in. A dev server that is a different program from the production one is\n * a source of \"works locally\" reports, and this one has no second implementation\n * to disagree with.\n */\nimport { readdir } from \"node:fs/promises\";\nimport { join, resolve } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\n\nimport { createApp, loadConfig, BootRefused } from \"../engine/index.js\";\nimport { getRegisteredControllers } from \"../decorators/controller.js\";\n\nconst USAGE = `palbase-backend — run this project's backend\n\n  palbase-backend serve      start the backend\n  palbase-backend dev        start it and reload on change\n  palbase-backend routes     print the route table and exit\n\nConfiguration comes from the environment (a .env beside package.json is read):\n\n  DATABASE_URL               required — the stack's Postgres\n  AUTH_JWKS_URL              required — where your stack publishes its signing keys\n  MODULE_BASE_URL            where Documents/Storage/Notifications/Flags/Realtime live\n  PALBASE_ANON_KEY           publishable key, sent on module calls\n  PALBASE_SERVICE_ROLE_KEY   secret key, for privileged module calls\n  PORT                       default 3000\n`;\n\nfunction die(message: string): never {\n  console.error(message);\n  process.exit(1);\n}\n\n/** Read a `.env` beside the project, without adding a dependency for it. */\nasync function loadDotEnv(root: string): Promise<void> {\n  const file = Bun.file(join(root, \".env\"));\n  if (!(await file.exists())) return;\n  for (const raw of (await file.text()).split(\"\\n\")) {\n    const line = raw.trim();\n    if (!line || line.startsWith(\"#\")) continue;\n    const eq = line.indexOf(\"=\");\n    if (eq < 1) continue;\n    const key = line.slice(0, eq).trim();\n    // The environment wins: an exported value is the operator being explicit,\n    // and a file quietly overriding it is how a \"why is it still pointing at\n    // the old database\" hour begins.\n    if (process.env[key] !== undefined) continue;\n    let value = line.slice(eq + 1).trim();\n    if (\n      (value.startsWith('\"') && value.endsWith('\"')) ||\n      (value.startsWith(\"'\") && value.endsWith(\"'\"))\n    ) {\n      value = value.slice(1, -1);\n    }\n    process.env[key] = value;\n  }\n}\n\n/** Every `*.controller.ts` under `controllers/`, sorted, recursively. */\n/** Directories that are never a project's source. */\nconst NEVER_WALK = new Set([\"node_modules\", \"dist\", \"build\", \".git\"]);\n\n/**\n * The project's MODULE files — the same one glob the bundlers use.\n *\n * Importing a module imports the classes it owns, so this reaches every\n * controller, service, job, hook, webhook and room the project declares, and\n * nothing it does not. It used to walk `controllers/` for `*.controller.ts`,\n * which made the directory a declaration and left `dev` seeing a different set\n * of classes than a deploy would.\n *\n * Recursive: a module lives beside the domain it owns, not in a folder this\n * file names.\n */\nasync function findModules(root: string): Promise<string[]> {\n  const out: string[] = [];\n  const walk = async (d: string): Promise<void> => {\n    let entries;\n    try {\n      entries = await readdir(d, { withFileTypes: true });\n    } catch {\n      return;\n    }\n    for (const entry of entries) {\n      if (NEVER_WALK.has(entry.name) || entry.name.startsWith(\".palbase\")) continue;\n      const full = join(d, entry.name);\n      if (entry.isDirectory()) await walk(full);\n      else if (/\\.module\\.(ts|js|mts|mjs)$/.test(entry.name)) out.push(full);\n    }\n  };\n  await walk(root);\n  // Sorted so declaration order is the same on every machine.\n  return out.sort();\n}\n\nasync function importSchemas(root: string): Promise<unknown[]> {\n  // ONE SCHEMA PER FILE, so the whole directory is the declaration. Reading a\n  // single well-known file would take the first one and leave the rest of the\n  // project's tables with no typed surface and no complaint.\n  //\n  // SORTED, because readdir order is not specified: an unsorted set would hand\n  // the runtime a different answer from one boot to the next.\n  let entries: string[];\n  try {\n    entries = (await readdir(join(root, \"db\"))).sort();\n  } catch {\n    // Not every project declares a database; the typed `.tables` surface is\n    // simply absent then.\n    return [];\n  }\n  const out: unknown[] = [];\n  for (const entry of entries) {\n    if (!entry.endsWith(\".ts\") && !entry.endsWith(\".js\")) continue;\n    if (entry.endsWith(\".d.ts\")) continue;\n    out.push((await import(pathToFileURL(join(root, \"db\", entry)).href)).default);\n  }\n  return out;\n}\n\nasync function main(): Promise<void> {\n  const command = process.argv[2] ?? \"serve\";\n  if (command === \"--help\" || command === \"-h\" || command === \"help\") {\n    console.log(USAGE);\n    return;\n  }\n  if (![\"serve\", \"dev\", \"routes\"].includes(command)) {\n    die(`palbase-backend: unknown command \"${command}\".\\n\\n${USAGE}`);\n  }\n  if (typeof Bun === \"undefined\") {\n    die(\n      \"palbase-backend needs Bun: the engine serves `fetch` natively and opens its own\\n\" +\n        \"Postgres pool through Bun.sql. Install it from https://bun.sh, then re-run.\",\n    );\n  }\n\n  // `dev` is `serve` under Bun's watcher. Re-exec rather than reimplement:\n  // one code path serves, and the reload is the runtime's job, not ours.\n  if (command === \"dev\" && !process.env.PALBASE_WATCHING) {\n    const self = Bun.fileURLToPath(import.meta.url);\n    const child = Bun.spawn([\"bun\", \"--watch\", self, \"serve\"], {\n      stdio: [\"inherit\", \"inherit\", \"inherit\"],\n      env: { ...process.env, PALBASE_WATCHING: \"1\" },\n    });\n    process.exit(await child.exited);\n  }\n\n  const root = resolve(process.env.PALBASE_PROJECT_DIR ?? process.cwd());\n  await loadDotEnv(root);\n\n  const files = await findModules(root);\n  if (files.length === 0) {\n    die(\n      `palbase-backend: no *.module.ts under ${root}.\\n` +\n        `A module is what says which classes exist, who owns them and what they may\\n` +\n        `reach — and it is the only place that says it. Add one and run again:\\n\\n` +\n        `  // todos.module.ts\\n` +\n        `  import { Module, type Token } from \"@palbase/backend\";\\n` +\n        `  import { TodosController } from \"./controllers/todos.controller.ts\";\\n` +\n        `  @Module({ controllers: [TodosController as Token] })\\n` +\n        `  export class TodosModule {}\\n`,\n    );\n  }\n\n  // Importing IS the registration — for the module AND for everything it owns,\n  // because a module imports the classes it lists.\n  for (const file of files) await import(pathToFileURL(file).href);\n  const controllers = getRegisteredControllers();\n  if (controllers.length === 0) {\n    die(\n      `palbase-backend: ${files.length} module file(s) loaded but no controller registered.\\n` +\n        `Either none of the listed classes carries @Controller, or the files were\\n` +\n        `compiled with decorators stripped. Nothing would answer, so this is fatal.`,\n    );\n  }\n\n  let config;\n  try {\n    config = loadConfig(process.env as Record<string, string | undefined>);\n  } catch (e) {\n    if (e instanceof BootRefused) {\n      die(\n        `${e.message}\\n\\n` +\n          `Put them in a .env beside package.json, or export them. A local stack\\n` +\n          `(docker compose up) publishes both.`,\n      );\n    }\n    throw e;\n  }\n\n  const app = await createApp({ config, controllers, schemas: await importSchemas(root) });\n\n  if (command === \"routes\") {\n    for (const route of app.routes) console.log(route.id);\n    await app.shutdown();\n    return;\n  }\n\n  Bun.serve({ port: config.port, idleTimeout: 60, fetch: app.handle });\n  console.log(`palbase-backend listening on http://localhost:${config.port}`);\n  console.log(`  ${app.routes.length} endpoint(s) from ${files.length} module file(s)`);\n  for (const route of app.routes) console.log(`  ${route.id}`);\n\n  for (const signal of [\"SIGTERM\", \"SIGINT\"] as const) {\n    process.on(signal, () => {\n      void app.shutdown().finally(() => process.exit(0));\n    });\n  }\n}\n\n// Not a top-level await: this file is also emitted in a CommonJS flavour, where\n// one is a build error. The rejection handler is the point either way — an\n// unhandled one exits 0 on some runtimes, which would report a dead backend as\n// a successful start.\nmain().catch((e: unknown) => {\n  console.error(e instanceof Error ? e.message : e);\n  process.exit(1);\n});\n"],"mappings":"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","names":["readdir","join","resolve","pathToFileURL","USAGE","die","message","console","error","process","exit","loadDotEnv","root","file","Bun","join","exists","raw","text","split","line","trim","startsWith","eq","indexOf","key","slice","env","undefined","value","endsWith","NEVER_WALK","Set","findModules","out","walk","d","entries","readdir","withFileTypes","entry","has","name","full","isDirectory","test","push","sort","importSchemas","pathToFileURL","href","default","main","command","argv","log","includes","PALBASE_WATCHING","self","fileURLToPath","url","child","spawn","stdio","exited","resolve","PALBASE_PROJECT_DIR","cwd","files","length","controllers","getRegisteredControllers","config","loadConfig","e","BootRefused","app","createApp","schemas","route","routes","id","shutdown","serve","port","idleTimeout","fetch","handle","signal","on","finally","catch","Error"]}
+{"version":3,"sources":["../../src/bin/palbase-backend.ts"],"sourcesContent":["#!/usr/bin/env bun\n/**\n * palbase-backend — run this project's backend.\n *\n *   npm run dev        →  palbase-backend dev     (reloads on change)\n *   npm start          →  palbase-backend serve\n *\n * There is no scaffolding step and no server file to write. The project IS the\n * backend: every `controllers/*.controller.ts` is imported, which is what\n * registers it, and the engine is built around whatever registered.\n *\n * It is the same engine the deployed runtime builds — not a development\n * stand-in. A dev server that is a different program from the production one is\n * a source of \"works locally\" reports, and this one has no second implementation\n * to disagree with.\n */\nimport { readdir } from \"node:fs/promises\";\nimport { join, resolve } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\n\nimport { createApp, loadConfig, BootRefused } from \"../engine/index.js\";\nimport { getRegisteredControllers } from \"../decorators/controller.js\";\n\nconst USAGE = `palbase-backend — run this project's backend\n\n  palbase-backend serve      start the backend\n  palbase-backend dev        start it and reload on change\n  palbase-backend routes     print the route table and exit\n\nConfiguration comes from the environment (a .env beside package.json is read):\n\n  DATABASE_URL               required — the stack's Postgres\n  AUTH_JWKS_URL              required — where your stack publishes its signing keys\n  MODULE_BASE_URL            where Documents/Storage/Notifications/Flags/Realtime live\n  PALBASE_ANON_KEY           publishable key, sent on module calls\n  PALBASE_SERVICE_ROLE_KEY   secret key, for privileged module calls\n  PORT                       default 3000\n`;\n\nfunction die(message: string): never {\n  console.error(message);\n  process.exit(1);\n}\n\n/** Read a `.env` beside the project, without adding a dependency for it. */\nasync function loadDotEnv(root: string): Promise<void> {\n  const file = Bun.file(join(root, \".env\"));\n  if (!(await file.exists())) return;\n  for (const raw of (await file.text()).split(\"\\n\")) {\n    const line = raw.trim();\n    if (!line || line.startsWith(\"#\")) continue;\n    const eq = line.indexOf(\"=\");\n    if (eq < 1) continue;\n    const key = line.slice(0, eq).trim();\n    // The environment wins: an exported value is the operator being explicit,\n    // and a file quietly overriding it is how a \"why is it still pointing at\n    // the old database\" hour begins.\n    if (process.env[key] !== undefined) continue;\n    let value = line.slice(eq + 1).trim();\n    if (\n      (value.startsWith('\"') && value.endsWith('\"')) ||\n      (value.startsWith(\"'\") && value.endsWith(\"'\"))\n    ) {\n      value = value.slice(1, -1);\n    }\n    process.env[key] = value;\n  }\n}\n\n/** Every `*.controller.ts` under `controllers/`, sorted, recursively. */\n/** Directories that are never a project's source. */\nconst NEVER_WALK = new Set([\"node_modules\", \"dist\", \"build\", \".git\"]);\n\n/**\n * The project's MODULE files — the same one glob the bundlers use.\n *\n * Importing a module imports the classes it owns, so this reaches every\n * controller, service, job, hook, webhook and room the project declares, and\n * nothing it does not. It used to walk `controllers/` for `*.controller.ts`,\n * which made the directory a declaration and left `dev` seeing a different set\n * of classes than a deploy would.\n *\n * Recursive: a module lives beside the domain it owns, not in a folder this\n * file names.\n */\nasync function findModules(root: string): Promise<string[]> {\n  const out: string[] = [];\n  const walk = async (d: string): Promise<void> => {\n    let entries;\n    try {\n      entries = await readdir(d, { withFileTypes: true });\n    } catch {\n      return;\n    }\n    for (const entry of entries) {\n      if (NEVER_WALK.has(entry.name) || entry.name.startsWith(\".palbase\")) continue;\n      const full = join(d, entry.name);\n      if (entry.isDirectory()) await walk(full);\n      else if (/\\.module\\.(ts|js|mts|mjs)$/.test(entry.name)) out.push(full);\n    }\n  };\n  await walk(root);\n  // Sorted so declaration order is the same on every machine.\n  return out.sort();\n}\n\nasync function importSchemas(root: string): Promise<unknown[]> {\n  // ONE SCHEMA PER FILE, so the whole directory is the declaration. Reading a\n  // single well-known file would take the first one and leave the rest of the\n  // project's tables with no typed surface and no complaint.\n  //\n  // SORTED, because readdir order is not specified: an unsorted set would hand\n  // the runtime a different answer from one boot to the next.\n  let entries: string[];\n  try {\n    entries = (await readdir(join(root, \"db\"))).sort();\n  } catch {\n    // Not every project declares a database; the typed `.tables` surface is\n    // simply absent then.\n    return [];\n  }\n  const out: unknown[] = [];\n  for (const entry of entries) {\n    if (!entry.endsWith(\".ts\") && !entry.endsWith(\".js\")) continue;\n    if (entry.endsWith(\".d.ts\")) continue;\n    out.push((await import(pathToFileURL(join(root, \"db\", entry)).href)).default);\n  }\n  return out;\n}\n\nasync function main(): Promise<void> {\n  const command = process.argv[2] ?? \"serve\";\n  if (command === \"--help\" || command === \"-h\" || command === \"help\") {\n    console.log(USAGE);\n    return;\n  }\n  if (![\"serve\", \"dev\", \"routes\"].includes(command)) {\n    die(`palbase-backend: unknown command \"${command}\".\\n\\n${USAGE}`);\n  }\n  if (typeof Bun === \"undefined\") {\n    die(\n      \"palbase-backend needs Bun: the engine serves `fetch` natively and opens its own\\n\" +\n        \"Postgres pool through Bun.sql. Install it from https://bun.sh, then re-run.\",\n    );\n  }\n\n  // `dev` is `serve` under Bun's watcher. Re-exec rather than reimplement:\n  // one code path serves, and the reload is the runtime's job, not ours.\n  if (command === \"dev\" && !process.env.PALBASE_WATCHING) {\n    const self = Bun.fileURLToPath(import.meta.url);\n    const child = Bun.spawn([\"bun\", \"--watch\", self, \"serve\"], {\n      stdio: [\"inherit\", \"inherit\", \"inherit\"],\n      env: { ...process.env, PALBASE_WATCHING: \"1\" },\n    });\n    process.exit(await child.exited);\n  }\n\n  const root = resolve(process.env.PALBASE_PROJECT_DIR ?? process.cwd());\n  await loadDotEnv(root);\n\n  const files = await findModules(root);\n  if (files.length === 0) {\n    die(\n      `palbase-backend: no *.module.ts under ${root}.\\n` +\n        `A module is what says which classes exist, who owns them and what they may\\n` +\n        `reach — and it is the only place that says it. Add one and run again:\\n\\n` +\n        `  // todos.module.ts\\n` +\n        `  import { Module, type Token } from \"@palbase/backend\";\\n` +\n        `  import { TodosController } from \"./controllers/todos.controller.ts\";\\n` +\n        `  @Module({ controllers: [TodosController as Token] })\\n` +\n        `  export class TodosModule {}\\n`,\n    );\n  }\n\n  // Importing IS the registration — for the module AND for everything it owns,\n  // because a module imports the classes it lists.\n  for (const file of files) await import(pathToFileURL(file).href);\n  const controllers = getRegisteredControllers();\n  if (controllers.length === 0) {\n    die(\n      `palbase-backend: ${files.length} module file(s) loaded but no controller registered.\\n` +\n        `Either none of the listed classes carries @Controller, or the files were\\n` +\n        `compiled with decorators stripped. Nothing would answer, so this is fatal.`,\n    );\n  }\n\n  let config;\n  try {\n    config = loadConfig(process.env as Record<string, string | undefined>);\n  } catch (e) {\n    if (e instanceof BootRefused) {\n      die(\n        `${e.message}\\n\\n` +\n          `Put them in a .env beside package.json, or export them. A local stack\\n` +\n          `(docker compose up) publishes both.`,\n      );\n    }\n    throw e;\n  }\n\n  const app = await createApp({ config, controllers, schemas: await importSchemas(root) });\n\n  if (command === \"routes\") {\n    for (const route of app.routes) console.log(route.id);\n    await app.shutdown();\n    return;\n  }\n\n  Bun.serve({ port: config.port, idleTimeout: 60, fetch: app.handle });\n  console.log(`palbase-backend listening on http://localhost:${config.port}`);\n  console.log(`  ${app.routes.length} endpoint(s) from ${files.length} module file(s)`);\n  for (const route of app.routes) console.log(`  ${route.id}`);\n\n  for (const signal of [\"SIGTERM\", \"SIGINT\"] as const) {\n    process.on(signal, () => {\n      void app.shutdown().finally(() => process.exit(0));\n    });\n  }\n}\n\n// Not a top-level await: this file is also emitted in a CommonJS flavour, where\n// one is a build error. The rejection handler is the point either way — an\n// unhandled one exits 0 on some runtimes, which would report a dead backend as\n// a successful start.\nmain().catch((e: unknown) => {\n  console.error(e instanceof Error ? e.message : e);\n  process.exit(1);\n});\n"],"mappings":"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","names":["readdir","join","resolve","pathToFileURL","USAGE","die","message","console","error","process","exit","loadDotEnv","root","file","Bun","join","exists","raw","text","split","line","trim","startsWith","eq","indexOf","key","slice","env","undefined","value","endsWith","NEVER_WALK","Set","findModules","out","walk","d","entries","readdir","withFileTypes","entry","has","name","full","isDirectory","test","push","sort","importSchemas","pathToFileURL","href","default","main","command","argv","log","includes","PALBASE_WATCHING","self","fileURLToPath","url","child","spawn","stdio","exited","resolve","PALBASE_PROJECT_DIR","cwd","files","length","controllers","getRegisteredControllers","config","loadConfig","e","BootRefused","app","createApp","schemas","route","routes","id","shutdown","serve","port","idleTimeout","fetch","handle","signal","on","finally","catch","Error"]}

package/dist/{chunk-YIQ4RS4F.js → chunk-5UGPXKMJ.js}

@@ -1,9 +1,23 @@
 import {
-  qualifiedTableKey
-} from "./chunk-SI4KGEM3.js";
+  queryColumnContract,
+  stableContract
+} from "./chunk-PRH45NZU.js";
+import {
+  TxPlanBuilder,
+  brandRef,
+  qualifiedTableKey,
+  retryBudget,
+  runTxPlan
+} from "./chunk-P7MGSAFT.js";
+import {
+  isRetryable
+} from "./chunk-UMESJJRS.js";
 import {
   __name
-} from "./chunk-KATPXCJ5.js";
+} from "./chunk-VXPNPVAG.js";
+
+// src/db/policy.ts
+import { z } from "zod";
 
 // src/db/schema.ts
 var IndexBuilder = class {
@@ -81,6 +95,10 @@ function defineTable(name, input) {
   if (name.trim() === "") {
     throw new Error("defineTable(name, \u2026): name must not be empty");
   }
+  {
+    const reserved = reservedCanRelation(name, input.columns);
+    if (reserved !== null) throw new Error(`defineTable(${JSON.stringify(name)}): ${reserved}`);
+  }
   const policies = (input.policies?.(exprCtx(Object.keys(input.columns), 0, name)) ?? []).map(toPolicyDef);
   const rls = policies.length > 0 || input.rls !== false;
   const owned = {};
@@ -109,6 +127,7 @@ function defineTable(name, input) {
   const declaredIndexes = (input.indexes?.(exprCtx(Object.keys(input.columns), 0, name)) ?? []).map((i) => i instanceof IndexBuilder ? i._def : i);
   if (declaredIndexes.length > 0) def.indexes = declaredIndexes;
   if (input.appendOnly === true) def.appendOnly = true;
+  if (input.ignored === true) def.ignored = true;
   if (input.search !== void 0) {
     const s = input.search;
     if (s.from !== void 0) {
@@ -168,6 +187,13 @@ function defineTable(name, input) {
 }
 __name(defineTable, "defineTable");
 var declaringSchemaOf = /* @__PURE__ */ new WeakMap();
+function declaredTableKey(table) {
+  const metadata = table[TABLE_META];
+  const schema = declaringSchemaOf.get(metadata);
+  if (schema === void 0) throw new Error(`defineQuery: table ${metadata.name} must belong to defineSchema before defining its query`);
+  return qualifiedTableKey(schema, metadata.name);
+}
+__name(declaredTableKey, "declaredTableKey");
 function resolveReferences(tables, schemaName) {
   for (const table of Object.values(tables)) {
     for (const [colName, builder] of Object.entries(table.columns)) {
@@ -491,6 +517,45 @@ function policy(name) {
   return new PolicyBuilder(name);
 }
 __name(policy, "policy");
+function can(table) {
+  const def = table;
+  if (typeof def.name !== "string" || def.columns === null || typeof def.columns !== "object" || !Array.isArray(def.policies)) {
+    throw new Error("can(<table>): expects the schema's table definition \u2014 can(publicSchema.tables.notes) \u2014 not the defineTable handle (`notes`)");
+  }
+  if (Object.prototype.hasOwnProperty.call(table.columns, "can")) {
+    throw new Error(`can(${table.name}): the table declares a column named "can", so the row carries that column and no policy echo \u2014 rename the column to get can`);
+  }
+  const rel = reservedCanRelation(table.name, table.columns);
+  if (rel !== null) {
+    throw new Error(`can(${table.name}): ${rel}`);
+  }
+  const names = table.policies.filter((p) => p.command === "update" && p.permissive !== false && Buffer.byteLength(`can:${p.name}`, "utf8") <= 63).map((p) => p.name);
+  if (names.length === 0) {
+    const all = table.policies.filter((p) => p.command === "all").map((p) => p.name);
+    const hint = all.length > 0 ? ` The table's ${all.map((n) => `"${n}"`).join(", ")} ${all.length === 1 ? "policy is" : "policies are"} for("all") \u2014 for("all") governs UPDATE but is not a named update policy and never appears in can.` : "";
+    throw new Error(`can(${table.name}): the table declares no update policy \u2014 there is nothing a row could echo. Name one with policy("<name>").for("update").using(\u2026) first.${hint}`);
+  }
+  return z.array(z.enum(names));
+}
+__name(can, "can");
+function reservedCanRelation(tableName, columns) {
+  if (tableName === "can") {
+    return `a table named "can" would put a relation named "can" on every parent it references \u2014 rename the table`;
+  }
+  for (const [col2, b] of Object.entries(columns)) {
+    const def = b._def;
+    if (def.referencesThunk === void 0 && def.selfRefColumn === void 0) continue;
+    if (def.reverseAs === "can") {
+      return `column "${col2}" names its reverse relation "can" \u2014 the parent's rows would carry a relation where can is reserved; pick another reverseAs`;
+    }
+    const forward = def.owns === true ? "owner" : def.refAs ?? (col2.endsWith("_id") ? col2.slice(0, -3) : col2);
+    if (forward === "can") {
+      return `column "${col2}" would be read as a relation named "can" (${def.refAs === void 0 ? "derived from the column name" : "its as: option"}) \u2014 can is reserved for the policy echo; rename it`;
+    }
+  }
+  return null;
+}
+__name(reservedCanRelation, "reservedCanRelation");
 
 // src/db/extensions.ts
 var PALBASE_EXTENSIONS = [
@@ -559,11 +624,265 @@ var openai = {
   }
 };
 
+// src/db/typed-db.ts
+function makeTypedTable(name, raw2) {
+  return {
+    insert: /* @__PURE__ */ __name((data) => raw2.insert(name, data), "insert"),
+    aggregate: /* @__PURE__ */ __name((q) => raw2.aggregate(name, q), "aggregate"),
+    insertMany: /* @__PURE__ */ __name((rows, opts) => raw2.insertMany(name, rows, opts), "insertMany"),
+    put: /* @__PURE__ */ __name((q) => raw2.put(name, q.data, {
+      onConflict: q.onConflict
+    }), "put"),
+    update: /* @__PURE__ */ __name((q) => raw2.update(name, q.where.id, q.set), "update"),
+    delete: /* @__PURE__ */ __name((id) => raw2.delete(name, id), "delete"),
+    findUnique: /* @__PURE__ */ __name((q) => raw2.findUnique(name, q.where, {
+      select: q.select
+    }), "findUnique"),
+    findById: /* @__PURE__ */ __name((id) => raw2.findById(name, id), "findById"),
+    page: /* @__PURE__ */ __name((q) => {
+      const { where, ...opts } = q ?? {};
+      return raw2.page(name, where, opts);
+    }, "page"),
+    findMany: /* @__PURE__ */ __name((q) => {
+      const { where, ...opts } = q ?? {};
+      return raw2.findMany(name, where, opts);
+    }, "findMany"),
+    updateMany: /* @__PURE__ */ __name((q) => raw2.updateMany(name, q.where, q.set, q.returning === void 0 ? void 0 : {
+      returning: q.returning
+    }), "updateMany"),
+    deleteMany: /* @__PURE__ */ __name((q) => raw2.deleteMany(name, q.where), "deleteMany"),
+    count: /* @__PURE__ */ __name((q) => raw2.count(name, q?.where), "count")
+  };
+}
+__name(makeTypedTable, "makeTypedTable");
+function makeTypedDB(schema, raw2) {
+  const tables = {};
+  for (const key of Object.keys(schema.tables)) {
+    const tableDef = schema.tables[key];
+    if (tableDef !== void 0) {
+      tables[key] = makeTypedTable(qualifiedTableKey(schema.name, tableDef.name), raw2);
+    }
+  }
+  const result = {
+    tables,
+    diagnostics: /* @__PURE__ */ __name(() => raw2.diagnostics(), "diagnostics"),
+    readQuery: /* @__PURE__ */ __name((query) => raw2.readQuery(query), "readQuery"),
+    compileQuery: /* @__PURE__ */ __name((query) => raw2.compileQuery(query), "compileQuery"),
+    explainQuery: /* @__PURE__ */ __name((query) => raw2.explainQuery(query), "explainQuery"),
+    command(fn, options) {
+      const builder = new TxPlanBuilder();
+      const planTables = Object.fromEntries(Object.entries(schema.tables).map(([key, table]) => [
+        key,
+        builder.table(qualifiedTableKey(schema.name, table.name))
+      ]));
+      return runTxPlan({
+        txPlan: /* @__PURE__ */ __name((plan) => raw2.command(plan, options), "txPlan")
+      }, {
+        tables: planTables
+      }, builder, fn);
+    },
+    transaction(fn) {
+      const builder = new TxPlanBuilder();
+      const planTables = {};
+      for (const key of Object.keys(schema.tables)) {
+        const tableDef = schema.tables[key];
+        if (tableDef !== void 0) planTables[key] = builder.table(qualifiedTableKey(schema.name, tableDef.name));
+      }
+      return runTxPlan(raw2, {
+        tables: planTables
+      }, builder, fn);
+    }
+  };
+  return result;
+}
+__name(makeTypedDB, "makeTypedDB");
+function col(name) {
+  return brandRef({
+    $col: name
+  }, "col");
+}
+__name(col, "col");
+async function withRetry(fn, opts = {}) {
+  const budget = retryBudget(opts.retry);
+  let attempt = 0;
+  for (; ; ) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (attempt >= budget || !isRetryable(e)) throw e;
+      attempt += 1;
+    }
+  }
+}
+__name(withRetry, "withRetry");
+function sqlFragment(strings, ...values) {
+  return brandRef({
+    $sql: {
+      text: [
+        ...strings
+      ],
+      values
+    }
+  }, "sql");
+}
+__name(sqlFragment, "sqlFragment");
+
+// src/db/query.ts
+import { z as z2 } from "zod";
+import { OpenAPIRegistry, OpenApiGeneratorV31, extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+extendZodWithOpenApi(z2);
+function responseColumn(column, validator) {
+  const contract = queryColumnContract(column);
+  let schema;
+  if (validator) return validator;
+  if (contract.codec === "number") schema = z2.number().finite();
+  else if (contract.codec === "decimal") schema = z2.string();
+  else switch (contract.type) {
+    case "integer":
+      schema = z2.number().int().min(-2147483648).max(2147483647);
+      break;
+    case "boolean":
+      schema = z2.boolean();
+      break;
+    case "vector":
+      schema = z2.array(z2.number().finite());
+      break;
+    case "enum": {
+      const values = contract.enumValues;
+      if (!values?.length) throw new Error("Query response requires declared enum values");
+      schema = z2.enum(values);
+      break;
+    }
+    case "uuid":
+    case "text":
+    case "timestamp":
+    case "numeric":
+    case "bigint":
+      schema = z2.string();
+      break;
+    case "jsonb":
+      throw new Error("Query response requires a fields validator for a selected jsonb column: its TypeScript payload is erased at runtime");
+    default:
+      throw new Error(`Query response does not support column type ${contract.type}`);
+  }
+  return contract.nullable ? schema.nullable() : schema;
+}
+__name(responseColumn, "responseColumn");
+function defineQuery(name, options) {
+  if (typeof name !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,127}$/.test(name)) throw new Error("defineQuery requires a stable name of 1\u2013128 letters, digits or underscores");
+  const table = declaredTableKey(options.table);
+  const select = [
+    ...options.select
+  ];
+  if (!select.length || new Set(select).size !== select.length) throw new Error(`Query ${name}: select must be explicit, nonempty and distinct`);
+  const shape = {}, columns = {};
+  for (const key of select) {
+    if (!Object.hasOwn(options.table[TABLE_META].columns, key)) throw new Error(`Query ${name}: unknown column ${key}`);
+    columns[key] = queryColumnContract(options.table[key]);
+    shape[key] = responseColumn(options.table[key], options.fields?.[key]);
+  }
+  const response = z2.array(z2.object(shape).strict());
+  const queryInput = options.input, where = options.where, limit = options.limit;
+  const orderBy = options.orderBy === void 0 ? void 0 : JSON.parse(JSON.stringify(options.orderBy));
+  const prepare = /* @__PURE__ */ __name((input) => {
+    const parsed = queryInput.parse(input);
+    const filter = where === void 0 ? {} : where(parsed);
+    if (!filter || typeof filter !== "object" || Array.isArray(filter) || typeof filter.then === "function") {
+      throw new Error(`Query ${name}: where must return a synchronous filter object`);
+    }
+    const size = typeof limit === "function" ? limit(parsed) : limit;
+    if (limit !== void 0 && (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0)) throw new Error(`Query ${name}: limit must produce a nonnegative safe integer`);
+    return {
+      name,
+      table,
+      columns: JSON.parse(JSON.stringify(columns)),
+      where: filter,
+      options: {
+        select: [
+          ...select
+        ],
+        ...orderBy === void 0 ? {} : {
+          orderBy: structuredClone(orderBy)
+        },
+        ...limit === void 0 ? {} : {
+          limit: size
+        }
+      }
+    };
+  }, "prepare");
+  const attach = /* @__PURE__ */ __name((schema) => {
+    const api = {
+      queryName: name,
+      input: queryInput,
+      prepare,
+      async run(database, input) {
+        const request = prepare(input);
+        const rows = await ("$readQuery" in database ? database.$readQuery(request) : database.readQuery(request));
+        return schema.parse(rows);
+      },
+      sql(database, input) {
+        const request = prepare(input);
+        return "$compileQuery" in database ? database.$compileQuery(request) : database.compileQuery(request);
+      },
+      explain(database, input) {
+        const request = prepare(input);
+        return "$explainQuery" in database ? database.$explainQuery(request) : database.explainQuery(request);
+      },
+      contract() {
+        const registry = new OpenAPIRegistry();
+        registry.register(`${name}Input`, queryInput);
+        registry.register(`${name}Response`, schema);
+        return JSON.parse(JSON.stringify({
+          name,
+          table,
+          select,
+          columns,
+          components: new OpenApiGeneratorV31(registry.definitions).generateComponents().components
+        }));
+      }
+    };
+    for (const key of [
+      "min",
+      "max",
+      "length",
+      "describe",
+      "openapi"
+    ]) {
+      const modify = schema[key].bind(schema);
+      Object.defineProperty(schema, key, {
+        value: /* @__PURE__ */ __name((...args) => attach(modify(...args)), "value"),
+        configurable: true
+      });
+    }
+    return Object.assign(schema, api);
+  }, "attach");
+  return attach(response);
+}
+__name(defineQuery, "defineQuery");
+function queryManifest(queries) {
+  const sorted = [
+    ...queries
+  ].sort((a, b) => a.queryName.localeCompare(b.queryName));
+  if (new Set(sorted.map((query) => query.queryName)).size !== sorted.length) throw new Error("Query manifest contains duplicate names");
+  return JSON.parse(stableContract({
+    version: 1,
+    queries: sorted.map((query) => query.contract())
+  }));
+}
+__name(queryManifest, "queryManifest");
+function assertQueryManifest(queries, baseline) {
+  if (stableContract(queryManifest(queries)) !== stableContract(baseline)) {
+    throw new Error("Query contract drift: compare queryManifest() with the committed manifest and review the API/client changes before updating it");
+  }
+}
+__name(assertQueryManifest, "assertQueryManifest");
+
 export {
   PolicyExprRef,
   exprCtx,
   PolicyBuilder,
   policy,
+  can,
   IndexBuilder,
   index,
   TABLE_META,
@@ -573,6 +892,13 @@ export {
   EXTENSION_DEPENDENCIES,
   isPalbaseExtension,
   raw,
-  openai
+  openai,
+  makeTypedDB,
+  col,
+  withRetry,
+  sqlFragment,
+  defineQuery,
+  queryManifest,
+  assertQueryManifest
 };
-//# sourceMappingURL=chunk-YIQ4RS4F.js.map
+//# sourceMappingURL=chunk-5UGPXKMJ.js.map