@palbase/backend 23.0.0 → 23.1.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, h as AuthVerifier, B as BootRefused, i as CreateAppOptions, E as EgressPolicy, j as EngineConfig, M as ModuleClients, k as RateLimiter, l as RequestDatabase, m as RouteEntry, n as RuntimeHooks, o as ScrubResult, p as SqlDriver, q as SqlTx, r as buildRouteTable, s as createApp, t as createLazyTransaction, u as createOps, v as createRequestDatabase, w as effectiveAuth, x as hostAllowed, y as installEgressFence, z as loadConfig, G as makeMemoryCache, H as matchRoute, I as quoteIdent, J as scrubSecrets, K as withTables } from '../index-CxeQSfJP.cjs';
+import '../endpoint-c9h5jriX.cjs';
 import '../stack.cjs';
 import 'node:async_hooks';
-import '../index-Bmvx1EvJ.cjs';
+import '../index-By8Dle5U.cjs';
 import '../db/env.cjs';
-import '../registry-C3H2uPeZ.cjs';
+import '../registry-CqPK2Qby.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, h as AuthVerifier, B as BootRefused, i as CreateAppOptions, E as EgressPolicy, j as EngineConfig, M as ModuleClients, k as RateLimiter, l as RequestDatabase, m as RouteEntry, n as RuntimeHooks, o as ScrubResult, p as SqlDriver, q as SqlTx, r as buildRouteTable, s as createApp, t as createLazyTransaction, u as createOps, v as createRequestDatabase, w as effectiveAuth, x as hostAllowed, y as installEgressFence, z as loadConfig, G as makeMemoryCache, H as matchRoute, I as quoteIdent, J as scrubSecrets, K as withTables } from '../index-BZrJXnVh.js';
+import '../endpoint-CVWXh6oG.js';
 import '../stack.js';
 import 'node:async_hooks';
-import '../index-B3jmmItD.js';
+import '../index-CwAJ7HEe.js';
 import '../db/env.js';
-import '../registry-DY3d9l1k.js';
+import '../registry-B3niOVYp.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-M5MCBWJI.js";
+import "../chunk-OHALWEOG.js";
+import "../chunk-NS5V43YQ.js";
+import "../chunk-RCLNBJCM.js";
 import "../chunk-7D4SUZUM.js";
 export {
   AuthVerifier,

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

@@ -1,8 +1,8 @@
 import { Buckets, BucketTypes } from './stack.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, T as TxPlanBody, f as TxPlanResponse } from './endpoint-BavvbW4P.js';
-import { E as EnvTypedDatabase } from './index-B3jmmItD.js';
-import { R as RouteMeta } from './registry-DY3d9l1k.js';
+import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, f as DBOps, T as TxPlanBody, g as TxPlanResponse } from './endpoint-CVWXh6oG.js';
+import { E as EnvTypedDatabase } from './index-CwAJ7HEe.js';
+import { R as RouteMeta } from './registry-B3niOVYp.js';
 
 /**
  * runtime.ts — request-scoped service singletons.
@@ -361,14 +361,41 @@ declare function createLazyTransaction(sql: SqlDriver, role: string, claimsJson:
 type LazyTransaction = ReturnType<typeof createLazyTransaction>;
 /** Either a live driver transaction or the lazy holder above. */
 type TxLike = SqlTx | LazyTransaction;
+/** What `findMany` accepts beside its filter: an ordering and a row ceiling.
+ * Both used to require dropping to raw SQL, and the docs said so — which is how
+ * a tenant's controllers filled up with hand-written SELECTs. */
+interface FindManyOptions {
+    orderBy?: {
+        column: string;
+        direction?: "asc" | "desc";
+    };
+    limit?: number;
+}
 /** The six string-keyed operations, plus an interactive `transaction`. */
 declare function createOps(tx: TxLike): {
     query(sql: string, params?: unknown[]): Promise<Row[]>;
     insert(table: string, data: Row): Promise<Row>;
+    /**
+     * INSERT the row, or UPDATE it when it collides on `onConflict`.
+     *
+     * WHY IT IS AN OPERATION rather than a recipe. "Try the insert, catch the
+     * unique violation, update instead" does not work here: a request runs in ONE
+     * Postgres transaction, so the failed insert aborts it and every later
+     * statement answers `current transaction is aborted`. A tenant measured that
+     * as 7 of 8 concurrent requests returning 500, gave up on upsert, and had a
+     * trigger create the row instead — a workaround that needs a new trigger for
+     * every table with a unique row.
+     *
+     * The conflict columns are excluded from the SET list: they are what MATCHED,
+     * so writing them back is at best a no-op and at worst a surprise.
+     */
+    upsert(table: string, data: Row, opts: {
+        onConflict: readonly string[];
+    }): Promise<Row>;
     update(table: string, id: string, data: Row): Promise<Row | null>;
     delete(table: string, id: string): Promise<void>;
     findById(table: string, id: string): Promise<Row | null>;
-    findMany(table: string, query?: Row): Promise<Row[]>;
+    findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
     /**
      * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
      * (1/(50+rank), CLAIM-N4). Operatör şema-nitelikli (C-10, M-1); GUC
@@ -476,6 +503,24 @@ declare function createOps(tx: TxLike): {
     supersede(table: string, id: string, row: Row): Promise<Row>;
     /** A real SAVEPOINT inside the request's transaction. */
     transaction<T>(cb: (t: unknown) => Promise<T>): Promise<T>;
+    /**
+     * Run `fn` against a handle bound to a SAVEPOINT, so a failure inside it
+     * rolls back only what that handle wrote and the request can keep writing.
+     *
+     * WHY THE HANDLE IS AN ARGUMENT. The obvious shape — `attempt(async () => {
+     * ... Database.insert(...) ... })`, with no parameter — would have to point
+     * the ambient `Database` at the savepoint for the duration, and a request is
+     * concurrent with itself: `Promise.all([Database.insert(a),
+     * Database.attempt(...)])` would put `a` inside the savepoint and roll it
+     * back with it. Silent data loss, and the same interleaving this file already
+     * refuses for `asService()`. Passing the handle makes the boundary something
+     * you can see in the code that crosses it.
+     *
+     * Postgres, not us: the savepoint is released on success and rolled back on
+     * failure by the driver, so an aborted statement inside `fn` does not poison
+     * the surrounding transaction.
+     */
+    attempt<T>(fn: (tx: DBOps) => Promise<T>): Promise<T>;
     /**
      * Execute a whole transaction plan — what `Database.transaction(fn)` builds.
      *

package/dist/{index-Bmvx1EvJ.d.cts → index-By8Dle5U.d.cts}

@@ -1,5 +1,5 @@
 import { Tables, TableTypes } from './db/env.cjs';
-import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-i8TTCohk.cjs';
+import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-c9h5jriX.cjs';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -36,6 +36,17 @@ 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;
@@ -80,6 +91,18 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
     defaultRandom(): ColumnBuilder<K, N, true, E, P>;
     /** Timestamp: default to now(). */
     defaultNow(): ColumnBuilder<K, N, true, E, P>;
+    /**
+     * 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>;
     /** Add a foreign key reference. */
     /**
      * Declares that this column used to be called `previous`.
@@ -247,22 +270,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 +287,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,6 +682,9 @@ 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. */
@@ -755,6 +793,16 @@ 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. */
@@ -856,6 +904,27 @@ interface EnvTypedDatabase extends Omit<DBClient, "txPlan" | "asService"> {
      * });
      */
     transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
+    /**
+     * Run `fn` inside a SAVEPOINT, so a write that fails in it does not poison the
+     * rest of the request.
+     *
+     * A request is ONE Postgres transaction: a failed statement aborts it and
+     * every later one answers `current transaction is aborted`. That is why
+     * "insert, catch the unique violation, update instead" cannot be written
+     * directly — and why {@link EnvTypedTableBase.upsert} exists for the common
+     * case. Reach for `attempt` when the recovery is not an upsert.
+     *
+     * The handle is a parameter, not the ambient `Database`: only what `tx` writes
+     * is inside the boundary, so a concurrent branch of the same request cannot be
+     * rolled back by someone else's failure.
+     *
+     * @example
+     * const claimed = await Database.attempt(async (tx) => {
+     *   await tx.insert("seats", { row: 4, seat: 12, user_id: user.id });
+     *   return true;
+     * }).catch(() => false);
+     */
+    attempt<T>(fn: (tx: Omit<DBClient, "attempt" | "txPlan" | "asService">) => Promise<T>): Promise<T>;
     /**
      * Return a sibling that bypasses RLS by running as the `service_role`. Use
      * sparingly and explicitly — the default `Database.*` path is RLS-enforced.

package/dist/{index-B3jmmItD.d.ts → index-CwAJ7HEe.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-CVWXh6oG.js';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -36,6 +36,17 @@ 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;
@@ -80,6 +91,18 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
     defaultRandom(): ColumnBuilder<K, N, true, E, P>;
     /** Timestamp: default to now(). */
     defaultNow(): ColumnBuilder<K, N, true, E, P>;
+    /**
+     * 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>;
     /** Add a foreign key reference. */
     /**
      * Declares that this column used to be called `previous`.
@@ -247,22 +270,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 +287,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,6 +682,9 @@ 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. */
@@ -755,6 +793,16 @@ 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. */
@@ -856,6 +904,27 @@ interface EnvTypedDatabase extends Omit<DBClient, "txPlan" | "asService"> {
      * });
      */
     transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
+    /**
+     * Run `fn` inside a SAVEPOINT, so a write that fails in it does not poison the
+     * rest of the request.
+     *
+     * A request is ONE Postgres transaction: a failed statement aborts it and
+     * every later one answers `current transaction is aborted`. That is why
+     * "insert, catch the unique violation, update instead" cannot be written
+     * directly — and why {@link EnvTypedTableBase.upsert} exists for the common
+     * case. Reach for `attempt` when the recovery is not an upsert.
+     *
+     * The handle is a parameter, not the ambient `Database`: only what `tx` writes
+     * is inside the boundary, so a concurrent branch of the same request cannot be
+     * rolled back by someone else's failure.
+     *
+     * @example
+     * const claimed = await Database.attempt(async (tx) => {
+     *   await tx.insert("seats", { row: 4, seat: 12, user_id: user.id });
+     *   return true;
+     * }).catch(() => false);
+     */
+    attempt<T>(fn: (tx: Omit<DBClient, "attempt" | "txPlan" | "asService">) => Promise<T>): Promise<T>;
     /**
      * Return a sibling that bypasses RLS by running as the `service_role`. Use
      * sparingly and explicitly — the default `Database.*` path is RLS-enforced.

package/dist/{index-E7OscPJT.d.cts → index-CxeQSfJP.d.cts}

@@ -1,8 +1,8 @@
 import { Buckets, BucketTypes } from './stack.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, T as TxPlanBody, f as TxPlanResponse } from './endpoint-i8TTCohk.cjs';
-import { E as EnvTypedDatabase } from './index-Bmvx1EvJ.cjs';
-import { R as RouteMeta } from './registry-C3H2uPeZ.cjs';
+import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, f as DBOps, T as TxPlanBody, g as TxPlanResponse } from './endpoint-c9h5jriX.cjs';
+import { E as EnvTypedDatabase } from './index-By8Dle5U.cjs';
+import { R as RouteMeta } from './registry-CqPK2Qby.cjs';
 
 /**
  * runtime.ts — request-scoped service singletons.
@@ -361,14 +361,41 @@ declare function createLazyTransaction(sql: SqlDriver, role: string, claimsJson:
 type LazyTransaction = ReturnType<typeof createLazyTransaction>;
 /** Either a live driver transaction or the lazy holder above. */
 type TxLike = SqlTx | LazyTransaction;
+/** What `findMany` accepts beside its filter: an ordering and a row ceiling.
+ * Both used to require dropping to raw SQL, and the docs said so — which is how
+ * a tenant's controllers filled up with hand-written SELECTs. */
+interface FindManyOptions {
+    orderBy?: {
+        column: string;
+        direction?: "asc" | "desc";
+    };
+    limit?: number;
+}
 /** The six string-keyed operations, plus an interactive `transaction`. */
 declare function createOps(tx: TxLike): {
     query(sql: string, params?: unknown[]): Promise<Row[]>;
     insert(table: string, data: Row): Promise<Row>;
+    /**
+     * INSERT the row, or UPDATE it when it collides on `onConflict`.
+     *
+     * WHY IT IS AN OPERATION rather than a recipe. "Try the insert, catch the
+     * unique violation, update instead" does not work here: a request runs in ONE
+     * Postgres transaction, so the failed insert aborts it and every later
+     * statement answers `current transaction is aborted`. A tenant measured that
+     * as 7 of 8 concurrent requests returning 500, gave up on upsert, and had a
+     * trigger create the row instead — a workaround that needs a new trigger for
+     * every table with a unique row.
+     *
+     * The conflict columns are excluded from the SET list: they are what MATCHED,
+     * so writing them back is at best a no-op and at worst a surprise.
+     */
+    upsert(table: string, data: Row, opts: {
+        onConflict: readonly string[];
+    }): Promise<Row>;
     update(table: string, id: string, data: Row): Promise<Row | null>;
     delete(table: string, id: string): Promise<void>;
     findById(table: string, id: string): Promise<Row | null>;
-    findMany(table: string, query?: Row): Promise<Row[]>;
+    findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
     /**
      * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
      * (1/(50+rank), CLAIM-N4). Operatör şema-nitelikli (C-10, M-1); GUC
@@ -476,6 +503,24 @@ declare function createOps(tx: TxLike): {
     supersede(table: string, id: string, row: Row): Promise<Row>;
     /** A real SAVEPOINT inside the request's transaction. */
     transaction<T>(cb: (t: unknown) => Promise<T>): Promise<T>;
+    /**
+     * Run `fn` against a handle bound to a SAVEPOINT, so a failure inside it
+     * rolls back only what that handle wrote and the request can keep writing.
+     *
+     * WHY THE HANDLE IS AN ARGUMENT. The obvious shape — `attempt(async () => {
+     * ... Database.insert(...) ... })`, with no parameter — would have to point
+     * the ambient `Database` at the savepoint for the duration, and a request is
+     * concurrent with itself: `Promise.all([Database.insert(a),
+     * Database.attempt(...)])` would put `a` inside the savepoint and roll it
+     * back with it. Silent data loss, and the same interleaving this file already
+     * refuses for `asService()`. Passing the handle makes the boundary something
+     * you can see in the code that crosses it.
+     *
+     * Postgres, not us: the savepoint is released on success and rolled back on
+     * failure by the driver, so an aborted statement inside `fn` does not poison
+     * the surrounding transaction.
+     */
+    attempt<T>(fn: (tx: DBOps) => Promise<T>): Promise<T>;
     /**
      * Execute a whole transaction plan — what `Database.transaction(fn)` builds.
      *