@palbase/backend 23.0.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-E7OscPJT.cjs';
-import '../endpoint-i8TTCohk.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-Bmvx1EvJ.cjs';
+import '../index-D-4-PNuQ.cjs';
 import '../db/env.cjs';
-import '../registry-C3H2uPeZ.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-B7YBEG5w.js';
-import '../endpoint-BavvbW4P.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-B3jmmItD.js';
+import '../index-CJiJU9ux.js';
 import '../db/env.js';
-import '../registry-DY3d9l1k.js';
+import '../registry-CEod_5sz.js';
 import 'zod';

package/dist/engine/index.js

@@ -16,10 +16,10 @@ import {
   quoteIdent,
   scrubSecrets,
   withTables
-} from "../chunk-REZU6UKT.js";
-import "../chunk-FSGSB42K.js";
-import "../chunk-W5ODXPY3.js";
-import "../chunk-OMRTHM4X.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-B3jmmItD.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-BavvbW4P.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';
@@ -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.