@palbase/backend 23.0.0 → 24.0.0

package/dist/{index-Bmvx1EvJ.d.cts → index-D-4-PNuQ.d.cts}

@@ -1,5 +1,5 @@
 import { Tables, TableTypes } from './db/env.cjs';
-import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-i8TTCohk.cjs';
+import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-CcQ1a36a.cjs';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -36,15 +36,47 @@ interface ColumnDef {
     enumName?: string;
     enumValues?: string[];
     unique?: boolean;
+    /**
+     * The value is written by the DATABASE — a trigger, a rule, an identity — not by
+     * the author and not by a DEFAULT this schema declares. It makes the column
+     * optional on INSERT without putting a DEFAULT in the DDL.
+     *
+     * Before this existed the only way to keep a trigger-filled column off the
+     * INSERT type was to give it a fake `default()`: a value the schema claimed to
+     * write and the trigger immediately overwrote. That made the schema lie about
+     * its own data.
+     */
+    dbAssigned?: boolean;
     /** 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")
@@ -52,34 +84,50 @@ 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 = never> {
     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.
+     *
+     * The column becomes optional on INSERT (the author has nothing to send) while
+     * the DDL stays free of a DEFAULT this schema would not honour. It is NOT
+     * `default()`: that declares a value the schema promises to write.
+     *
+     * Naming: deliberately not `generated()`. Postgres has GENERATED columns and
+     * 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, T>;
     /** Add a foreign key reference. */
     /**
      * Declares that this column used to be called `previous`.
@@ -92,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
@@ -114,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
@@ -133,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.
@@ -149,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> ? [T] extends [never] ? 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. */
@@ -247,22 +322,6 @@ interface PolicyDef {
     withCheck: string | null;
     permissive: boolean;
 }
-/**
- * Fluent RLS policy builder.
- *
- * Defaults (documented, applied at construction):
- *  - `command`: `"all"` — applies to every SQL command unless `.for(...)` narrows it.
- *  - `roles`: `["authenticated"]` — the common case is "rule applies to signed-in
- *    users". Call `.to(...)` to override; pass `.to()` with no roles (or never
- *    call it after a reset) to target PUBLIC.
- *  - `using` / `withCheck`: `null` — no row filter / write check until set.
- *  - `permissive`: `true` — `AS PERMISSIVE` (policies OR together).
- *
- * Each method mutates `_def` in place and returns `this`, so the chain is a
- * single builder instance (no per-call allocation, like a tagged-template
- * compile target). The terminal `PolicyDef` is read directly off `_def` by
- * `schema_extract.js`.
- */
 declare class PolicyBuilder {
     readonly _def: PolicyDef;
     constructor(name: string);
@@ -280,6 +339,34 @@ declare class PolicyBuilder {
     to(...roles: string[]): this;
     /** Set the `USING (...)` row-visibility expression (raw SQL). */
     using(sqlExpr: string): this;
+    /**
+     * "Rows of THIS table whose owner the caller is a member of" — the membership
+     * pattern, written so it cannot recurse.
+     *
+     * THE TRAP IT EXISTS FOR. Written by hand, membership policies point at each
+     * other: `channels` is visible to members, so its policy reads
+     * `channel_members`; `channel_members` is visible to members, so its policy
+     * reads `channels`. Postgres refuses the pair at query time with `infinite
+     * recursion detected in policy for relation ...`, and the error names the
+     * relation but not the cycle. The way out is asymmetry — the MEMBERSHIP table
+     * is protected by `user_id = auth.uid()` and nothing else, and every other
+     * table subqueries INTO it. That shape was in the platform's own schema and
+     * written down nowhere; a customer recovered it by reading that schema.
+     *
+     * `(select auth.uid())` rather than a bare call: the scalar subquery is
+     * evaluated ONCE per statement instead of per row.
+     *
+     * @example
+     * // channels: visible to members. The membership table gets the simple one.
+     * policy("member_read").for("select").to("authenticated")
+     *   .memberOf("channel_members", "channel_id")
+     * // → id IN (SELECT "channel_id" FROM "channel_members"
+     * //          WHERE "user_id" = (select auth.uid()))
+     */
+    memberOf(membershipTable: string, foreignKey: string, options?: {
+        column?: string;
+        userColumn?: string;
+    }): this;
     /** Set the `WITH CHECK (...)` write-validation expression (raw SQL). */
     withCheck(sqlExpr: string): this;
     /** Set the policy mode: `"permissive"` (default, OR-combined) or
@@ -647,13 +734,24 @@ type RowShape<T extends TableDef> = {
 /** A typed table accessor that mirrors the runtime DBClient surface. */
 interface TypedTable<T extends TableDef> {
     insert(data: InsertShape<T>): Promise<RowShape<T>>;
+    upsert(data: InsertShape<T>, opts: {
+        onConflict: readonly string[];
+    }): Promise<RowShape<T>>;
     /** Update the row by id; resolves to the updated row, or `null` if no row
      * matched (absent or RLS-hidden) — an idempotent outcome, mirroring
      * `findById`. The runtime returns a null row rather than throwing. */
     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> {
@@ -692,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. */
@@ -755,13 +877,31 @@ type RecommendParamsTyped<T extends TableTypes> = SimilarParamsTyped<T> & {
 /** Temel tablo erişimcisi — search'süz beş op. */
 interface EnvTypedTableBase<T extends TableTypes> {
     insert(data: T["insert"]): Promise<T["row"]>;
+    /**
+     * Insert the row, or update it when it collides on `onConflict`.
+     *
+     * The conflict columns must carry a unique constraint or index — that is what
+     * Postgres matches on — and they are excluded from the update, since they are
+     * what matched.
+     */
+    upsert(data: T["insert"], opts: {
+        onConflict: readonly Extract<keyof T["row"], string>[];
+    }): Promise<T["row"]>;
     /** Update the row by id; resolves to the updated row, or `null` if no row
      * matched (absent or RLS-hidden) — an idempotent outcome, mirroring
      * `findById`. The runtime returns a null row rather than throwing. */
     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ı
@@ -784,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"] & {
@@ -856,6 +1008,27 @@ interface EnvTypedDatabase extends Omit<DBClient, "txPlan" | "asService"> {
      * });
      */
     transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
+    /**
+     * Run `fn` inside a SAVEPOINT, so a write that fails in it does not poison the
+     * rest of the request.
+     *
+     * A request is ONE Postgres transaction: a failed statement aborts it and
+     * every later one answers `current transaction is aborted`. That is why
+     * "insert, catch the unique violation, update instead" cannot be written
+     * directly — and why {@link EnvTypedTableBase.upsert} exists for the common
+     * case. Reach for `attempt` when the recovery is not an upsert.
+     *
+     * The handle is a parameter, not the ambient `Database`: only what `tx` writes
+     * is inside the boundary, so a concurrent branch of the same request cannot be
+     * rolled back by someone else's failure.
+     *
+     * @example
+     * const claimed = await Database.attempt(async (tx) => {
+     *   await tx.insert("seats", { row: 4, seat: 12, user_id: user.id });
+     *   return true;
+     * }).catch(() => false);
+     */
+    attempt<T>(fn: (tx: Omit<DBClient, "attempt" | "txPlan" | "asService">) => Promise<T>): Promise<T>;
     /**
      * Return a sibling that bypasses RLS by running as the `service_role`. Use
      * sparingly and explicitly — the default `Database.*` path is RLS-enforced.

package/dist/{index-B7YBEG5w.d.ts → index-D17r-MKb.d.ts}

@@ -1,8 +1,8 @@
 import { Buckets, BucketTypes } from './stack.js';
 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, T as TxPlanBody, f as TxPlanResponse } from './endpoint-BavvbW4P.js';
-import { E as EnvTypedDatabase } from './index-B3jmmItD.js';
-import { R as RouteMeta } from './registry-DY3d9l1k.js';
+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-0_DGBajf.js';
+import { E as EnvTypedDatabase } from './index-CJiJU9ux.js';
+import { R as RouteMeta } from './registry-CEod_5sz.js';
 
 /**
  * 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,14 +427,79 @@ 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, 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): {
     query(sql: string, params?: unknown[]): Promise<Row[]>;
     insert(table: string, data: Row): Promise<Row>;
+    /**
+     * INSERT the row, or UPDATE it when it collides on `onConflict`.
+     *
+     * WHY IT IS AN OPERATION rather than a recipe. "Try the insert, catch the
+     * unique violation, update instead" does not work here: a request runs in ONE
+     * Postgres transaction, so the failed insert aborts it and every later
+     * statement answers `current transaction is aborted`. A tenant measured that
+     * as 7 of 8 concurrent requests returning 500, gave up on upsert, and had a
+     * trigger create the row instead — a workaround that needs a new trigger for
+     * every table with a unique row.
+     *
+     * The conflict columns are excluded from the SET list: they are what MATCHED,
+     * so writing them back is at best a no-op and at worst a surprise.
+     */
+    upsert(table: string, data: Row, opts: {
+        onConflict: readonly string[];
+    }): 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): Promise<Row[]>;
+    findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
     /**
      * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
      * (1/(50+rank), CLAIM-N4). Operatör şema-nitelikli (C-10, M-1); GUC
@@ -417,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;
@@ -476,6 +622,24 @@ declare function createOps(tx: TxLike): {
     supersede(table: string, id: string, row: Row): Promise<Row>;
     /** A real SAVEPOINT inside the request's transaction. */
     transaction<T>(cb: (t: unknown) => Promise<T>): Promise<T>;
+    /**
+     * Run `fn` against a handle bound to a SAVEPOINT, so a failure inside it
+     * rolls back only what that handle wrote and the request can keep writing.
+     *
+     * WHY THE HANDLE IS AN ARGUMENT. The obvious shape — `attempt(async () => {
+     * ... Database.insert(...) ... })`, with no parameter — would have to point
+     * the ambient `Database` at the savepoint for the duration, and a request is
+     * concurrent with itself: `Promise.all([Database.insert(a),
+     * Database.attempt(...)])` would put `a` inside the savepoint and roll it
+     * back with it. Silent data loss, and the same interleaving this file already
+     * refuses for `asService()`. Passing the handle makes the boundary something
+     * you can see in the code that crosses it.
+     *
+     * Postgres, not us: the savepoint is released on success and rolled back on
+     * failure by the driver, so an aborted statement inside `fn` does not poison
+     * the surrounding transaction.
+     */
+    attempt<T>(fn: (tx: DBOps) => Promise<T>): Promise<T>;
     /**
      * Execute a whole transaction plan — what `Database.transaction(fn)` builds.
      *
@@ -587,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.
@@ -596,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 {
@@ -879,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 };