@palbase/backend 23.1.0 → 24.0.1

package/dist/engine/index.d.cts

@@ -1,8 +1,8 @@
-export { A as App, h as AuthVerifier, B as BootRefused, i as CreateAppOptions, E as EgressPolicy, j as EngineConfig, M as ModuleClients, k as RateLimiter, l as RequestDatabase, m as RouteEntry, n as RuntimeHooks, o as ScrubResult, p as SqlDriver, q as SqlTx, r as buildRouteTable, s as createApp, t as createLazyTransaction, u as createOps, v as createRequestDatabase, w as effectiveAuth, x as hostAllowed, y as installEgressFence, z as loadConfig, G as makeMemoryCache, H as matchRoute, I as quoteIdent, J as scrubSecrets, K as withTables } from '../index-CxeQSfJP.cjs';
-import '../endpoint-c9h5jriX.cjs';
+export { A as App, m as AuthVerifier, B as BootRefused, n as CreateAppOptions, E as EgressPolicy, p as EngineConfig, M as ModuleClients, q as RateLimiter, r as RequestDatabase, s as RouteEntry, t as RuntimeHooks, u as ScrubResult, v as SqlDriver, w as SqlTx, x as buildRouteTable, y as createApp, z as createLazyTransaction, G as createOps, H as createRequestDatabase, I as effectiveAuth, J as hostAllowed, K as installEgressFence, O as loadConfig, P as makeMemoryCache, Q as matchRoute, T as quoteIdent, U as scrubSecrets, V as withTables } from '../index-C84bLgeO.cjs';
+import '../endpoint-CcQ1a36a.cjs';
 import '../stack.cjs';
 import 'node:async_hooks';
-import '../index-By8Dle5U.cjs';
+import '../index-MoQ31B6M.cjs';
 import '../db/env.cjs';
-import '../registry-CqPK2Qby.cjs';
+import '../registry-1X-skBNu.cjs';
 import 'zod';

package/dist/engine/index.d.ts

@@ -1,8 +1,8 @@
-export { A as App, h as AuthVerifier, B as BootRefused, i as CreateAppOptions, E as EgressPolicy, j as EngineConfig, M as ModuleClients, k as RateLimiter, l as RequestDatabase, m as RouteEntry, n as RuntimeHooks, o as ScrubResult, p as SqlDriver, q as SqlTx, r as buildRouteTable, s as createApp, t as createLazyTransaction, u as createOps, v as createRequestDatabase, w as effectiveAuth, x as hostAllowed, y as installEgressFence, z as loadConfig, G as makeMemoryCache, H as matchRoute, I as quoteIdent, J as scrubSecrets, K as withTables } from '../index-BZrJXnVh.js';
-import '../endpoint-CVWXh6oG.js';
+export { A as App, m as AuthVerifier, B as BootRefused, n as CreateAppOptions, E as EgressPolicy, p as EngineConfig, M as ModuleClients, q as RateLimiter, r as RequestDatabase, s as RouteEntry, t as RuntimeHooks, u as ScrubResult, v as SqlDriver, w as SqlTx, x as buildRouteTable, y as createApp, z as createLazyTransaction, G as createOps, H as createRequestDatabase, I as effectiveAuth, J as hostAllowed, K as installEgressFence, O as loadConfig, P as makeMemoryCache, Q as matchRoute, T as quoteIdent, U as scrubSecrets, V as withTables } from '../index-dJNhDZ7j.js';
+import '../endpoint-0_DGBajf.js';
 import '../stack.js';
 import 'node:async_hooks';
-import '../index-CwAJ7HEe.js';
+import '../index-BOS_rFBO.js';
 import '../db/env.js';
-import '../registry-B3niOVYp.js';
+import '../registry-CEod_5sz.js';
 import 'zod';

package/dist/engine/index.js

@@ -16,10 +16,10 @@ import {
   quoteIdent,
   scrubSecrets,
   withTables
-} from "../chunk-M5MCBWJI.js";
-import "../chunk-OHALWEOG.js";
-import "../chunk-NS5V43YQ.js";
-import "../chunk-RCLNBJCM.js";
+} from "../chunk-YSQBC2VL.js";
+import "../chunk-7Z6MGMXQ.js";
+import "../chunk-P2Q27SGP.js";
+import "../chunk-H3JAISUY.js";
 import "../chunk-7D4SUZUM.js";
 export {
   AuthVerifier,

package/dist/{index-CwAJ7HEe.d.ts → index-BOS_rFBO.d.ts}

@@ -1,5 +1,5 @@
 import { Tables, TableTypes } from './db/env.js';
-import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-CVWXh6oG.js';
+import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-0_DGBajf.js';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -50,12 +50,33 @@ interface ColumnDef {
     /** vector(n): the declared dimension count — part of the TYPE (typmod), read
      * by the wire serializer and the deploy's auto-index (FR-001). */
     dimensions?: number;
+    /**
+     * How the stored value is projected in and out of this process (FR-009).
+     *
+     * NOT part of the DDL: the column's Postgres type is unchanged and this pair
+     * is never serialized into a migration. It exists so the row surface can hand
+     * back the type the application actually works with.
+     */
+    transform?: ColumnTransform;
+}
+/**
+ * The read/write pair a column may declare (FR-009).
+ *
+ * `fromDb` takes whatever the driver produced for this column and returns the
+ * value the application sees; `toDb` is its inverse on the way out. Kept
+ * deliberately unexported — a column declares one inline, nobody needs to name
+ * the shape.
+ */
+interface ColumnTransform<T = unknown> {
+    fromDb: (value: unknown) => T;
+    toDb: (value: T) => unknown;
 }
 declare const __colKind: unique symbol;
 declare const __colNullable: unique symbol;
 declare const __colHasDefault: unique symbol;
 declare const __colEnumValues: unique symbol;
 declare const __colPayload: unique symbol;
+declare const __colTransform: unique symbol;
 /**
  * Fluent column builder with phantom type params:
  *  K — ColumnType literal (e.g. "text", "integer")
@@ -63,34 +84,38 @@ declare const __colPayload: unique symbol;
  *  D — boolean: true when a default has been set
  *  E — enum value union (never for non-enum columns)
  *  P — jsonb payload shape (unknown unless jsonb<T>() supplied one)
+ *  T — transform target type (`never` when the column declares no transform;
+ *      `never` is the sentinel because it is the only type that survives
+ *      `[T] extends [never]` and never collides with a real target type)
  *
- * All five params have defaults so bare `ColumnBuilder` (no args) still
+ * All six params have defaults so bare `ColumnBuilder` (no args) still
  * satisfies `Record<string, ColumnBuilder>` in schema.ts without modification.
  *
- * The five `declare readonly` brand fields carry the phantom types into the
+ * The six `declare readonly` brand fields carry the phantom types into the
  * structural shape so that conditional types like ColValue<C> can discriminate
  * on K without requiring runtime values on those fields.
  */
-declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean = boolean, D extends boolean = boolean, E = unknown, P = unknown> {
+declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean = boolean, D extends boolean = boolean, E = unknown, P = unknown, T = unknown> {
     readonly [__colKind]: K;
     readonly [__colNullable]: N;
     readonly [__colHasDefault]: D;
     readonly [__colEnumValues]: E;
     readonly [__colPayload]: P;
+    readonly [__colTransform]: T;
     readonly _def: ColumnDef;
     constructor(type: K, existingDef?: ColumnDef);
     /** Mark this column as the primary key. */
-    primaryKey(): ColumnBuilder<K, N, D, E, P>;
+    primaryKey(): ColumnBuilder<K, N, D, E, P, T>;
     /** Mark this column as NOT NULL (default). */
-    notNull(): ColumnBuilder<K, false, D, E, P>;
+    notNull(): ColumnBuilder<K, false, D, E, P, T>;
     /** Allow NULL values. */
-    nullable(): ColumnBuilder<K, true, D, E, P>;
+    nullable(): ColumnBuilder<K, true, D, E, P, T>;
     /** Set a default value. */
-    default(value: unknown): ColumnBuilder<K, N, true, E, P>;
+    default(value: unknown): ColumnBuilder<K, N, true, E, P, T>;
     /** UUID: generate a random default (gen_random_uuid()). */
-    defaultRandom(): ColumnBuilder<K, N, true, E, P>;
+    defaultRandom(): ColumnBuilder<K, N, true, E, P, T>;
     /** Timestamp: default to now(). */
-    defaultNow(): ColumnBuilder<K, N, true, E, P>;
+    defaultNow(): ColumnBuilder<K, N, true, E, P, T>;
     /**
      * The DATABASE assigns this column's value — a trigger, a rule, an identity.
      *
@@ -102,7 +127,7 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
      * they are a different thing; borrowing the word would send a reader — or a
      * model writing a schema — to the wrong feature.
      */
-    dbAssigned(): ColumnBuilder<K, N, true, E, P>;
+    dbAssigned(): ColumnBuilder<K, N, true, E, P, T>;
     /** Add a foreign key reference. */
     /**
      * Declares that this column used to be called `previous`.
@@ -115,8 +140,8 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
      * Once the rename has been applied the annotation is inert (the old name is no
      * longer there to rename), so it can be deleted at your leisure.
      */
-    renamedFrom(previous: string): ColumnBuilder<K, N, D, E, P>;
-    references(table: string, column: string): ColumnBuilder<K, N, D, E, P>;
+    renamedFrom(previous: string): ColumnBuilder<K, N, D, E, P, T>;
+    references(table: string, column: string): ColumnBuilder<K, N, D, E, P, T>;
     /**
      * Add a real DB-level foreign key to the built-in auth users
      * (`REFERENCES auth.users(id)`), so a column like `user_id` gets true
@@ -137,7 +162,7 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
      * express (referencing column is text, `set null` needs a nullable column) —
      * as the real boundary; this signature is the compile-time DX mirror.
      */
-    referencesAuthUser(onDelete: AuthUserOnDelete): ColumnBuilder<K, N, D, E, P>;
+    referencesAuthUser(onDelete: AuthUserOnDelete): ColumnBuilder<K, N, D, E, P, T>;
     /**
      * Add a real DB-level foreign key to the canonical, server-minted installation
      * anchor (`REFERENCES auth.installations(id)`) — the app-scoped verified-device
@@ -156,11 +181,30 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
      * blocked by a lingering FK. The server (validateAuthAnchorFK) is the real
      * boundary; this signature is the compile-time DX mirror.
      */
-    referencesInstallation(onDelete: AuthUserOnDelete): ColumnBuilder<K, N, D, E, P>;
+    referencesInstallation(onDelete: AuthUserOnDelete): ColumnBuilder<K, N, D, E, P, T>;
     /** Set the ON DELETE action for a foreign key reference. */
-    onDelete(action: OnDeleteAction): ColumnBuilder<K, N, D, E, P>;
+    onDelete(action: OnDeleteAction): ColumnBuilder<K, N, D, E, P, T>;
     /** Add a single-column UNIQUE constraint. */
-    unique(): ColumnBuilder<K, N, D, E, P>;
+    unique(): ColumnBuilder<K, N, D, E, P, T>;
+    /**
+     * Declare how this column's value is projected in and out of the process.
+     *
+     * The DDL does not move: `numeric` stays `numeric`, and the driver still hands
+     * back what Postgres sent. What changes is the type the row surface exposes —
+     * it becomes `Target`:
+     *
+     *   amount: numeric().transform<number>({ fromDb: Number, toDb: String })
+     *
+     * `numeric` surfacing as `string` is CORRECT (a JS number cannot hold
+     * arbitrary precision), and that is exactly why this exists: application code
+     * that does arithmetic on the column otherwise rewrites the same
+     * `Number(row.amount)` / `String(x)` pair in every controller that touches it,
+     * and each rewrite is a place the two directions can drift apart.
+     *
+     * A transform is a PROJECTION, never a constraint: it lives only in this
+     * process, so it can neither validate nor migrate what is stored.
+     */
+    transform<Target>(fns: ColumnTransform<Target>): ColumnBuilder<K, N, D, E, P, Target>;
 }
 /**
  * Extracts the TypeScript value type for a column, respecting nullability.
@@ -172,14 +216,22 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
  * - "boolean" → boolean
  * - "jsonb" → P (the dev-supplied payload shape from jsonb<T>(), else unknown)
  * - "enum" → E (the union of literal values)
+ *
+ * A declared `.transform<T>()` OVERRIDES the table above: the column then
+ * surfaces as T (or T | null when nullable), because that is the value the
+ * application is handed. Nullability is still the column's, not the
+ * transform's — `fromDb` is not called for a NULL.
  */
-type ColValue<C> = C extends ColumnBuilder<'uuid' | 'text' | 'timestamp' | 'bigint' | 'numeric', infer N, infer _D, infer _E, infer _P> ? N extends true ? string | null : string : C extends ColumnBuilder<'integer', infer N, infer _D, infer _E, infer _P> ? N extends true ? number | null : number : C extends ColumnBuilder<'boolean', infer N, infer _D, infer _E, infer _P> ? N extends true ? boolean | null : boolean : C extends ColumnBuilder<'jsonb', infer N, infer _D, infer _E, infer P> ? N extends true ? P | null : P : C extends ColumnBuilder<'vector', infer N, infer _D, infer _E, infer _P> ? N extends true ? number[] | null : number[] : C extends ColumnBuilder<'enum', infer N, infer _D, infer E, infer _P> ? N extends true ? E | null : E : never;
+type ColValue<C> = C extends ColumnBuilder<ColumnType, infer N, boolean, unknown, unknown, infer T> ? [unknown] extends [T] ? ColStoredValue<C> : N extends true ? T | null : T : never;
+/** The value as the DATABASE hands it over — the branch table above, before any
+ * transform. This is what a column's `fromDb` receives. */
+type ColStoredValue<C> = C extends ColumnBuilder<'uuid' | 'text' | 'timestamp' | 'bigint' | 'numeric', infer N, infer _D, infer _E, infer _P> ? N extends true ? string | null : string : C extends ColumnBuilder<'integer', infer N, infer _D, infer _E, infer _P> ? N extends true ? number | null : number : C extends ColumnBuilder<'boolean', infer N, infer _D, infer _E, infer _P> ? N extends true ? boolean | null : boolean : C extends ColumnBuilder<'jsonb', infer N, infer _D, infer _E, infer P> ? N extends true ? P | null : P : C extends ColumnBuilder<'vector', infer N, infer _D, infer _E, infer _P> ? N extends true ? number[] | null : number[] : C extends ColumnBuilder<'enum', infer N, infer _D, infer E, infer _P> ? N extends true ? E | null : E : never;
 /**
  * True when a column is optional on INSERT:
  *  - nullable columns (N = true) — the DB allows NULL so the field may be omitted
  *  - columns with a default (D = true) — the DB fills in the value when absent
  */
-type ColIsOptionalOnInsert<C> = C extends ColumnBuilder<infer _K, true, infer _D, infer _E> ? true : C extends ColumnBuilder<infer _K, infer _N, true, infer _E> ? true : false;
+type ColIsOptionalOnInsert<C> = C extends ColumnBuilder<ColumnType, true, boolean, unknown, unknown, unknown> ? true : C extends ColumnBuilder<ColumnType, boolean, true, unknown, unknown, unknown> ? true : false;
 /** Create a UUID column. */
 declare function uuid(): ColumnBuilder<'uuid', false, false, never>;
 /** Create a TEXT column. */
@@ -691,7 +743,15 @@ interface TypedTable<T extends TableDef> {
     update(id: string, data: Partial<InsertShape<T>>): Promise<RowShape<T> | null>;
     delete(id: string): Promise<void>;
     findById(id: string): Promise<RowShape<T> | null>;
-    findMany(query?: Partial<RowShape<T>>): Promise<RowShape<T>[]>;
+    /** Rows matching the filter. Operators, ordering and paging are the ENGINE's
+     * surface — this declaration is what makes them callable. */
+    findMany(query?: WhereFilter<RowShape<T>>, opts?: FindManyOpts<RowShape<T>>): Promise<RowShape<T>[]>;
+    /** Update every matching row in one statement; an empty filter is refused. */
+    updateMany(where: WhereFilter<RowShape<T>>, set: Partial<InsertShape<T>>): Promise<RowShape<T>[]>;
+    /** Delete every matching row; resolves to how many. Empty filter refused. */
+    deleteMany(where: WhereFilter<RowShape<T>>): Promise<number>;
+    /** How many rows match. An empty filter is legitimate: counting is a read. */
+    count(where?: WhereFilter<RowShape<T>>): Promise<number>;
 }
 /** A typed DB facade covering all tables declared in schema `S`. */
 interface TypedDB<S extends SchemaDef> {
@@ -730,6 +790,30 @@ type WhereOp<V> = V | {
     neq?: V;
     in?: V[];
 };
+/**
+ * A filter over a row: every field optional, each one a plain value (equality)
+ * or an operator object. THE filter language — `findMany`, `updateMany`,
+ * `deleteMany` and `count` all take this one, because two spellings of a filter
+ * is how the two come to disagree.
+ */
+type WhereFilter<Row> = {
+    [K in keyof Row]?: WhereOp<Row[K]>;
+};
+/**
+ * Ordering and paging for a read.
+ *
+ * `column` is `keyof Row`, not `string`: a mistyped column name is a compile
+ * error here rather than a runtime rejection three layers down. `offset`
+ * without `limit` is refused by the engine — a page with no size is not a page.
+ */
+type FindManyOpts<Row> = {
+    orderBy?: {
+        column: Extract<keyof Row, string>;
+        direction?: "asc" | "desc";
+    };
+    limit?: number;
+    offset?: number;
+};
 /** search() parametreleri, satır tipiyle koşullanmış (FR-013). `offset` BİLEREK yok (UD-013). */
 interface SearchParamsTyped<T extends TableTypes> {
     /** Metin sorgusu: FTS kolunu besler; embed beyanlıysa sorgu vektörü de bundan üretilir. */
@@ -809,7 +893,15 @@ interface EnvTypedTableBase<T extends TableTypes> {
     update(id: string, data: Partial<T["insert"]>): Promise<T["row"] | null>;
     delete(id: string): Promise<void>;
     findById(id: string): Promise<T["row"] | null>;
-    findMany(query?: Partial<T["row"]>): Promise<T["row"][]>;
+    /** Rows matching the filter. See {@link WhereFilter} / {@link FindManyOpts} —
+     * this declaration is what makes the engine's operators callable. */
+    findMany(query?: WhereFilter<T["row"]>, opts?: FindManyOpts<T["row"]>): Promise<T["row"][]>;
+    /** Update every matching row in one statement; an empty filter is refused. */
+    updateMany(where: WhereFilter<T["row"]>, set: Partial<T["insert"]>): Promise<T["row"][]>;
+    /** Delete every matching row; resolves to how many. Empty filter refused. */
+    deleteMany(where: WhereFilter<T["row"]>): Promise<number>;
+    /** How many rows match. An empty filter is legitimate: counting is a read. */
+    count(where?: WhereFilter<T["row"]>): Promise<number>;
     /** Validity'li tabloda satırın yeni versiyonu (FR-029, C-9): eski satır
      * kapanır (valid_to/superseded_by), yenisi TEK savepoint'te eklenir; dönüş
      * yeni satır. Validity beyanı olmayan tabloda adlandırılmış çalışma-zamanı
@@ -832,6 +924,18 @@ type EnvTypedTable<T extends TableTypes> = EnvTypedTableBase<T> & (T extends {
     similar(id: string, params?: SimilarParamsTyped<T>): Promise<Array<T["row"] & {
         _score: number;
     }>>;
+    /** D-021: sayaçlar bağımsız dönüşle — search'ün dizi-üstü _facets'i
+     * JSON.stringify'da kaybolur; ciddi sözleşme budur. */
+    facets(params: {
+        facets: Array<keyof T["row"] & string>;
+        where?: Partial<T["row"]>;
+        validity?: "all" | {
+            asOf: string;
+        };
+    }): Promise<Record<string, {
+        value: string | null;
+        count: number;
+    }[]>>;
     /** positive/negative beğenilerden öneri (FR-023): hedef vektör DB-içi
      * avg CTE'leriyle; kaynak id'ler sonuçta yoktur. */
     recommend(params: RecommendParamsTyped<T>): Promise<Array<T["row"] & {

package/dist/{index-CxeQSfJP.d.cts → index-C84bLgeO.d.cts}

@@ -1,8 +1,8 @@
 import { Buckets, BucketTypes } from './stack.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, f as DBOps, T as TxPlanBody, g as TxPlanResponse } from './endpoint-c9h5jriX.cjs';
-import { E as EnvTypedDatabase } from './index-By8Dle5U.cjs';
-import { R as RouteMeta } from './registry-CqPK2Qby.cjs';
+import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, f as DBOps, T as TxPlanBody, g as TxPlanResponse, A as AuthSpec } from './endpoint-CcQ1a36a.cjs';
+import { E as EnvTypedDatabase } from './index-MoQ31B6M.cjs';
+import { R as RouteMeta } from './registry-1X-skBNu.cjs';
 
 /**
  * runtime.ts — request-scoped service singletons.
@@ -112,6 +112,72 @@ declare function __runWithRuntime<T>(services: RuntimeServices, fn: () => T): T;
  * process-global fallback (dev-server / tests). NOT part of the public
  * author-facing API — used by the runtime and the singleton Proxies. */
 declare function __getRuntime(): RuntimeServices;
+/** A lifecycle hook. Sync or async; the runtime awaits what it returns. */
+type LifecycleHook = () => void | Promise<void>;
+/** Runs one release's shutdown hooks. Handed back by {@link __runStartHooks}
+ * and called by the engine's `app.shutdown()`. Idempotent. */
+type ShutdownRunner = () => Promise<void>;
+/**
+ * Run `hook` ONCE while the application comes up, before it serves anything.
+ *
+ * Call it at MODULE SCOPE in a file the application imports — the same rule
+ * `defineDefaultAuth` and `@Controller` follow, and for the same reason: the
+ * declaration is claimed when the app boots, which is after module loading and
+ * before the first request. `name` is not decoration: a hook that throws is
+ * reported by that name and the boot is REFUSED, so it is what tells an
+ * operator which resource did not come up.
+ *
+ * There is no request scope yet, so the `Database`/`Secrets`/… singletons are
+ * NOT available inside a start hook. A secret is read from `process.env` here
+ * (the runtime mirrors the vault into it at boot).
+ *
+ * @example
+ * // resources/graph.ts
+ * import neo4j from "neo4j-driver";
+ * import { onStart, onShutdown } from "@palbase/backend";
+ *
+ * export let graph: Driver;
+ * onStart("graph", () => {
+ *   graph = neo4j.driver(process.env.NEO4J_URL!, neo4j.auth.basic("neo4j", process.env.NEO4J_PASSWORD!));
+ * });
+ * onShutdown("graph", () => graph.close());
+ */
+declare function onStart(name: string, hook: LifecycleHook): void;
+/**
+ * Run `hook` while the application shuts down — the place a pool opened in
+ * {@link onStart} is closed.
+ *
+ * Shutdown is BEST-EFFORT by design: a hook that throws is reported by name and
+ * the rest still run. A drain that abandoned the remaining hooks on the first
+ * failure would leak exactly what this exists to release, and the process is
+ * leaving anyway.
+ *
+ * Hooks run in REVERSE declaration order, so a resource is released before what
+ * it was built on.
+ */
+declare function onShutdown(name: string, hook: LifecycleHook): void;
+/**
+ * CLAIM what has been declared, run the start hooks, and hand back the runner
+ * for this release's shutdown hooks. Called by the engine's `createApp`; the
+ * `App.shutdown()` it builds calls what comes back. NOT part of the public
+ * author-facing API.
+ *
+ * IT CLAIMS RATHER THAN READS, which is what makes it correct in this runtime:
+ * a candidate release is loaded BESIDE the live one in one process
+ * (`v2/runtime/src/registry-scope.ts`), and both bundles append to the one
+ * shared slot above. If each app read the whole list, the live app's shutdown
+ * would close the candidate's pool and the candidate's would close the live
+ * app's. Taking the declarations leaves each app holding exactly its own.
+ *
+ * A start hook that throws REFUSES THE BOOT — with the hook's name in the
+ * message — after releasing whatever the earlier hooks already opened. Serving
+ * from a half-initialised app is the silence this whole surface replaces, and a
+ * boot that dies holding an open pool is the leak it replaces.
+ */
+declare function __runStartHooks(): Promise<ShutdownRunner>;
+/** Drop every declaration. For tests, which declare repeatedly in one process.
+ * NOT part of the public author-facing API. */
+declare function __resetLifecycleHooks(): void;
 /**
  * The project's own Postgres (pgx, schema `env_<envId>`).
  *
@@ -361,15 +427,18 @@ declare function createLazyTransaction(sql: SqlDriver, role: string, claimsJson:
 type LazyTransaction = ReturnType<typeof createLazyTransaction>;
 /** Either a live driver transaction or the lazy holder above. */
 type TxLike = SqlTx | LazyTransaction;
-/** What `findMany` accepts beside its filter: an ordering and a row ceiling.
- * Both used to require dropping to raw SQL, and the docs said so — which is how
- * a tenant's controllers filled up with hand-written SELECTs. */
+/** What `findMany` accepts beside its filter: an ordering, a row ceiling and a
+ * page offset. All three used to require dropping to raw SQL, and the docs said
+ * so — which is how a tenant's controllers filled up with hand-written SELECTs. */
 interface FindManyOptions {
     orderBy?: {
         column: string;
         direction?: "asc" | "desc";
     };
     limit?: number;
+    /** Rows to skip before the page starts. Only meaningful with `limit`, and
+     * refused without it — see `offsetClause`. */
+    offset?: number;
 }
 /** The six string-keyed operations, plus an interactive `transaction`. */
 declare function createOps(tx: TxLike): {
@@ -394,6 +463,41 @@ declare function createOps(tx: TxLike): {
     }): Promise<Row>;
     update(table: string, id: string, data: Row): Promise<Row | null>;
     delete(table: string, id: string): Promise<void>;
+    /**
+     * Update every row the filter matches, in ONE statement.
+     *
+     * The capability was already here and only reachable from inside a
+     * transaction plan (`tx.tables.x.updateWhere`, since 11.0.0). Outside it the
+     * only door was `update(id, …)`, so "mark every unapproved row in this
+     * household" was an N+1 loop or hand-written SQL — and hand-written SQL is
+     * where the typed surface and RLS both stop helping.
+     *
+     * The filter language is `findMany`'s, compiled by the same `compileWhere`:
+     * one filter language, or the two spellings drift.
+     *
+     * AN EMPTY FILTER IS REFUSED. `UPDATE … WHERE true` is a whole-table write,
+     * and the shape that produces it by accident — a filter object built from
+     * request input that happened to come back empty — is exactly the shape that
+     * should not silently succeed. Callers who mean every row say so with a
+     * predicate that is true for every row.
+     */
+    updateMany(table: string, where: Row, set: Row): Promise<Row[]>;
+    /**
+     * Delete every row the filter matches, in ONE statement; resolves to how
+     * many went. Same filter language, same empty-filter refusal as
+     * {@link updateMany} — and here the accident is worse.
+     */
+    deleteMany(table: string, where: Row): Promise<number>;
+    /**
+     * How many rows match — the half of pagination `limit`/`offset` cannot
+     * supply. Without it a page count is either a guess or "fetch everything and
+     * read .length", and the second one is the scale risk this surface exists to
+     * remove.
+     *
+     * An empty filter is legitimate HERE: counting a whole table is a read, and
+     * reads do not destroy anything.
+     */
+    count(table: string, where?: Row): Promise<number>;
     findById(table: string, id: string): Promise<Row | null>;
     findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
     /**
@@ -444,6 +548,21 @@ declare function createOps(tx: TxLike): {
      * tek SQL'de "id yok" ile "0 komşu" ayrılamazdı; +1 küçük turla id-yokluğu
      * adlandırılmış hataya çevrilir. Sonuç şekli search ile aynı (FR-015).
      */
+    /** D-021 (FR-027 DX): sayaçlar BAĞIMSIZ op'la — search'ün dizi-üstü
+     * `_facets` özelliği JSON.stringify'da kaybolur (dizi özelliği), tenant
+     * yanıtına koyunca sessizce yok olurdu. Ayrı dönüş ciddi bir sözleşmedir;
+     * search'teki alan geriye-uyum için DURUR. where + validity default'u
+     * sayaçlara da uygulanır (sayaç, kullanıcının gördüğü kümeyi anlatır). */
+    facets(table: string, params: {
+        facets: string[];
+        where?: Record<string, unknown>;
+        validity?: "all" | {
+            asOf: string;
+        };
+    }): Promise<Record<string, {
+        value: string | null;
+        count: number;
+    }[]>>;
     similar(table: string, id: string, opts?: {
         where?: Record<string, unknown>;
         limit?: number;
@@ -632,8 +751,11 @@ interface RouteEntry {
     instance: Record<string, (...args: unknown[]) => unknown>;
     /** `GET /todos/{id}` — stable, human-readable, used as the rate-limit key. */
     id: string;
-    /** The controller's `auth` default, if it declared one. */
-    controllerAuth: unknown;
+    /** The auth spec that applies when the route itself declares none —
+     * controller default ?? application default ?? `true`, resolved once at boot
+     * by `resolveEffectiveAuth`. `engine/index.ts` reconciles the route's own
+     * spec against it per request. */
+    controllerAuth: AuthSpec;
 }
 /**
  * Build the table from controller classes.
@@ -641,6 +763,9 @@ interface RouteEntry {
  * @throws when a class carries no routes — a controller that collected zero
  *   endpoints is the silent failure this whole runtime is built to refuse, and
  *   it must be loud at boot rather than a 404 in production.
+ * @throws when a class declares constructor parameters — the same class of
+ *   silence one level down (FR-010): nothing here has an argument to pass, so
+ *   the field would simply be `undefined` in production.
  */
 declare function buildRouteTable(controllers: readonly unknown[]): RouteEntry[];
 interface RouteMatch {
@@ -924,4 +1049,4 @@ interface App {
  */
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
-export { type App as A, BootRefused as B, Cache as C, Database as D, type EgressPolicy as E, Flags as F, makeMemoryCache as G, matchRoute as H, quoteIdent as I, scrubSecrets as J, withTables as K, Log as L, type ModuleClients as M, Notifications as N, Realtime as R, Secrets as S, __getRuntime as _, Documents as a, type RequestStore as b, type RuntimeServices as c, Storage as d, __requestALS as e, __runWithRuntime as f, __setRuntime as g, AuthVerifier as h, type CreateAppOptions as i, type EngineConfig as j, RateLimiter as k, type RequestDatabase as l, type RouteEntry as m, type RuntimeHooks as n, type ScrubResult as o, type SqlDriver as p, type SqlTx as q, buildRouteTable as r, createApp as s, createLazyTransaction as t, createOps as u, createRequestDatabase as v, effectiveAuth as w, hostAllowed as x, installEgressFence as y, loadConfig as z };
+export { type App as A, BootRefused as B, Cache as C, Database as D, type EgressPolicy as E, Flags as F, createOps as G, createRequestDatabase as H, effectiveAuth as I, hostAllowed as J, installEgressFence as K, type LifecycleHook as L, type ModuleClients as M, Notifications as N, loadConfig as O, makeMemoryCache as P, matchRoute as Q, Realtime as R, Secrets as S, quoteIdent as T, scrubSecrets as U, withTables as V, __getRuntime as _, Documents as a, Log as b, type RequestStore as c, type RuntimeServices as d, type ShutdownRunner as e, Storage as f, __requestALS as g, __resetLifecycleHooks as h, __runStartHooks as i, __runWithRuntime as j, __setRuntime as k, onStart as l, AuthVerifier as m, type CreateAppOptions as n, onShutdown as o, type EngineConfig as p, RateLimiter as q, type RequestDatabase as r, type RouteEntry as s, type RuntimeHooks as t, type ScrubResult as u, type SqlDriver as v, type SqlTx as w, buildRouteTable as x, createApp as y, createLazyTransaction as z };