@palbase/backend 33.0.1 → 34.0.0

package/dist/{index-DB_nW-AV.d.cts → endpoint-kYgEHrrV.d.cts}

@@ -1,8 +1,112 @@
-import { Schemas, Tables, TableTypes } from './db/env.cjs';
 import { ZodSchema, z } from 'zod';
 import { PalbaseFlagKey, Buckets, BucketTypes, PalbaseSecretName } from './stack.cjs';
+import { Schemas, Tables, TableTypes } from './db/env.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
+interface CommandOptions {
+    /** auto uses the sequential plan when a command cannot be compiled or the
+     * executor is not installed. compiled refuses fallback; sequential opts out. */
+    mode?: "auto" | "compiled" | "sequential";
+}
+
+interface InsertManyOptions<Key extends string = string> {
+    onConflict?: readonly Key[];
+    /** Defaults to ignore when onConflict is supplied. */
+    action?: "ignore" | "update";
+    /** false returns the affected row count and skips row serialization. */
+    returning?: boolean;
+}
+
+/** Forward and backward requests are exclusive. Omit the size for 50 rows. */
+type PageNavigation = {
+    first?: number;
+    after?: string;
+    last?: never;
+    before?: never;
+} | {
+    last?: number;
+    before?: string;
+    first?: never;
+    after?: never;
+};
+interface PageInfo {
+    startCursor: string | null;
+    endCursor: string | null;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+}
+interface Page<Row> {
+    rows: Row[];
+    pageInfo: PageInfo;
+}
+/** The raw transport surface. Typed tables restrict column and relation names. */
+type RawPageOptions = PageNavigation & {
+    orderBy?: {
+        column: string;
+        direction?: "asc" | "desc";
+        nulls?: "first" | "last";
+    } | readonly {
+        column: string;
+        direction?: "asc" | "desc";
+        nulls?: "first" | "last";
+    }[];
+    select?: readonly string[];
+    with?: Record<string, unknown>;
+};
+
+interface DatabaseBudget {
+    /** Application statements, including failed statements and retry attempts. */
+    maxQueries?: number;
+    /** Root rows returned across application statements. Nested relation rows are included in bytes. */
+    maxRows?: number;
+    /** Estimated JSON result bytes; this is not PostgreSQL protocol traffic. */
+    maxBytes?: number;
+}
+interface DatabaseQueryEvent {
+    ordinal: number;
+    fingerprint: string;
+    name?: string;
+    sql?: string;
+    source?: string;
+    durationMs: number;
+    rows: number;
+    bytes: number;
+    errorCode?: string;
+}
+interface DatabaseDiagnostics {
+    endpoint?: string;
+    requestId?: string;
+    outcome: "active" | "committed" | "failed";
+    elapsedMs: number;
+    queries: number;
+    rows: number;
+    bytes: number;
+    queueMs: number;
+    /** Time until the driver's transaction callback starts; includes wire BEGIN. */
+    poolMs: number;
+    setupMs: number;
+    /** Driver wait including PostgreSQL execution/locks and network time. */
+    sqlMs: number;
+    commitMs: number;
+    rollbackMs: number;
+    commits: number;
+    commitFailures: number;
+    rollbackRequests: number;
+    retries: number;
+    /** Bounded to the first 200 completed statements. Totals include every statement. */
+    statements: readonly DatabaseQueryEvent[];
+}
+interface DatabaseDiagnosticsOptions extends DatabaseBudget {
+    endpoint?: string;
+    requestId?: string;
+    /** Opt-in because a stack capture costs work on every statement. */
+    captureSource?: boolean;
+    /** SQL parameters are never recorded. Raw SQL text can contain inline literals. */
+    includeSql?: boolean;
+    onQuery?: (event: DatabaseQueryEvent) => void | Promise<void>;
+    onComplete?: (diagnostics: DatabaseDiagnostics) => void | Promise<void>;
+}
+
 /** Supported HTTP methods for endpoints. */
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 /**
@@ -144,6 +248,13 @@ type MiddlewareHandler = (ctx: MiddlewareContext, next: () => Promise<void>) =>
  */
 declare function defineMiddleware(_fn: MiddlewareHandler): never;
 
+/** A union of exact keys, not a partial row that could match many records. */
+type UniqueWhere<Row, Keys> = Keys extends readonly (infer Key extends readonly string[])[] ? Key extends unknown ? {
+    [K in Extract<Key[number], keyof Row>]-?: NonNullable<Row[K]>;
+} & {
+    [K in Exclude<keyof Row, Key[number]>]?: never;
+} : never : never;
+
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
 /**
@@ -2938,23 +3049,95 @@ declare const Flags: PalbaseFlagsAmbient;
  */
 declare const Realtime: PalbaseRealtimeClient;
 
-/**
- * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.
- *
- * Derives INSERT and full-row TypeScript types from a `defineSchema()` result
- * and wraps the untyped runtime `DBClient` with a typed facade.
- *
- * No value-any. No `as unknown as X`. The two narrow `as` casts in
- * `makeTypedTable` are safe because:
- *  - `data as Record<string, unknown>`: InsertShape<T> maps string keys to
- *    typed values; all value types are subsets of `unknown`, so the cast is
- *    structurally sound.
- *  - `result as RowShape<T>`: The runtime DBClient returns `Record<string,
- *    unknown>` which is the erased form of the typed row; we're narrowing back
- *    to the precise shape that the schema declared.
- * Both casts are narrowing only (not widening) and correctness is guaranteed
- * by the schema the caller provides.
- */
+/** Limits apply per engine process. PostgreSQL locks remain the authority when
+ * several replicas write the same rows. Size the total budget across replicas. */
+interface WorkloadOptions {
+    concurrency: number;
+    queueLimit: number;
+    tenantConcurrency?: number;
+    tenantQueueLimit?: number;
+    queueTimeoutMs?: number;
+    /** Read from authenticated claims; defaults to tenant_id, then sub, then one
+     * shared anonymous bucket. A request body never chooses the tenant budget. */
+    tenantClaim?: string;
+}
+interface DatabaseWorkload {
+    readonly name: string;
+    readonly concurrency: number;
+    readonly queueLimit: number;
+    readonly tenantConcurrency: number;
+    readonly tenantQueueLimit: number;
+    readonly queueTimeoutMs: number;
+    readonly tenantClaim: string;
+}
+/** Declare once at module scope and reuse on $atomic calls. Keys, queue limits
+ * and tenant budgets affect admission, not SQL permissions or isolation. */
+declare function defineWorkload(name: string, options: WorkloadOptions): DatabaseWorkload;
+
+/** A PostgreSQL isolation level supported by the explicit root transaction. */
+type TransactionIsolation = "read committed" | "repeatable read" | "serializable";
+interface AtomicOptions {
+    /** Each retry opens a fresh transaction and reruns the complete callback.
+     * Defaults to zero. Keep external effects outside it; persist an outbox instead. */
+    retry?: number;
+    isolation?: TransactionIsolation;
+    readOnly?: boolean;
+    /** Maximum wait for a PostgreSQL lock. Defaults to 5000 ms. */
+    lockTimeoutMs?: number;
+    /** PostgreSQL statement timeout; applies to every statement in this scope. */
+    statementTimeoutMs?: number;
+    /** Total work deadline including queueing and retries. Active Bun queries are
+     * cancelled; rollback settles before release. An in-flight COMMIT is awaited. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    workload?: DatabaseWorkload;
+    /** Resource names shared within a workload. Include a tenant prefix if the
+     * resource ID itself is only unique inside a tenant. Requires workload. */
+    conflictKeys?: readonly string[];
+}
+
+/** Storage metadata that affects the declared response; defaults and unrelated
+ * columns do not change an explicitly projected query's contract. */
+interface QueryColumnContract {
+    type: string;
+    nullable: boolean;
+    codec?: string;
+    enumValues?: readonly string[];
+    dimensions?: number;
+}
+interface PreparedRead {
+    name: string;
+    table: string;
+    columns: Record<string, QueryColumnContract>;
+    where: Record<string, unknown>;
+    options: {
+        select: string[];
+        orderBy?: {
+            column: string;
+            direction?: "asc" | "desc";
+            nulls?: "first" | "last";
+        } | {
+            column: string;
+            direction?: "asc" | "desc";
+            nulls?: "first" | "last";
+        }[];
+        limit?: number;
+    };
+}
+interface CompiledRead {
+    sql: string;
+    params: unknown[];
+}
+interface QueryDatabase {
+    readQuery(query: PreparedRead): Promise<Record<string, unknown>[]>;
+    compileQuery(query: PreparedRead): CompiledRead;
+    explainQuery(query: PreparedRead): Promise<unknown[]>;
+}
+interface EnvQueryDatabase {
+    $readQuery: QueryDatabase["readQuery"];
+    $compileQuery: QueryDatabase["compileQuery"];
+    $explainQuery: QueryDatabase["explainQuery"];
+}
 
 /** Keys of C whose columns are required on INSERT (not nullable, no default). */
 type RequiredKeys<C> = {
@@ -2986,12 +3169,22 @@ type RowShape<T extends TableDef> = {
 };
 /** A typed table accessor that mirrors the runtime DBClient surface. */
 interface TypedTable<T extends TableDef> {
+    /** Runtime validates the key against the installed schema. Generated env tables
+     * also check the complete unique/composite key at compile time. */
+    findUnique<K extends keyof RowShape<T> = keyof RowShape<T>>(q: {
+        where: Partial<RowShape<T>>;
+        select?: readonly K[];
+    }): Promise<Pick<RowShape<T>, K> | null>;
+    page<K extends keyof RowShape<T> = keyof RowShape<T>>(q?: PageInput<RowShape<T>, K>): Promise<Page<Pick<RowShape<T>, K>>>;
     insert(data: InsertValues<InsertShape<T>>): Promise<RowShape<T>>;
     /** Çok satır, TEK statement. Satırların anahtar kümesi aynı olmalı. */
-    insertMany(rows: readonly InsertValues<InsertShape<T>>[], opts?: {
-        onConflict: readonly string[];
-        action?: "ignore" | "update";
+    insertMany(rows: readonly InsertValues<InsertShape<T>>[], opts: InsertManyOptions & {
+        returning: false;
+    }): Promise<number>;
+    insertMany(rows: readonly InsertValues<InsertShape<T>>[], opts?: InsertManyOptions & {
+        returning?: true;
     }): Promise<RowShape<T>[]>;
+    insertMany(rows: readonly InsertValues<InsertShape<T>>[], opts?: InsertManyOptions): Promise<RowShape<T>[] | number>;
     put(q: {
         data: InsertShape<T>;
         onConflict: readonly string[];
@@ -3058,7 +3251,9 @@ interface TypedTable<T extends TableDef> {
     }): Promise<number>;
 }
 /** A typed DB facade covering all tables declared in schema `S`. */
-interface TypedDB<S extends SchemaDef> {
+interface TypedDB<S extends SchemaDef> extends QueryDatabase {
+    diagnostics: DBOps["diagnostics"];
+    command<T>(fn: (tx: TypedTx<S>) => T extends Promise<unknown> ? never : T, options?: CommandOptions): Promise<Materialized<T>>;
     tables: {
         [K in keyof S["tables"]]: TypedTable<S["tables"][K]>;
     };
@@ -3095,7 +3290,7 @@ type TypedTx<S extends SchemaDef> = TxPlanHandle<{
  * object to the precise mapped type (TS cannot infer the mapped-type result
  * through `Object.keys` iteration) — see the module-level doc comment.
  */
-declare function makeTypedDB<S extends SchemaDef>(schema: S, raw: DBClient): TypedDB<S>;
+declare function makeTypedDB<S extends SchemaDef>(schema: S, raw: AtomicClient): TypedDB<S>;
 /** Bir where değeri: düz eşitlik YA DA operatör nesnesi (FR-016). */
 /**
  * Metin operatörleri YALNIZ metin kolonlarında görünür (FR-005).
@@ -3240,10 +3435,9 @@ type SqlFragment = {
 /**
  * Retryable bir hatada işlemi yeniden dener (FR-037).
  *
- * D-016: retry'SIZ bir izolasyon yükseltmesi sunmak defect'tir — kullanıcıya
- * çalışmayan bir düğme vermektir. `SerializationFailure`'ın metni
- * *"{ retry: n } verebilirsiniz"* diyor; bu fonksiyon o düğmenin gerçekten
- * çalışan yarısı.
+ * `fn` must open and settle a NEW transaction on each invocation. Repeating
+ * a savepoint retains the old snapshot and cannot retry a failed COMMIT.
+ * Database.$atomic owns that boundary for ordinary application code.
  *
  * VARSAYILAN SIFIR. Sessiz bir varsayılan retry, idempotent OLMAYAN bir işlemi
  * çağıranın haberi olmadan iki kez çalıştırırdı — bir para transferini iki kez.
@@ -3283,7 +3477,12 @@ type TextOps<V> = V extends string ? {
     icontains?: string;
     startsWith?: string;
     endsWith?: string;
-} : Record<never, never>;
+} : {
+    contains?: never;
+    icontains?: never;
+    startsWith?: never;
+    endsWith?: never;
+};
 /** Operatör gövdesi, kolon-referans tipi DIŞARIDAN verilmiş hâliyle.
  *
  * `C` bir parametre, çünkü `ColRefOf<Row, V>` aksi hâlde altı operatör
@@ -3469,16 +3668,17 @@ type HasBranch<Row, Rels> = [unknown] extends [Rels] ? never : [keyof Rels] exte
  * `true` bütün kolonları, bir nesne ise `select`/`where`/`orderBy`/`limit` ile
  * daraltılmış hâlini getiriyor. Tek sorgu: LATERAL + `json_agg`.
  */
-type WithOpts<To> = {
+type WithOpts<To, D extends HasDepth> = {
     select?: readonly Extract<keyof RelatedRow<To>, string>[];
     where?: WhereFilter<RelatedRow<To>>;
     orderBy?: OrderBySpec<RelatedRow<To>> | readonly OrderBySpec<RelatedRow<To>>[];
     limit?: number;
+    with?: D extends 1 ? never : [keyof RelatedRels<To>] extends [never] ? never : WithInput<RelatedRels<To>, HasDec[D]>;
 };
-type WithInput<Rels> = {
+type WithInput<Rels, D extends HasDepth = 3> = {
     [R in keyof Rels]?: Rels[R] extends {
         to: infer To;
-    } ? true | WithOpts<To> : never;
+    } ? true | WithOpts<To, D> : never;
 };
 /** Bir `with` dalının DÖNÜŞ tipi — `many` dizi, `one` tekil ya da null. */
 type WithRowOf<Rels, R extends keyof Rels, Q> = Rels[R] extends {
@@ -3486,7 +3686,9 @@ type WithRowOf<Rels, R extends keyof Rels, Q> = Rels[R] extends {
     kind: infer K;
 } ? (Q extends {
     select: readonly (infer C extends keyof RelatedRow<To>)[];
-} ? Pick<RelatedRow<To>, C> : RelatedRow<To>) extends infer Row ? [K] extends ["many"] ? Row[] : Row | null : never : never;
+} ? Pick<RelatedRow<To>, C> : RelatedRow<To>) & (Q extends {
+    with: infer W;
+} ? WithResult<RelatedRels<To>, W> : unknown) extends infer Row ? [K] extends ["many"] ? Row[] : Row | null : never : never;
 /**
  * `with` istenmediğinde `unknown` — kesişimde YOK OLSUN diye.
  *
@@ -3544,6 +3746,9 @@ type QueryInput<Row, K extends keyof Row = keyof Row, Rels = unknown> = {
      */
     select?: readonly K[];
 } & FindManyOpts<Row>;
+type PageInput<Row, K extends keyof Row = keyof Row, Rels = unknown> = Omit<QueryInput<Row, keyof Row, Rels>, "limit" | "offset" | "select"> & {
+    select?: readonly K[];
+} & PageNavigation;
 /** Bir yazmanın TEK parametresi: neyi (`where`) neye çevirdiğin (`set`). */
 type MutateInput<Row, Insert, Rels = unknown> = {
     where: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels>;
@@ -3727,6 +3932,16 @@ type AggregateResult<Q, Row> = Q extends {
 } & AggBody<Q, Row>)[] : AggBody<Q, Row>;
 /** Temel tablo erişimcisi — search'süz beş op. */
 interface EnvTypedTableBase<T extends TableTypes> {
+    findUnique<K extends keyof T["row"] = keyof T["row"], W extends WithInput<RelsOf<T>> = Record<never, never>>(q: {
+        where: UniqueWhere<T["row"], T["uniqueKeys"]>;
+        select?: readonly K[];
+        with?: QueryInput<T["row"], keyof T["row"], RelsOf<T>>["with"] & W;
+    }): Promise<(Pick<T["row"], K> & WithResult<RelsOf<T>, W>) | null>;
+    /** Index-backed pagination. The engine appends the declared primary key to
+     * orderBy, encrypts cursor values and validates the query and caller scope. */
+    page<K extends keyof T["row"] = keyof T["row"], W extends WithInput<RelsOf<T>> = Record<never, never>>(q?: PageInput<T["row"], K, RelsOf<T>> & {
+        with?: W;
+    }): Promise<Page<Pick<T["row"], K> & WithResult<RelsOf<T>, W>>>;
     insert(data: InsertValues<T["insert"]>): Promise<T["row"]>;
     /**
      * Çok satırı TEK statement'la ekle (tek gidiş-dönüş).
@@ -3743,14 +3958,13 @@ interface EnvTypedTableBase<T extends TableTypes> {
      *
      * Boş dizi boş sonuç döner — hata değil: "eklenecek bir şey yoktu".
      */
-    insertMany(rows: readonly InsertValues<T["insert"]>[], opts?: {
-        /** Çakışmanın ARANDIĞI kolonlar — benzersiz bir kısıt ya da index taşımalı. */
-        onConflict: readonly Extract<keyof T["row"], string>[];
-        /** `"ignore"` (VARSAYILAN, plan yoluyla aynı) çakışanı atlar ve o satır
-         *  SONUÇTA DÖNMEZ — Postgres yalnız yazdıklarını döndürür; `"update"`
-         *  üzerine yazar. */
-        action?: "ignore" | "update";
+    insertMany(rows: readonly InsertValues<T["insert"]>[], opts: InsertManyOptions<Extract<keyof T["row"], string>> & {
+        returning: false;
+    }): Promise<number>;
+    insertMany(rows: readonly InsertValues<T["insert"]>[], opts?: InsertManyOptions<Extract<keyof T["row"], string>> & {
+        returning?: true;
     }): Promise<T["row"][]>;
+    insertMany(rows: readonly InsertValues<T["insert"]>[], opts?: InsertManyOptions<Extract<keyof T["row"], string>>): Promise<T["row"][] | number>;
     /**
      * Bir idempotency anahtarını sahiplen (FR-033).
      *
@@ -4007,13 +4221,22 @@ type TxPlan = TxPlanHandle<TxTables> & TxSchemaSurface;
  * Every op it performs runs as the `service_role` (BYPASSRLS).
  */
 type EnvServiceDatabase = EnvSchemaSurface & {
+    /** Commits independently of the request. All decision reads and writes belong
+     * inside this callback; each retry includes a new BEGIN and COMMIT. */
+    $atomic<T>(fn: (tx: AtomicDatabase) => Promise<T>, options?: AtomicOptions): Promise<T>;
     /** Ham SQL. Generic verilmezse `unknown[]` döner (FR-021). */
     $query: DBClient["query"];
     $insert: DBClient["insert"];
     $update: DBClient["update"];
     $delete: DBClient["delete"];
     $findById: DBClient["findById"];
+    $findUnique: DBClient["findUnique"];
+    $readQuery: DBClient["readQuery"];
+    $diagnostics: DBClient["diagnostics"];
+    $compileQuery: DBClient["compileQuery"];
+    $explainQuery: DBClient["explainQuery"];
     $findMany: DBClient["findMany"];
+    $page: DBClient["page"];
     $put: DBClient["put"];
     $updateMany: DBClient["updateMany"];
     $deleteMany: DBClient["deleteMany"];
@@ -4027,12 +4250,12 @@ type EnvServiceDatabase = EnvSchemaSurface & {
     $lockRows: DBClient["lockRows"];
     $advisoryXactLock: DBClient["advisoryXactLock"];
     $attempt: DBClient["attempt"];
+    $command<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T, options?: CommandOptions): Promise<Materialized<T>>;
     /** Bkz. {@link EnvTypedDatabase.$transaction}. */
     /**
-     * `opts.retry` verilirse, `SerializationFailure` / `DeadlockDetected`
-     * alındığında plan BAŞTAN kurulup yeniden çalıştırılır (FR-037).
-     * Varsayılan 0 — sessiz bir retry, idempotent olmayan bir işlemi çağıranın
-     * haberi olmadan iki kez çalıştırırdı.
+     * A plan is a savepoint in the current transaction. Nonzero `retry` is
+     * refused; use $atomic for whole-transaction retry, including decision reads
+     * and COMMIT. The default plan keeps request-scoped commit/rollback behavior.
      */
     $transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T, opts?: {
         retry?: number;
@@ -4072,13 +4295,22 @@ type EnvSchemaSurface = {
  * await Database.$transaction((tx) => { … });
  */
 type EnvTypedDatabase = EnvSchemaSurface & {
+    /** Commits independently of the request. A later handler failure does not
+     * undo this scope. The callback cannot switch RLS identity or nest a root. */
+    $atomic<T>(fn: (tx: AtomicDatabase) => Promise<T>, options?: AtomicOptions): Promise<T>;
     /** Ham SQL. Generic verilmezse `unknown[]` döner (FR-021). */
     $query: DBClient["query"];
     $insert: DBClient["insert"];
     $update: DBClient["update"];
     $delete: DBClient["delete"];
     $findById: DBClient["findById"];
+    $findUnique: DBClient["findUnique"];
+    $readQuery: DBClient["readQuery"];
+    $diagnostics: DBClient["diagnostics"];
+    $compileQuery: DBClient["compileQuery"];
+    $explainQuery: DBClient["explainQuery"];
     $findMany: DBClient["findMany"];
+    $page: DBClient["page"];
     $put: DBClient["put"];
     $updateMany: DBClient["updateMany"];
     $deleteMany: DBClient["deleteMany"];
@@ -4092,6 +4324,7 @@ type EnvTypedDatabase = EnvSchemaSurface & {
     $lockRows: DBClient["lockRows"];
     $advisoryXactLock: DBClient["advisoryXactLock"];
     $attempt: DBClient["attempt"];
+    $command<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T, options?: CommandOptions): Promise<Materialized<T>>;
     /** RLS'i bypass eden kardeş yüzey. Kendisi `$asService` TAŞIMAZ — çift bypass yok. */
     $asService(): EnvServiceDatabase;
     /**
@@ -4100,15 +4333,16 @@ type EnvTypedDatabase = EnvSchemaSurface & {
      * Callback SENKRONDUR: döndüğünde hiçbir şey çalışmamıştır.
      */
     /**
-     * `opts.retry` verilirse, `SerializationFailure` / `DeadlockDetected`
-     * alındığında plan BAŞTAN kurulup yeniden çalıştırılır (FR-037).
-     * Varsayılan 0 — sessiz bir retry, idempotent olmayan bir işlemi çağıranın
-     * haberi olmadan iki kez çalıştırırdı.
+     * A plan is a savepoint in the current transaction. Nonzero `retry` is
+     * refused; use $atomic for whole-transaction retry, including decision reads
+     * and COMMIT. The default plan keeps request-scoped commit/rollback behavior.
      */
     $transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T, opts?: {
         retry?: number;
     }): Promise<Materialized<T>>;
 };
+/** The same typed table/query surface on one active physical transaction. */
+type AtomicDatabase = Omit<EnvServiceDatabase, "$atomic">;
 
 /**
  * tx-plan.ts — `Database.$transaction()` as a PLAN, not a pinned session.
@@ -4768,7 +5002,16 @@ interface RateLimitConfig {
 }
 /** The six raw string-keyed DB operations shared by `DBClient` and the
  * transaction-scoped client. */
-interface DBOps {
+interface DBOps extends QueryDatabase {
+    /** Null when diagnostics/budgets are disabled. Binding values are never included. */
+    diagnostics(): DatabaseDiagnostics | null;
+    /** Match exactly one declared primary/unique key; null never denotes a unique value. */
+    findUnique(table: string, where: Record<string, unknown>, opts?: {
+        select?: readonly string[];
+        with?: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | null>;
+    /** Keyset pagination with opaque, lossless cursors and a unique ordering. */
+    page(table: string, query?: Record<string, unknown>, opts?: RawPageOptions): Promise<Page<Record<string, unknown>>>;
     /**
      * Run SQL on the REQUEST'S OWN transaction.
      *
@@ -4814,10 +5057,13 @@ interface DBOps {
         count?: boolean;
         groupBy?: readonly string[];
     }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
-    insertMany(table: string, rows: readonly Record<string, unknown>[], opts?: {
-        onConflict: readonly string[];
-        action?: "ignore" | "update";
+    insertMany(table: string, rows: readonly Record<string, unknown>[], opts: InsertManyOptions & {
+        returning: false;
+    }): Promise<number>;
+    insertMany(table: string, rows: readonly Record<string, unknown>[], opts?: InsertManyOptions & {
+        returning?: true;
     }): Promise<Record<string, unknown>[]>;
+    insertMany(table: string, rows: readonly Record<string, unknown>[], opts?: InsertManyOptions): Promise<Record<string, unknown>[] | number>;
     /**
      * Insert the row, or update it when it collides on `onConflict` — one
      * statement, so two concurrent callers cannot both lose.
@@ -4945,7 +5191,14 @@ interface DBOps {
         orderBy?: {
             column: string;
             direction?: "asc" | "desc";
-        };
+            nulls?: "first" | "last";
+        } | {
+            column: string;
+            direction?: "asc" | "desc";
+            nulls?: "first" | "last";
+        }[];
+        select?: string[];
+        with?: Record<string, unknown>;
         limit?: number;
         offset?: number;
     }): Promise<Record<string, unknown>[]>;
@@ -4995,15 +5248,18 @@ interface DBOps {
 }
 /** Database client interface injected into endpoint context. */
 interface DBClient extends DBOps {
+    /** Execute a compilable plan on PostgreSQL, with an explicit fallback policy. */
+    command(plan: TxPlanBody, options?: CommandOptions): Promise<TxPlanResponse>;
+    /** An independent physical transaction. Resolves after COMMIT, and retries the
+     * complete callback on a fresh transaction. One identity for its entire scope. */
+    atomic<T>(fn: (tx: AtomicClient) => Promise<T>, options?: AtomicOptions): Promise<T>;
     /**
      * Run a whole transaction as ONE plan, executed on the request's own
      * transaction inside a savepoint.
      *
      * The low-level seam behind `Database.$transaction(plan)`: the SDK builds the
-     * plan, this sends it, and the broker executes every operation inside a single
-     * transaction that commits or rolls back before the response is written.
-     * Nothing pins a Postgres backend across round trips, because there is only
-     * one round trip.
+     * plan and the local engine executes it on this transaction. A single API
+     * call can issue several SQL statements; it does not promise one DB round trip.
      *
      * On failure the runtime must reject with an error carrying the broker's
      * envelope fields — see {@link TxPlanRejection}. `slot` in particular is what
@@ -5028,6 +5284,8 @@ interface DBClient extends DBOps {
      */
     asService(): Omit<DBClient, "asService">;
 }
+/** An active root-transaction handle cannot switch identities or nest another root. */
+type AtomicClient = Omit<DBClient, "asService" | "atomic">;
 /** Logger interface injected into endpoint context. */
 interface Logger {
     info(message: string, ...args: unknown[]): void;
@@ -5319,4 +5577,4 @@ type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise
  */
 type AuthSpec = boolean | Partial<AuthConfig>;
 
-export { type Materialized as $, type AuthSpec as A, BadRequest as B, type CacheClient as C, type DBClient as D, type EnvServiceDatabase as E, type EnvTypedTable as F, type ErrorDef as G, HttpError as H, type ErrorMap as I, type ErrorThrowers as J, type FileContext as K, type FindManyOpts as L, Flags as M, Forbidden as N, type HttpMethod as O, type PalbaseResult as P, IndexBuilder as Q, type RateLimitConfig as R, type SchemaDef as S, type TxPlanBody as T, type IndexDef as U, type InsertShape as V, type InsertValues as W, type LifecycleHook as X, Log as Y, type Logger as Z, __runWithRuntime as _, type RuntimeServices as a, type PalbaseInitialLink as a$, type Middleware as a0, type MiddlewareContext as a1, type MiddlewareHandler as a2, type MutateInput as a3, NotFound as a4, Notifications as a5, type OnDeleteAction as a6, type OrderBySpec as a7, PALBASE_EXTENSIONS as a8, type PBRequest as a9, type PalbaseDocumentRef as aA, type PalbaseDocumentSnapshot as aB, type PalbaseEmailClient as aC, type PalbaseEmailSendParams as aD, type PalbaseEmailSendResponse as aE, type PalbaseEventNamesResult as aF, type PalbaseEventsQueryInput as aG, type PalbaseEventsResult as aH, type PalbaseExtension as aI, type PalbaseFileObject as aJ, type PalbaseFlag as aK, type PalbaseFlagContext as aL, type PalbaseFlagSource as aM, type PalbaseFlagValue as aN, type PalbaseFlagVariant as aO, type PalbaseFlagsClient as aP, type PalbaseFlagsServiceClient as aQ, type PalbaseFunctionsClient as aR, type PalbaseFunnelQueryInput as aS, type PalbaseFunnelResult as aT, type PalbaseIdentifyTraits as aU, type PalbaseInboxClient as aV, type PalbaseInboxListOptions as aW, type PalbaseInboxListResult as aX, type PalbaseInboxMessage as aY, type PalbaseInboxSendParams as aZ, type PalbaseInboxSendResponse as a_, PalError as aa, type PalbaseAnalyticsClient as ab, type PalbaseAnalyticsManagementNamespace as ac, type PalbaseAnalyticsProperties as ad, type PalbaseAnalyticsQueryNamespace as ae, type PalbaseAttestAndroidParams as af, type PalbaseAttestAndroidResult as ag, type PalbaseAttestiOSParams as ah, type PalbaseAttestiOSResult as ai, type PalbaseAuthAdminClient as aj, type PalbaseAuthClient as ak, type PalbaseBatchOverrideOperation as al, type PalbaseBatchSetOverridesResult as am, type PalbaseBindDeviceParams as an, type PalbaseBucketClient as ao, type PalbaseClearAllOverridesResult as ap, type PalbaseClearOverrideResult as aq, type PalbaseCohortQueryInput as ar, type PalbaseCohortResult as as, type PalbaseCollectionRef as at, type PalbaseCountQueryInput as au, type PalbaseCountResult as av, type PalbaseCreateLinkParams as aw, type PalbaseDeviceInfo as ax, type PalbaseDeviceTokenView as ay, type PalbaseDocsClient as az, type DBOps as b, type TableDef as b$, type PalbaseInvokeOptions as b0, type PalbaseLink as b1, type PalbaseLinkAnalytics as b2, type PalbaseLinkDetails as b3, type PalbaseLinksClient as b4, type PalbaseListLinksOptions as b5, type PalbaseListLinksResult as b6, type PalbaseListOptions as b7, type PalbaseMatchParams as b8, type PalbaseMultiChannelResponse as b9, type PalbaseUsersQueryInput as bA, type PalbaseUsersResult as bB, type PalbaseVerifyRequestSignatureParams as bC, type PalbaseWhereOperator as bD, type PolicyBinOp as bE, PolicyBuilder as bF, type PolicyCommand as bG, type PolicyDef as bH, type PolicyExprCtx as bI, PolicyExprRef as bJ, type PolicyMode as bK, type PolicyOperand as bL, type QueryInput as bM, type RawConstraintDef as bN, Realtime as bO, type Ref as bP, type RequestStore as bQ, type RowShape as bR, Secrets as bS, type SecretsService as bT, SerializationFailure as bU, type SetShape as bV, type SetValue as bW, type ShutdownRunner as bX, type SqlFragment as bY, Storage as bZ, TABLE_META as b_, type PalbaseNotificationsClient as ba, type PalbaseOverviewResult as bb, type PalbasePreferences as bc, type PalbasePreferencesClient as bd, type PalbasePushClient as be, type PalbasePushSendParams as bf, type PalbasePushSendResponse as bg, type PalbaseQrCodeOptions as bh, type PalbaseQuerySnapshot as bi, type PalbaseRealtimeClient as bj, type PalbaseRegisterDeviceParams as bk, type PalbaseRetentionQueryInput as bl, type PalbaseRetentionResult as bm, type PalbaseSession as bn, type PalbaseSetOverrideResult as bo, type PalbaseSetOverridesResult as bp, type PalbaseSignedUrlResponse as bq, type PalbaseSmsClient as br, type PalbaseSmsSendParams as bs, type PalbaseSmsSendResponse as bt, type PalbaseStorageClient as bu, type PalbaseTransformOptions as bv, type PalbaseUpdateLinkParams as bw, type PalbaseUploadOptions as bx, type PalbaseUser as by, type PalbaseUserDetailResult as bz, type TxPlanResponse as c, ownedByUser as c$, type TableHandle as c0, type TableInput as c1, TooManyRequests as c2, type TxColumnExpr as c3, type TxInsertShape as c4, type TxInsertValue as c5, type TxNow as c6, type TxPlan as c7, TxPlanError as c8, type TxPlanHandle as c9, __resetLifecycleHooks as cA, __runStartHooks as cB, __setRuntime as cC, bigint as cD, boolean as cE, col as cF, dec as cG, decrement as cH, defineMiddleware as cI, defineSchema as cJ, defineTable as cK, enumType as cL, exprCtx as cM, inc as cN, increment as cO, index as cP, installationRef as cQ, integer as cR, isPalbaseExtension as cS, isRetryable as cT, jsonb as cU, makeTypedDB as cV, now as cW, numeric as cX, onShutdown as cY, onStart as cZ, openai as c_, type TxPlanOpResult as ca, type TxPlanRejection as cb, TxRefError as cc, type TxRow as cd, type TxRows as ce, type TxSelectOptions as cf, type TxSetShape as cg, type TxSetValue as ch, type TxTable as ci, type TxTables as cj, type TxWhere as ck, type TxWireExpr as cl, type TxWireGuard as cm, type TxWireOp as cn, type TxWireRef as co, type TxWireValue as cp, type TypedDB as cq, type TypedTable as cr, type TypedTx as cs, Unauthorized as ct, UniqueViolation as cu, type User as cv, type VerifiedDevice as cw, type WhereFilter as cx, type WhereOp as cy, __getRuntime as cz, __requestALS as d, policy as d0, raw as d1, sqlFragment as d2, text as d3, timestamp as d4, userRef as d5, uuid as d6, vector as d7, withRetry as d8, type PolicyExpr as e, type AggregateInput as f, type AggregateResult as g, type AnyColumn as h, Auth as i, type AuthConfig as j, Cache as k, type ClientInfo as l, type ColRef as m, ColumnBuilder as n, type ColumnDef as o, type ColumnMap as p, type ColumnType as q, Conflict as r, Database as s, DeadlockDetected as t, Documents as u, EXTENSION_DEPENDENCIES as v, type EmbeddingModelRef as w, type EnvSchemas as x, type EnvTables as y, type EnvTypedDatabase as z };
+export { type ErrorMap as $, type AuthSpec as A, BadRequest as B, type CompiledRead as C, type DatabaseBudget as D, type EnvServiceDatabase as E, type ColumnMap as F, type ColumnType as G, HttpError as H, Conflict as I, Database as J, type DatabaseQueryEvent as K, type DatabaseWorkload as L, DeadlockDetected as M, Documents as N, EXTENSION_DEPENDENCIES as O, type PreparedRead as P, type EmbeddingModelRef as Q, type RateLimitConfig as R, type SchemaDef as S, type TransactionIsolation as T, type EnvQueryDatabase as U, type EnvSchemas as V, type EnvTables as W, type EnvTypedDatabase as X, type EnvTypedTable as Y, type ErrorDef as Z, __runWithRuntime as _, type DBClient as a, type PalbaseFileObject as a$, type ErrorThrowers as a0, type FileContext as a1, type FindManyOpts as a2, Flags as a3, Forbidden as a4, type HttpMethod as a5, IndexBuilder as a6, type IndexDef as a7, type InsertManyOptions as a8, type InsertShape as a9, type PalbaseAttestiOSResult as aA, type PalbaseAuthAdminClient as aB, type PalbaseAuthClient as aC, type PalbaseBatchOverrideOperation as aD, type PalbaseBatchSetOverridesResult as aE, type PalbaseBindDeviceParams as aF, type PalbaseBucketClient as aG, type PalbaseClearAllOverridesResult as aH, type PalbaseClearOverrideResult as aI, type PalbaseCohortQueryInput as aJ, type PalbaseCohortResult as aK, type PalbaseCollectionRef as aL, type PalbaseCountQueryInput as aM, type PalbaseCountResult as aN, type PalbaseCreateLinkParams as aO, type PalbaseDeviceInfo as aP, type PalbaseDeviceTokenView as aQ, type PalbaseDocsClient as aR, type PalbaseDocumentRef as aS, type PalbaseDocumentSnapshot as aT, type PalbaseEmailClient as aU, type PalbaseEmailSendParams as aV, type PalbaseEmailSendResponse as aW, type PalbaseEventNamesResult as aX, type PalbaseEventsQueryInput as aY, type PalbaseEventsResult as aZ, type PalbaseExtension as a_, type InsertValues as aa, type LifecycleHook as ab, Log as ac, type Logger as ad, type Materialized as ae, type Middleware as af, type MiddlewareContext as ag, type MiddlewareHandler as ah, type MutateInput as ai, NotFound as aj, Notifications as ak, type OnDeleteAction as al, type OrderBySpec as am, PALBASE_EXTENSIONS as an, type PBRequest as ao, type PageInfo as ap, type PageInput as aq, type PageNavigation as ar, PalError as as, type PalbaseAnalyticsClient as at, type PalbaseAnalyticsManagementNamespace as au, type PalbaseAnalyticsProperties as av, type PalbaseAnalyticsQueryNamespace as aw, type PalbaseAttestAndroidParams as ax, type PalbaseAttestAndroidResult as ay, type PalbaseAttestiOSParams as az, type RuntimeServices as b, PolicyExprRef as b$, type PalbaseFlag as b0, type PalbaseFlagContext as b1, type PalbaseFlagSource as b2, type PalbaseFlagValue as b3, type PalbaseFlagVariant as b4, type PalbaseFlagsClient as b5, type PalbaseFlagsServiceClient as b6, type PalbaseFunctionsClient as b7, type PalbaseFunnelQueryInput as b8, type PalbaseFunnelResult as b9, type PalbaseQuerySnapshot as bA, type PalbaseRealtimeClient as bB, type PalbaseRegisterDeviceParams as bC, type PalbaseRetentionQueryInput as bD, type PalbaseRetentionResult as bE, type PalbaseSession as bF, type PalbaseSetOverrideResult as bG, type PalbaseSetOverridesResult as bH, type PalbaseSignedUrlResponse as bI, type PalbaseSmsClient as bJ, type PalbaseSmsSendParams as bK, type PalbaseSmsSendResponse as bL, type PalbaseStorageClient as bM, type PalbaseTransformOptions as bN, type PalbaseUpdateLinkParams as bO, type PalbaseUploadOptions as bP, type PalbaseUser as bQ, type PalbaseUserDetailResult as bR, type PalbaseUsersQueryInput as bS, type PalbaseUsersResult as bT, type PalbaseVerifyRequestSignatureParams as bU, type PalbaseWhereOperator as bV, type PolicyBinOp as bW, PolicyBuilder as bX, type PolicyCommand as bY, type PolicyDef as bZ, type PolicyExprCtx as b_, type PalbaseIdentifyTraits as ba, type PalbaseInboxClient as bb, type PalbaseInboxListOptions as bc, type PalbaseInboxListResult as bd, type PalbaseInboxMessage as be, type PalbaseInboxSendParams as bf, type PalbaseInboxSendResponse as bg, type PalbaseInitialLink as bh, type PalbaseInvokeOptions as bi, type PalbaseLink as bj, type PalbaseLinkAnalytics as bk, type PalbaseLinkDetails as bl, type PalbaseLinksClient as bm, type PalbaseListLinksOptions as bn, type PalbaseListLinksResult as bo, type PalbaseListOptions as bp, type PalbaseMatchParams as bq, type PalbaseMultiChannelResponse as br, type PalbaseNotificationsClient as bs, type PalbaseOverviewResult as bt, type PalbasePreferences as bu, type PalbasePreferencesClient as bv, type PalbasePushClient as bw, type PalbasePushSendParams as bx, type PalbasePushSendResponse as by, type PalbaseQrCodeOptions as bz, type DatabaseDiagnosticsOptions as c, col as c$, type PolicyMode as c0, type PolicyOperand as c1, type QueryColumnContract as c2, type QueryDatabase as c3, type QueryInput as c4, type RawConstraintDef as c5, Realtime as c6, type Ref as c7, type RequestStore as c8, type RowShape as c9, type TxSetShape as cA, type TxSetValue as cB, type TxTable as cC, type TxTables as cD, type TxWhere as cE, type TxWireExpr as cF, type TxWireGuard as cG, type TxWireOp as cH, type TxWireRef as cI, type TxWireValue as cJ, type TypedDB as cK, type TypedTable as cL, type TypedTx as cM, Unauthorized as cN, UniqueViolation as cO, type UniqueWhere as cP, type User as cQ, type VerifiedDevice as cR, type WhereFilter as cS, type WhereOp as cT, type WorkloadOptions as cU, __getRuntime as cV, __resetLifecycleHooks as cW, __runStartHooks as cX, __setRuntime as cY, bigint as cZ, boolean as c_, Secrets as ca, type SecretsService as cb, SerializationFailure as cc, type SetShape as cd, type SetValue as ce, type ShutdownRunner as cf, type SqlFragment as cg, Storage as ch, TABLE_META as ci, type TableDef as cj, type TableHandle as ck, type TableInput as cl, TooManyRequests as cm, type TxColumnExpr as cn, type TxInsertShape as co, type TxInsertValue as cp, type TxNow as cq, type TxPlan as cr, TxPlanError as cs, type TxPlanHandle as ct, type TxPlanOpResult as cu, type TxPlanRejection as cv, TxRefError as cw, type TxRow as cx, type TxRows as cy, type TxSelectOptions as cz, type DatabaseDiagnostics as d, dec as d0, decrement as d1, defineMiddleware as d2, defineSchema as d3, defineTable as d4, defineWorkload as d5, enumType as d6, exprCtx as d7, inc as d8, increment as d9, index as da, installationRef as db, integer as dc, isPalbaseExtension as dd, isRetryable as de, jsonb as df, makeTypedDB as dg, now as dh, numeric as di, onShutdown as dj, onStart as dk, openai as dl, ownedByUser as dm, policy as dn, raw as dp, sqlFragment as dq, text as dr, timestamp as ds, userRef as dt, uuid as du, vector as dv, withRetry as dw, type ColValue as dx, type DBOps as e, type RawPageOptions as f, type Page as g, type TxPlanBody as h, type CommandOptions as i, type TxPlanResponse as j, type CacheClient as k, __requestALS as l, type PalbaseResult as m, type PolicyExpr as n, type AggregateInput as o, type AggregateResult as p, type AnyColumn as q, type AtomicDatabase as r, type AtomicOptions as s, Auth as t, type AuthConfig as u, Cache as v, type ClientInfo as w, type ColRef as x, ColumnBuilder as y, type ColumnDef as z };