@palbase/backend 23.0.0 → 23.1.0

package/dist/db/index.d.cts

@@ -1,5 +1,5 @@
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EmbeddingModelRef, f as EnvServiceDatabase, E as EnvTypedDatabase, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as RawConstraintDef, n as RowShape, S as SchemaDef, o as SchemaInput, T as TableDef, p as TableInput, q as TxPlan, r as TxTables, s as TypedDB, t as TypedTable, u as TypedTx, v as bigint, w as boolean, x as defineSchema, y as enumType, z as integer, A as isPalbaseExtension, B as jsonb, D as makeTypedDB, G as openai, H as policy, J as raw, K as text, L as timestamp, M as uuid, N as vector } from '../index-Bmvx1EvJ.cjs';
-export { M as Materialized, b1 as Ref, b3 as TxColumnExpr, b4 as TxInsertShape, b6 as TxNow, T as TxPlanBody, b7 as TxPlanError, b8 as TxPlanHandle, b9 as TxPlanOpResult, ba as TxPlanRejection, f as TxPlanResponse, bb as TxRefError, bc as TxRow, bd as TxRows, be as TxSelectOptions, bf as TxSetShape, bh as TxTable, bi as TxWhere, br as dec, bt as inc, bu as now } from '../endpoint-i8TTCohk.cjs';
+export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EmbeddingModelRef, f as EnvServiceDatabase, E as EnvTypedDatabase, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as RawConstraintDef, n as RowShape, S as SchemaDef, o as SchemaInput, T as TableDef, p as TableInput, q as TxPlan, r as TxTables, s as TypedDB, t as TypedTable, u as TypedTx, v as bigint, w as boolean, x as defineSchema, y as enumType, z as integer, A as isPalbaseExtension, B as jsonb, D as makeTypedDB, G as openai, H as policy, J as raw, K as text, L as timestamp, M as uuid, N as vector } from '../index-By8Dle5U.cjs';
+export { M as Materialized, b1 as Ref, b3 as TxColumnExpr, b4 as TxInsertShape, b6 as TxNow, T as TxPlanBody, b7 as TxPlanError, b8 as TxPlanHandle, b9 as TxPlanOpResult, ba as TxPlanRejection, g as TxPlanResponse, bb as TxRefError, bc as TxRow, bd as TxRows, be as TxSelectOptions, bf as TxSetShape, bh as TxTable, bi as TxWhere, br as dec, bt as inc, bu as now } from '../endpoint-c9h5jriX.cjs';
 import './env.cjs';
 import '../stack.cjs';
 import 'zod';

package/dist/db/index.d.ts

@@ -1,5 +1,5 @@
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EmbeddingModelRef, f as EnvServiceDatabase, E as EnvTypedDatabase, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as RawConstraintDef, n as RowShape, S as SchemaDef, o as SchemaInput, T as TableDef, p as TableInput, q as TxPlan, r as TxTables, s as TypedDB, t as TypedTable, u as TypedTx, v as bigint, w as boolean, x as defineSchema, y as enumType, z as integer, A as isPalbaseExtension, B as jsonb, D as makeTypedDB, G as openai, H as policy, J as raw, K as text, L as timestamp, M as uuid, N as vector } from '../index-B3jmmItD.js';
-export { M as Materialized, b1 as Ref, b3 as TxColumnExpr, b4 as TxInsertShape, b6 as TxNow, T as TxPlanBody, b7 as TxPlanError, b8 as TxPlanHandle, b9 as TxPlanOpResult, ba as TxPlanRejection, f as TxPlanResponse, bb as TxRefError, bc as TxRow, bd as TxRows, be as TxSelectOptions, bf as TxSetShape, bh as TxTable, bi as TxWhere, br as dec, bt as inc, bu as now } from '../endpoint-BavvbW4P.js';
+export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EmbeddingModelRef, f as EnvServiceDatabase, E as EnvTypedDatabase, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as RawConstraintDef, n as RowShape, S as SchemaDef, o as SchemaInput, T as TableDef, p as TableInput, q as TxPlan, r as TxTables, s as TypedDB, t as TypedTable, u as TypedTx, v as bigint, w as boolean, x as defineSchema, y as enumType, z as integer, A as isPalbaseExtension, B as jsonb, D as makeTypedDB, G as openai, H as policy, J as raw, K as text, L as timestamp, M as uuid, N as vector } from '../index-CwAJ7HEe.js';
+export { M as Materialized, b1 as Ref, b3 as TxColumnExpr, b4 as TxInsertShape, b6 as TxNow, T as TxPlanBody, b7 as TxPlanError, b8 as TxPlanHandle, b9 as TxPlanOpResult, ba as TxPlanRejection, g as TxPlanResponse, bb as TxRefError, bc as TxRow, bd as TxRows, be as TxSelectOptions, bf as TxSetShape, bh as TxTable, bi as TxWhere, br as dec, bt as inc, bu as now } from '../endpoint-CVWXh6oG.js';
 import './env.js';
 import '../stack.js';
 import 'zod';

package/dist/db/index.js

@@ -17,14 +17,14 @@ import {
   timestamp,
   uuid,
   vector
-} from "../chunk-HAF67F2H.js";
+} from "../chunk-PY7YJDCT.js";
 import {
   TxPlanError,
   TxRefError,
   dec,
   inc,
   now
-} from "../chunk-W5ODXPY3.js";
+} from "../chunk-NS5V43YQ.js";
 import "../chunk-7D4SUZUM.js";
 export {
   EXTENSION_DEPENDENCIES,

package/dist/{endpoint-BavvbW4P.d.ts → endpoint-CVWXh6oG.d.ts}

@@ -142,7 +142,7 @@ declare function defineMiddleware(fn: MiddlewareHandler): MiddlewareHandler;
  * # Wire contract
  *
  * The JSON this file emits is consumed by
- * `modules/backend/internal/management/tx_program.go`. That decoder rejects
+ * the plan executor in `engine/db.ts`. That executor 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:
@@ -206,7 +206,9 @@ interface TxWireGuard {
 /** 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";
+    /** upsert only: the columns Postgres matches on. */
+    onConflict?: readonly string[];
+    op: "insert" | "insertMany" | "upsert" | "update" | "delete" | "select";
     table: string;
     values?: Record<string, TxWireValue>;
     rows?: Record<string, TxWireValue>[];
@@ -388,6 +390,17 @@ interface TxTable<Row, Insert> {
      * An empty list writes nothing and sends nothing.
      */
     insertMany(rows: readonly TxInsertShape<Insert>[]): TxRows<Row>;
+    /**
+     * Insert the row, or update it when it collides on `onConflict` — inside the
+     * plan's savepoint, with the same meaning `tables.<t>.upsert()` has outside it.
+     *
+     * It is an operation because the alternative is not writable here: a failed
+     * insert aborts the whole transaction, so "try, then fall back" cannot be two
+     * plan steps.
+     */
+    upsert(values: TxInsertShape<Insert>, options: {
+        onConflict: readonly Extract<keyof Row, string>[];
+    }): 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
@@ -1546,6 +1559,13 @@ interface PalbaseFlagsClient {
 /**
  * Realtime broadcast surface (backend handler → subscribed clients).
  *
+ * **Every channel must be DECLARED, or the join is refused.** Channel names are
+ * not free text: `channels.ts` at the project root publishes which names exist
+ * and who may subscribe, publish, or write state, and a client joining a name no
+ * declaration matches is rejected without ever reaching your code. Declare with
+ * `ownerOnly()`, `publicChannel()`, or a custom `authorize(ctx)` — see
+ * {@link defineChannels}. Broadcasting to an undeclared channel reaches nobody.
+ *
  * Backend-side this is BROADCAST-ONLY: a handler pushes an event to a channel
  * and every client subscribed to that channel (via the client SDK's
  * `pb.realtime.channel(...).on(...)`) receives it. There is no `subscribe()` on
@@ -1554,9 +1574,10 @@ interface PalbaseFlagsClient {
  * once the broadcast is accepted (or with an `error` if it could not be sent),
  * but it never blocks the handler waiting on subscribers.
  *
- * Channel naming is app-defined and arbitrary (e.g. `"room:42"`, `"orders"`).
- * The Palbase-managed `flags:<ref>` channels are internal — author channels for
- * your own features.
+ * Channel names are yours to choose (e.g. `"room:42"`, `"orders"`) but not yours
+ * to leave undeclared: each must match a pattern in `channels.ts`, which is where
+ * `"room:{roomId}"` is authorized. The Palbase-managed `flags:<ref>` channels are
+ * internal — author channels for your own features.
  *
  * @example
  * // Notify everyone in a chat room that a message landed:
@@ -1816,9 +1837,36 @@ interface RateLimitConfig {
 /** The six raw string-keyed DB operations shared by `DBClient` and the
  * transaction-scoped client. */
 interface DBOps {
-    /** Run a read-only SQL query (executes in a READ ONLY transaction). */
+    /**
+     * Run SQL on the REQUEST'S OWN transaction.
+     *
+     * This is **not** read-only. Nothing marks that transaction `READ ONLY`, so a
+     * write passed here executes and commits with the request — a plain `UPDATE`, a
+     * write hidden in a CTE, or a function that writes. What stands between a
+     * statement and your data is RLS and the role the request runs as, exactly as
+     * for every other operation on this client.
+     *
+     * `INSERT … ON CONFLICT DO UPDATE` therefore works here; `tables.<t>.upsert()`
+     * is the same thing with types. Array parameters are encoded as Postgres array
+     * literals, so `= ANY($1::uuid[])` takes a plain JS array.
+     *
+     * This comment used to claim a `READ ONLY` transaction. It was wrong, and the
+     * cost was measured: a tenant read it, concluded an upsert was impossible from
+     * here, abandoned `ON CONFLICT` and wrote a database trigger instead.
+     */
     query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
     insert(table: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Insert the row, or update it when it collides on `onConflict` — one
+     * statement, so two concurrent callers cannot both lose.
+     *
+     * Read-then-write cannot be made safe here by catching the unique violation: a
+     * request runs in one transaction, so the failed insert aborts it and every
+     * later statement answers `current transaction is aborted`.
+     */
+    upsert(table: string, data: Record<string, unknown>, opts: {
+        onConflict: readonly string[];
+    }): Promise<Record<string, unknown>>;
     /**
      * Update the row with the given id and resolve to the updated row, or `null`
      * if no row matched (the id is absent, or the row is hidden by RLS). This is
@@ -1862,7 +1910,13 @@ interface DBOps {
     /** Validity'li tabloda satırın yeni versiyonu — eski kapanır (valid_to/superseded_by),
      * yenisi eklenir; TEK savepoint, dönüş yeni satır (FR-029, C-9). */
     supersede(table: string, id: string, row: Record<string, unknown>): Promise<Record<string, unknown>>;
-    findMany(table: string, query?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    findMany(table: string, query?: Record<string, unknown>, opts?: {
+        orderBy?: {
+            column: string;
+            direction?: "asc" | "desc";
+        };
+        limit?: number;
+    }): Promise<Record<string, unknown>[]>;
     /** "Bu satıra benzer satırlar" (FR-022) — satır-modunda kolon vektörüyle,
      * chunk-modunda chunk-ortalamasıyla; kendisi hariç. */
     similar(table: string, id: string, opts?: {
@@ -1913,6 +1967,14 @@ interface DBClient extends DBOps {
      * `.expectOne(…)`; without it a declared expectation degrades to a generic 409.
      */
     txPlan(plan: TxPlanBody): Promise<TxPlanResponse>;
+    /**
+     * Run `fn` inside a SAVEPOINT on this request's transaction, so a failure in
+     * it rolls back only what `fn`'s handle wrote.
+     *
+     * The handle is a PARAMETER on purpose: an ambient swap would capture writes
+     * a concurrent `Promise.all` branch made outside the boundary.
+     */
+    attempt<T>(fn: (tx: DBOps) => Promise<T>): Promise<T>;
     /**
      * Return a sibling DB client that bypasses Row-Level Security by running as
      * the `service_role` (BYPASSRLS). Use sparingly and explicitly — the default
@@ -2213,4 +2275,4 @@ type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise
  */
 type AuthSpec = boolean | Partial<AuthConfig>;
 
-export { type PalbaseCreateLinkParams 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 PalbaseAttestiOSParams as G, HttpError as H, type PalbaseAttestiOSResult as I, type PalbaseAuthClient as J, type PalbaseBatchOverrideOperation as K, type Logger as L, type Materialized as M, NotFound as N, type PalbaseBatchSetOverridesResult as O, type PalbaseDocsClient as P, type PalbaseBindDeviceParams as Q, type RateLimitConfig as R, type SecretsService as S, type TxPlanBody as T, type PalbaseClearAllOverridesResult as U, type PalbaseClearOverrideResult as V, type PalbaseCohortQueryInput as W, type PalbaseCohortResult as X, type PalbaseCollectionRef as Y, type PalbaseCountQueryInput as Z, type PalbaseCountResult as _, type PalbaseFlagsClient as a, type PalbaseVerifyRequestSignatureParams as a$, type PalbaseDeviceInfo as a0, type PalbaseDeviceTokenView as a1, type PalbaseDocumentRef as a2, type PalbaseDocumentSnapshot as a3, type PalbaseEmailClient as a4, type PalbaseEmailSendParams as a5, type PalbaseEmailSendResponse as a6, type PalbaseEventNamesResult as a7, type PalbaseEventsQueryInput as a8, type PalbaseEventsResult as a9, type PalbaseMatchParams as aA, type PalbaseMultiChannelResponse as aB, type PalbaseOverviewResult as aC, type PalbasePreferences as aD, type PalbasePreferencesClient 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 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 PalbaseFileObject as aa, type PalbaseFlag as ab, type PalbaseFlagContext as ac, type PalbaseFlagSource as ad, type PalbaseFlagValue as ae, type PalbaseFlagVariant as af, type PalbaseFlagsServiceClient as ag, type PalbaseFunctionsClient as ah, type PalbaseFunnelQueryInput as ai, type PalbaseFunnelResult as aj, type PalbaseIdentifyTraits as ak, type PalbaseInboxClient as al, type PalbaseInboxListOptions as am, type PalbaseInboxListResult as an, type PalbaseInboxMessage as ao, type PalbaseInboxSendParams as ap, type PalbaseInboxSendResponse as aq, type PalbaseInitialLink as ar, type PalbaseInvokeOptions as as, type PalbaseLink as at, type PalbaseLinkAnalytics as au, type PalbaseLinkDetails as av, type PalbaseLinksClient as aw, type PalbaseListLinksOptions as ax, type PalbaseListLinksResult as ay, type PalbaseListOptions as az, type PalbaseNotificationsClient as b, type PalbaseWhereOperator as b0, type Ref as b1, TooManyRequests as b2, type TxColumnExpr as b3, type TxInsertShape as b4, type TxInsertValue as b5, type TxNow as b6, TxPlanError as b7, type TxPlanHandle as b8, type TxPlanOpResult as b9, type TxPlanRejection as ba, TxRefError as bb, type TxRow as bc, type TxRows as bd, type TxSelectOptions as be, type TxSetShape as bf, type TxSetValue as bg, type TxTable as bh, type TxWhere as bi, type TxWireExpr as bj, type TxWireGuard as bk, type TxWireOp as bl, type TxWireRef as bm, type TxWireValue as bn, Unauthorized as bo, type User as bp, type VerifiedDevice as bq, dec as br, defineMiddleware as bs, inc as bt, now as bu, type PalbaseRealtimeClient as c, type PalbaseStorageClient as d, type PalbaseBucketClient as e, type TxPlanResponse as f, type PalbaseResult as g, type AuthConfig as h, type ClientInfo as i, Conflict as j, type DBOps as k, type ErrorMap as l, type ErrorThrowers as m, Forbidden as n, type HttpMethod as o, type Middleware as p, type MiddlewareContext as q, type MiddlewareHandler as r, type PBRequest as s, PalError as t, type PalbaseAnalyticsClient as u, type PalbaseAnalyticsManagementNamespace as v, type PalbaseAnalyticsProperties as w, type PalbaseAnalyticsQueryNamespace as x, type PalbaseAttestAndroidParams as y, type PalbaseAttestAndroidResult as z };
+export { type PalbaseCreateLinkParams 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 PalbaseAttestiOSParams as G, HttpError as H, type PalbaseAttestiOSResult as I, type PalbaseAuthClient as J, type PalbaseBatchOverrideOperation as K, type Logger as L, type Materialized as M, NotFound as N, type PalbaseBatchSetOverridesResult as O, type PalbaseDocsClient as P, type PalbaseBindDeviceParams as Q, type RateLimitConfig as R, type SecretsService as S, type TxPlanBody as T, type PalbaseClearAllOverridesResult as U, type PalbaseClearOverrideResult as V, type PalbaseCohortQueryInput as W, type PalbaseCohortResult as X, type PalbaseCollectionRef as Y, type PalbaseCountQueryInput as Z, type PalbaseCountResult as _, type PalbaseFlagsClient as a, type PalbaseVerifyRequestSignatureParams as a$, type PalbaseDeviceInfo as a0, type PalbaseDeviceTokenView as a1, type PalbaseDocumentRef as a2, type PalbaseDocumentSnapshot as a3, type PalbaseEmailClient as a4, type PalbaseEmailSendParams as a5, type PalbaseEmailSendResponse as a6, type PalbaseEventNamesResult as a7, type PalbaseEventsQueryInput as a8, type PalbaseEventsResult as a9, type PalbaseMatchParams as aA, type PalbaseMultiChannelResponse as aB, type PalbaseOverviewResult as aC, type PalbasePreferences as aD, type PalbasePreferencesClient 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 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 PalbaseFileObject as aa, type PalbaseFlag as ab, type PalbaseFlagContext as ac, type PalbaseFlagSource as ad, type PalbaseFlagValue as ae, type PalbaseFlagVariant as af, type PalbaseFlagsServiceClient as ag, type PalbaseFunctionsClient as ah, type PalbaseFunnelQueryInput as ai, type PalbaseFunnelResult as aj, type PalbaseIdentifyTraits as ak, type PalbaseInboxClient as al, type PalbaseInboxListOptions as am, type PalbaseInboxListResult as an, type PalbaseInboxMessage as ao, type PalbaseInboxSendParams as ap, type PalbaseInboxSendResponse as aq, type PalbaseInitialLink as ar, type PalbaseInvokeOptions as as, type PalbaseLink as at, type PalbaseLinkAnalytics as au, type PalbaseLinkDetails as av, type PalbaseLinksClient as aw, type PalbaseListLinksOptions as ax, type PalbaseListLinksResult as ay, type PalbaseListOptions as az, type PalbaseNotificationsClient as b, type PalbaseWhereOperator as b0, type Ref as b1, TooManyRequests as b2, type TxColumnExpr as b3, type TxInsertShape as b4, type TxInsertValue as b5, type TxNow as b6, TxPlanError as b7, type TxPlanHandle as b8, type TxPlanOpResult as b9, type TxPlanRejection as ba, TxRefError as bb, type TxRow as bc, type TxRows as bd, type TxSelectOptions as be, type TxSetShape as bf, type TxSetValue as bg, type TxTable as bh, type TxWhere as bi, type TxWireExpr as bj, type TxWireGuard as bk, type TxWireOp as bl, type TxWireRef as bm, type TxWireValue as bn, Unauthorized as bo, type User as bp, type VerifiedDevice as bq, dec as br, defineMiddleware as bs, inc as bt, now as bu, type PalbaseRealtimeClient as c, type PalbaseStorageClient as d, type PalbaseBucketClient as e, type DBOps as f, type TxPlanResponse as g, type PalbaseResult as h, type AuthConfig as i, type ClientInfo as j, Conflict as k, type ErrorMap as l, type ErrorThrowers as m, Forbidden as n, type HttpMethod as o, type Middleware as p, type MiddlewareContext as q, type MiddlewareHandler as r, type PBRequest as s, PalError as t, type PalbaseAnalyticsClient as u, type PalbaseAnalyticsManagementNamespace as v, type PalbaseAnalyticsProperties as w, type PalbaseAnalyticsQueryNamespace as x, type PalbaseAttestAndroidParams as y, type PalbaseAttestAndroidResult as z };

package/dist/{endpoint-i8TTCohk.d.cts → endpoint-c9h5jriX.d.cts}

@@ -142,7 +142,7 @@ declare function defineMiddleware(fn: MiddlewareHandler): MiddlewareHandler;
  * # Wire contract
  *
  * The JSON this file emits is consumed by
- * `modules/backend/internal/management/tx_program.go`. That decoder rejects
+ * the plan executor in `engine/db.ts`. That executor 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:
@@ -206,7 +206,9 @@ interface TxWireGuard {
 /** 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";
+    /** upsert only: the columns Postgres matches on. */
+    onConflict?: readonly string[];
+    op: "insert" | "insertMany" | "upsert" | "update" | "delete" | "select";
     table: string;
     values?: Record<string, TxWireValue>;
     rows?: Record<string, TxWireValue>[];
@@ -388,6 +390,17 @@ interface TxTable<Row, Insert> {
      * An empty list writes nothing and sends nothing.
      */
     insertMany(rows: readonly TxInsertShape<Insert>[]): TxRows<Row>;
+    /**
+     * Insert the row, or update it when it collides on `onConflict` — inside the
+     * plan's savepoint, with the same meaning `tables.<t>.upsert()` has outside it.
+     *
+     * It is an operation because the alternative is not writable here: a failed
+     * insert aborts the whole transaction, so "try, then fall back" cannot be two
+     * plan steps.
+     */
+    upsert(values: TxInsertShape<Insert>, options: {
+        onConflict: readonly Extract<keyof Row, string>[];
+    }): 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
@@ -1546,6 +1559,13 @@ interface PalbaseFlagsClient {
 /**
  * Realtime broadcast surface (backend handler → subscribed clients).
  *
+ * **Every channel must be DECLARED, or the join is refused.** Channel names are
+ * not free text: `channels.ts` at the project root publishes which names exist
+ * and who may subscribe, publish, or write state, and a client joining a name no
+ * declaration matches is rejected without ever reaching your code. Declare with
+ * `ownerOnly()`, `publicChannel()`, or a custom `authorize(ctx)` — see
+ * {@link defineChannels}. Broadcasting to an undeclared channel reaches nobody.
+ *
  * Backend-side this is BROADCAST-ONLY: a handler pushes an event to a channel
  * and every client subscribed to that channel (via the client SDK's
  * `pb.realtime.channel(...).on(...)`) receives it. There is no `subscribe()` on
@@ -1554,9 +1574,10 @@ interface PalbaseFlagsClient {
  * once the broadcast is accepted (or with an `error` if it could not be sent),
  * but it never blocks the handler waiting on subscribers.
  *
- * Channel naming is app-defined and arbitrary (e.g. `"room:42"`, `"orders"`).
- * The Palbase-managed `flags:<ref>` channels are internal — author channels for
- * your own features.
+ * Channel names are yours to choose (e.g. `"room:42"`, `"orders"`) but not yours
+ * to leave undeclared: each must match a pattern in `channels.ts`, which is where
+ * `"room:{roomId}"` is authorized. The Palbase-managed `flags:<ref>` channels are
+ * internal — author channels for your own features.
  *
  * @example
  * // Notify everyone in a chat room that a message landed:
@@ -1816,9 +1837,36 @@ interface RateLimitConfig {
 /** The six raw string-keyed DB operations shared by `DBClient` and the
  * transaction-scoped client. */
 interface DBOps {
-    /** Run a read-only SQL query (executes in a READ ONLY transaction). */
+    /**
+     * Run SQL on the REQUEST'S OWN transaction.
+     *
+     * This is **not** read-only. Nothing marks that transaction `READ ONLY`, so a
+     * write passed here executes and commits with the request — a plain `UPDATE`, a
+     * write hidden in a CTE, or a function that writes. What stands between a
+     * statement and your data is RLS and the role the request runs as, exactly as
+     * for every other operation on this client.
+     *
+     * `INSERT … ON CONFLICT DO UPDATE` therefore works here; `tables.<t>.upsert()`
+     * is the same thing with types. Array parameters are encoded as Postgres array
+     * literals, so `= ANY($1::uuid[])` takes a plain JS array.
+     *
+     * This comment used to claim a `READ ONLY` transaction. It was wrong, and the
+     * cost was measured: a tenant read it, concluded an upsert was impossible from
+     * here, abandoned `ON CONFLICT` and wrote a database trigger instead.
+     */
     query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
     insert(table: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Insert the row, or update it when it collides on `onConflict` — one
+     * statement, so two concurrent callers cannot both lose.
+     *
+     * Read-then-write cannot be made safe here by catching the unique violation: a
+     * request runs in one transaction, so the failed insert aborts it and every
+     * later statement answers `current transaction is aborted`.
+     */
+    upsert(table: string, data: Record<string, unknown>, opts: {
+        onConflict: readonly string[];
+    }): Promise<Record<string, unknown>>;
     /**
      * Update the row with the given id and resolve to the updated row, or `null`
      * if no row matched (the id is absent, or the row is hidden by RLS). This is
@@ -1862,7 +1910,13 @@ interface DBOps {
     /** Validity'li tabloda satırın yeni versiyonu — eski kapanır (valid_to/superseded_by),
      * yenisi eklenir; TEK savepoint, dönüş yeni satır (FR-029, C-9). */
     supersede(table: string, id: string, row: Record<string, unknown>): Promise<Record<string, unknown>>;
-    findMany(table: string, query?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    findMany(table: string, query?: Record<string, unknown>, opts?: {
+        orderBy?: {
+            column: string;
+            direction?: "asc" | "desc";
+        };
+        limit?: number;
+    }): Promise<Record<string, unknown>[]>;
     /** "Bu satıra benzer satırlar" (FR-022) — satır-modunda kolon vektörüyle,
      * chunk-modunda chunk-ortalamasıyla; kendisi hariç. */
     similar(table: string, id: string, opts?: {
@@ -1913,6 +1967,14 @@ interface DBClient extends DBOps {
      * `.expectOne(…)`; without it a declared expectation degrades to a generic 409.
      */
     txPlan(plan: TxPlanBody): Promise<TxPlanResponse>;
+    /**
+     * Run `fn` inside a SAVEPOINT on this request's transaction, so a failure in
+     * it rolls back only what `fn`'s handle wrote.
+     *
+     * The handle is a PARAMETER on purpose: an ambient swap would capture writes
+     * a concurrent `Promise.all` branch made outside the boundary.
+     */
+    attempt<T>(fn: (tx: DBOps) => Promise<T>): Promise<T>;
     /**
      * Return a sibling DB client that bypasses Row-Level Security by running as
      * the `service_role` (BYPASSRLS). Use sparingly and explicitly — the default
@@ -2213,4 +2275,4 @@ type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise
  */
 type AuthSpec = boolean | Partial<AuthConfig>;
 
-export { type PalbaseCreateLinkParams 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 PalbaseAttestiOSParams as G, HttpError as H, type PalbaseAttestiOSResult as I, type PalbaseAuthClient as J, type PalbaseBatchOverrideOperation as K, type Logger as L, type Materialized as M, NotFound as N, type PalbaseBatchSetOverridesResult as O, type PalbaseDocsClient as P, type PalbaseBindDeviceParams as Q, type RateLimitConfig as R, type SecretsService as S, type TxPlanBody as T, type PalbaseClearAllOverridesResult as U, type PalbaseClearOverrideResult as V, type PalbaseCohortQueryInput as W, type PalbaseCohortResult as X, type PalbaseCollectionRef as Y, type PalbaseCountQueryInput as Z, type PalbaseCountResult as _, type PalbaseFlagsClient as a, type PalbaseVerifyRequestSignatureParams as a$, type PalbaseDeviceInfo as a0, type PalbaseDeviceTokenView as a1, type PalbaseDocumentRef as a2, type PalbaseDocumentSnapshot as a3, type PalbaseEmailClient as a4, type PalbaseEmailSendParams as a5, type PalbaseEmailSendResponse as a6, type PalbaseEventNamesResult as a7, type PalbaseEventsQueryInput as a8, type PalbaseEventsResult as a9, type PalbaseMatchParams as aA, type PalbaseMultiChannelResponse as aB, type PalbaseOverviewResult as aC, type PalbasePreferences as aD, type PalbasePreferencesClient 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 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 PalbaseFileObject as aa, type PalbaseFlag as ab, type PalbaseFlagContext as ac, type PalbaseFlagSource as ad, type PalbaseFlagValue as ae, type PalbaseFlagVariant as af, type PalbaseFlagsServiceClient as ag, type PalbaseFunctionsClient as ah, type PalbaseFunnelQueryInput as ai, type PalbaseFunnelResult as aj, type PalbaseIdentifyTraits as ak, type PalbaseInboxClient as al, type PalbaseInboxListOptions as am, type PalbaseInboxListResult as an, type PalbaseInboxMessage as ao, type PalbaseInboxSendParams as ap, type PalbaseInboxSendResponse as aq, type PalbaseInitialLink as ar, type PalbaseInvokeOptions as as, type PalbaseLink as at, type PalbaseLinkAnalytics as au, type PalbaseLinkDetails as av, type PalbaseLinksClient as aw, type PalbaseListLinksOptions as ax, type PalbaseListLinksResult as ay, type PalbaseListOptions as az, type PalbaseNotificationsClient as b, type PalbaseWhereOperator as b0, type Ref as b1, TooManyRequests as b2, type TxColumnExpr as b3, type TxInsertShape as b4, type TxInsertValue as b5, type TxNow as b6, TxPlanError as b7, type TxPlanHandle as b8, type TxPlanOpResult as b9, type TxPlanRejection as ba, TxRefError as bb, type TxRow as bc, type TxRows as bd, type TxSelectOptions as be, type TxSetShape as bf, type TxSetValue as bg, type TxTable as bh, type TxWhere as bi, type TxWireExpr as bj, type TxWireGuard as bk, type TxWireOp as bl, type TxWireRef as bm, type TxWireValue as bn, Unauthorized as bo, type User as bp, type VerifiedDevice as bq, dec as br, defineMiddleware as bs, inc as bt, now as bu, type PalbaseRealtimeClient as c, type PalbaseStorageClient as d, type PalbaseBucketClient as e, type TxPlanResponse as f, type PalbaseResult as g, type AuthConfig as h, type ClientInfo as i, Conflict as j, type DBOps as k, type ErrorMap as l, type ErrorThrowers as m, Forbidden as n, type HttpMethod as o, type Middleware as p, type MiddlewareContext as q, type MiddlewareHandler as r, type PBRequest as s, PalError as t, type PalbaseAnalyticsClient as u, type PalbaseAnalyticsManagementNamespace as v, type PalbaseAnalyticsProperties as w, type PalbaseAnalyticsQueryNamespace as x, type PalbaseAttestAndroidParams as y, type PalbaseAttestAndroidResult as z };
+export { type PalbaseCreateLinkParams 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 PalbaseAttestiOSParams as G, HttpError as H, type PalbaseAttestiOSResult as I, type PalbaseAuthClient as J, type PalbaseBatchOverrideOperation as K, type Logger as L, type Materialized as M, NotFound as N, type PalbaseBatchSetOverridesResult as O, type PalbaseDocsClient as P, type PalbaseBindDeviceParams as Q, type RateLimitConfig as R, type SecretsService as S, type TxPlanBody as T, type PalbaseClearAllOverridesResult as U, type PalbaseClearOverrideResult as V, type PalbaseCohortQueryInput as W, type PalbaseCohortResult as X, type PalbaseCollectionRef as Y, type PalbaseCountQueryInput as Z, type PalbaseCountResult as _, type PalbaseFlagsClient as a, type PalbaseVerifyRequestSignatureParams as a$, type PalbaseDeviceInfo as a0, type PalbaseDeviceTokenView as a1, type PalbaseDocumentRef as a2, type PalbaseDocumentSnapshot as a3, type PalbaseEmailClient as a4, type PalbaseEmailSendParams as a5, type PalbaseEmailSendResponse as a6, type PalbaseEventNamesResult as a7, type PalbaseEventsQueryInput as a8, type PalbaseEventsResult as a9, type PalbaseMatchParams as aA, type PalbaseMultiChannelResponse as aB, type PalbaseOverviewResult as aC, type PalbasePreferences as aD, type PalbasePreferencesClient 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 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 PalbaseFileObject as aa, type PalbaseFlag as ab, type PalbaseFlagContext as ac, type PalbaseFlagSource as ad, type PalbaseFlagValue as ae, type PalbaseFlagVariant as af, type PalbaseFlagsServiceClient as ag, type PalbaseFunctionsClient as ah, type PalbaseFunnelQueryInput as ai, type PalbaseFunnelResult as aj, type PalbaseIdentifyTraits as ak, type PalbaseInboxClient as al, type PalbaseInboxListOptions as am, type PalbaseInboxListResult as an, type PalbaseInboxMessage as ao, type PalbaseInboxSendParams as ap, type PalbaseInboxSendResponse as aq, type PalbaseInitialLink as ar, type PalbaseInvokeOptions as as, type PalbaseLink as at, type PalbaseLinkAnalytics as au, type PalbaseLinkDetails as av, type PalbaseLinksClient as aw, type PalbaseListLinksOptions as ax, type PalbaseListLinksResult as ay, type PalbaseListOptions as az, type PalbaseNotificationsClient as b, type PalbaseWhereOperator as b0, type Ref as b1, TooManyRequests as b2, type TxColumnExpr as b3, type TxInsertShape as b4, type TxInsertValue as b5, type TxNow as b6, TxPlanError as b7, type TxPlanHandle as b8, type TxPlanOpResult as b9, type TxPlanRejection as ba, TxRefError as bb, type TxRow as bc, type TxRows as bd, type TxSelectOptions as be, type TxSetShape as bf, type TxSetValue as bg, type TxTable as bh, type TxWhere as bi, type TxWireExpr as bj, type TxWireGuard as bk, type TxWireOp as bl, type TxWireRef as bm, type TxWireValue as bn, Unauthorized as bo, type User as bp, type VerifiedDevice as bq, dec as br, defineMiddleware as bs, inc as bt, now as bu, type PalbaseRealtimeClient as c, type PalbaseStorageClient as d, type PalbaseBucketClient as e, type DBOps as f, type TxPlanResponse as g, type PalbaseResult as h, type AuthConfig as i, type ClientInfo as j, Conflict as k, type ErrorMap as l, type ErrorThrowers as m, Forbidden as n, type HttpMethod as o, type Middleware as p, type MiddlewareContext as q, type MiddlewareHandler as r, type PBRequest as s, PalError as t, type PalbaseAnalyticsClient as u, type PalbaseAnalyticsManagementNamespace as v, type PalbaseAnalyticsProperties as w, type PalbaseAnalyticsQueryNamespace as x, type PalbaseAttestAndroidParams as y, type PalbaseAttestAndroidResult as z };