@palbase/backend 10.3.0 → 12.0.0

package/dist/{endpoint-92kVepng.d.ts → endpoint-Ck4hER_7.d.ts}

@@ -67,6 +67,333 @@ type MiddlewareHandler = (ctx: MiddlewareContext, next: () => Promise<void>) =>
  */
 declare function defineMiddleware(fn: MiddlewareHandler): MiddlewareHandler;
 
+/**
+ * tx-plan.ts — `Database.transaction()` as a PLAN, not a pinned session.
+ *
+ * A transaction used to be a conversation: BEGIN, then one network round trip
+ * per operation, then COMMIT. Each of those round trips cost ~4 ms and, because
+ * the pooler runs in transaction mode, an open transaction pinned a Postgres
+ * backend for the whole conversation. A 121-operation statement upload pinned
+ * one backend for ~490 ms.
+ *
+ * So the callback no longer TALKS to the database. It DESCRIBES what should
+ * happen; the description is serialised and sent once; the broker runs the whole
+ * thing inside one transaction and answers once. Committing on return and
+ * rolling back on throw is unchanged — that is the only property tenant code
+ * actually asked for.
+ *
+ * The consequences, stated plainly, because they are the whole design:
+ *
+ *   - The callback is SYNCHRONOUS. There is nothing to await: no statement has
+ *     run yet when it returns. `async` on the callback and `await` inside it are
+ *     both compile errors (see {@link TxPlan} and {@link NotAwaitable}).
+ *   - `insert()` does not hand back a row, it hands back {@link TxRows}. Reading
+ *     a field requires `.expectOne(err)` first, which makes "what if the row
+ *     isn't there" a question you cannot route around: it is the argument.
+ *   - A field read from a row is a {@link Ref} — a PROMISE OF A VALUE THE SERVER
+ *     WILL PRODUCE, not the value. It can be written into a later operation and
+ *     it can be returned from the callback (it is substituted for the real value
+ *     before `transaction()` resolves). It cannot be branched on. See the
+ *     "Truthiness" note below — this is the sharp edge of the whole design.
+ *   - Control flow that needs a real value must move OUT of the callback: read
+ *     before the transaction, or express the condition as a guard
+ *     (`updateWhere({ id, accepted_at: null }, …).expectOne(new Conflict(…))`)
+ *     which the server evaluates and which rolls the whole plan back.
+ *
+ * # Truthiness — the hole this file CANNOT close
+ *
+ * JavaScript does not let a Proxy trap truthiness. `if (ref)` takes the true
+ * branch, always, for every Ref, and no `get` handler ever runs. `tsc` is silent
+ * because a Ref is a perfectly good object. So:
+ *
+ *     const pot = tx.tables.pots.select({ id }, { limit: 1 }).expectOne(e);
+ *     if (!pot.balance) { … }        // ← ALWAYS false. Silently wrong data.
+ *
+ * What this file does close: coercion (`Symbol.toPrimitive`/`valueOf`/
+ * `toString`), awaiting (`then` is a callable member with a non-thenable
+ * signature, which is a *compile* error), serialisation (`toJSON`), and nesting
+ * a Ref inside a literal value where the server would store it as data. What it
+ * cannot close is a bare truthiness test. The real defence is the build-time
+ * static analysis (`tx_analysis.js`, phase P4); until that ships, this hole is
+ * open and this comment is the only warning.
+ *
+ * # Wire contract
+ *
+ * The JSON this file emits is consumed by
+ * `modules/backend/internal/management/tx_program.go`. That decoder rejects
+ * unknown fields at every level, so an op carries EXACTLY the fields its kind
+ * takes. Everything here that looks like a needless restriction is one of the
+ * server's rules made visible early:
+ *
+ *   - `$ref` only points BACKWARDS, and only at an op statically known to yield
+ *     at most one row (insert, or a `one`/`atMost 1` guard, or `select limit 1`).
+ *     `.expectOne()` is what this file uses to satisfy that, always.
+ *   - `$expr` is a closed set: `inc`/`dec` (update only — they read the column's
+ *     current value) and `now()`.
+ *   - `update`/`delete` require a `where`; `insert` refuses one.
+ *   - `insertMany` rows must all set the same columns.
+ *   - ≤1000 ops, ≤5000 rows per insertMany, ≤8 MiB of JSON.
+ *
+ * Column keys are emitted SORTED, so the same callback always produces byte-
+ * identical JSON. That is what lets the Go decoder be locked to golden files
+ * this SDK emits (`testdata/tx_plan_golden/`).
+ */
+/**
+ * A plan handle was used as if it were a value: awaited, coerced to a string or
+ * number, serialised, or nested inside another value.
+ *
+ * Thrown while the callback is still BUILDING the plan, so nothing has been sent
+ * and nothing has been written.
+ */
+declare class TxRefError extends Error {
+    constructor(message: string);
+}
+/**
+ * The plan the callback described cannot be sent: it breaks a rule the server
+ * would reject, and rejecting it here names the line that wrote it instead of
+ * returning a 400 about an op index.
+ */
+declare class TxPlanError extends Error {
+    constructor(message: string);
+}
+/** A backwards reference to an earlier op's single-row result. */
+interface TxWireRef {
+    $ref: {
+        op: number;
+        field: string;
+    };
+}
+/** A call from the server's closed function set. */
+interface TxWireExpr {
+    $expr: {
+        fn: "inc" | "dec";
+        by: number;
+    } | {
+        fn: "now";
+    };
+}
+/** One value in a `values`/`set`/`where` map: a literal, a `$ref` or a `$expr`. */
+type TxWireValue = TxWireRef | TxWireExpr | unknown;
+/** The tenant's declared expectation about an op's row count. `slot` indexes the
+ * client-side error table — the error OBJECT never travels. */
+interface TxWireGuard {
+    kind: "one" | "none" | "atLeast" | "atMost";
+    n: number;
+    slot: number;
+}
+/** One operation in the wire plan. Fields are omitted, never null: the decoder
+ * rejects a field that does not belong to the op's kind. */
+interface TxWireOp {
+    op: "insert" | "insertMany" | "update" | "delete" | "select";
+    table: string;
+    values?: Record<string, TxWireValue>;
+    rows?: Record<string, TxWireValue>[];
+    set?: Record<string, TxWireValue>;
+    where?: Record<string, TxWireValue>;
+    limit?: number;
+    lock?: "update";
+    guard?: TxWireGuard;
+}
+/** The request body of `POST /internal-api/db/tx`. */
+interface TxPlanBody {
+    ops: TxWireOp[];
+}
+/** One op's outcome, positionally matched to the plan's ops. */
+interface TxPlanOpResult {
+    rows: Record<string, unknown>[];
+    rows_affected: number;
+}
+/** The response body of `POST /internal-api/db/tx`. */
+interface TxPlanResponse {
+    results: TxPlanOpResult[];
+}
+/**
+ * The fields the runtime must copy from the broker's error envelope onto the
+ * rejection it throws out of {@link DBClient.txPlan}.
+ *
+ * `slot` is the whole point: on a guard failure the server answers with the
+ * INDEX of the expectation that did not hold, never with an error message of its
+ * own, and this SDK maps that index back to the `Error` the callback handed to
+ * `.expectOne(…)`. Without `slot` a guard failure degrades to a generic 409.
+ */
+interface TxPlanRejection {
+    status?: number;
+    /** `tx_plan_invalid` | `tx_guard_failed` | `tx_ref_unresolved` | a pg class. */
+    error_code?: string;
+    /** Present only for `tx_guard_failed`: the client-side error table index. */
+    slot?: number;
+    /** Present on a database error: which op failed. */
+    op?: number;
+}
+declare const refBrand: unique symbol;
+declare const rowBrand: unique symbol;
+declare const rowsBrand: unique symbol;
+/**
+ * Makes a handle a compile error to `await`.
+ *
+ * `then` is declared as a CALLABLE member whose signature is not `PromiseLike`,
+ * which is precisely the shape TypeScript rejects: `await handle` is TS1320 and
+ * `async () => handle` is TS1058. A non-callable `then` would not do it — the
+ * compiler simply ignores those.
+ */
+interface NotAwaitable {
+    /** Not a promise. Nothing here has run yet; there is nothing to await. */
+    then(doNotAwaitAPlanHandle: "a transaction plan is built synchronously"): never;
+}
+/**
+ * A value the SERVER will produce, standing in for a column of a row this plan
+ * writes or reads.
+ *
+ * Legal uses: write it into a later operation's `values`/`set`/`where`, or
+ * return it from the callback (it is replaced by the real value before
+ * `transaction()` resolves).
+ *
+ * Illegal, and caught: `await`, `String(ref)`, `` `${ref}` ``, `ref + 1`,
+ * `JSON.stringify(ref)`, burying it inside a jsonb object.
+ *
+ * Illegal, and NOT caught: `if (ref)`. See the truthiness note at the top.
+ */
+interface Ref<T> extends NotAwaitable {
+    readonly [refBrand]: T;
+}
+/** The brand carried by a single-row handle, and the seam `Materialized` reads
+ * to turn `return st` into the whole row. */
+interface TxRowHandle<Row> extends NotAwaitable {
+    readonly [rowBrand]: Row;
+}
+/**
+ * A row this plan is known to produce exactly one of. Every property is a
+ * {@link Ref}; returning the handle itself yields the whole row.
+ *
+ * Only `.expectOne(err)` produces one — which is the design: a row you can read
+ * fields from is a row whose absence you have already answered for.
+ */
+type TxRow<Row> = {
+    readonly [K in keyof Row]: Ref<Row[K]>;
+} & TxRowHandle<Row>;
+/**
+ * The result of one operation, before any expectation is declared about it.
+ *
+ * Deliberately not a row and not a list: an operation's row count is not known
+ * until the server runs it, so the only thing that can be said about it here is
+ * an EXPECTATION. Declaring one is also the only way to get a readable row.
+ *
+ * At most one expectation per operation — the wire carries one guard per op, and
+ * a second call throws rather than silently dropping the first.
+ */
+interface TxRows<Row> extends NotAwaitable {
+    readonly [rowsBrand]: Row;
+    /**
+     * Require exactly one row, and read it. On any other count the server rolls
+     * the whole transaction back and this `error` is thrown to the caller.
+     *
+     * This is the only way to reach a row's fields, and the only shape a `$ref`
+     * may point at.
+     */
+    expectOne(error: Error): TxRow<Row>;
+    /** Require zero rows (e.g. "this membership must not already exist"). */
+    expectNone(error: Error): void;
+    /** Require at least `n` rows. */
+    expectAtLeast(n: number, error: Error): void;
+    /** Require at most `n` rows. */
+    expectAtMost(n: number, error: Error): void;
+}
+/** `now()` — the server's clock, usable wherever a value is. */
+interface TxNow extends NotAwaitable {
+    readonly $expr: {
+        fn: "now";
+    };
+}
+/** `inc(n)` / `dec(n)` — read the column's CURRENT value and write it back
+ * changed. Only meaningful in an update's `set`, which is where the types allow
+ * it and where the server allows it. */
+interface TxColumnExpr extends NotAwaitable {
+    readonly $expr: {
+        fn: "inc" | "dec";
+        by: number;
+    };
+}
+/**
+ * Resolve a callback's return type against what actually comes back: every
+ * {@link Ref} becomes its value, every {@link TxRow} becomes its row, and
+ * anything else keeps its shape.
+ *
+ * A {@link TxRows} resolves to an explanatory string type rather than a row
+ * list: it has no single answer to give, and saying so in the type is louder
+ * than a runtime throw.
+ */
+type Materialized<T> = T extends Ref<infer U> ? U : T extends TxRowHandle<infer R> ? R : T extends TxRows<unknown> ? "a TxRows cannot leave the transaction callback — read a row with .expectOne(err) first" : T extends Date ? T : T extends object ? {
+    [K in keyof T]: Materialized<T[K]>;
+} : T;
+/** A value written by an INSERT: a literal, an earlier row's field, or `now()`.
+ * `inc`/`dec` are absent on purpose — they read a current value, and an inserted
+ * row has none. */
+type TxInsertValue<V> = V | Ref<V> | TxNow;
+/** A value written by an UPDATE's `set`: everything an insert takes, plus the
+ * read-modify-write expressions. */
+type TxSetValue<V> = V | Ref<V> | TxNow | TxColumnExpr;
+/** An insert payload: the table's insert shape, with refs and `now()` allowed. */
+type TxInsertShape<Insert> = {
+    [K in keyof Insert]: TxInsertValue<Insert[K]>;
+};
+/** An update's `set`: any subset of the insert shape, with expressions allowed. */
+type TxSetShape<Insert> = {
+    [K in keyof Insert]?: TxSetValue<Insert[K]>;
+};
+/**
+ * A filter. Every entry is an equality test and they are AND-ed; a `null`
+ * becomes `IS NULL`, which is what makes `{ accepted_at: null }` a usable
+ * "not yet accepted" guard rather than a clause that matches nothing.
+ */
+type TxWhere<Row> = {
+    [K in keyof Row]?: Row[K] | Ref<Row[K]>;
+};
+/** Options for a plan `select`. */
+interface TxSelectOptions {
+    /** Cap the rows read. */
+    limit?: number;
+    /** Take a real `FOR UPDATE` row lock for the rest of the transaction. */
+    lock?: "update";
+}
+/** One table, as the plan sees it. */
+interface TxTable<Row, Insert> {
+    /** Insert one row. Returns a handle — call `.expectOne(err)` to read fields. */
+    insert(values: TxInsertShape<Insert>): TxRows<Row>;
+    /**
+     * Insert many rows in ONE statement. Every row must set the same columns
+     * (a row that omits one would silently take the column's default).
+     *
+     * An empty list writes nothing and sends nothing.
+     */
+    insertMany(rows: readonly TxInsertShape<Insert>[]): TxRows<Row>;
+    /**
+     * Update every row matching `where`. The filter comes first because it is the
+     * dangerous half: an update whose `where` you got wrong rewrites rows you
+     * never looked at. The server refuses an update with no `where` at all.
+     */
+    updateWhere(where: TxWhere<Row>, set: TxSetShape<Insert>): TxRows<Row>;
+    /** Delete every row matching `where`. The server refuses an unfiltered delete. */
+    deleteWhere(where: TxWhere<Row>): TxRows<Row>;
+    /** Read rows, optionally locking them for the rest of the transaction. */
+    select(where?: TxWhere<Row>, options?: TxSelectOptions): TxRows<Row>;
+}
+/**
+ * The handle a transaction callback receives.
+ *
+ * It carries tables and nothing else: no `query`, no `findById`, no `asService`.
+ * A read whose value the plan does not write belongs OUTSIDE the transaction,
+ * where it costs one round trip and can be branched on like an ordinary value.
+ */
+interface TxPlanHandle<TTables> {
+    tables: TTables;
+}
+/** The server's `now()`. */
+declare function now(): TxNow;
+/** Add `by` to the column's current value. Only valid in an update's `set`. */
+declare function inc(by: number): TxColumnExpr;
+/** Subtract `by` from the column's current value. Only valid in an update's `set`. */
+declare function dec(by: number): TxColumnExpr;
+
 /** HTTP error with structured error response format.
  *
  * The base class for the throwable error classes (`PalError`, `Conflict`,
@@ -1397,24 +1724,29 @@ interface DBOps {
     findById(table: string, id: string): Promise<Record<string, unknown> | null>;
     findMany(table: string, query?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
 }
-/** The transaction-scoped client passed to `db.transaction(fn)` — the raw DB
- * ops only. No nested transaction and no `asService` (the DB role is fixed once
- * when the transaction begins; see `Database.asService().transaction(...)`). */
-type TxClient = DBOps;
 /** Database client interface injected into endpoint context. */
 interface DBClient extends DBOps {
     /**
-     * Run an interactive transaction. The callback receives a `tx` with the same
-     * DB ops as this client; returning normally commits, throwing rolls back.
-     * Nested transactions are not supported.
+     * Run a whole transaction in ONE request (`POST /internal-api/db/tx`).
+     *
+     * 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.
+     *
+     * On failure the runtime must reject with an error carrying the broker's
+     * envelope fields — see {@link TxPlanRejection}. `slot` in particular is what
+     * turns a `tx_guard_failed` back into the `Error` the tenant handed to
+     * `.expectOne(…)`; without it a declared expectation degrades to a generic 409.
      */
-    transaction<T>(fn: (tx: TxClient) => Promise<T>): Promise<T>;
+    txPlan(plan: TxPlanBody): Promise<TxPlanResponse>;
     /**
      * Return a sibling DB client that bypasses Row-Level Security by running as
      * the `service_role` (BYPASSRLS). Use sparingly and explicitly — the default
      * `Database.*` path is RLS-enforced. The returned client exposes the same op
-     * surface (`query`/`insert`/.../`transaction`) but never re-exposes
-     * `asService` (no double-bypass).
+     * surface (`query`/`insert`/.../`txPlan`) but never re-exposes `asService`
+     * (no double-bypass).
      */
     asService(): Omit<DBClient, "asService">;
 }
@@ -1652,4 +1984,4 @@ type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise
  */
 type AuthSpec = boolean | Partial<AuthConfig>;
 
-export { type PalbaseDeviceTokenView as $, type AuthSpec as A, BadRequest as B, type CacheClient as C, type DBClient as D, type ErrorDef as E, type FileContext as F, type PalbaseBatchOverrideOperation as G, HttpError as H, type PalbaseBatchSetOverridesResult as I, type PalbaseBindDeviceParams as J, type PalbaseBucketClient as K, type Logger as L, type Middleware as M, NotFound as N, type PalbaseClearAllOverridesResult as O, type PBRequest as P, type QueueClient as Q, type RateLimitConfig as R, type PalbaseClearOverrideResult as S, type PalbaseCohortQueryInput as T, type User as U, type PalbaseCohortResult as V, type PalbaseCollectionRef as W, type PalbaseCountQueryInput as X, type PalbaseCountResult as Y, type PalbaseCreateLinkParams as Z, type PalbaseDeviceInfo as _, type PalbaseModuleClients as a, type PalbaseVerifyRequestSignatureParams as a$, type PalbaseDocumentRef as a0, type PalbaseDocumentSnapshot as a1, type PalbaseEmailClient as a2, type PalbaseEmailSendParams as a3, type PalbaseEmailSendResponse as a4, type PalbaseEventNamesResult as a5, type PalbaseEventsQueryInput as a6, type PalbaseEventsResult as a7, type PalbaseFileObject as a8, type PalbaseFlag as a9, type PalbaseOverviewResult as aA, type PalbasePreferences as aB, type PalbasePreferencesClient as aC, type PalbasePublicUrlResponse as aD, type PalbasePushClient as aE, type PalbasePushSendParams as aF, type PalbasePushSendResponse as aG, type PalbaseQrCodeOptions as aH, type PalbaseQuerySnapshot as aI, type PalbaseRegisterDeviceParams as aJ, type PalbaseResult as aK, type PalbaseRetentionQueryInput as aL, type PalbaseRetentionResult as aM, type PalbaseSession as aN, type PalbaseSetOverrideResult as aO, type PalbaseSetOverridesResult as aP, type PalbaseSignedUrlResponse as aQ, type PalbaseSmsClient as aR, type PalbaseSmsSendParams as aS, type PalbaseSmsSendResponse as aT, type PalbaseTransformOptions as aU, type PalbaseUpdateLinkParams as aV, type PalbaseUploadOptions as aW, type PalbaseUser as aX, type PalbaseUserDetailResult as aY, type PalbaseUsersQueryInput as aZ, type PalbaseUsersResult as a_, type PalbaseFlagContext as aa, type PalbaseFlagSource as ab, type PalbaseFlagValue as ac, type PalbaseFlagVariant as ad, type PalbaseFlagsServiceClient as ae, type PalbaseFunctionsClient as af, type PalbaseFunnelQueryInput as ag, type PalbaseFunnelResult as ah, type PalbaseIdentifyTraits as ai, type PalbaseInboxClient as aj, type PalbaseInboxListOptions as ak, type PalbaseInboxListResult as al, type PalbaseInboxMessage as am, type PalbaseInboxSendParams as an, type PalbaseInboxSendResponse as ao, type PalbaseInitialLink as ap, type PalbaseInvokeOptions as aq, type PalbaseLink as ar, type PalbaseLinkAnalytics as as, type PalbaseLinkDetails as at, type PalbaseLinksClient as au, type PalbaseListLinksOptions as av, type PalbaseListLinksResult as aw, type PalbaseListOptions as ax, type PalbaseMatchParams as ay, type PalbaseMultiChannelResponse as az, type PalbaseDocsClient as b, type PalbaseWhereOperator as b0, TooManyRequests as b1, type TxClient as b2, Unauthorized as b3, type VerifiedDevice as b4, defineMiddleware as b5, type PalbaseFlagsClient as c, type PalbaseNotificationsClient as d, type PalbaseRealtimeClient as e, type PalbaseStorageClient as f, type AuthConfig as g, type ClientInfo as h, Conflict as i, type DBOps as j, type ErrorMap as k, type ErrorThrowers as l, Forbidden as m, type HttpMethod as n, type MiddlewareContext as o, type MiddlewareHandler as p, PalError as q, type PalbaseAnalyticsClient as r, type PalbaseAnalyticsManagementNamespace as s, type PalbaseAnalyticsProperties as t, type PalbaseAnalyticsQueryNamespace as u, type PalbaseAttestAndroidParams as v, type PalbaseAttestAndroidResult as w, type PalbaseAttestiOSParams as x, type PalbaseAttestiOSResult as y, type PalbaseAuthClient as z };
+export { type PalbaseDeviceInfo as $, type AuthSpec as A, BadRequest as B, type CacheClient as C, type DBClient as D, type ErrorDef as E, type FileContext as F, type PalbaseAuthClient as G, HttpError as H, type PalbaseBatchOverrideOperation as I, type PalbaseBatchSetOverridesResult as J, type PalbaseBindDeviceParams as K, type Logger as L, type Materialized as M, NotFound as N, type PalbaseBucketClient as O, type PBRequest as P, type QueueClient as Q, type RateLimitConfig as R, type PalbaseClearAllOverridesResult as S, type PalbaseClearOverrideResult as T, type User as U, type PalbaseCohortQueryInput as V, type PalbaseCohortResult as W, type PalbaseCollectionRef as X, type PalbaseCountQueryInput as Y, type PalbaseCountResult as Z, type PalbaseCreateLinkParams as _, type PalbaseModuleClients as a, type PalbaseUsersResult as a$, type PalbaseDeviceTokenView as a0, type PalbaseDocumentRef as a1, type PalbaseDocumentSnapshot as a2, type PalbaseEmailClient as a3, type PalbaseEmailSendParams as a4, type PalbaseEmailSendResponse as a5, type PalbaseEventNamesResult as a6, type PalbaseEventsQueryInput as a7, type PalbaseEventsResult as a8, type PalbaseFileObject as a9, type PalbaseMultiChannelResponse as aA, type PalbaseOverviewResult as aB, type PalbasePreferences as aC, type PalbasePreferencesClient as aD, type PalbasePublicUrlResponse as aE, type PalbasePushClient as aF, type PalbasePushSendParams as aG, type PalbasePushSendResponse as aH, type PalbaseQrCodeOptions as aI, type PalbaseQuerySnapshot as aJ, type PalbaseRegisterDeviceParams as aK, type PalbaseResult as aL, type PalbaseRetentionQueryInput as aM, type PalbaseRetentionResult as aN, type PalbaseSession as aO, type PalbaseSetOverrideResult as aP, type PalbaseSetOverridesResult as aQ, type PalbaseSignedUrlResponse as aR, type PalbaseSmsClient as aS, type PalbaseSmsSendParams as aT, type PalbaseSmsSendResponse as aU, type PalbaseTransformOptions as aV, type PalbaseUpdateLinkParams as aW, type PalbaseUploadOptions as aX, type PalbaseUser as aY, type PalbaseUserDetailResult as aZ, type PalbaseUsersQueryInput as a_, type PalbaseFlag as aa, type PalbaseFlagContext as ab, type PalbaseFlagSource as ac, type PalbaseFlagValue as ad, type PalbaseFlagVariant as ae, type PalbaseFlagsServiceClient as af, type PalbaseFunctionsClient as ag, type PalbaseFunnelQueryInput as ah, type PalbaseFunnelResult as ai, type PalbaseIdentifyTraits as aj, type PalbaseInboxClient as ak, type PalbaseInboxListOptions as al, type PalbaseInboxListResult as am, type PalbaseInboxMessage as an, type PalbaseInboxSendParams as ao, type PalbaseInboxSendResponse as ap, type PalbaseInitialLink as aq, type PalbaseInvokeOptions as ar, type PalbaseLink as as, type PalbaseLinkAnalytics as at, type PalbaseLinkDetails as au, type PalbaseLinksClient as av, type PalbaseListLinksOptions as aw, type PalbaseListLinksResult as ax, type PalbaseListOptions as ay, type PalbaseMatchParams as az, type PalbaseDocsClient as b, type PalbaseVerifyRequestSignatureParams as b0, type PalbaseWhereOperator as b1, type Ref as b2, TooManyRequests as b3, type TxColumnExpr as b4, type TxInsertShape as b5, type TxInsertValue as b6, type TxNow as b7, type TxPlanBody as b8, TxPlanError as b9, type TxPlanHandle as ba, type TxPlanOpResult as bb, type TxPlanRejection as bc, type TxPlanResponse as bd, TxRefError as be, type TxRow as bf, type TxRows as bg, type TxSelectOptions as bh, type TxSetShape as bi, type TxSetValue as bj, type TxTable as bk, type TxWhere as bl, type TxWireExpr as bm, type TxWireGuard as bn, type TxWireOp as bo, type TxWireRef as bp, type TxWireValue as bq, Unauthorized as br, type VerifiedDevice as bs, dec as bt, defineMiddleware as bu, inc as bv, now as bw, type PalbaseFlagsClient as c, type PalbaseNotificationsClient as d, type PalbaseRealtimeClient as e, type PalbaseStorageClient as f, type AuthConfig as g, type ClientInfo as h, Conflict as i, type DBOps as j, type ErrorMap as k, type ErrorThrowers as l, Forbidden as m, type HttpMethod as n, type Middleware as o, type MiddlewareContext as p, type MiddlewareHandler as q, PalError as r, type PalbaseAnalyticsClient as s, type PalbaseAnalyticsManagementNamespace as t, type PalbaseAnalyticsProperties as u, type PalbaseAnalyticsQueryNamespace as v, type PalbaseAttestAndroidParams as w, type PalbaseAttestAndroidResult as x, type PalbaseAttestiOSParams as y, type PalbaseAttestiOSResult as z };

package/dist/{index-BaHs33jr.d.cts → index-BJAf1uPC.d.cts}

@@ -1,5 +1,5 @@
 import { Tables, TableTypes } from './db/env.cjs';
-import { D as DBClient } from './endpoint-92kVepng.cjs';
+import { D as DBClient, ba as TxPlanHandle, bk as TxTable, M as Materialized } from './endpoint-Ck4hER_7.cjs';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -536,29 +536,27 @@ interface TypedDB<S extends SchemaDef> {
     tables: {
         [K in keyof S["tables"]]: TypedTable<S["tables"][K]>;
     };
-    transaction<T>(fn: (tx: TypedTx<S>) => Promise<T>): Promise<T>;
-}
-/** Transaction-scoped typed facade: same typed tables, no nested transaction. */
-interface TypedTx<S extends SchemaDef> {
-    tables: {
-        [K in keyof S["tables"]]: TypedTable<S["tables"][K]>;
-    };
+    /** Run a transaction plan. See {@link EnvTypedDatabase.transaction}. */
+    transaction<T>(fn: (tx: TypedTx<S>) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
 }
+/** The plan-building handle a `TypedDB<S>` transaction callback receives: the
+ * schema's tables, expressed as plan operations rather than awaited calls. */
+type TypedTx<S extends SchemaDef> = TxPlanHandle<{
+    [K in keyof S["tables"]]: TxTable<RowShape<S["tables"][K]>, InsertShape<S["tables"][K]>>;
+}>;
 /**
  * Wraps a raw `DBClient` with the type-safe `TypedDB<S>` facade derived from
- * the provided schema. No behavior change — all calls delegate to `raw` with
- * the table name as a plain string.
+ * the provided schema. No behavior change for the direct ops — all calls
+ * delegate to `raw` with the table name as a plain string.
  *
- * `buildTables` is the reusable factory that wraps any op-bearing client
- * (`TxClient` — the surface shared by `DBClient` and the transaction-scoped
- * client) into the typed tables map. It is used both for the top-level db
- * (wrapping `raw`) and inside `transaction`, where it wraps the raw `TxClient`
- * the runtime yields so the callback sees the same typed `.tables` API.
+ * `transaction` does NOT delegate to a per-op client: the callback describes a
+ * plan against a fresh {@link TxPlanBuilder}, and the whole plan travels in one
+ * `raw.txPlan` call. The schema is used only for its table NAMES; the values
+ * are typed by `S` at compile time and are plain strings at run time.
  *
- * `transaction` delegates straight to `raw.transaction`; the two narrow
- * `as TypedTx<S>` / `as TypedDB<S>` casts are single structural narrowings
- * from the dynamically-built tables object to the precise mapped type (TS
- * cannot infer through `Object.keys` iteration) — see module-level doc comment.
+ * The `as` casts are single structural narrowings from a dynamically-built
+ * 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>;
 /** A typed table accessor derived from one env `Tables` entry's flat shapes. */
@@ -578,34 +576,66 @@ interface EnvTypedTable<T extends TableTypes> {
 type EnvTables = {
     [K in keyof Tables]: EnvTypedTable<Tables[K]>;
 };
-/** Transaction-scoped typed facade for the env-augmented surface: same typed
- * tables, no nested transaction. */
-interface EnvTypedTx {
-    tables: EnvTables;
-}
+/** The project's tables as PLAN operations, keyed by the env `Tables`
+ * interface. The transaction twin of {@link EnvTables}. */
+type TxTables = {
+    [K in keyof Tables]: TxTable<Tables[K]["row"], Tables[K]["insert"]>;
+};
+/**
+ * The handle a `Database.transaction(…)` callback receives.
+ *
+ * Tables only — no `query`, no `findById`, no `asService`. A read whose value
+ * the plan does not write belongs outside the transaction, where it costs one
+ * round trip and is an ordinary value you can branch on.
+ */
+type TxPlan = TxPlanHandle<TxTables>;
 /**
  * The RLS-bypass sibling returned by `Database.asService()`. Same typed surface
  * as {@link EnvTypedDatabase} — `tables`, the raw string ops, and a typed
  * `transaction` — but it does NOT re-expose `asService` (no double-bypass).
  * Every op it performs runs as the `service_role` (BYPASSRLS).
  */
-interface EnvServiceDatabase extends Omit<DBClient, "transaction" | "asService"> {
+interface EnvServiceDatabase extends Omit<DBClient, "txPlan" | "asService"> {
     tables: EnvTables;
-    transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+    transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
 }
 /**
  * The typed-by-default Database surface: the raw string-keyed `DBClient` ops
  * PLUS a `tables` map typed against the project's generated `palbase-env.d.ts`,
- * a `transaction` whose callback receives the typed tables, and `asService()`
- * for the explicit RLS-bypass sibling.
+ * a `transaction` that runs a whole plan in one request, and `asService()` for
+ * the explicit RLS-bypass sibling.
  *
- * `transaction` is declared here (overriding `DBClient["transaction"]`) so the
- * `tx` the callback receives carries the typed `.tables` API. `asService` is
- * re-typed to return the typed {@link EnvServiceDatabase} sibling.
+ * The low-level `txPlan` op is deliberately NOT re-exposed here: `transaction`
+ * is the surface, and a hand-built plan would bypass the ref/guard machinery
+ * that makes one safe to write.
  */
-interface EnvTypedDatabase extends Omit<DBClient, "transaction" | "asService"> {
+interface EnvTypedDatabase extends Omit<DBClient, "txPlan" | "asService"> {
     tables: EnvTables;
-    transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+    /**
+     * Run a transaction. The callback DESCRIBES the operations; the whole
+     * description travels in one request and the broker runs it inside a single
+     * transaction — committing when it finishes, rolling back on any failure.
+     *
+     * The callback is SYNCHRONOUS: nothing has run when it returns, so there is
+     * nothing to await. `async` on it and `await` inside it are compile errors.
+     * Values a later operation needs are {@link Ref}s, written straight into the
+     * next operation; values the CALLER needs are returned and substituted before
+     * this promise resolves.
+     *
+     * @example
+     * const { statementId } = await Database.transaction((tx) => {
+     *   const st = tx.tables.statements
+     *     .insert({ household_id: hid, file_sha256: sha, status: "reviewing" })
+     *     .expectOne(new Internal("statement insert failed"));
+     *
+     *   tx.tables.statement_lines.insertMany(
+     *     lines.map((l) => ({ statement_id: st.id, category: resolveCategory(l) })),
+     *   );
+     *
+     *   return { statementId: st.id };
+     * });
+     */
+    transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
     /**
      * Return a sibling that bypasses RLS by running as the `service_role`. Use
      * sparingly and explicitly — the default `Database.*` path is RLS-enforced.
@@ -617,4 +647,4 @@ interface EnvTypedDatabase extends Omit<DBClient, "transaction" | "asService"> {
     asService(): EnvServiceDatabase;
 }
 
-export { makeTypedDB as A, numeric as B, ColumnBuilder as C, policy as D, type EnvTypedDatabase as E, raw as F, text as G, timestamp as H, type InsertShape as I, uuid as J, type OnDeleteAction as O, PALBASE_EXTENSIONS as P, type RawConstraintDef as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, EXTENSION_DEPENDENCIES as d, type EnvServiceDatabase as e, type EnvTables as f, type EnvTypedTable as g, type EnvTypedTx as h, type PalbaseExtension as i, PolicyBuilder as j, type PolicyCommand as k, type PolicyDef as l, type PolicyMode as m, type RowShape as n, type SchemaInput as o, type TableInput as p, type TypedDB as q, type TypedTable as r, type TypedTx as s, bigint as t, boolean as u, defineSchema as v, enumType as w, integer as x, isPalbaseExtension as y, jsonb as z };
+export { jsonb as A, makeTypedDB as B, ColumnBuilder as C, numeric as D, type EnvTypedDatabase as E, policy as F, raw as G, text as H, type InsertShape as I, timestamp as J, uuid as K, type OnDeleteAction as O, PALBASE_EXTENSIONS as P, type RawConstraintDef as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, EXTENSION_DEPENDENCIES as d, type EnvServiceDatabase as e, type EnvTables as f, type EnvTypedTable as g, type PalbaseExtension as h, PolicyBuilder as i, type PolicyCommand as j, type PolicyDef as k, type PolicyMode as l, type RowShape as m, type SchemaInput as n, type TableInput as o, type TxPlan as p, type TxTables as q, type TypedDB as r, type TypedTable as s, type TypedTx as t, bigint as u, boolean as v, defineSchema as w, enumType as x, integer as y, isPalbaseExtension as z };