@palbase/backend 33.0.2 → 34.0.0

package/dist/engine/index.d.cts

@@ -1,8 +1,8 @@
-import '../index-DB_nW-AV.cjs';
-export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-DLveQoOf.cjs';
-import '../db/env.cjs';
-import '../stack.cjs';
+import '../endpoint-kYgEHrrV.cjs';
+export { A as App, g as AuthVerifier, B as BootRefused, h as COMMAND_EXECUTOR_DDL, j as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, k as EngineConfig, M as ModuleClients, R as RateLimiter, l as RequestDatabase, m as RouteEntry, n as RuntimeHooks, S as ScrubResult, o as SqlDriver, p as SqlTx, q as buildRouteTable, r as createApp, s as createLazyTransaction, t as createOps, u as createRequestDatabase, v as effectiveAuth, w as hostAllowed, x as installCommandExecutor, y as installEgressFence, i as isDeclarationRefused, z as loadConfig, F as makeMemoryCache, G as matchRoute, H as quoteIdent, I as scrubSecrets, J as setCursorKey, K as withQueryCancellation, L as withTables } from '../index-pnDsEfxJ.cjs';
 import 'zod';
+import '../stack.cjs';
+import '../db/env.cjs';
 import 'node:async_hooks';
 import '../module-Dl1KFVtc.cjs';
-import '../registry-DSTThhKf.cjs';
+import '../registry-BcOd8Zhf.cjs';

package/dist/engine/index.d.ts

@@ -1,8 +1,8 @@
-import '../index-DMZG3kpo.js';
-export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-D-3duy8Y.js';
-import '../db/env.js';
-import '../stack.js';
+import '../endpoint-DpNUx-ON.js';
+export { A as App, g as AuthVerifier, B as BootRefused, h as COMMAND_EXECUTOR_DDL, j as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, k as EngineConfig, M as ModuleClients, R as RateLimiter, l as RequestDatabase, m as RouteEntry, n as RuntimeHooks, S as ScrubResult, o as SqlDriver, p as SqlTx, q as buildRouteTable, r as createApp, s as createLazyTransaction, t as createOps, u as createRequestDatabase, v as effectiveAuth, w as hostAllowed, x as installCommandExecutor, y as installEgressFence, i as isDeclarationRefused, z as loadConfig, F as makeMemoryCache, G as matchRoute, H as quoteIdent, I as scrubSecrets, J as setCursorKey, K as withQueryCancellation, L as withTables } from '../index-JrHqNsjQ.js';
 import 'zod';
+import '../stack.js';
+import '../db/env.js';
 import 'node:async_hooks';
 import '../module-Dl1KFVtc.js';
-import '../registry-JjF5lcj4.js';
+import '../registry-BoX5iNyY.js';

package/dist/engine/index.js

@@ -1,6 +1,7 @@
 import {
   AuthVerifier,
   BootRefused,
+  COMMAND_EXECUTOR_DDL,
   RateLimiter,
   buildRouteTable,
   createApp,
@@ -9,27 +10,33 @@ import {
   createRequestDatabase,
   effectiveAuth,
   hostAllowed,
+  installCommandExecutor,
   installEgressFence,
   loadConfig,
   makeMemoryCache,
   matchRoute,
   quoteIdent,
   scrubSecrets,
+  setCursorKey,
+  withQueryCancellation,
   withTables
-} from "../chunk-C6COAB3E.js";
+} from "../chunk-MNGZE2MM.js";
 import {
   DECLARATION_REFUSAL,
   DeclarationRefused,
   isDeclarationRefused
-} from "../chunk-WWUG2QXF.js";
-import "../chunk-TVCCR6SO.js";
-import "../chunk-XOX6RFPZ.js";
-import "../chunk-SI4KGEM3.js";
-import "../chunk-AAT5G7KY.js";
-import "../chunk-KATPXCJ5.js";
+} from "../chunk-YX7UA7VC.js";
+import "../chunk-GHNC2UHS.js";
+import "../chunk-LOGL2ZHD.js";
+import "../chunk-PRH45NZU.js";
+import "../chunk-FOWA7PF4.js";
+import "../chunk-JJW3L62T.js";
+import "../chunk-UMESJJRS.js";
+import "../chunk-VXPNPVAG.js";
 export {
   AuthVerifier,
   BootRefused,
+  COMMAND_EXECUTOR_DDL,
   DECLARATION_REFUSAL,
   DeclarationRefused,
   RateLimiter,
@@ -40,6 +47,7 @@ export {
   createRequestDatabase,
   effectiveAuth,
   hostAllowed,
+  installCommandExecutor,
   installEgressFence,
   isDeclarationRefused,
   loadConfig,
@@ -47,6 +55,8 @@ export {
   matchRoute,
   quoteIdent,
   scrubSecrets,
+  setCursorKey,
+  withQueryCancellation,
   withTables
 };
 //# sourceMappingURL=index.js.map

package/dist/{index-D-3duy8Y.d.ts → index-JrHqNsjQ.d.ts}

@@ -1,6 +1,6 @@
-import { D as DBClient, b as DBOps, T as TxPlanBody, c as TxPlanResponse, A as AuthSpec, C as CacheClient, a as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-DMZG3kpo.js';
+import { c as DatabaseDiagnosticsOptions, d as DatabaseDiagnostics, a as DBClient, T as TransactionIsolation, e as DBOps, P as PreparedRead, C as CompiledRead, f as RawPageOptions, g as Page, h as TxPlanBody, i as CommandOptions, j as TxPlanResponse, A as AuthSpec, k as CacheClient, b as RuntimeServices, _ as __runWithRuntime, l as __requestALS } from './endpoint-DpNUx-ON.js';
 import { T as Token } from './module-Dl1KFVtc.js';
-import { R as RouteMeta } from './registry-JjF5lcj4.js';
+import { R as RouteMeta } from './registry-BoX5iNyY.js';
 
 /**
  * engine/config.ts — settings from the environment, and the gate that refuses
@@ -47,6 +47,11 @@ interface EngineConfig {
     anonKey: string;
     /** Secret key. Used for privileged module calls. */
     serviceRoleKey: string;
+    /** Optional dedicated cursor encryption secret, shared by all replicas. */
+    cursorSecret?: string;
+    /** Install the invoker-only PostgreSQL command helper at boot. Requires DDL
+     * rights on the connection role; execution retains each request's RLS role. */
+    enableCommands?: boolean;
     /** HMAC the realtime broadcast token is signed with. Empty ⇒ broadcast
      * returns a clear `realtime_unconfigured` error instead of failing silently. */
     realtimeSecret: string;
@@ -65,6 +70,7 @@ interface EngineConfig {
      */
     dbServiceRole: string;
     poolMax: number;
+    databaseDiagnostics?: DatabaseDiagnosticsOptions;
 }
 /**
  * THE ENVIRONMENT THIS STACK WAS HANDED IS UNUSABLE. Carries the missing names.
@@ -87,42 +93,62 @@ declare class BootRefused extends Error {
  */
 declare function loadConfig(env: Record<string, string | undefined>): EngineConfig;
 
-/**
- * engine/db.ts — a real pooled connection, and the identity every request is
- * bound to inside it.
- *
- * # Why one transaction per request
- *
- * In the isolate architecture every `Database.*` call was its own HTTP hop to a
- * capability surface, so two writes in one handler could not be atomic — a
- * handler that wrote and then threw left the first write behind. Here the whole
- * request runs inside one transaction: it commits when the handler returns and
- * rolls back when it throws. Atomicity stops being something the author has to
- * ask for.
- *
- * # Why it opens lazily
- *
- * A handler that touches no table must cost no round trip. Opening eagerly cost
- * four (BEGIN + bind + … + COMMIT) on endpoints that never query — measured at
- * 1,243 rps against 31,579 for the same endpoint once the open became lazy.
- *
- * # How the caller's identity reaches RLS
- *
- * One statement, not three:
- *
- *   select set_config('role',$1,true),
- *          set_config('search_path','public',true),
- *          set_config('request.jwt.claims',$2,true)
- *
- * `set_config(..., is_local => true)` is transaction-scoped exactly like
- * `SET LOCAL`, but takes BOUND PARAMETERS, which `SET LOCAL` cannot. So the
- * role and the caller's claims travel as parameters — user identity is never
- * spliced into SQL text — and `auth.uid()` resolves inside RLS policies, which
- * means the row filter is enforced by Postgres rather than by our code.
- */
+type CancellableQuery = Promise<unknown> & {
+    cancel?: () => unknown;
+};
+/** Abort callback work and active statements, then let the transaction owner
+ * await rollback. COMMIT is never raced with a timer: its acknowledged result
+ * or connection failure remains authoritative. */
+declare class TransactionControl {
+    private controller;
+    private active;
+    private cancelBackend?;
+    private cancellation;
+    private timer?;
+    private unlink;
+    private rejection;
+    readonly deadline: number | undefined;
+    get signal(): AbortSignal;
+    constructor(timeoutMs?: number, external?: AbortSignal);
+    check(): void;
+    remainingMs(): number | undefined;
+    race<T>(work: Promise<T>): Promise<T>;
+    bindBackend(cancel: () => Promise<void>): void;
+    /** Keep the application's connection parked until the cancellation request
+     * and all statements settle; a late cancel must not hit its next borrower. */
+    drainCancellation(): Promise<void>;
+    watch(query: CancellableQuery): Promise<unknown>;
+    dispose(): void;
+}
+
+type Timing = "queueMs" | "poolMs" | "setupMs" | "sqlMs" | "commitMs" | "rollbackMs";
+/** Allocated only when diagnostics or a budget is configured. One collector
+ * follows the request's user/service handles and independent atomic attempts. */
+declare class DatabaseTrace {
+    private readonly options;
+    private readonly start;
+    private ended?;
+    private failure?;
+    private readonly state;
+    constructor(options: DatabaseDiagnosticsOptions);
+    check(): void;
+    time(key: Timing, started: number): void;
+    retry(): void;
+    committed(): void;
+    commitFailed(): void;
+    failed(): void;
+    rolledBack(): void;
+    private refuse;
+    private emit;
+    query(sql: string, name: string | undefined, run: () => Promise<unknown>): Promise<unknown>;
+    get snapshot(): DatabaseDiagnostics;
+    complete(outcome: "committed" | "failed"): void;
+}
 
 /** The slice of a SQL driver the engine uses. `Bun.sql` satisfies it. */
 interface SqlDriver {
+    /** Optional reliable cancellation through a separate control connection. */
+    cancelBackend?(pid: number, startedAt: string): Promise<void>;
     /** Run a parameterised statement. */
     unsafe(sql: string, params?: unknown[]): Promise<unknown>;
     /** Open a transaction; the driver commits when `cb` resolves and rolls back
@@ -130,7 +156,9 @@ interface SqlDriver {
     begin<T>(cb: (tx: SqlTx) => Promise<T>): Promise<T>;
 }
 interface SqlTx {
-    unsafe(sql: string, params?: unknown[]): Promise<unknown>;
+    unsafe(sql: string, params?: unknown[], metadata?: {
+        name?: string;
+    }): Promise<unknown>;
     savepoint<T>(cb: (sp: SqlTx) => Promise<T>): Promise<T>;
 }
 type Row = Record<string, unknown>;
@@ -147,6 +175,12 @@ declare function quoteIdent(name: string): string;
  */
 declare function createLazyTransaction(sql: SqlDriver, role: string, claimsJson: string, options?: {
     lockTimeout?: string;
+    statementTimeout?: string;
+    isolation?: TransactionIsolation;
+    readOnly?: boolean;
+    scope?: symbol;
+    control?: TransactionControl;
+    trace?: DatabaseTrace;
 }): {
     ensure: () => Promise<SqlTx>;
     readonly opened: boolean;
@@ -186,7 +220,13 @@ interface FindManyOptions {
      * refused without it — see `offsetClause`. */
     offset?: number;
 }
-declare function createOps(tx: TxLike): {
+interface OpsContext {
+    readonly cursorScope?: string;
+    readonly commands?: boolean;
+    readonly trace?: DatabaseTrace;
+}
+declare function createOps(tx: TxLike, context?: OpsContext): {
+    diagnostics(): DatabaseDiagnostics | null;
     query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
     insert(table: string, data: Row): Promise<Row>;
     /**
@@ -203,10 +243,7 @@ declare function createOps(tx: TxLike): {
      * bir satırın fazla kolonu SESSİZCE YAZILMAZDI. Eksik kolon için `null`
      * yazın ya da varsayılanı istiyorsanız o satırları ayrı çağrıda ekleyin.
      */
-    insertMany(table: string, rows: readonly Row[], opts?: {
-        onConflict: readonly string[];
-        action?: "ignore" | "update";
-    }): Promise<Row[]>;
+    insertMany: DBOps["insertMany"];
     /**
      * Bir ADI kilitle — satırı değil (FR-054).
      *
@@ -338,8 +375,16 @@ declare function createOps(tx: TxLike): {
         groupBy?: readonly string[];
     }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
     count(table: string, where?: Row): Promise<number>;
+    findUnique(table: string, where: Row, opts?: {
+        select?: readonly string[];
+        with?: Record<string, unknown>;
+    }): Promise<Row | null>;
     findById(table: string, id: string): Promise<Row | null>;
+    compileQuery(query: PreparedRead): CompiledRead;
+    readQuery(query: PreparedRead): Promise<Row[]>;
+    explainQuery(query: PreparedRead): Promise<unknown[]>;
     findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
+    page(table: string, query?: Row, opts?: RawPageOptions): Promise<Page<Row>>;
     /**
      * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
      * (1/(50+rank), CLAIM-N4). Operatör şema-nitelikli (C-10, M-1); GUC
@@ -495,15 +540,9 @@ declare function createOps(tx: TxLike): {
      * "transport.txPlan is not a function" while every test that covered
      * transactions passed against a mock that did implement it.
      */
+    command(plan: TxPlanBody, options?: CommandOptions): Promise<TxPlanResponse>;
     txPlan(plan: TxPlanBody): Promise<TxPlanResponse>;
 };
-/**
- * Merge the typed `.tables` accessor onto a raw op surface.
- *
- * Mirrors what the pod runtime does, including the recursive application to the
- * transaction callback: without it `tx.tables.rooms.insert(...)` throws
- * "Cannot read properties of undefined".
- */
 declare function withTables<T extends ReturnType<typeof createOps>>(ops: T, schema?: {
     tables?: Record<string, {
         name?: string;
@@ -580,7 +619,7 @@ declare function createRequestDatabase(sql: SqlDriver, identity: {
     role: string;
     serviceRole: string;
     claimsJson: string;
-}): RequestDatabase;
+}, diagnostics?: DatabaseDiagnosticsOptions): RequestDatabase;
 
 /**
  * The two ways a stack refuses to boot — and they are two because their CURES
@@ -926,6 +965,25 @@ interface MemoryCacheOptions {
  */
 declare function makeMemoryCache(opts?: MemoryCacheOptions): CacheClient;
 
+/** One application secret shared by replicas. Rotation invalidates old cursors.
+ * Encryption also hides sort values omitted by the public projection. */
+declare function setCursorKey(secret: string | null): void;
+
+/** Statements remain sequential inside PostgreSQL. Each sees preceding writes,
+ * including triggers, unlike sibling data-modifying CTEs in one SQL statement.
+ * The exception block is a subtransaction, matching a savepoint plan. */
+declare const COMMAND_EXECUTOR_DDL = "\nCREATE SCHEMA IF NOT EXISTS palbase_runtime;\nCREATE OR REPLACE FUNCTION palbase_runtime.command_v1(steps jsonb) RETURNS jsonb\nLANGUAGE plpgsql VOLATILE SECURITY INVOKER SET search_path = pg_catalog, public AS $pb_command$\nDECLARE\n  results jsonb := '[]'::jsonb;\n  step jsonb; chunk jsonb; binding jsonb; source jsonb; rows jsonb;\n  statement text; rendered text; detail text; guard jsonb;\n  index integer := 0; affected integer; passed boolean;\nBEGIN\n  FOR step IN SELECT value FROM jsonb_array_elements(steps) LOOP\n    IF step->>'empty' = 'true' THEN rows := '[]'::jsonb;\n    ELSE\n      statement := '';\n      FOR chunk IN SELECT value FROM jsonb_array_elements(step->'chunks') LOOP\n        IF jsonb_typeof(chunk) = 'string' THEN statement := statement || (chunk #>> '{}');\n        ELSE\n          binding := step->'bindings'->((chunk->>'bind')::integer);\n          IF binding ? 'ref' THEN\n            source := results->((binding->'ref'->>'op')::integer)->'rows'->0;\n            IF source IS NULL OR NOT source ? (binding->'ref'->>'field') THEN\n              RAISE EXCEPTION 'Command reference has no source row/column; use expectOne before reading it'\n                USING ERRCODE = 'PBC02', DETAIL = jsonb_build_object('error_code','tx_ref_unresolved','op',index)::text;\n            END IF;\n            source := source->(binding->'ref'->>'field');\n          ELSE source := binding->'value'; END IF;\n          rendered := CASE WHEN source IS NULL OR source = 'null'::jsonb THEN NULL\n            WHEN binding->>'json' = 'true' THEN source::text\n            WHEN jsonb_typeof(source) = 'string' THEN source #>> '{}' ELSE source::text END;\n          -- PostgreSQL quotes the value itself. Values reach this function as\n          -- one bound JSON parameter, never as application-generated SQL text.\n          statement := statement || quote_nullable(rendered);\n        END IF;\n      END LOOP;\n      EXECUTE statement INTO rows;\n    END IF;\n    affected := jsonb_array_length(rows);\n    guard := step->'guard';\n    IF guard IS NOT NULL AND guard <> 'null'::jsonb THEN\n      passed := CASE guard->>'kind'\n        WHEN 'one' THEN affected = 1 WHEN 'none' THEN affected = 0\n        WHEN 'atLeast' THEN affected >= (guard->>'n')::integer\n        WHEN 'atMost' THEN affected <= (guard->>'n')::integer ELSE false END;\n      IF NOT passed THEN\n        RAISE EXCEPTION 'Command expectation failed'\n          USING ERRCODE = 'PBC01', DETAIL = jsonb_build_object('error_code','tx_guard_failed','slot',guard->'slot','op',index)::text;\n      END IF;\n    END IF;\n    results := results || jsonb_build_array(jsonb_build_object('rows',rows,'rows_affected',affected));\n    index := index + 1;\n  END LOOP;\n  RETURN jsonb_build_object('results',results);\nEXCEPTION WHEN SQLSTATE 'PBC01' OR SQLSTATE 'PBC02' THEN\n  GET STACKED DIAGNOSTICS detail = PG_EXCEPTION_DETAIL;\n  RETURN jsonb_build_object('error',detail::jsonb);\nEND\n$pb_command$;\nREVOKE ALL ON FUNCTION palbase_runtime.command_v1(jsonb) FROM PUBLIC;\nCREATE OR REPLACE FUNCTION palbase_runtime.command_rows_v1(rows jsonb, guard jsonb) RETURNS jsonb\nLANGUAGE plpgsql VOLATILE SECURITY INVOKER SET search_path = pg_catalog, public AS $pb_rows$\nDECLARE affected integer := jsonb_array_length(rows); passed boolean;\nBEGIN\n  IF guard IS NOT NULL AND guard <> 'null'::jsonb THEN\n    passed := CASE guard->>'kind'\n      WHEN 'one' THEN affected = 1 WHEN 'none' THEN affected = 0\n      WHEN 'atLeast' THEN affected >= (guard->>'n')::integer\n      WHEN 'atMost' THEN affected <= (guard->>'n')::integer ELSE false END;\n    IF NOT passed THEN\n      RAISE EXCEPTION 'Command expectation failed'\n        USING ERRCODE = 'PBC01', DETAIL = jsonb_build_object('error_code','tx_guard_failed','slot',guard->'slot')::text;\n    END IF;\n  END IF;\n  RETURN rows;\nEND\n$pb_rows$;\nREVOKE ALL ON FUNCTION palbase_runtime.command_rows_v1(jsonb,jsonb) FROM PUBLIC;\n";
+/** Run once with a migration/owner connection. Runtime execution retains each
+ * caller's role and RLS; there is no SECURITY DEFINER capability. */
+declare function installCommandExecutor(sql: SqlDriver, roles: readonly string[]): Promise<void>;
+
+/** The control pool must be separate from the application pool, connect as the
+ * same session user and to the same PostgreSQL server. Cancellation must still
+ * have a connection when every application connection is occupied. */
+declare function withQueryCancellation(application: SqlDriver, control: SqlDriver): SqlDriver & {
+    close(): Promise<void>;
+};
+
 /**
  * engine/fence.ts — what the tenant's own code may reach.
  *
@@ -1063,4 +1121,4 @@ interface App {
 }
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
-export { type App as A, BootRefused as B, type Container as C, DECLARATION_REFUSAL as D, type EgressPolicy as E, quoteIdent as F, scrubSecrets as G, withTables as H, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, DeclarationRefused as a, DiError as b, type DiKind as c, type ModulePressure as d, assertNoOrphanEntryPoints as e, buildContainer as f, AuthVerifier as g, type CreateAppOptions as h, isDeclarationRefused as i, type EngineConfig as j, type RequestDatabase as k, type RouteEntry as l, type RuntimeHooks as m, type SqlDriver as n, type SqlTx as o, buildRouteTable as p, createApp as q, createLazyTransaction as r, createOps as s, createRequestDatabase as t, effectiveAuth as u, hostAllowed as v, installEgressFence as w, loadConfig as x, makeMemoryCache as y, matchRoute as z };
+export { type App as A, BootRefused as B, type Container as C, DECLARATION_REFUSAL as D, type EgressPolicy as E, makeMemoryCache as F, matchRoute as G, quoteIdent as H, scrubSecrets as I, setCursorKey as J, withQueryCancellation as K, withTables as L, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, DeclarationRefused as a, DiError as b, type DiKind as c, type ModulePressure as d, assertNoOrphanEntryPoints as e, buildContainer as f, AuthVerifier as g, COMMAND_EXECUTOR_DDL as h, isDeclarationRefused as i, type CreateAppOptions as j, type EngineConfig as k, type RequestDatabase as l, type RouteEntry as m, type RuntimeHooks as n, type SqlDriver as o, type SqlTx as p, buildRouteTable as q, createApp as r, createLazyTransaction as s, createOps as t, createRequestDatabase as u, effectiveAuth as v, hostAllowed as w, installCommandExecutor as x, installEgressFence as y, loadConfig as z };

package/dist/{index-DLveQoOf.d.cts → index-pnDsEfxJ.d.cts}

@@ -1,6 +1,6 @@
-import { D as DBClient, b as DBOps, T as TxPlanBody, c as TxPlanResponse, A as AuthSpec, C as CacheClient, a as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-DB_nW-AV.cjs';
+import { c as DatabaseDiagnosticsOptions, d as DatabaseDiagnostics, a as DBClient, T as TransactionIsolation, e as DBOps, P as PreparedRead, C as CompiledRead, f as RawPageOptions, g as Page, h as TxPlanBody, i as CommandOptions, j as TxPlanResponse, A as AuthSpec, k as CacheClient, b as RuntimeServices, _ as __runWithRuntime, l as __requestALS } from './endpoint-kYgEHrrV.cjs';
 import { T as Token } from './module-Dl1KFVtc.cjs';
-import { R as RouteMeta } from './registry-DSTThhKf.cjs';
+import { R as RouteMeta } from './registry-BcOd8Zhf.cjs';
 
 /**
  * engine/config.ts — settings from the environment, and the gate that refuses
@@ -47,6 +47,11 @@ interface EngineConfig {
     anonKey: string;
     /** Secret key. Used for privileged module calls. */
     serviceRoleKey: string;
+    /** Optional dedicated cursor encryption secret, shared by all replicas. */
+    cursorSecret?: string;
+    /** Install the invoker-only PostgreSQL command helper at boot. Requires DDL
+     * rights on the connection role; execution retains each request's RLS role. */
+    enableCommands?: boolean;
     /** HMAC the realtime broadcast token is signed with. Empty ⇒ broadcast
      * returns a clear `realtime_unconfigured` error instead of failing silently. */
     realtimeSecret: string;
@@ -65,6 +70,7 @@ interface EngineConfig {
      */
     dbServiceRole: string;
     poolMax: number;
+    databaseDiagnostics?: DatabaseDiagnosticsOptions;
 }
 /**
  * THE ENVIRONMENT THIS STACK WAS HANDED IS UNUSABLE. Carries the missing names.
@@ -87,42 +93,62 @@ declare class BootRefused extends Error {
  */
 declare function loadConfig(env: Record<string, string | undefined>): EngineConfig;
 
-/**
- * engine/db.ts — a real pooled connection, and the identity every request is
- * bound to inside it.
- *
- * # Why one transaction per request
- *
- * In the isolate architecture every `Database.*` call was its own HTTP hop to a
- * capability surface, so two writes in one handler could not be atomic — a
- * handler that wrote and then threw left the first write behind. Here the whole
- * request runs inside one transaction: it commits when the handler returns and
- * rolls back when it throws. Atomicity stops being something the author has to
- * ask for.
- *
- * # Why it opens lazily
- *
- * A handler that touches no table must cost no round trip. Opening eagerly cost
- * four (BEGIN + bind + … + COMMIT) on endpoints that never query — measured at
- * 1,243 rps against 31,579 for the same endpoint once the open became lazy.
- *
- * # How the caller's identity reaches RLS
- *
- * One statement, not three:
- *
- *   select set_config('role',$1,true),
- *          set_config('search_path','public',true),
- *          set_config('request.jwt.claims',$2,true)
- *
- * `set_config(..., is_local => true)` is transaction-scoped exactly like
- * `SET LOCAL`, but takes BOUND PARAMETERS, which `SET LOCAL` cannot. So the
- * role and the caller's claims travel as parameters — user identity is never
- * spliced into SQL text — and `auth.uid()` resolves inside RLS policies, which
- * means the row filter is enforced by Postgres rather than by our code.
- */
+type CancellableQuery = Promise<unknown> & {
+    cancel?: () => unknown;
+};
+/** Abort callback work and active statements, then let the transaction owner
+ * await rollback. COMMIT is never raced with a timer: its acknowledged result
+ * or connection failure remains authoritative. */
+declare class TransactionControl {
+    private controller;
+    private active;
+    private cancelBackend?;
+    private cancellation;
+    private timer?;
+    private unlink;
+    private rejection;
+    readonly deadline: number | undefined;
+    get signal(): AbortSignal;
+    constructor(timeoutMs?: number, external?: AbortSignal);
+    check(): void;
+    remainingMs(): number | undefined;
+    race<T>(work: Promise<T>): Promise<T>;
+    bindBackend(cancel: () => Promise<void>): void;
+    /** Keep the application's connection parked until the cancellation request
+     * and all statements settle; a late cancel must not hit its next borrower. */
+    drainCancellation(): Promise<void>;
+    watch(query: CancellableQuery): Promise<unknown>;
+    dispose(): void;
+}
+
+type Timing = "queueMs" | "poolMs" | "setupMs" | "sqlMs" | "commitMs" | "rollbackMs";
+/** Allocated only when diagnostics or a budget is configured. One collector
+ * follows the request's user/service handles and independent atomic attempts. */
+declare class DatabaseTrace {
+    private readonly options;
+    private readonly start;
+    private ended?;
+    private failure?;
+    private readonly state;
+    constructor(options: DatabaseDiagnosticsOptions);
+    check(): void;
+    time(key: Timing, started: number): void;
+    retry(): void;
+    committed(): void;
+    commitFailed(): void;
+    failed(): void;
+    rolledBack(): void;
+    private refuse;
+    private emit;
+    query(sql: string, name: string | undefined, run: () => Promise<unknown>): Promise<unknown>;
+    get snapshot(): DatabaseDiagnostics;
+    complete(outcome: "committed" | "failed"): void;
+}
 
 /** The slice of a SQL driver the engine uses. `Bun.sql` satisfies it. */
 interface SqlDriver {
+    /** Optional reliable cancellation through a separate control connection. */
+    cancelBackend?(pid: number, startedAt: string): Promise<void>;
     /** Run a parameterised statement. */
     unsafe(sql: string, params?: unknown[]): Promise<unknown>;
     /** Open a transaction; the driver commits when `cb` resolves and rolls back
@@ -130,7 +156,9 @@ interface SqlDriver {
     begin<T>(cb: (tx: SqlTx) => Promise<T>): Promise<T>;
 }
 interface SqlTx {
-    unsafe(sql: string, params?: unknown[]): Promise<unknown>;
+    unsafe(sql: string, params?: unknown[], metadata?: {
+        name?: string;
+    }): Promise<unknown>;
     savepoint<T>(cb: (sp: SqlTx) => Promise<T>): Promise<T>;
 }
 type Row = Record<string, unknown>;
@@ -147,6 +175,12 @@ declare function quoteIdent(name: string): string;
  */
 declare function createLazyTransaction(sql: SqlDriver, role: string, claimsJson: string, options?: {
     lockTimeout?: string;
+    statementTimeout?: string;
+    isolation?: TransactionIsolation;
+    readOnly?: boolean;
+    scope?: symbol;
+    control?: TransactionControl;
+    trace?: DatabaseTrace;
 }): {
     ensure: () => Promise<SqlTx>;
     readonly opened: boolean;
@@ -186,7 +220,13 @@ interface FindManyOptions {
      * refused without it — see `offsetClause`. */
     offset?: number;
 }
-declare function createOps(tx: TxLike): {
+interface OpsContext {
+    readonly cursorScope?: string;
+    readonly commands?: boolean;
+    readonly trace?: DatabaseTrace;
+}
+declare function createOps(tx: TxLike, context?: OpsContext): {
+    diagnostics(): DatabaseDiagnostics | null;
     query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
     insert(table: string, data: Row): Promise<Row>;
     /**
@@ -203,10 +243,7 @@ declare function createOps(tx: TxLike): {
      * bir satırın fazla kolonu SESSİZCE YAZILMAZDI. Eksik kolon için `null`
      * yazın ya da varsayılanı istiyorsanız o satırları ayrı çağrıda ekleyin.
      */
-    insertMany(table: string, rows: readonly Row[], opts?: {
-        onConflict: readonly string[];
-        action?: "ignore" | "update";
-    }): Promise<Row[]>;
+    insertMany: DBOps["insertMany"];
     /**
      * Bir ADI kilitle — satırı değil (FR-054).
      *
@@ -338,8 +375,16 @@ declare function createOps(tx: TxLike): {
         groupBy?: readonly string[];
     }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
     count(table: string, where?: Row): Promise<number>;
+    findUnique(table: string, where: Row, opts?: {
+        select?: readonly string[];
+        with?: Record<string, unknown>;
+    }): Promise<Row | null>;
     findById(table: string, id: string): Promise<Row | null>;
+    compileQuery(query: PreparedRead): CompiledRead;
+    readQuery(query: PreparedRead): Promise<Row[]>;
+    explainQuery(query: PreparedRead): Promise<unknown[]>;
     findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
+    page(table: string, query?: Row, opts?: RawPageOptions): Promise<Page<Row>>;
     /**
      * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
      * (1/(50+rank), CLAIM-N4). Operatör şema-nitelikli (C-10, M-1); GUC
@@ -495,15 +540,9 @@ declare function createOps(tx: TxLike): {
      * "transport.txPlan is not a function" while every test that covered
      * transactions passed against a mock that did implement it.
      */
+    command(plan: TxPlanBody, options?: CommandOptions): Promise<TxPlanResponse>;
     txPlan(plan: TxPlanBody): Promise<TxPlanResponse>;
 };
-/**
- * Merge the typed `.tables` accessor onto a raw op surface.
- *
- * Mirrors what the pod runtime does, including the recursive application to the
- * transaction callback: without it `tx.tables.rooms.insert(...)` throws
- * "Cannot read properties of undefined".
- */
 declare function withTables<T extends ReturnType<typeof createOps>>(ops: T, schema?: {
     tables?: Record<string, {
         name?: string;
@@ -580,7 +619,7 @@ declare function createRequestDatabase(sql: SqlDriver, identity: {
     role: string;
     serviceRole: string;
     claimsJson: string;
-}): RequestDatabase;
+}, diagnostics?: DatabaseDiagnosticsOptions): RequestDatabase;
 
 /**
  * The two ways a stack refuses to boot — and they are two because their CURES
@@ -926,6 +965,25 @@ interface MemoryCacheOptions {
  */
 declare function makeMemoryCache(opts?: MemoryCacheOptions): CacheClient;
 
+/** One application secret shared by replicas. Rotation invalidates old cursors.
+ * Encryption also hides sort values omitted by the public projection. */
+declare function setCursorKey(secret: string | null): void;
+
+/** Statements remain sequential inside PostgreSQL. Each sees preceding writes,
+ * including triggers, unlike sibling data-modifying CTEs in one SQL statement.
+ * The exception block is a subtransaction, matching a savepoint plan. */
+declare const COMMAND_EXECUTOR_DDL = "\nCREATE SCHEMA IF NOT EXISTS palbase_runtime;\nCREATE OR REPLACE FUNCTION palbase_runtime.command_v1(steps jsonb) RETURNS jsonb\nLANGUAGE plpgsql VOLATILE SECURITY INVOKER SET search_path = pg_catalog, public AS $pb_command$\nDECLARE\n  results jsonb := '[]'::jsonb;\n  step jsonb; chunk jsonb; binding jsonb; source jsonb; rows jsonb;\n  statement text; rendered text; detail text; guard jsonb;\n  index integer := 0; affected integer; passed boolean;\nBEGIN\n  FOR step IN SELECT value FROM jsonb_array_elements(steps) LOOP\n    IF step->>'empty' = 'true' THEN rows := '[]'::jsonb;\n    ELSE\n      statement := '';\n      FOR chunk IN SELECT value FROM jsonb_array_elements(step->'chunks') LOOP\n        IF jsonb_typeof(chunk) = 'string' THEN statement := statement || (chunk #>> '{}');\n        ELSE\n          binding := step->'bindings'->((chunk->>'bind')::integer);\n          IF binding ? 'ref' THEN\n            source := results->((binding->'ref'->>'op')::integer)->'rows'->0;\n            IF source IS NULL OR NOT source ? (binding->'ref'->>'field') THEN\n              RAISE EXCEPTION 'Command reference has no source row/column; use expectOne before reading it'\n                USING ERRCODE = 'PBC02', DETAIL = jsonb_build_object('error_code','tx_ref_unresolved','op',index)::text;\n            END IF;\n            source := source->(binding->'ref'->>'field');\n          ELSE source := binding->'value'; END IF;\n          rendered := CASE WHEN source IS NULL OR source = 'null'::jsonb THEN NULL\n            WHEN binding->>'json' = 'true' THEN source::text\n            WHEN jsonb_typeof(source) = 'string' THEN source #>> '{}' ELSE source::text END;\n          -- PostgreSQL quotes the value itself. Values reach this function as\n          -- one bound JSON parameter, never as application-generated SQL text.\n          statement := statement || quote_nullable(rendered);\n        END IF;\n      END LOOP;\n      EXECUTE statement INTO rows;\n    END IF;\n    affected := jsonb_array_length(rows);\n    guard := step->'guard';\n    IF guard IS NOT NULL AND guard <> 'null'::jsonb THEN\n      passed := CASE guard->>'kind'\n        WHEN 'one' THEN affected = 1 WHEN 'none' THEN affected = 0\n        WHEN 'atLeast' THEN affected >= (guard->>'n')::integer\n        WHEN 'atMost' THEN affected <= (guard->>'n')::integer ELSE false END;\n      IF NOT passed THEN\n        RAISE EXCEPTION 'Command expectation failed'\n          USING ERRCODE = 'PBC01', DETAIL = jsonb_build_object('error_code','tx_guard_failed','slot',guard->'slot','op',index)::text;\n      END IF;\n    END IF;\n    results := results || jsonb_build_array(jsonb_build_object('rows',rows,'rows_affected',affected));\n    index := index + 1;\n  END LOOP;\n  RETURN jsonb_build_object('results',results);\nEXCEPTION WHEN SQLSTATE 'PBC01' OR SQLSTATE 'PBC02' THEN\n  GET STACKED DIAGNOSTICS detail = PG_EXCEPTION_DETAIL;\n  RETURN jsonb_build_object('error',detail::jsonb);\nEND\n$pb_command$;\nREVOKE ALL ON FUNCTION palbase_runtime.command_v1(jsonb) FROM PUBLIC;\nCREATE OR REPLACE FUNCTION palbase_runtime.command_rows_v1(rows jsonb, guard jsonb) RETURNS jsonb\nLANGUAGE plpgsql VOLATILE SECURITY INVOKER SET search_path = pg_catalog, public AS $pb_rows$\nDECLARE affected integer := jsonb_array_length(rows); passed boolean;\nBEGIN\n  IF guard IS NOT NULL AND guard <> 'null'::jsonb THEN\n    passed := CASE guard->>'kind'\n      WHEN 'one' THEN affected = 1 WHEN 'none' THEN affected = 0\n      WHEN 'atLeast' THEN affected >= (guard->>'n')::integer\n      WHEN 'atMost' THEN affected <= (guard->>'n')::integer ELSE false END;\n    IF NOT passed THEN\n      RAISE EXCEPTION 'Command expectation failed'\n        USING ERRCODE = 'PBC01', DETAIL = jsonb_build_object('error_code','tx_guard_failed','slot',guard->'slot')::text;\n    END IF;\n  END IF;\n  RETURN rows;\nEND\n$pb_rows$;\nREVOKE ALL ON FUNCTION palbase_runtime.command_rows_v1(jsonb,jsonb) FROM PUBLIC;\n";
+/** Run once with a migration/owner connection. Runtime execution retains each
+ * caller's role and RLS; there is no SECURITY DEFINER capability. */
+declare function installCommandExecutor(sql: SqlDriver, roles: readonly string[]): Promise<void>;
+
+/** The control pool must be separate from the application pool, connect as the
+ * same session user and to the same PostgreSQL server. Cancellation must still
+ * have a connection when every application connection is occupied. */
+declare function withQueryCancellation(application: SqlDriver, control: SqlDriver): SqlDriver & {
+    close(): Promise<void>;
+};
+
 /**
  * engine/fence.ts — what the tenant's own code may reach.
  *
@@ -1063,4 +1121,4 @@ interface App {
 }
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
-export { type App as A, BootRefused as B, type Container as C, DECLARATION_REFUSAL as D, type EgressPolicy as E, quoteIdent as F, scrubSecrets as G, withTables as H, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, DeclarationRefused as a, DiError as b, type DiKind as c, type ModulePressure as d, assertNoOrphanEntryPoints as e, buildContainer as f, AuthVerifier as g, type CreateAppOptions as h, isDeclarationRefused as i, type EngineConfig as j, type RequestDatabase as k, type RouteEntry as l, type RuntimeHooks as m, type SqlDriver as n, type SqlTx as o, buildRouteTable as p, createApp as q, createLazyTransaction as r, createOps as s, createRequestDatabase as t, effectiveAuth as u, hostAllowed as v, installEgressFence as w, loadConfig as x, makeMemoryCache as y, matchRoute as z };
+export { type App as A, BootRefused as B, type Container as C, DECLARATION_REFUSAL as D, type EgressPolicy as E, makeMemoryCache as F, matchRoute as G, quoteIdent as H, scrubSecrets as I, setCursorKey as J, withQueryCancellation as K, withTables as L, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, DeclarationRefused as a, DiError as b, type DiKind as c, type ModulePressure as d, assertNoOrphanEntryPoints as e, buildContainer as f, AuthVerifier as g, COMMAND_EXECUTOR_DDL as h, isDeclarationRefused as i, type CreateAppOptions as j, type EngineConfig as k, type RequestDatabase as l, type RouteEntry as m, type RuntimeHooks as n, type SqlDriver as o, type SqlTx as p, buildRouteTable as q, createApp as r, createLazyTransaction as s, createOps as t, createRequestDatabase as u, effectiveAuth as v, hostAllowed as w, installCommandExecutor as x, installEgressFence as y, loadConfig as z };