@palbase/backend 23.1.0 → 24.0.0

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-DRFxf07H.cjs';
+import '../endpoint-CcQ1a36a.cjs';
 import '../stack.cjs';
 import 'node:async_hooks';
-import '../index-By8Dle5U.cjs';
+import '../index-D-4-PNuQ.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-D17r-MKb.js';
+import '../endpoint-0_DGBajf.js';
 import '../stack.js';
 import 'node:async_hooks';
-import '../index-CwAJ7HEe.js';
+import '../index-CJiJU9ux.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-NXDH6VQJ.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-CJiJU9ux.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 = 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.
      *
@@ -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> ? [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. */
@@ -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-By8Dle5U.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-c9h5jriX.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';
@@ -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 = 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.
      *
@@ -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> ? [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. */
@@ -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"] & {