@palbase/backend 24.3.0 → 25.0.0

package/dist/chunk-ZQRWW37O.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/decorators/registry.ts","../src/decorators/controller.ts","../src/errors.ts"],"sourcesContent":["// The decorator registry — the single plain-data store the method + parameter\n// decorators write into, and the deploy/dispatch pipeline reads back. No\n// `reflect-metadata`, no `emitDecoratorMetadata`: the registry is built from the\n// decorator arguments + the parameter INDEX that esbuild/tsc preserve for legacy\n// parameter decorators (verified — see the design spec §0/§4.1).\n//\n// A controller class carries its route metadata on a symbol-keyed static\n// property (`ROUTES`). `@Get`/`@Post`/… append a {@link RouteMeta} entry;\n// `@Body`/`@User`/… append a {@link ParamMeta} entry onto the route for the\n// method they decorate. Because parameter decorators run BEFORE the method\n// decorator for the same member (TS evaluates innermost-first, params before the\n// method), the route entry may not exist yet when a param decorator fires — so\n// param metadata is buffered per method name and merged when the method\n// decorator creates the route entry.\nimport type { AuthSpec, RateLimitConfig } from \"../endpoint.js\";\nimport type { UploadConfig } from \"./upload.js\";\nimport type { SseConfig } from \"./sse.js\";\nimport type { ZodTypeAny } from \"zod\";\n\n/** The HTTP verbs a route may declare, upper-cased (the runtime router +\n * OpenAPI lower-case on their own). */\nexport type HttpMethodUpper = \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\" | \"QUERY\";\n\n/** Route-level options accepted by the method decorators (`@Get`/`@Post`/…). */\nexport interface RouteOptions {\n  /** OVERRIDES the controller-level default auth for this one route. */\n  auth?: AuthSpec;\n  /** Per-route rate limit. */\n  rateLimit?: RateLimitConfig;\n  /** Direct-storage upload config — present ONLY on `@Upload` routes (the\n   * `@Get`/`@Post`/… decorators never set it). Its presence is what MARKS a\n   * route as an upload route through the whole pipeline (registry → flatten →\n   * openapi → codegen). The bytes go client→storage directly; the method body\n   * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */\n  uploadConfig?: UploadConfig;\n  /** Streaming config — present ONLY on `@Sse` routes (the `@Get`/`@Post`/…\n   * decorators never set it). Its presence is what MARKS a route as a streaming\n   * route through the whole pipeline (registry → flatten → openapi → codegen),\n   * exactly as `uploadConfig` does for uploads — never a special HTTP verb. An\n   * `@Sse` route registers POST like any input-bearing route, so the verb cannot\n   * carry the distinction. See {@link SseConfig} (decorators/sse.ts). */\n  sseConfig?: SseConfig;\n}\n\n/** The kind of value a parameter decorator injects. Drives both dispatch\n * (which request slice to inject) and codegen (which OpenAPI parameter source a\n * schema-bearing kind maps to). */\nexport type ParamKind =\n  | \"body\"\n  | \"query\"\n  | \"param\"\n  | \"headers\"\n  | \"user\"\n  | \"optionalUser\"\n  | \"client\"\n  | \"requestId\"\n  | \"traceId\"\n  | \"req\"\n  // `@UploadedObject()` — injects the uploaded object (completion input) on an\n  // `@Upload` route. No schema (the shape is the fixed UploadedObject type).\n  | \"uploadedObject\"\n  // `@SseOut()` — injects the frame writer on an `@Sse` route. No schema (the\n  // shape is the fixed SseWriter type).\n  | \"sseOut\"\n  // `@Signal()` — injects the request's AbortSignal, which aborts when the\n  // client disconnects. No schema. NOT derivable from `@Req()`: PBRequest\n  // carries only request-scoped data and has no signal (endpoint.ts:358-363).\n  | \"signal\";\n\n/** One parameter decorator's recorded metadata. `index` is the parameter\n * position esbuild/tsc preserve; `schema` is present for the schema-bearing\n * kinds (`body`/`query`/`headers`); `name` is the path-param name for `param`. */\nexport interface ParamMeta {\n  index: number;\n  kind: ParamKind;\n  /** Zod schema for `body`/`query`/`headers` (validation + codegen source). */\n  schema?: ZodTypeAny;\n  /** Path-param name for `@Param(\"id\")`. */\n  name?: string;\n}\n\n/** One inferred throw site: the error CLASS name (e.g. \"TodoLocked\") and its\n * wire code (e.g. \"todo_locked\"). `status`, `hasData`, and the data JSON schema\n * are NOT carried here — they resolve from the error registry by `code` at\n * extract/openapi time (single source of truth). */\nexport interface ThrowDescriptor {\n  name: string;\n  code: string;\n}\n\n/** One route's recorded metadata: the verb + subpath + method name + options,\n * the ordered parameter metas, and the resolved return schema (injected by the\n * codegen step — see `returnSchema`). */\nexport interface RouteMeta {\n  method: HttpMethodUpper;\n  subpath: string;\n  fnName: string;\n  options: RouteOptions;\n  params: ParamMeta[];\n  /** Response schema for the route, if any. Derived from the method's RETURN\n   * TYPE by codegen and written here via `recordReturn` (a generated top-level\n   * IIFE injected per controller), not by an author-written decorator. */\n  returnSchema?: ZodTypeAny;\n  /** Error classes this route can throw, if inferred. Derived from the method\n   * body + service call graph by the deploy stager's throw analysis and written\n   * here via `recordThrows` (a generated top-level IIFE injected per controller,\n   * the `recordReturn` twin), not by an author-written decorator. */\n  throws?: ThrowDescriptor[];\n}\n\n/** Symbol the route metadata list is stored under on a controller class. Using\n * a symbol (not a string key) keeps it off the public structural surface and\n * avoids any chance of an authored property collision. */\nexport const ROUTES: unique symbol = Symbol.for(\"palbase.backend.routes\");\n\n/** Symbol the per-method buffered parameter metas are stored under while a class\n * is being decorated. Parameter decorators fire before the method decorator, so\n * they buffer here keyed by method name; the method decorator drains the buffer\n * into the route entry it creates. */\nconst PARAM_BUFFER: unique symbol = Symbol.for(\"palbase.backend.paramBuffer\");\n\n/** A room's own slots. Rooms are NOT routes — no verb, no path, no params — so\n *  they get their own carrier slots instead of being squeezed into RouteMeta. */\nconst ROOM: unique symbol = Symbol.for(\"palbase.backend.room\");\nconst ROOM_HOOKS: unique symbol = Symbol.for(\"palbase.backend.roomHooks\");\n\n/** Symbol the per-method buffered return-type schemas are stored under while a\n * class's registry is being populated. The codegen-injected `recordReturn` call\n * can fire before OR after the method decorator; it buffers here keyed by method\n * name and `recordRoute` drains it into the route entry (and `recordReturn`\n * writes through if the route already exists). Buffering on BOTH sides means a\n * fully-formed route entry always carries its return schema — a raw-symbol\n * reader (the runtime) never has to re-merge. */\nconst RETURN_BUFFER: unique symbol = Symbol.for(\"palbase.backend.returnBuffer\");\n\n/** Symbol the per-method buffered throw descriptors are stored under while a\n * class's registry is being populated. The stager-injected `recordThrows` call\n * can fire before OR after the method decorator; it buffers here keyed by method\n * name and `recordRoute` drains it into the route entry (and `recordThrows`\n * writes through if the route already exists). Buffering on BOTH sides means a\n * fully-formed route entry always carries its throw descriptors — a raw-symbol\n * reader (the runtime) never has to re-merge. */\nconst THROWS_BUFFER: unique symbol = Symbol.for(\"palbase.backend.throwsBuffer\");\n\n/** A class constructor carrying the symbol-keyed registry slots. We type the\n * registry-bearing class as this so the decorators can read/write the slots\n * without `any` — a plain `Function` does not carry index signatures. */\ninterface RegistryCarrier {\n  [ROUTES]?: RouteMeta[];\n  [PARAM_BUFFER]?: Record<string, ParamMeta[]>;\n  [ROOM]?: RoomMeta;\n  [ROOM_HOOKS]?: RoomBuffer;\n  [RETURN_BUFFER]?: Record<string, ZodTypeAny>;\n  [THROWS_BUFFER]?: Record<string, ThrowDescriptor[]>;\n}\n\n/** Coerce a decorated target (class constructor or its prototype) into the\n * registry carrier that owns the slots. Method/param decorators receive the\n * PROTOTYPE as their target; the class decorator receives the constructor. We\n * always anchor the registry on the CONSTRUCTOR so `getRoutes(ctor)` finds it. */\nfunction carrierOf(target: object): RegistryCarrier {\n  // For instance-member decorators, `target` is the prototype; its `.constructor`\n  // is the class. For a static member or the class decorator, `target` is the\n  // constructor already. Resolve to the constructor either way.\n  const ctor =\n    typeof target === \"function\"\n      ? (target as unknown as RegistryCarrier)\n      : (((target as { constructor?: unknown }).constructor ??\n          target) as unknown as RegistryCarrier);\n  return ctor;\n}\n\n/** Get (creating if absent) the own route list for a class constructor. Own —\n * not inherited — so a subclass does not mutate its base's routes. */\nfunction ownRoutes(carrier: RegistryCarrier): RouteMeta[] {\n  if (!Object.prototype.hasOwnProperty.call(carrier, ROUTES)) {\n    carrier[ROUTES] = [];\n  }\n  return carrier[ROUTES] as RouteMeta[];\n}\n\n/** Get (creating if absent) the own per-method param buffer for a class. */\nfunction ownParamBuffer(carrier: RegistryCarrier): Record<string, ParamMeta[]> {\n  if (!Object.prototype.hasOwnProperty.call(carrier, PARAM_BUFFER)) {\n    carrier[PARAM_BUFFER] = {};\n  }\n  return carrier[PARAM_BUFFER] as Record<string, ParamMeta[]>;\n}\n\n/** Record a route (called by the method decorators). Drains any parameter\n * metas already buffered for `fnName` into the new route entry, then sorts them\n * by parameter index so dispatch can inject positionally. */\nexport function recordRoute(\n  target: object,\n  fnName: string,\n  method: HttpMethodUpper,\n  subpath: string,\n  options: RouteOptions,\n): void {\n  const carrier = carrierOf(target);\n  const routes = ownRoutes(carrier);\n  const buffer = ownParamBuffer(carrier);\n  const params = (buffer[fnName] ?? []).slice().sort((a, b) => a.index - b.index);\n  const route: RouteMeta = { method, subpath, fnName, options, params };\n  // Drain a buffered return schema (the recordReturn-ran-first ordering) so the\n  // route entry is complete the moment it's created — a raw-symbol consumer\n  // (the runtime extractor/worker) sees the return schema without re-merging.\n  const returnBuffer = carrier[RETURN_BUFFER];\n  if (returnBuffer && returnBuffer[fnName] !== undefined) {\n    route.returnSchema = returnBuffer[fnName];\n  }\n  // Same drain for buffered throw descriptors (the recordThrows-ran-first\n  // ordering) — the route entry is complete the moment it's created.\n  const throwsBuffer = carrier[THROWS_BUFFER];\n  if (throwsBuffer && throwsBuffer[fnName] !== undefined) {\n    route.throws = throwsBuffer[fnName];\n  }\n  routes.push(route);\n}\n\n/** Record one parameter decorator (called by `@Body`/`@User`/…). Buffers per\n * method name; the method decorator merges the buffer into the route entry. If\n * the route already exists (method decorator ran first — TS does evaluate the\n * method decorator AFTER its parameter decorators, but we stay order-robust),\n * the meta is also appended directly so neither ordering loses it. */\nexport function recordParam(target: object, fnName: string, meta: ParamMeta): void {\n  const carrier = carrierOf(target);\n  const buffer = ownParamBuffer(carrier);\n  (buffer[fnName] ??= []).push(meta);\n\n  // Order-robust: if the route already exists, merge in place + keep sorted.\n  const routes = carrier[ROUTES];\n  if (routes) {\n    const route = routes.find((r) => r.fnName === fnName);\n    if (route) {\n      route.params.push(meta);\n      route.params.sort((a, b) => a.index - b.index);\n    }\n  }\n}\n\n/** Attach a return schema to the route for `fnName` (called by the codegen\n * injection that reads the method's return type). If the route does not exist\n * yet, the schema is buffered (RETURN_BUFFER) and drained into the route by\n * `recordRoute` when the method decorator runs. */\nexport function recordReturn(target: object, fnName: string, schema: ZodTypeAny): void {\n  const carrier = carrierOf(target);\n  const routes = carrier[ROUTES];\n  const route = routes?.find((r) => r.fnName === fnName);\n  if (route) {\n    route.returnSchema = schema;\n    return;\n  }\n  if (!Object.prototype.hasOwnProperty.call(carrier, RETURN_BUFFER)) {\n    carrier[RETURN_BUFFER] = {};\n  }\n  const returnBuffer = carrier[RETURN_BUFFER];\n  if (returnBuffer) returnBuffer[fnName] = schema;\n}\n\n/** Attach the inferred throw descriptors to the route for `fnName` (called by\n * the stager-injected IIFE that carries the throw analysis result — the\n * `recordReturn` twin). If the route does not exist yet, the descriptors are\n * buffered (THROWS_BUFFER) and drained into the route by `recordRoute` when the\n * method decorator runs. */\nexport function recordThrows(target: object, fnName: string, throws: ThrowDescriptor[]): void {\n  const carrier = carrierOf(target);\n  const routes = carrier[ROUTES];\n  const route = routes?.find((r) => r.fnName === fnName);\n  if (route) {\n    route.throws = throws;\n    return;\n  }\n  if (!Object.prototype.hasOwnProperty.call(carrier, THROWS_BUFFER)) {\n    carrier[THROWS_BUFFER] = {};\n  }\n  const throwsBuffer = carrier[THROWS_BUFFER];\n  if (throwsBuffer) throwsBuffer[fnName] = throws;\n}\n\n/** Read the route metadata for a controller class (the deploy/dispatch entry\n * point). Applies any buffered return schemas + throw descriptors (for the\n * recordReturn/recordThrows-runs-before orderings) and returns a defensive copy\n * so callers cannot mutate the registry.\n */\nexport function getRoutes(ctor: object): RouteMeta[] {\n  const carrier = carrierOf(ctor);\n  const routes = carrier[ROUTES] ?? [];\n  const returnBuffer = carrier[RETURN_BUFFER];\n  if (returnBuffer) {\n    for (const route of routes) {\n      const buffered = returnBuffer[route.fnName];\n      if (buffered && route.returnSchema === undefined) {\n        route.returnSchema = buffered;\n      }\n    }\n  }\n  const throwsBuffer = carrier[THROWS_BUFFER];\n  if (throwsBuffer) {\n    for (const route of routes) {\n      const buffered = throwsBuffer[route.fnName];\n      if (buffered && route.throws === undefined) {\n        route.throws = buffered;\n      }\n    }\n  }\n  return routes.map((r) => ({\n    ...r,\n    params: r.params.slice(),\n    ...(r.throws !== undefined ? { throws: r.throws.slice() } : {}),\n  }));\n}\n\n// ── rooms ───────────────────────────────────────────────────────────────────\n\n/** Which lifecycle hook a method is bound to. */\nexport type RoomHook = \"authorize\" | \"first\" | \"join\" | \"leave\" | \"empty\";\n\nexport interface RoomMessageMeta {\n  fnName: string;\n  schema: ZodTypeAny;\n}\n\nexport interface RoomMeta {\n  pattern: string;\n  events: Record<string, ZodTypeAny>;\n  graceMs: number;\n  /** hook → the method name that implements it. */\n  hooks: Partial<Record<RoomHook, string>>;\n  /** inbound message name → its method and payload schema. */\n  messages: Record<string, RoomMessageMeta>;\n}\n\ninterface RoomBuffer {\n  hooks: Partial<Record<RoomHook, string>>;\n  messages: Record<string, RoomMessageMeta>;\n}\n\n/** Get (creating if absent) the own hook buffer. Own — not inherited — so a\n *  subclass never mutates its base's hooks. Member decorators fill this BEFORE\n *  the class decorator runs; controller.ts:203 depends on the same ordering. */\nfunction ownRoomBuffer(carrier: RegistryCarrier): RoomBuffer {\n  if (!Object.prototype.hasOwnProperty.call(carrier, ROOM_HOOKS)) {\n    carrier[ROOM_HOOKS] = { hooks: {}, messages: {} };\n  }\n  return carrier[ROOM_HOOKS] as RoomBuffer;\n}\n\n/** Record a lifecycle hook. A second method for the same hook is refused: two\n *  answers to \"who handles this\" cannot be resolved at dispatch, and silently\n *  keeping one is how a hook stops running without anyone being told. */\nexport function recordRoomHook(target: object, hook: RoomHook, fnName: string): void {\n  const buffer = ownRoomBuffer(carrierOf(target));\n  const existing = buffer.hooks[hook];\n  if (existing !== undefined && existing !== fnName) {\n    const label = `On${hook.charAt(0).toUpperCase()}${hook.slice(1)}`;\n    throw new Error(\n      `@${label} is declared twice in one room (${existing} and ${fnName}). ` +\n        `A room has one of each hook.`,\n    );\n  }\n  buffer.hooks[hook] = fnName;\n}\n\n/** Record an inbound message handler. */\nexport function recordRoomMessage(\n  target: object,\n  name: string,\n  fnName: string,\n  schema: ZodTypeAny,\n): void {\n  const buffer = ownRoomBuffer(carrierOf(target));\n  const existing = buffer.messages[name];\n  if (existing !== undefined && existing.fnName !== fnName) {\n    throw new Error(\n      `@OnMessage(\"${name}\") is declared twice in one room (${existing.fnName} and ${fnName}).`,\n    );\n  }\n  buffer.messages[name] = { fnName, schema };\n}\n\n/** Record the room itself (called by the class decorator), draining the buffer\n *  the member decorators already filled. */\nexport function recordRoom(\n  ctor: object,\n  meta: Omit<RoomMeta, \"hooks\" | \"messages\">,\n): void {\n  const carrier = carrierOf(ctor);\n  const buffer = ownRoomBuffer(carrier);\n  carrier[ROOM] = { ...meta, hooks: buffer.hooks, messages: buffer.messages };\n}\n\n/** The room a class declares, or undefined. A class with no `@Room` is not a\n *  room — the marker is the CONFIG's presence, never a name or a base class\n *  (the rule upload.ts:13-16 states for uploads). */\nexport function getRoom(ctor: object): RoomMeta | undefined {\n  const carrier = carrierOf(ctor);\n  if (!Object.prototype.hasOwnProperty.call(carrier, ROOM)) return undefined;\n  return carrier[ROOM] as RoomMeta;\n}\n","// `@Controller(basePath, options?)` — the class decorator that marks a class as\n// a Palbase backend controller. It stamps a non-enumerable `__palbase`\n// discriminant + the resolved controller metadata onto the class so the\n// deploy/dispatch pipeline (and `isController`/`resolveController`) can detect\n// and read it without `reflect-metadata`.\nimport type { AuthSpec } from \"../endpoint.js\";\nimport { getRoutes } from \"./registry.js\";\n\n/** The controller metadata stamped onto a `@Controller`-decorated class. The\n * default export of a `controllers/*.controller.ts` file resolves to this via\n * {@link resolveController}. */\nexport interface ControllerMeta {\n  /** Discriminant the runtime + tooling read. */\n  readonly __palbase: \"controller\";\n  /** The base path every route in this controller mounts under (e.g. \"/todos\"). */\n  basePath: string;\n  /** Controller-level default auth, applied to routes that don't set their own\n   * (`@Get(\"/x\", { auth })` overrides this). `undefined` ⇒ the application\n   * default ({@link defineDefaultAuth}), and secure-by-default below that —\n   * see {@link resolveEffectiveAuth} for the whole cascade. */\n  defaultAuth?: AuthSpec;\n}\n\n/** Options accepted by `@Controller`. */\nexport interface ControllerOptions {\n  /** Default auth for ALL routes in this controller (route-level overrides;\n   * omitting it falls through to the application default declared with\n   * {@link defineDefaultAuth}). */\n  auth?: AuthSpec;\n}\n\n/** Symbol the controller metadata is stamped under. Symbol-keyed (not a string\n * property) so it never collides with an authored member and stays off the\n * structural surface. */\nexport const CONTROLLER_META: unique symbol = Symbol.for(\"palbase.backend.controllerMeta\");\n\n/**\n * Every class `@Controller` has decorated, in decoration order.\n *\n * This is what lets a controller file need no export at all: importing the file\n * runs the decorator, the decorator records the class here, and the runtime\n * reads the list. Without it the only handle on a class is its export name, so\n * every controller had to be exported AND named in a generated entry — the\n * ceremony NestJS still charges (`export class` PLUS\n * `@Module({controllers:[…]})`).\n *\n * Keyed on a well-known Symbol against globalThis rather than held in a module\n * variable, because a deployed bundle inlines its own copy of this package: two\n * copies would keep two lists, and the runtime would read the empty one. The\n * same hazard `runtimeHooks` exists for, closed the same way — one shared slot.\n */\nconst REGISTRY: unique symbol = Symbol.for(\"palbase.backend.allControllers\") as never;\n\nfunction registry(): unknown[] {\n  const g = globalThis as unknown as Record<symbol, unknown[] | undefined>;\n  const existing = g[REGISTRY];\n  if (existing) return existing;\n  const fresh: unknown[] = [];\n  g[REGISTRY] = fresh;\n  return fresh;\n}\n\n/**\n * The controller classes this process has loaded, in decoration order.\n *\n * Decoration order is import order, which the bundler fixes by sorting the\n * files it emits imports for — so two builds of one tree produce the same\n * route table, and route precedence is not a function of module-resolution\n * accidents.\n */\nexport function getRegisteredControllers(): readonly unknown[] {\n  return registry().slice();\n}\n\n/** Empty the registry. For tests, which load controllers repeatedly. */\nexport function __resetRegisteredControllers(): void {\n  registry().length = 0;\n}\n\n/**\n * The APPLICATION-level default auth.\n *\n * Held on globalThis under a well-known Symbol for exactly the reason\n * {@link REGISTRY} is: a deployed bundle inlines its own copy of this package,\n * and two copies keeping two defaults is how a security setting silently\n * becomes two different settings.\n */\nconst APP_DEFAULT_AUTH: unique symbol = Symbol.for(\"palbase.backend.appDefaultAuth\") as never;\n\nfunction appAuthSlot(): Record<symbol, AuthSpec | undefined> {\n  return globalThis as unknown as Record<symbol, AuthSpec | undefined>;\n}\n\n/**\n * Declare the default auth for EVERY route in the application — the ring the\n * cascade consults when neither the route nor its controller says anything.\n *\n * The measured problem it removes: `auth: { verifiedEmail: true }` repeated by\n * hand on ten `@Controller`s. A security setting that must be repeated is a\n * security setting that will be forgotten — the eleventh controller opens the\n * door and nothing says so.\n *\n * Call it at MODULE SCOPE in a file the application imports (the controllers'\n * own barrel, or a module a controller imports). The cascade reads this slot\n * when the route table is built and when the spec is emitted — both of which\n * run after module loading — so declaration order does not matter, but being\n * imported at all does.\n *\n * @example\n * defineDefaultAuth({ verifiedEmail: true });  // every route, unless it says otherwise\n */\nexport function defineDefaultAuth(auth: AuthSpec): void {\n  appAuthSlot()[APP_DEFAULT_AUTH] = auth;\n}\n\n/** The declared application default, or `undefined` when none was declared. */\nexport function getDefaultAuth(): AuthSpec | undefined {\n  return appAuthSlot()[APP_DEFAULT_AUTH];\n}\n\n/** Clear the application default. For tests, which declare it repeatedly. */\nexport function __resetDefaultAuth(): void {\n  delete appAuthSlot()[APP_DEFAULT_AUTH];\n}\n\n/**\n * THE auth cascade: route → controller → application → `true`.\n *\n * One function, every caller — the route table (`engine/router.ts`) and the\n * spec emitter (`openapi/controllers.ts`) ASK for the answer instead of\n * spelling the chain themselves. Two hand-written copies of a cascade is how\n * the build-time answer and the runtime answer come to disagree about who may\n * call an endpoint, and the disagreement shows up as an open door.\n *\n * The terminal `true` is secure-by-default and is load-bearing: a route that\n * declared nothing, under a controller that declared nothing, in an\n * application that declared nothing, is CLOSED.\n */\nexport function resolveEffectiveAuth(\n  routeAuth: AuthSpec | undefined,\n  controllerAuth: AuthSpec | undefined,\n): AuthSpec {\n  return routeAuth ?? controllerAuth ?? getDefaultAuth() ?? true;\n}\n\n/** A class carrying the stamped controller metadata + discriminant. */\ninterface ControllerCarrier {\n  __palbase?: \"controller\";\n  [CONTROLLER_META]?: ControllerMeta;\n}\n\n/** The one path segment the platform owns. The isolate matches\n * `^/webhooks/([^/]+)$` on the raw request path BEFORE controller dispatch, so\n * anything a controller resolves to under it answers `404 webhook_not_found`\n * and never runs. */\nconst RESERVED_FIRST_SEGMENT = \"webhooks\";\n\n/**\n * Throw if `path` resolves under the reserved segment. Segments are compared the\n * way the isolate compares them — `split(\"/\").filter(Boolean)` — NOT by string\n * prefix, because empty segments collapse there: `@Controller(\"/\")` +\n * `@Post(\"/webhooks/x\")` composes to `//webhooks/x`, which the isolate serves as\n * `/webhooks/x`. A prefix check reads that as safe; the segment check does not.\n * `/webhooksy` stays allowed for the same reason — it is a different segment.\n *\n * Every verb is refused, not just the POST the isolate currently intercepts: the\n * reservation is of the URL namespace, so a `@Get(\"/webhooks/x\")` that happens\n * to work today would be silently shadowed the moment the isolate's method gate\n * widens. Refusing at build is recoverable; discovering it as a 404 is not.\n */\nfunction assertNotReserved(path: string, subject: string): void {\n  const [first] = path.split(\"/\").filter(Boolean);\n  if (first === RESERVED_FIRST_SEGMENT) {\n    throw new Error(\n      `${subject} resolves under the reserved /${RESERVED_FIRST_SEGMENT} path — ` +\n        \"inbound webhooks are served there and would shadow this route\",\n    );\n  }\n}\n\n/**\n * Mark a class as a Palbase backend controller. `basePath` is the mount path\n * for every route the class declares; `options.auth` sets the controller-level\n * default auth (a route's own `auth` overrides it; absent ⇒ secure-by-default).\n *\n * @example\n * \\@Controller(\"/todos\", { auth: false })\n * export class TodosController {\n *   \\@Get(\"\") list(\\@QueryParams(ListTodosQuery) q: ListTodosQuery): TodoSchema[] { … }\n * }\n */\nexport function Controller(basePath: string, options: ControllerOptions = {}) {\n  return function <T extends abstract new (...args: never[]) => object>(ctor: T): T {\n    // /webhooks/* belongs to the platform: the isolate matches the inbound\n    // webhook route before controller dispatch, so a controller mounted here\n    // would never receive a request. Silent shadowing is the failure mode this\n    // whole change exists to remove, so refuse it at build.\n    //\n    // The COMPOSED path is what gets shadowed, not the base path. `@Controller(\"\")`\n    // and `@Controller(\"/\")` both pass a base-path-only check while a\n    // `@Post(\"/webhooks/stripe\")` inside them resolves to exactly the path the\n    // isolate intercepts. Method decorators run BEFORE the class decorator (TS\n    // evaluates members first), so every route this class declares is already in\n    // the registry here — which is why the composed check can live at this one\n    // seam instead of on the dispatch read path. The `@Controller(\"\") +\n    // @Post(\"/webhooks/stripe\")` test is the lock on that ordering: if it ever\n    // stopped holding, that test goes red.\n    assertNotReserved(basePath, `@Controller(\"${basePath}\")`);\n    for (const route of getRoutes(ctor)) {\n      assertNotReserved(\n        `${basePath}${route.subpath}`,\n        `@${route.method}(\"${route.subpath}\") in @Controller(\"${basePath}\")`,\n      );\n    }\n\n    const carrier = ctor as unknown as ControllerCarrier;\n    const meta: ControllerMeta = {\n      __palbase: \"controller\",\n      basePath,\n      ...(options.auth !== undefined ? { defaultAuth: options.auth } : {}),\n    };\n    // Non-enumerable so it doesn't leak onto instances / structural checks.\n    Object.defineProperty(carrier, CONTROLLER_META, {\n      value: meta,\n      enumerable: false,\n      configurable: true,\n      writable: false,\n    });\n    // The bare `__palbase` discriminant is the cheap detection marker the\n    // runtime/extractor checks; keep it readable but non-enumerable.\n    Object.defineProperty(carrier, \"__palbase\", {\n      value: \"controller\",\n      enumerable: false,\n      configurable: true,\n      writable: false,\n    });\n    // Record it, so importing the file is enough and exporting is optional.\n    // Guarded against a double-decoration re-entering the same class twice.\n    const all = registry();\n    if (!all.includes(ctor)) all.push(ctor);\n    return ctor;\n  };\n}\n\n/** True when `value` is a `@Controller`-decorated class (cheap discriminant\n * check). Accepts the class constructor (the default export of a controller\n * file). */\nexport function isController(value: unknown): boolean {\n  if (typeof value !== \"function\" && (typeof value !== \"object\" || value === null)) {\n    return false;\n  }\n  const carrier = value as ControllerCarrier;\n  return carrier.__palbase === \"controller\" && carrier[CONTROLLER_META] !== undefined;\n}\n\n/** Read the resolved controller metadata off a `@Controller`-decorated class.\n * Throws if the class was not decorated — callers should gate with\n * {@link isController} first (the loader does). */\nexport function resolveController(ctor: unknown): ControllerMeta {\n  if (typeof ctor !== \"function\" && (typeof ctor !== \"object\" || ctor === null)) {\n    throw new TypeError(\"resolveController: value is not a class\");\n  }\n  const meta = (ctor as ControllerCarrier)[CONTROLLER_META];\n  if (!meta) {\n    throw new TypeError(\n      \"resolveController: class is not a @Controller — every controller file must `export default` a @Controller-decorated class\",\n    );\n  }\n  return meta;\n}\n\n/**\n * A class the runtime constructs takes NO constructor parameters.\n *\n * ONE writer, four callers (controller, hook, job, webhook) and the build's own\n * check. Four hand-written copies of this message is how the four come to\n * disagree about what is refused — and the disagreement is silent, because a\n * class that slips past one of them still ends up with `undefined` fields.\n *\n * Why it is refused rather than injected: there is no container. The parameter\n * would arrive `undefined`, the code would compile, deploy, and fail at the\n * first request that touches the field — the most expensive place to learn it.\n */\nexport function assertZeroArgConstructor(Ctrl: unknown, kind: string): void {\n  const arity = (Ctrl as { length?: number }).length ?? 0;\n  if (arity === 0) return;\n  const name = (Ctrl as { name?: string }).name ?? \"<anonymous>\";\n  throw new Error(\n    `${kind} ${name} declares a constructor with ${arity} parameter(s). ` +\n      `A ${kind} is constructed by the runtime with a zero-argument constructor — ` +\n      `there is no injector to supply them, so every parameter would arrive as ` +\n      `undefined. Hold the dependency as a module-level singleton the ${kind} ` +\n      \"imports (`const repo = makeRepo()` beside the class), and construct the \" +\n      \"service directly in tests (e.g. `new TodoService(fakeDatabase().db)`).\",\n  );\n}\n","/**\n * The brand that identifies an HttpError ACROSS SDK instances.\n *\n * A process legitimately holds more than one copy of this SDK — the runtime\n * loads the engine from its own node_modules while the tenant's bundle carries\n * an inlined copy, which is why the controller registry and the error registry\n * are both anchored on `Symbol.for`. The one place that did not follow the\n * pattern was the engine's catch: `err instanceof HttpError` compares CLASS\n * IDENTITY, so a `throw new NotFound()` from the bundle's copy did not match\n * the engine's copy and every typed error in every deployed backend degraded to\n * `500 internal_error`. Measured through the edge on a real deploy: a route\n * throwing `NotFound` answered 500 while the runtime's own log printed the\n * error object with `status: 404` right beside it.\n *\n * `Symbol.for` puts this in the cross-realm registry, so every copy of the SDK\n * agrees on it by VALUE rather than by identity.\n */\nexport const HTTP_ERROR_BRAND: unique symbol = Symbol.for(\"palbase.backend.httpError\");\n\n/**\n * Set on an `HttpError` the ENGINE built out of a driver failure, as opposed to\n * one the author constructed to ANSWER a request.\n *\n * The distinction cannot be read off the status, and 409 is why. The scaffold\n * teaches `throw new Conflict(\"title already taken\")` as the way to answer\n * (template/AGENTS.md), and the engine raises `UniqueViolation` — also a 409 —\n * when a write hits a unique index. Logging by status therefore either loses the\n * engine's event or writes an \"unhandled\" line every time an author takes the\n * documented path. Measured: it did the second.\n *\n * `Symbol.for` so the mark survives the bundle/runtime SDK split, the same way\n * {@link HTTP_ERROR_BRAND} does.\n */\nexport const ENGINE_RAISED: unique symbol = Symbol.for(\"palbase.backend.engineRaised\") as never;\n\n/** Mark `e` as engine-raised and return it, so a conversion site reads as one expression. */\nexport function markEngineRaised<E extends object>(e: E): E {\n  (e as Record<symbol, unknown>)[ENGINE_RAISED] = true;\n  return e;\n}\n\n/** Whether the engine built this error, rather than the author throwing it to answer. */\nexport function isEngineRaised(e: unknown): boolean {\n  return typeof e === \"object\" && e !== null && (e as Record<symbol, unknown>)[ENGINE_RAISED] === true;\n}\n\n/**\n * Whether a thrown value is an HttpError from ANY copy of this SDK.\n *\n * The shape is checked as well as the brand: the brand says \"this claims to be\n * one of ours\", the fields say the envelope can actually be built from it, and\n * a half-formed object must fall through to the 500 path rather than produce a\n * malformed response.\n */\nexport function isHttpError(err: unknown): err is HttpError {\n  if (typeof err !== \"object\" || err === null) return false;\n  const e = err as Record<PropertyKey, unknown>;\n  return (\n    e[HTTP_ERROR_BRAND] === true &&\n    typeof e.status === \"number\" &&\n    typeof e.error === \"string\" &&\n    typeof e.errorDescription === \"string\"\n  );\n}\n\n/** HTTP error with structured error response format.\n *\n * The base class for the throwable error classes (`PalError`, `Conflict`,\n * `NotFound`, …). Construct one directly with `throw new HttpError(404,\n * \"todo_not_found\", \"No such todo\")`, or throw a named subclass\n * (`throw new NotFound(\"todo not found\")`). The runtime catches any `HttpError`\n * and emits the standard envelope; on the wire (and to iOS) it surfaces as\n * `BackendError.server(code, status, message, requestId)`.\n *\n * The optional `data` field carries a structured payload alongside the\n * standard envelope — for errors that need to ship extra context\n * (e.g. `new Conflict(\"locked\", \"title_locked\", { retryAfter: 30 })`). It rides\n * through to the iOS typed enum's associated value.\n */\nexport class HttpError extends Error {\n  public readonly status: number;\n  public readonly error: string;\n  public readonly errorDescription: string;\n  public readonly data?: unknown;\n  /** See {@link HTTP_ERROR_BRAND} — how the engine recognises this across SDK copies. */\n  public readonly [HTTP_ERROR_BRAND] = true;\n\n  constructor(status: number, error: string, errorDescription: string, data?: unknown) {\n    super(errorDescription);\n    this.name = \"HttpError\";\n    this.status = status;\n    this.error = error;\n    this.errorDescription = errorDescription;\n    if (data !== undefined) {\n      this.data = data;\n    }\n  }\n\n  /**\n   * Serialize to the standard Palbase error response format.\n   * The `requestId` is injected by the runtime layer from the request context.\n   * When called without arguments (e.g. JSON.stringify), request_id is omitted.\n   * When `data` is set, it is appended as a strict-superset field.\n   */\n  toJSON(requestId?: string): {\n    error: string;\n    error_description: string;\n    status: number;\n    request_id?: string;\n    data?: unknown;\n  } {\n    const result: {\n      error: string;\n      error_description: string;\n      status: number;\n      request_id?: string;\n      data?: unknown;\n    } = {\n      error: this.error,\n      error_description: this.errorDescription,\n      status: this.status,\n    };\n    if (requestId) {\n      result.request_id = requestId;\n    }\n    if (this.data !== undefined) {\n      result.data = this.data;\n    }\n    return result;\n  }\n}\n\n/**\n * Throw with a custom HTTP status + wire code. The general-purpose escape hatch\n * when none of the named classes (`Conflict`/`NotFound`/…) fits.\n *\n * @example\n * throw new PalError(418, \"teapot\", \"I'm a teapot\");\n */\nexport class PalError extends HttpError {\n  constructor(status: number, code: string, description: string, data?: unknown) {\n    super(status, code, description, data);\n    this.name = \"PalError\";\n  }\n}\n\n/** Base for the named status classes. Each subclass fixes its HTTP status; the\n * `code` defaults to the class's canonical wire code (overridable), and the\n * `message` defaults to a human-readable label (overridable). */\nabstract class NamedHttpError extends HttpError {\n  protected constructor(\n    status: number,\n    defaultCode: string,\n    name: string,\n    message?: string,\n    code?: string,\n    data?: unknown,\n  ) {\n    super(status, code ?? defaultCode, message ?? defaultMessage(name), data);\n    this.name = name;\n  }\n}\n\n/** Derive a default human-readable message from a class name\n * (\"NotFound\" → \"Not found\", \"TooManyRequests\" → \"Too many requests\"). */\nfunction defaultMessage(name: string): string {\n  const spaced = name.replace(/([a-z0-9])([A-Z])/g, \"$1 $2\");\n  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();\n}\n\n/**\n * 400 — the request was malformed or failed validation. Carries a fixed typed\n * payload: `new BadRequest({ fields: [{ field: \"email\", message: \"invalid\" }] })`.\n * The shape is declared once in the SDK so codegen surfaces `error.data.fields`\n * typed on the client.\n */\nexport class BadRequest extends NamedHttpError {\n  public declare readonly data: BadRequestData;\n  constructor(data: BadRequestData, message?: string) {\n    super(400, \"bad_request\", \"BadRequest\", message, undefined, data);\n  }\n}\n\n/** 401 — the caller is not authenticated. */\nexport class Unauthorized extends NamedHttpError {\n  constructor(message?: string, code?: string, data?: unknown) {\n    super(401, \"unauthorized\", \"Unauthorized\", message, code, data);\n  }\n}\n\n/** 403 — the caller is authenticated but not allowed. */\nexport class Forbidden extends NamedHttpError {\n  constructor(message?: string, code?: string, data?: unknown) {\n    super(403, \"forbidden\", \"Forbidden\", message, code, data);\n  }\n}\n\n/** 404 — the requested resource does not exist. */\nexport class NotFound extends NamedHttpError {\n  constructor(message?: string, code?: string, data?: unknown) {\n    super(404, \"not_found\", \"NotFound\", message, code, data);\n  }\n}\n\n/** 409 — the request conflicts with the current state. */\nexport class Conflict extends NamedHttpError {\n  constructor(message?: string, code?: string, data?: unknown) {\n    super(409, \"conflict\", \"Conflict\", message, code, data);\n  }\n}\n\n/**\n * 409 — a write was refused because it would duplicate an existing row.\n * Carries the NAME of the unique constraint Postgres named (`users_email_key`).\n *\n * The engine produces it: a statement rejected with SQLSTATE `23505` is\n * converted here rather than surfacing as an opaque driver error (see\n * `engine/db.ts`, `diagnosingDriver`). What that removes is the string match —\n * before this, the only way to act on a duplicate was to test the driver\n * message for \"duplicate key value violates unique constraint\", a contract\n * nobody signed that breaks on a Postgres upgrade, a locale, or a constraint\n * rename, silently and in production.\n *\n * THE NAME IS A FIELD AND STAYS OUT OF THE DEFAULT MESSAGE. The two are not\n * the same audience. `constraint` is read by the code that catches this — the\n * developer, who already knows the schema. `errorDescription` is the HTTP\n * response body, and an UNCAUGHT duplicate puts it in front of the\n * application's end user: `users_email_key` there discloses how the schema is\n * built to whoever sent the request. The platform's own data API took the same\n * decision one surface over and wrote down why —\n * `v2/internal/modules/database/internal/handler/pgerror.go:83-87` collapses\n * every 23xxx to a generic conflict, \"never disclose the constraint/column\n * name\". A thrower who WANTS the name on the wire passes it deliberately\n * (`new UniqueViolation(c, \\`\\${c} already exists\\`)`, or through `data`).\n *\n * @example\n * try {\n *   await Database.tables.users.insert({ email });\n * } catch (e) {\n *   if (UniqueViolation.is(e) && e.constraint === \"users_email_key\") {\n *     throw new Conflict(\"That email is taken\", \"email_taken\");\n *   }\n *   throw e;\n * }\n */\nexport class UniqueViolation extends Conflict {\n  /**\n   * Whether `e` is a unique violation — REGARDLESS of which copy of this SDK\n   * constructed it.\n   *\n   * Use this instead of `instanceof`. Measured on a live stack: a controller\n   * bundle INLINES its own copy of `@palbase/backend`, and the engine that\n   * raises this error is the runtime's copy. Two copies, two class identities,\n   * and `e instanceof UniqueViolation` is false in the one place a caller\n   * writes it — a check that reads as correct and silently never matches.\n   */\n  static is(e: unknown): e is UniqueViolation {\n    return (\n      typeof e === \"object\" &&\n      e !== null &&\n      (e as { name?: unknown }).name === \"UniqueViolation\" &&\n      typeof (e as { constraint?: unknown }).constraint === \"string\"\n    );\n  }\n\n  /** The unique constraint the statement violated, as Postgres named it.\n   * `\"\"` when the driver did not say which — see `engine/db.ts`. */\n  public readonly constraint: string;\n\n  constructor(constraint: string, message?: string, code?: string, data?: unknown) {\n    super(message ?? \"Unique constraint violated\", code ?? \"unique_violation\", data);\n    this.name = \"UniqueViolation\";\n    this.constraint = constraint;\n  }\n}\n\n/** A single field-level validation failure carried by {@link BadRequest}. */\nexport interface FieldError {\n  /** The offending field's name (dotted path for nested fields). */\n  field: string;\n  /** Human-readable reason the field failed. */\n  message: string;\n}\n\n/** The fixed, typed payload {@link BadRequest} ships. */\nexport interface BadRequestData {\n  /** The fields that failed validation. */\n  fields: FieldError[];\n}\n\n/** The fixed, typed payload {@link TooManyRequests} ships. */\nexport interface TooManyRequestsData {\n  /** Seconds the caller should wait before retrying. */\n  retryAfter: number;\n}\n\n/**\n * 429 — the caller has exceeded the rate limit. Carries a fixed typed payload:\n * `new TooManyRequests({ retryAfter: 30 })`. The shape is declared once in the\n * SDK (error-registry pre-seed) so codegen surfaces `error.data.retryAfter`\n * typed on the client — no per-project definition needed.\n */\nexport class TooManyRequests extends NamedHttpError {\n  public declare readonly data: TooManyRequestsData;\n  constructor(data: TooManyRequestsData, message?: string) {\n    super(429, \"too_many_requests\", \"TooManyRequests\", message, undefined, data);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/db/env.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/db/env.ts"],"sourcesContent":["/**\n * `@palbase/backend/env` — the controlled global augmentation target for the\n * project's schema.\n *\n * `Database.tables.<name>` is typed against the `Tables` interface declared\n * here. By default `Tables` is EMPTY; the generated `palbase-env.d.ts`\n * (emitted from `db/schema.ts` by {@link makeEnvDts}) augments it with one\n * member per table:\n *\n *   // palbase-env.d.ts (generated — do not edit)\n *   declare module \"@palbase/backend/env\" {\n *     interface Tables {\n *       todos: { row: {...}; insert: {...} };\n *     }\n *   }\n *\n * Because a `br-<ref>` pod is single-project, augmenting one global `Tables`\n * interface is safe — there is no cross-project \"leak\" to worry about (a pod\n * only ever compiles one project's schema). This is the C5 decision: typed\n * `Database.tables.*` with NO import and NO generic in handler code.\n *\n * Authors who want the row type explicitly can import it:\n *\n *   import type { Tables } from \"@palbase/backend/env\";\n *   type Todo = Tables[\"todos\"][\"row\"];\n */\n\n/**\n * One typed table's shapes and its position in the user-rooted graph:\n *\n * - `row` — the full row, every column present.\n * - `insert` — the write payload, required vs optional columns.\n * - `owner` — the column that foreign-keys `auth.users` (declared in\n *   `db/schema.ts` with `.referencesAuthUser(...)`), or `null` when the table\n *   is not user-rooted. This is what makes a seed/fixture DSL able to OMIT the\n *   owner column from the author-facing type: the apply step fills it.\n * - `children` — tables that foreign-key THIS table, mapped to the FK column on\n *   the child (`{ todos: \"list_id\" }`). Lets a nested seed attach children\n *   without the author ever writing the FK. Self-FKs and cycle back-edges are\n *   omitted by the generator so recursive types over `children` terminate.\n *\n * The generated `palbase-env.d.ts` fills `row`/`insert` with flat object types —\n * no `ColumnBuilder` phantom types ever appear in the generated output — and\n * `owner`/`children` with string literals.\n */\nexport interface TableTypes {\n  row: Record<string, unknown>;\n  insert: Record<string, unknown>;\n  owner: string | null;\n  children: Record<string, string>;\n}\n\n/**\n * The project's tables, keyed by table name. EMPTY by default; the generated\n * `palbase-env.d.ts` augments this interface (module augmentation), so\n * `Database.tables` is typed everywhere with no per-file import.\n */\n// biome-ignore lint/suspicious/noEmptyInterface: augmentation target — filled by generated palbase-env.d.ts.\nexport interface Tables {}\n\n// BUCKETS MOVED TO `@palbase/backend/stack` (2026-08-29).\n//\n// `BucketTypes` and `Buckets` lived here because `config/storage.ts` declared\n// buckets and the deploy folded them into `palbase-env.d.ts` beside the schema's\n// tables. Buckets never came from the schema, and they do not come from a\n// declaration any more: the STACK holds them, so their types are generated into\n// `palbase-stack.d.ts` with the secrets and flags.\n//\n// Re-exported here so `Storage.buckets` keeps its one import site and no caller\n// has to learn that the source moved.\nexport type { BucketTypes, Buckets } from \"../stack.js\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/db/env.ts"],"sourcesContent":["/**\n * `@palbase/backend/env` — the controlled global augmentation target for the\n * project's schema.\n *\n * `Database.tables.<name>` is typed against the `Tables` interface declared\n * here. By default `Tables` is EMPTY; the generated `palbase-env.d.ts`\n * (emitted from `db/schema.ts` by {@link makeEnvDts}) augments it with one\n * member per table:\n *\n *   // palbase-env.d.ts (generated — do not edit)\n *   declare module \"@palbase/backend/env\" {\n *     interface Tables {\n *       todos: { row: {...}; insert: {...} };\n *     }\n *   }\n *\n * Because a `br-<ref>` pod is single-project, augmenting one global `Tables`\n * interface is safe — there is no cross-project \"leak\" to worry about (a pod\n * only ever compiles one project's schema). This is the C5 decision: typed\n * `Database.tables.*` with NO import and NO generic in handler code.\n *\n * Authors who want the row type explicitly can import it:\n *\n *   import type { Tables } from \"@palbase/backend/env\";\n *   type Todo = Tables[\"todos\"][\"row\"];\n */\n\n/**\n * One typed table's shapes and its relations:\n *\n * - `row` — the full row, every column present.\n * - `insert` — the write payload, required vs optional columns.\n * - `relations` — every foreign key this table takes part in, named, in both\n *   directions. `{ list: { to: \"lists\", kind: \"one\", via: \"list_id\" } }` on the\n *   child; `{ todos: { to: \"todos\", kind: \"many\", via: \"list_id\" } }` on the\n *   parent. Ownership declared with `ownedByUser()` appears as `owner`.\n *\n * The generated `palbase-env.d.ts` fills `row`/`insert` with flat object types —\n * no `ColumnBuilder` phantom types ever appear in the generated output — and\n * `relations` with string literals.\n */\nexport interface TableTypes {\n  row: Record<string, unknown>;\n  insert: Record<string, unknown>;\n  /**\n   * The table's relations, derived from its declared foreign keys.\n   *\n   * Replaces the old `owner` / `children` pair, which nothing ever read: `owner`\n   * was whichever column happened to reference `auth.users` FIRST in declaration\n   * order, and `children` silently kept only ONE foreign key per parent.\n   *\n   * `to` is the target's table key — bare for `public`, schema-qualified\n   * otherwise, the same convention `RefJSON.table` uses.\n   */\n  relations: Record<string, { to: string; kind: \"one\" | \"many\"; via: string }>;\n}\n\n/**\n * The project's tables, keyed by table name. EMPTY by default; the generated\n * `palbase-env.d.ts` augments this interface (module augmentation), so\n * `Database.tables` is typed everywhere with no per-file import.\n */\n// biome-ignore lint/suspicious/noEmptyInterface: augmentation target — filled by generated palbase-env.d.ts.\nexport interface Tables {}\n\n// biome-ignore lint/suspicious/noEmptyInterface: augmentation target — filled by generated palbase-env.d.ts.\n/**\n * Tables in schemas other than `public`, reached with\n * `Database.schema(\"<name>\").tables.*`. Declaring a schema does not put it on\n * the internet — see `exposed`.\n */\nexport interface Schemas {}\n\n// BUCKETS MOVED TO `@palbase/backend/stack` (2026-08-29).\n//\n// `BucketTypes` and `Buckets` lived here because `config/storage.ts` declared\n// buckets and the deploy folded them into `palbase-env.d.ts` beside the schema's\n// tables. Buckets never came from the schema, and they do not come from a\n// declaration any more: the STACK holds them, so their types are generated into\n// `palbase-stack.d.ts` with the secrets and flags.\n//\n// Re-exported here so `Storage.buckets` keeps its one import site and no caller\n// has to learn that the source moved.\nexport type { BucketTypes, Buckets } from \"../stack.js\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/db/env.d.cts

@@ -27,28 +27,37 @@ export { BucketTypes, Buckets } from '../stack.cjs';
  *   type Todo = Tables["todos"]["row"];
  */
 /**
- * One typed table's shapes and its position in the user-rooted graph:
+ * One typed table's shapes and its relations:
  *
  * - `row` — the full row, every column present.
  * - `insert` — the write payload, required vs optional columns.
- * - `owner` — the column that foreign-keys `auth.users` (declared in
- *   `db/schema.ts` with `.referencesAuthUser(...)`), or `null` when the table
- *   is not user-rooted. This is what makes a seed/fixture DSL able to OMIT the
- *   owner column from the author-facing type: the apply step fills it.
- * - `children` — tables that foreign-key THIS table, mapped to the FK column on
- *   the child (`{ todos: "list_id" }`). Lets a nested seed attach children
- *   without the author ever writing the FK. Self-FKs and cycle back-edges are
- *   omitted by the generator so recursive types over `children` terminate.
+ * - `relations` — every foreign key this table takes part in, named, in both
+ *   directions. `{ list: { to: "lists", kind: "one", via: "list_id" } }` on the
+ *   child; `{ todos: { to: "todos", kind: "many", via: "list_id" } }` on the
+ *   parent. Ownership declared with `ownedByUser()` appears as `owner`.
  *
  * The generated `palbase-env.d.ts` fills `row`/`insert` with flat object types —
  * no `ColumnBuilder` phantom types ever appear in the generated output — and
- * `owner`/`children` with string literals.
+ * `relations` with string literals.
  */
 interface TableTypes {
     row: Record<string, unknown>;
     insert: Record<string, unknown>;
-    owner: string | null;
-    children: Record<string, string>;
+    /**
+     * The table's relations, derived from its declared foreign keys.
+     *
+     * Replaces the old `owner` / `children` pair, which nothing ever read: `owner`
+     * was whichever column happened to reference `auth.users` FIRST in declaration
+     * order, and `children` silently kept only ONE foreign key per parent.
+     *
+     * `to` is the target's table key — bare for `public`, schema-qualified
+     * otherwise, the same convention `RefJSON.table` uses.
+     */
+    relations: Record<string, {
+        to: string;
+        kind: "one" | "many";
+        via: string;
+    }>;
 }
 /**
  * The project's tables, keyed by table name. EMPTY by default; the generated
@@ -57,5 +66,12 @@ interface TableTypes {
  */
 interface Tables {
 }
+/**
+ * Tables in schemas other than `public`, reached with
+ * `Database.schema("<name>").tables.*`. Declaring a schema does not put it on
+ * the internet — see `exposed`.
+ */
+interface Schemas {
+}
 
-export type { TableTypes, Tables };
+export type { Schemas, TableTypes, Tables };

package/dist/db/env.d.ts

@@ -27,28 +27,37 @@ export { BucketTypes, Buckets } from '../stack.js';
  *   type Todo = Tables["todos"]["row"];
  */
 /**
- * One typed table's shapes and its position in the user-rooted graph:
+ * One typed table's shapes and its relations:
  *
  * - `row` — the full row, every column present.
  * - `insert` — the write payload, required vs optional columns.
- * - `owner` — the column that foreign-keys `auth.users` (declared in
- *   `db/schema.ts` with `.referencesAuthUser(...)`), or `null` when the table
- *   is not user-rooted. This is what makes a seed/fixture DSL able to OMIT the
- *   owner column from the author-facing type: the apply step fills it.
- * - `children` — tables that foreign-key THIS table, mapped to the FK column on
- *   the child (`{ todos: "list_id" }`). Lets a nested seed attach children
- *   without the author ever writing the FK. Self-FKs and cycle back-edges are
- *   omitted by the generator so recursive types over `children` terminate.
+ * - `relations` — every foreign key this table takes part in, named, in both
+ *   directions. `{ list: { to: "lists", kind: "one", via: "list_id" } }` on the
+ *   child; `{ todos: { to: "todos", kind: "many", via: "list_id" } }` on the
+ *   parent. Ownership declared with `ownedByUser()` appears as `owner`.
  *
  * The generated `palbase-env.d.ts` fills `row`/`insert` with flat object types —
  * no `ColumnBuilder` phantom types ever appear in the generated output — and
- * `owner`/`children` with string literals.
+ * `relations` with string literals.
  */
 interface TableTypes {
     row: Record<string, unknown>;
     insert: Record<string, unknown>;
-    owner: string | null;
-    children: Record<string, string>;
+    /**
+     * The table's relations, derived from its declared foreign keys.
+     *
+     * Replaces the old `owner` / `children` pair, which nothing ever read: `owner`
+     * was whichever column happened to reference `auth.users` FIRST in declaration
+     * order, and `children` silently kept only ONE foreign key per parent.
+     *
+     * `to` is the target's table key — bare for `public`, schema-qualified
+     * otherwise, the same convention `RefJSON.table` uses.
+     */
+    relations: Record<string, {
+        to: string;
+        kind: "one" | "many";
+        via: string;
+    }>;
 }
 /**
  * The project's tables, keyed by table name. EMPTY by default; the generated
@@ -57,5 +66,12 @@ interface TableTypes {
  */
 interface Tables {
 }
+/**
+ * Tables in schemas other than `public`, reached with
+ * `Database.schema("<name>").tables.*`. Declaring a schema does not put it on
+ * the internet — see `exposed`.
+ */
+interface Schemas {
+}
 
-export type { TableTypes, Tables };
+export type { Schemas, TableTypes, Tables };