@palbase/backend 25.1.0 → 27.0.0

package/dist/index-Bve7BBTL.d.cts

@@ -0,0 +1,4844 @@
+import { Tables, TableTypes, Schemas } from './db/env.cjs';
+import { ZodSchema, z } from 'zod';
+import { PalbaseFlagKey, Buckets, BucketTypes, PalbaseSecretName } from './stack.cjs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/** Supported HTTP methods for endpoints. */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Verified device claim, minted at the platform attestation boundary (App
+ * Attest / Play Integrity). Server-owned and immutable: it is populated ONLY
+ * from a successful, request-bound verification — never from a raw client
+ * header or from user/JWT metadata.
+ */
+interface VerifiedDevice {
+    /** Server-minted `auth.installations` anchor (`ins_…`); may be "" until the installation binding is wired at the verify boundary. */
+    installationId: string;
+    /** Palauth device record (`dev_…`) proven by the App Attest assertion. Absent on the Android integrity path. */
+    authDeviceId?: string;
+    platform: "ios" | "android" | "web";
+    /** Proven verification tier — never a string-matched or header-asserted value. */
+    assurance: "attested" | "app_integrity" | "registered";
+}
+/** Authenticated user attached to the request context. */
+interface User {
+    id: string;
+    /** User's email, if they signed up with one (absent for phone-only users). */
+    email?: string;
+    /**
+     * Whether that email address has been confirmed.
+     *
+     * Server-resolved from the verified user profile, not read from the JWT: a
+     * token claim is only true as of when the token was minted, so a user who
+     * verifies mid-session would keep reporting `false` until it expired.
+     *
+     * `false` for a phone-only user (no address to confirm) and for any user who
+     * has not clicked through yet. Before this field existed, answering "is this
+     * address confirmed" in a handler cost an extra network round-trip PER
+     * REQUEST for one boolean the runtime already had.
+     */
+    emailVerified: boolean;
+    role: string;
+    metadata: Record<string, unknown>;
+    /**
+     * Reserved, server-owned verified device claim. `null` on an authenticated
+     * request with no verified device. The context assembler is the sole writer;
+     * user/JWT metadata can never populate it.
+     */
+    device: VerifiedDevice | null;
+}
+/** Authentication configuration for an endpoint. */
+interface AuthConfig {
+    /** Whether authentication is required. Defaults to true. */
+    required: boolean;
+    /** Required role for access. If undefined, any authenticated user is allowed.
+     *
+     * Matched against the caller's `metadata.role` — NOT `user.role`, which is the
+     * database role RLS reads and is always "authenticated" for a signed-in user.
+     * Not signed in → 401; signed in with a different or missing role → 403. */
+    role?: string;
+    /** Require a confirmed email address. An unverified caller gets 403
+     * `email_not_verified`. Fences a whole controller; for a partial rule read
+     * `user.emailVerified` in the handler instead. */
+    verifiedEmail?: boolean;
+}
+
+/** Middleware context — subset of EndpointContext without input (not yet validated). */
+interface MiddlewareContext extends PalbaseModuleClients {
+    params: Record<string, string>;
+    query: Record<string, string>;
+    headers: Record<string, string>;
+    user: User | null;
+    db: DBClient;
+    env: Record<string, string>;
+    log: Logger;
+    cache: CacheClient;
+    requestId: string;
+    environmentId: string;
+}
+/** Middleware function signature — receives context and next function. */
+type MiddlewareHandler = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * REMOVED IN BEHAVIOUR, KEPT IN NAME.
+ *
+ * There is no middleware pipeline in this runtime. No bundler reads a
+ * `middleware/` directory, the engine never calls a handler defined here, and
+ * measured on 2026-08-31 this function had no caller anywhere in the runtime or
+ * the CLI. It returned its argument unchanged, so code written against it
+ * compiled, deployed, and then never ran — with nothing reporting that.
+ *
+ * A silent shell is the worst version of a retired feature: it lets a user (or a
+ * coding assistant, which is how this surfaced) ship a request logger, an auth
+ * check or a rate limiter that simply does not exist in production. So the call
+ * refuses, and says where the work belongs.
+ *
+ * The SYMBOL survives because removing a published export costs a major and
+ * 25.0.1 had just shipped. Deleting it is a proposal for the next one; the types
+ * below stay either way, so a file that only annotates with them still compiles.
+ *
+ * This is the shape the SDK already uses for a retired surface: `@Query(schema)`
+ * on a parameter throws at decoration time with a message naming its
+ * replacement.
+ */
+declare function defineMiddleware(_fn: MiddlewareHandler): never;
+
+/** On delete action for foreign key references. */
+type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
+/**
+ * The ON DELETE actions permitted on a foreign key to the built-in auth users
+ * (`auth.users`). Both let a user's rows be removed (`cascade`) or detached
+ * (`set null`) when the account is erased; `restrict` / `no action` would BLOCK
+ * erasure and are therefore excluded. This is the CLIENT-SIDE mirror of the
+ * server's auth-FK deletion policy — the server (validateAuthUserFK) is the real
+ * boundary, this narrows the type so the common mistake is caught at compile time.
+ */
+type AuthUserOnDelete = Extract<OnDeleteAction, 'cascade' | 'set null'>;
+/** Column type identifiers. */
+type ColumnType = 'uuid' | 'text' | 'integer' | 'bigint' | 'numeric' | 'boolean' | 'timestamp' | 'jsonb' | 'enum' | 'vector';
+/** Base column definition shared by all column types. */
+interface ColumnDef {
+    type: ColumnType;
+    nullable: boolean;
+    primaryKey: boolean;
+    defaultValue?: unknown;
+    defaultRandom?: boolean;
+    defaultNow?: boolean;
+    references?: {
+        table: string;
+        column: string;
+    };
+    /** Pending FK target, resolved by `defineSchema` once every binding exists. */
+    referencesThunk?: () => ColumnBuilder;
+    /** FK onto THIS table — no thunk needed, the target is the declaring table. */
+    selfRefColumn?: string;
+    /** This column OWNS the row: erasure, RLS and the `owner` relation read it. */
+    owns?: true;
+    /** Explicit name for the FORWARD relation (child → parent), when the one
+     * derived from the column would be ambiguous or unclear. */
+    refAs?: string;
+    /**
+     * Explicit name for the REVERSE relation (parent → children).
+     *
+     * Separate from {@link refAs} because the two directions are different facts:
+     * the forward name describes the parent this row points at (`author`), the
+     * reverse one describes the rows hanging off the parent (`posts`). One option
+     * naming both made an ordinary schema undeclarable — `posts.author_id` and
+     * `comments.author_id` both named `{ as: "author" }` collided on `users`, and
+     * the refusal asked for the `{ as }` they had both already written.
+     */
+    reverseAs?: string;
+    /** The table this column belongs to; set by `defineTable`. */
+    ownerTable?: {
+        name: string;
+        columns: Record<string, ColumnBuilder>;
+    };
+    /**
+     * The name this column used to have. A diff cannot tell a rename from a drop and
+     * an add — both leave one name gone and another present — so the intent has to be
+     * declared. Without it, renaming a column loses its data.
+     */
+    renamedFrom?: string;
+    /**
+     * This release's PROMISE that it does not reference this column — neither
+     * reads it nor writes it, and never names it in a filter, a sort or a SET.
+     *
+     * The contraction gate reads it and nothing else does: dropping a column is
+     * refused while the RUNNING release's declaration still lacks this mark, so
+     * removing a column is two deploys — mark it, ship, then drop it.
+     *
+     * The word is `ignored` and not `deprecated` deliberately: RFC 9745 defines
+     * deprecation as changing NO behaviour, and this changes what a deploy will
+     * accept. Rails calls the same thing `ignored_columns`.
+     */
+    ignored?: boolean;
+    onDeleteAction?: OnDeleteAction;
+    /** FR-044: yalnız AÇIKÇA `false` bildirilince var. Türev FK index'ini kapatır. */
+    index?: boolean;
+    /** FR-049: kolon `increment()` ile güncelleniyor. Plan HOT çakışmasını uyarır. */
+    counter?: boolean;
+    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;
+    /**
+     * How the stored value is projected in and out of this process (FR-009).
+     *
+     * NOT part of the DDL: the column's Postgres type is unchanged and this pair
+     * is never serialized into a migration. It exists so the row surface can hand
+     * back the type the application actually works with.
+     */
+    transform?: ColumnTransform;
+}
+/**
+ * The read/write pair a column may declare (FR-009).
+ *
+ * `fromDb` takes whatever the driver produced for this column and returns the
+ * value the application sees; `toDb` is its inverse on the way out. Kept
+ * deliberately unexported — a column declares one inline, nobody needs to name
+ * the shape.
+ */
+interface ColumnTransform<T = unknown> {
+    fromDb: (value: unknown) => T;
+    toDb: (value: T) => unknown;
+}
+declare const __colKind: unique symbol;
+declare const __colNullable: unique symbol;
+declare const __colHasDefault: unique symbol;
+declare const __colEnumValues: unique symbol;
+declare const __colPayload: unique symbol;
+declare const __colTransform: unique symbol;
+/**
+ * Fluent column builder with phantom type params:
+ *  K — ColumnType literal (e.g. "text", "integer")
+ *  N — boolean: true when nullable() has been called last (false = NOT NULL)
+ *  D — boolean: true when a default has been set
+ *  E — enum value union (never for non-enum columns)
+ *  P — jsonb payload shape (unknown unless jsonb<T>() supplied one)
+ *  T — transform target type (`never` when the column declares no transform;
+ *      `never` is the sentinel because it is the only type that survives
+ *      `[T] extends [never]` and never collides with a real target type)
+ *
+ * All six params have defaults so bare `ColumnBuilder` (no args) still
+ * satisfies `Record<string, ColumnBuilder>` in schema.ts without modification.
+ *
+ * The six `declare readonly` brand fields carry the phantom types into the
+ * structural shape so that conditional types like ColValue<C> can discriminate
+ * on K without requiring runtime values on those fields.
+ */
+declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean = boolean, D extends boolean = boolean, E = unknown, P = unknown, T = unknown> {
+    readonly [__colKind]: K;
+    readonly [__colNullable]: N;
+    readonly [__colHasDefault]: D;
+    readonly [__colEnumValues]: E;
+    readonly [__colPayload]: P;
+    readonly [__colTransform]: T;
+    readonly _def: ColumnDef;
+    constructor(type: K, existingDef?: ColumnDef);
+    /** Mark this column as the primary key. */
+    primaryKey(): ColumnBuilder<K, N, D, E, P, T>;
+    /** Mark this column as NOT NULL (default). */
+    notNull(): ColumnBuilder<K, false, D, E, P, T>;
+    /** Allow NULL values. */
+    nullable(): ColumnBuilder<K, true, D, E, P, T>;
+    /** Set a default value. */
+    default(value: unknown): ColumnBuilder<K, N, true, E, P, T>;
+    /** UUID: generate a random default (gen_random_uuid()). */
+    defaultRandom(): ColumnBuilder<K, N, true, E, P, T>;
+    /** Timestamp: default to now(). */
+    defaultNow(): ColumnBuilder<K, N, true, E, P, T>;
+    /**
+     * 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, T>;
+    /** Add a foreign key reference. */
+    /**
+     * Declares that this column used to be called `previous`.
+     *
+     * A schema diff sees one name gone and another present; it cannot know whether
+     * you renamed a column or dropped one and added another, and the two are very
+     * different — the second loses every value. Saying so here turns the plan into
+     * `ALTER TABLE … RENAME COLUMN` instead.
+     *
+     * Once the rename has been applied the annotation is inert (the old name is no
+     * longer there to rename), so it can be deleted at your leisure.
+     */
+    renamedFrom(previous: string): ColumnBuilder<K, N, D, E, P, T>;
+    /**
+     * See {@link ColumnDef.ignored}.
+     *
+     * COPIES the def rather than mutating it. The constructor takes an existing
+     * def BY REFERENCE, so every builder derived from another shares one object —
+     * `const a = slug.unique()` leaves `a._def === slug._def`. An in-place
+     * `ignored = true` therefore marks every column sharing that def, including
+     * one another table actively reads, and the gate would let THAT column be
+     * dropped. Measured before this copy existed.
+     *
+     * The aliasing is older than this method and other fields leak through it too.
+     * The reason this one cannot wait: every other leak produces a VISIBLE schema
+     * difference — the plan shows it, the DDL shows it. This one is invisible by
+     * design (no DDL, no diff, no plan line), so its only effect is to disarm a
+     * safety gate in silence.
+     */
+    ignored(): ColumnBuilder<K, N, D, E, P, T>;
+    /**
+     * Foreign key onto another table's column.
+     *
+     * The target is a THUNK, not a direct reference. In a cycle (`x → y`, `y → x`)
+     * the second table does not exist yet when the first is built; a direct
+     * reference makes TypeScript chase its own tail (TS7022 — measured, and making
+     * the return type independent of the target does NOT help). The thunk is
+     * invoked in `defineSchema`, where every binding exists and every table
+     * already knows its name.
+     *
+     * In a cycle, ONE side needs an explicit return type:
+     * `references((): AnyColumn => y.id)`. One side is enough — measured.
+     * For a self-reference use `selfReferences(column)`: no thunk, no annotation.
+     *
+     * `as` names the FORWARD relation (`author_id` → `author` by default);
+     * `reverseAs` names the REVERSE one on the parent, whose default is this
+     * table's own name (`users.posts`). Two foreign keys from one table onto one
+     * parent therefore need a `reverseAs` on at least one of them — the reverse
+     * names would otherwise both be this table's name.
+     */
+    references(target: () => AnyColumn, opts?: {
+        as?: string;
+        reverseAs?: string;
+        onDelete?: OnDeleteAction;
+        /**
+         * Bu FK kolonu için TÜREVİ index üretilsin mi (FR-044). Varsayılan açık.
+         *
+         * Postgres bir foreign key'i otomatik indekslemez — yalnız hedef
+         * taraftaki unique kısıt vardır. Bedeli FK üzerinden her JOIN'de ve her
+         * `ON DELETE CASCADE`'de ödenir: bir parent silinirken child tablo tam
+         * taranır.
+         *
+         * `false` demek gerçek bir ihtiyaç, nezaket değil (D-028): FK kolonu aynı
+         * zamanda SIK GÜNCELLENEN bir kolonsa index HOT güncellemeyi kırar — ve
+         * HOT, DEĞİŞEN kolon indeksliyse kırılır, tablo indeksli diye değil.
+         */
+        index?: boolean;
+    }): ColumnBuilder<K, N, D, E, P, T>;
+    /**
+     * Bu kolon `increment()` / `decrement()` ile güncelleniyor (FR-049).
+     *
+     * Deploy kontrolcü kodunu OKUMAZ, o yüzden bildirimin söylemesi gerekiyor —
+     * ve söylediği anda plan bir şeyi görebiliyor: aynı kolon hem sayaç hem
+     * indeksliyse her güncelleme HOT'u kaybeder.
+     *
+     * ZİNCİR (D-028+D-030): HOT kaybı → ölü tuple → autovacuum yükü → ve
+     * autovacuum worker'ları KÜME GENELİNDE bir kaynak, yani bedeli başka
+     * kiracıların tabloları da öder.
+     *
+     * Sektörde çare "dokümana uyarı yaz"dır, çünkü index'i ekleyen kişi
+     * `increment()`'i yazan kişi değildir. Bu bildirimde ikisi de YAN YANA
+     * duruyor.
+     *
+     * Uyarı, HATA DEĞİL: sayaç kolonunu indekslemek bazen doğru karardır.
+     */
+    counter(): ColumnBuilder<K, N, D, E, P, T>;
+    /**
+     * Foreign key onto THIS table (`parent_id → id`) — category trees, comment
+     * replies, org charts.
+     *
+     * No thunk and no type annotation: the target table is the one being declared,
+     * so there is nothing to defer and nothing for TypeScript to chase in a circle.
+     * Drizzle forces an explicit `(): AnyPgColumn =>` here because its reference
+     * always goes through a callback; measured, we do not need one.
+     */
+    selfReferences(column: string, opts?: {
+        as?: string;
+        onDelete?: OnDeleteAction;
+    }): ColumnBuilder<K, N, D, E, P, T>;
+    /** Set the ON DELETE action for a foreign key reference. */
+    onDelete(action: OnDeleteAction): ColumnBuilder<K, N, D, E, P, T>;
+    /** Add a single-column UNIQUE constraint. */
+    unique(): ColumnBuilder<K, N, D, E, P, T>;
+    /**
+     * Declare how this column's value is projected in and out of the process.
+     *
+     * The DDL does not move: `numeric` stays `numeric`, and the driver still hands
+     * back what Postgres sent. What changes is the type the row surface exposes —
+     * it becomes `Target`:
+     *
+     *   amount: numeric().transform<number>({ fromDb: Number, toDb: String })
+     *
+     * `numeric` surfacing as `string` is CORRECT (a JS number cannot hold
+     * arbitrary precision), and that is exactly why this exists: application code
+     * that does arithmetic on the column otherwise rewrites the same
+     * `Number(row.amount)` / `String(x)` pair in every controller that touches it,
+     * and each rewrite is a place the two directions can drift apart.
+     *
+     * A transform is a PROJECTION, never a constraint: it lives only in this
+     * process, so it can neither validate nor migrate what is stored.
+     */
+    transform<Target>(fns: ColumnTransform<Target>): ColumnBuilder<K, N, D, E, P, Target>;
+}
+/**
+ * Extracts the TypeScript value type for a column, respecting nullability.
+ * - "uuid" | "text" | "timestamp" | "bigint" | "numeric" → string (or string | null when N = true)
+ *   Note: bigint/numeric surface as string — JS number loses precision past 2^53,
+ *   and pgx/PostgREST serialize int8/numeric as strings. App code uses
+ *   BigInt(row.amount) for bigint, or a decimal lib for numeric.
+ * - "integer" → number
+ * - "boolean" → boolean
+ * - "jsonb" → P (the dev-supplied payload shape from jsonb<T>(), else unknown)
+ * - "enum" → E (the union of literal values)
+ *
+ * A declared `.transform<T>()` OVERRIDES the table above: the column then
+ * surfaces as T (or T | null when nullable), because that is the value the
+ * application is handed. Nullability is still the column's, not the
+ * transform's — `fromDb` is not called for a NULL.
+ */
+type ColValue<C> = C extends ColumnBuilder<ColumnType, infer N, boolean, unknown, unknown, infer T> ? [unknown] extends [T] ? ColStoredValue<C> : N extends true ? T | null : T : never;
+/** The value as the DATABASE hands it over — the branch table above, before any
+ * transform. This is what a column's `fromDb` receives. */
+type ColStoredValue<C> = C extends ColumnBuilder<'uuid' | 'text' | 'timestamp' | 'bigint' | 'numeric', infer N, infer _D, infer _E, infer _P> ? N extends true ? string | null : string : C extends ColumnBuilder<'integer', infer N, infer _D, infer _E, infer _P> ? N extends true ? number | null : number : C extends ColumnBuilder<'boolean', infer N, infer _D, infer _E, infer _P> ? N extends true ? boolean | null : boolean : C extends ColumnBuilder<'jsonb', infer N, infer _D, infer _E, infer P> ? N extends true ? P | null : P : C extends ColumnBuilder<'vector', infer N, infer _D, infer _E, infer _P> ? N extends true ? number[] | null : number[] : C extends ColumnBuilder<'enum', infer N, infer _D, infer E, infer _P> ? N extends true ? E | null : E : never;
+/**
+ * True when a column is optional on INSERT:
+ *  - nullable columns (N = true) — the DB allows NULL so the field may be omitted
+ *  - columns with a default (D = true) — the DB fills in the value when absent
+ */
+type ColIsOptionalOnInsert<C> = C extends ColumnBuilder<ColumnType, true, boolean, unknown, unknown, unknown> ? true : C extends ColumnBuilder<ColumnType, boolean, true, unknown, unknown, unknown> ? true : false;
+/** Create a UUID column. */
+declare function uuid(): ColumnBuilder<'uuid', false, false, never>;
+/** Create a TEXT column. */
+declare function text(): ColumnBuilder<'text', false, false, never>;
+/** Create an INTEGER column. Emits int4 (max ~2.1B). */
+declare function integer(): ColumnBuilder<'integer', false, false, never>;
+/**
+ * Create a BIGINT column (Postgres int8, max ~9.2×10^18).
+ * Surfaces as `string` in row/insert types — JS number loses precision past 2^53
+ * and pgx/PostgREST serialize int8 as a JSON string. Use BigInt(row.column) in app code.
+ */
+declare function bigint(): ColumnBuilder<'bigint', false, false, never>;
+/**
+ * Create a NUMERIC column (Postgres `numeric`/`decimal`, arbitrary precision).
+ * For exact fractional values (money with cents as a decimal, rates, weights)
+ * where int4/int8 don't fit. Surfaces as `string` in row/insert types — JS
+ * number can't hold arbitrary-precision decimals without rounding, and
+ * pgx/PostgREST serialize numeric as a JSON string. Parse with a decimal lib
+ * (or BigInt for scaled integers) in app code.
+ */
+declare function numeric(): ColumnBuilder<'numeric', false, false, never>;
+/** Create a BOOLEAN column. */
+declare function boolean(): ColumnBuilder<'boolean', false, false, never>;
+/** Create a TIMESTAMP column. */
+declare function timestamp(): ColumnBuilder<'timestamp', false, false, never>;
+/**
+ * Create a JSONB column. Pass a payload type to make the generated row/insert
+ * type concrete instead of `unknown`:
+ *
+ *   tags: jsonb<string[]>()           // row.tags: string[]
+ *   meta: jsonb<{ tier: string }>()   // row.meta: { tier: string }
+ *   raw:  jsonb()                      // row.raw: unknown (back-compat)
+ *
+ * The runtime accepts a plain JS object/array directly (no JSON.stringify); the
+ * generic only refines the TYPE the env codegen emits.
+ */
+declare function jsonb<T = unknown>(): ColumnBuilder<'jsonb', false, false, never, T>;
+/**
+ * Create an ENUM column.
+ * @param name   The PostgreSQL enum type name (used in DDL).
+ * @param values A readonly tuple of valid string values — kept `const` so the
+ *               union `V[number]` is as narrow as possible.
+ */
+declare function enumType<const V extends readonly string[]>(name: string, values: V): ColumnBuilder<'enum', false, false, V[number]>;
+/** vector(n) — pgvector kolonu. n TİPİN parçasıdır (typmod) ve [1, 2000] —
+ * 2000 = pgvector'ün HNSW-indekslenebilir tavanı; auto-index bu beyanla bağlı
+ * (spec FR-001, D-3). */
+declare function vector(dimensions: number): ColumnBuilder<'vector', false, false, unknown, number[]>;
+/**
+ * Any column, whatever its type parameters.
+ *
+ * Exported so a cycle can be broken from ONE side:
+ * `references((): AnyColumn => y.id)`.
+ */
+type AnyColumn = ColumnBuilder;
+/**
+ * The column that OWNS this row: a `text` FK onto `auth.users(id)`, NOT NULL,
+ * ON DELETE CASCADE.
+ *
+ * Ownership drives account erasure, so cascade is the only correct action and
+ * takes no argument. The referencing column must be `text` (palauth ids are
+ * `usr_<uuid>`) and NOT NULL — both are implied here rather than left to the
+ * caller, so three rules the type could not express before become UNWRITABLE.
+ *
+ * At most ONE per table. The old shape let several columns reference
+ * `auth.users` and picked the FIRST IN DECLARATION ORDER as the owner — moving a
+ * `created_by` above a `user_id` silently changed which rows an account deletion
+ * took with it. A second one is now rejected at push.
+ *
+ * For a column that merely POINTS at a user without owning the row
+ * (`created_by`, `edited_by`), use `userRef({ onDelete })`.
+ */
+declare function ownedByUser(): ColumnBuilder<'text', false, false, never>;
+/**
+ * A plain FK onto `auth.users(id)` that does NOT own the row.
+ *
+ * `created_by` / `edited_by`: deleting that user must not delete the row. ON
+ * DELETE is required and limited to `cascade | set null` so an erasure request
+ * is never blocked by a lingering FK; `set null` needs a nullable column.
+ */
+declare function userRef(opts: {
+    onDelete: AuthUserOnDelete;
+    as?: string;
+}): ColumnBuilder<'text', boolean, false, never>;
+/**
+ * A plain FK onto `auth.installations(id)` — the app-scoped verified-device
+ * anchor.
+ *
+ * An installation is an APP INSTALL, not a user: this is NOT ownership. A
+ * user-owned row still needs its own `ownedByUser()` so account erasure removes
+ * it; an installation reference alone does not tie a row to a user's deletion.
+ */
+declare function installationRef(opts: {
+    onDelete: AuthUserOnDelete;
+    as?: string;
+}): ColumnBuilder<'text', boolean, false, never>;
+
+/**
+ * policy.ts — the RLS policy authoring DSL.
+ *
+ * `policy(name)` returns a fluent builder that mirrors the `ColumnBuilder`
+ * style in columns.ts: each chainable method mutates the underlying
+ * definition and returns the builder so calls compose. The terminal value is
+ * a plain {@link PolicyDef} — the exact JSON shape the runtime's
+ * `schema_extract.js` reads off the bundled module and the Go side parses into
+ * `PolicyJSON` (CONTRACT-POLICY).
+ *
+ * @example
+ * import { policy } from "@palbase/backend";
+ *
+ * policy("owner_select")
+ *   .for("select")
+ *   .to("authenticated")
+ *   .using("owner = (select auth.uid())");
+ */
+/** Politika ifadesinin düğümleri. DÜZ VERİ: tele bu şekilde gider. */
+type PolicyExpr = {
+    kind: "col";
+    name: string;
+    /**
+     * Hangi tablonun kolonu (FR-023). Yoksa POLİTİKANIN KENDİ tablosu —
+     * Postgres politika ifadesinde onu niteliksiz çözer. Doluysa bir
+     * `existsIn` alt-sorgusunun takma adı.
+     *
+     * Bu ayrım korelasyonun tamamı: ayırt edilmezse `team_id = team_id`
+     * üretilir, her satır için doğrudur, ve politika HİÇBİR ŞEYİ süzmez —
+     * yani tüm belgeler herkese görünür.
+     */
+    alias?: string;
+} | {
+    kind: "authUid";
+} | {
+    kind: "lit";
+    value: string | number | boolean | null;
+} | {
+    kind: "binop";
+    op: PolicyBinOp;
+    left: PolicyExpr;
+    right: PolicyExpr;
+} | {
+    kind: "and";
+    parts: PolicyExpr[];
+} | {
+    kind: "or";
+    parts: PolicyExpr[];
+} | {
+    kind: "not";
+    expr: PolicyExpr;
+} | {
+    kind: "isNull";
+    expr: PolicyExpr;
+    negated: boolean;
+} | {
+    /**
+     * Korelasyonlu `EXISTS (SELECT 1 FROM <table> <alias> WHERE <predicate>)`.
+     *
+     * FR-024 BAĞLAYICI: alt-sorgu DOĞRUDAN üretilir, bir `SECURITY DEFINER`
+     * fonksiyona SARILMAZ. Ölçüldü (spec Research Appendix, pg16): doğrudan
+     * alt-sorguda hedef tablonun KENDİ RLS'i uygulanıyor — yani sızıntı
+     * kanalı yok. Sarmalama ise onu bypass ederdi.
+     */
+    kind: "exists";
+    table: string;
+    alias: string;
+    /**
+     * POLİTİKANIN KENDİ tablosunun adı — korelasyonun çalışması için ŞART.
+     *
+     * ÖLÇÜLDÜ (canlı pg16): alt-sorgu içinde niteliksiz bir kolon adı
+     * Postgres tarafından İÇ tabloya çözülüyor. Yani dış kolon niteliksiz
+     * bırakılınca `pb_e1.team_id = pb_e1.team_id` üretiliyor — her satır
+     * için doğru, ve politika HİÇBİR ŞEYİ süzmüyor: iki farklı kullanıcı
+     * da tüm belgeleri gördü. Dış tablo adı burada taşınıyor ki emitter
+     * `"documents"."team_id"` yazabilsin.
+     */
+    outer: string;
+    predicate: PolicyExpr;
+};
+/** Karşılaştırma operatörleri. `in` sağ tarafta liste bekler. */
+type PolicyBinOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in";
+/**
+ * Bir ifadenin ETRAFINDAKİ akıcı sarmalayıcı.
+ *
+ * Düğüm (`expr`) düz veri kalıyor, metotlar sarmalayıcıda yaşıyor: `_def.using`
+ * serileştiğinde metotlu bir nesne değil, tam olarak tele gidecek şekil olsun
+ * diye. `.using()` sarmalayıcıyı açar.
+ */
+declare class PolicyExprRef {
+    readonly expr: PolicyExpr;
+    constructor(expr: PolicyExpr);
+    private bin;
+    eq(other: PolicyOperand): PolicyExprRef;
+    neq(other: PolicyOperand): PolicyExprRef;
+    gt(other: PolicyOperand): PolicyExprRef;
+    gte(other: PolicyOperand): PolicyExprRef;
+    lt(other: PolicyOperand): PolicyExprRef;
+    lte(other: PolicyOperand): PolicyExprRef;
+    /**
+     * `IS NULL` / `IS NOT NULL` — `= NULL` SQL'de her zaman UNKNOWN'dır, o yüzden
+     * niyet ayrı bir düğümle yazılır. Partial index'in en sık koşulu
+     * (`WHERE deleted_at IS NULL`) tam olarak bu.
+     */
+    isNull(negated?: boolean): PolicyExprRef;
+    and(...others: PolicyExprRef[]): PolicyExprRef;
+    or(...others: PolicyExprRef[]): PolicyExprRef;
+    not(): PolicyExprRef;
+}
+/** `.eq()` gibi metotların sağ tarafı: başka bir ifade ya da düz bir değer. */
+type PolicyOperand = PolicyExprRef | string | number | boolean | null;
+/**
+ * Politika ifadesi bağlamı — `defineTable`'ın `policies` callback'ine verilir.
+ *
+ * Kolon adları TABLONUN KENDİ kolonlarıyla sınırlıdır (FR-022). Bu, `policies`
+ * bir dizi değil de callback olduğu için mümkün: TypeScript `columns`'tan
+ * `C`'yi çıkarıp callback'i onunla bağlamlandırıyor. `policy("x")` tek başına
+ * çağrıldığında hangi tabloda olduğunu bilemezdi.
+ */
+interface PolicyExprCtx<Cols extends string = string> {
+    /** Bu tablonun bir kolonu. Bilinmeyen ad DERLENMEZ. */
+    col(name: Cols): PolicyExprRef;
+    /**
+     * "Bu satırın sahibi olduğum bir takıma ait mi?" — üyelik tabanlı kiracılık
+     * (FR-023), korelasyonlu bir `EXISTS` alt-sorgusu olarak.
+     *
+     * ```ts
+     * policies: (p) => [
+     *   policy("team_read").for("select").using(
+     *     p.existsIn(teamMembers, (m) =>
+     *       m.col("team_id").eq(p.col("team_id"))
+     *        .and(m.col("user_id").eq(p.auth.uid()))),
+     *   ),
+     * ]
+     * ```
+     *
+     * `m` ÜYELİK tablosunun kolonlarını, `p` bu tablonunkileri verir; ikisi de
+     * tipli ve SQL'de farklı nitelenirler. Karışsalardı `team_id = team_id`
+     * üretilir ve politika hiçbir şeyi süzmezdi.
+     *
+     * ÖZYİNELEME TUZAĞI: üyelik tablosunun KENDİ politikası `existsIn`
+     * KULLANMAZ — `user_id = auth.uid()` yazar. İki tablo birbirini
+     * sorgularsa Postgres sorgu anında
+     * `infinite recursion detected in policy for relation …` der. Asimetri
+     * kasıtlıdır: üyelik tablosu basit olanı alır, diğer her tablo ona
+     * alt-sorgu ATAR.
+     */
+    existsIn<C extends ColumnMap, N extends string>(table: TableHandle<C, N>, predicate: (row: PolicyExprCtx<Extract<keyof C, string>>) => PolicyExprRef): PolicyExprRef;
+    /** Çağıranın kimliği. SQL'e `(select auth.uid())` olarak iner (InitPlan). */
+    auth: {
+        uid(): PolicyExprRef;
+    };
+    /** Düz bir değer — karşılaştırmanın sağ tarafında açıkça literal demek için. */
+    lit(v: string | number | boolean | null): PolicyExprRef;
+    and(...parts: PolicyExprRef[]): PolicyExprRef;
+    or(...parts: PolicyExprRef[]): PolicyExprRef;
+    not(part: PolicyExprRef): PolicyExprRef;
+}
+/**
+ * İfade bağlamını kurar. `defineTable` bunu kendi kolon adlarıyla çağırır;
+ * testler ve elle kullanım için de dışa açık.
+ */
+declare function exprCtx<Cols extends string = string>(_columns?: readonly Cols[], depth?: number, 
+/**
+ * POLİTİKANIN KENDİ tablosu — her derinlikte AYNI kalır.
+ *
+ * Alt-sorgunun içinde takma adsız duran bir kolon, dış sorgudaki tabloya
+ * bağlanmak zorundadır; Go tarafı onu bu adla nitelendiriyor. Değer iç içe
+ * geçmede ORTA tablonun adına kayıyordu (`meta.name` aşağı veriliyordu) ve
+ * sonuç canlıda `ERROR: missing FROM-clause entry for table "…"` oluyordu —
+ * yani iç içe `existsIn` içinden politikanın kendi kolonuna erişmek imkânsızdı
+ * (nihai inceleme I-1, ölçüldü). Kök tablo aşağı DEĞİŞMEDEN taşınır.
+ */
+ownTable?: string): PolicyExprCtx<Cols>;
+/** The SQL command a policy applies to. `"all"` covers SELECT/INSERT/UPDATE/DELETE. */
+type PolicyCommand = "all" | "select" | "insert" | "update" | "delete";
+/** Whether a policy is permissive (OR-combined, the default) or restrictive
+ * (AND-combined). Mirrors Postgres `CREATE POLICY ... AS PERMISSIVE|RESTRICTIVE`. */
+type PolicyMode = "permissive" | "restrictive";
+/**
+ * The compiled, serializable policy definition — the EXACT shape consumed by
+ * `schema_extract.js` → Go `PolicyJSON` (CONTRACT-POLICY).
+ *
+ * - `roles`: the DB roles this policy applies to (`TO` clause). An empty array
+ *   means the policy applies to PUBLIC (all roles) — the Postgres default.
+ * - `using`: the `USING (...)` row-visibility expression, or `null` when none.
+ * - `withCheck`: the `WITH CHECK (...)` write-validation expression, or `null`.
+ * - `permissive`: `true` for `AS PERMISSIVE` (default), `false` for restrictive.
+ */
+interface PolicyDef {
+    name: string;
+    command: PolicyCommand;
+    roles: string[];
+    /** Yapı (FR-022) ya da ham string (FR-028 kaçış kapağı). */
+    using: string | PolicyExpr | null;
+    withCheck: string | PolicyExpr | null;
+    permissive: boolean;
+}
+declare class PolicyBuilder {
+    readonly _def: PolicyDef;
+    constructor(name: string);
+    /** Restrict the policy to a single SQL command (default `"all"`). */
+    for(command: PolicyCommand): this;
+    /**
+     * Set the DB roles the policy applies to (the `TO` clause), replacing any
+     * previously-set roles. Call with no arguments to target PUBLIC (all roles).
+     *
+     * @example
+     * policy("p").to("authenticated")
+     * policy("p").to("authenticated", "service_role")
+     * policy("p").to() // PUBLIC
+     */
+    to(...roles: string[]): this;
+    /**
+     * `USING (...)` satır görünürlüğü ifadesi.
+     *
+     * Tercih edilen biçim YAPI'dır (FR-022) — `policies` callback'inin verdiği
+     * bağlamla kurulur ve kolon adları derlemede doğrulanır:
+     *
+     * ```ts
+     * policies: (p) => [
+     *   policy("owner_read").for("select").using(p.col("owner").eq(p.auth.uid())),
+     * ]
+     * ```
+     *
+     * Ham string KAÇIŞ KAPAĞI olarak kalır (FR-028): yapının ifade edemediği bir
+     * şey gerektiğinde yol kapanmaz. Ama o yolda kolon adı doğrulaması yoktur ve
+     * hata deploy anında Postgres'ten gelir.
+     */
+    using(expr: string | PolicyExprRef): 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;
+    /** `WITH CHECK (...)` yazma doğrulaması — `using` ile aynı iki biçim. */
+    withCheck(expr: string | PolicyExprRef): this;
+    /** Set the policy mode: `"permissive"` (default, OR-combined) or
+     * `"restrictive"` (AND-combined). */
+    as(mode: PolicyMode): this;
+}
+/**
+ * Start authoring an RLS policy. Returns a {@link PolicyBuilder}; the resulting
+ * `PolicyBuilder` is accepted directly in a table's `policies: [...]` array
+ * (its `_def` is read at schema-extract time).
+ *
+ * @param name The policy name. Palbase reconciliation keys policies by
+ *             `(table, name)`, so names must be unique per table.
+ */
+declare function policy(name: string): PolicyBuilder;
+
+/**
+ * Postgres extensions a Palbase project can enable from its schema.
+ *
+ * Extensions are config-as-code: declare them in `defineSchema({ extensions })`
+ * and the deploy installs them (CREATE EXTENSION … SCHEMA extensions) using the
+ * deploy path's privileged connection. They are NOT toggled live from Studio —
+ * CREATE EXTENSION requires a superuser role that only the deploy path holds.
+ *
+ * The list is an allowlist (a string-literal union) so editors autocomplete the
+ * supported names and a typo fails typecheck. It is intentionally extensible:
+ * add a name here (+ confirm the base image ships it) to support more.
+ */
+declare const PALBASE_EXTENSIONS: readonly ["vector", "pg_trgm", "unaccent", "citext", "cube", "earthdistance", "hstore", "ltree", "btree_gist", "pgcrypto", "uuid-ossp"];
+/** A Postgres extension supported by Palbase (allowlist union). */
+type PalbaseExtension = (typeof PALBASE_EXTENSIONS)[number];
+/**
+ * Extensions that depend on another extension. The deploy installs
+ * dependencies first; declaring `earthdistance` without `cube` still works
+ * because the deploy resolves the order, but listing both is clearer.
+ */
+declare const EXTENSION_DEPENDENCIES: Partial<Record<PalbaseExtension, PalbaseExtension[]>>;
+/** Runtime guard: is `name` a supported Palbase extension? */
+declare function isPalbaseExtension(name: string): name is PalbaseExtension;
+
+/**
+ * A named raw-SQL DDL object declared in a schema file (`db/public.ts`,
+ * `db/billing.ts`, …) for anything the typed DSL
+ * cannot express (EXCLUDE, CHECK, partial/expression indexes, triggers, views).
+ * The deploy emits `up` verbatim on the privileged DDL connection — same trust
+ * posture as policy().using(). Tracked by NAME (not by diffing the body), so a
+ * changed body needs a new name or an explicit drop+add.
+ */
+interface RawConstraintDef {
+    name: string;
+    up: string;
+    down?: string;
+}
+declare function raw(name: string, up: string, opts?: {
+    down?: string;
+}): RawConstraintDef;
+
+/** Embedding sağlayıcı DESKRIPTORU — canlı istemci değil, düz veri: şemayla
+ * birlikte serileşir, çağrıyı Go worker (yazma) ve engine (sorgu) yapar.
+ * Adlandırma Vercel AI SDK'nın aynasıdır (openai.embedding("...")) ama paket
+ * bağımlılığı bilinçli olarak YOKTUR (spec C-3, UD-016). v1 sağlayıcı: openai (D-10). */
+interface EmbeddingModelRef {
+    provider: "openai";
+    model: string;
+    dimensions?: number;
+    apiKeyName?: string;
+    baseURL?: string;
+}
+/** Chat/damıtma modeli DESKRIPTORU (C-11, D-019) — memory beyanının extract'i.
+ * Embedding gibi düz veridir; çağrıyı worker yapar, anahtar vault'taki
+ * OPENAI_API_KEY'dir (D-017: aynı sağlayıcı, yeni dış sistem yok). */
+interface ChatModelRef {
+    provider: "openai";
+    model: string;
+}
+declare const openai: {
+    embedding(model: string, opts?: {
+        dimensions?: number;
+        apiKeyName?: string;
+        baseURL?: string;
+    }): EmbeddingModelRef;
+    chat(model: string): ChatModelRef;
+};
+
+/**
+ * A map of column builders keyed by column name — the value you write under
+ * the `columns` key of `defineTable("<name>", { columns })`.
+ *
+ * The default `Record<string, ColumnBuilder>` keeps bare references compiling
+ * without a type argument.
+ */
+type ColumnMap = Record<string, ColumnBuilder>;
+/**
+ * The author-facing value written under each table key:
+ * `{ columns, rls?, policies? }`.
+ *
+ * - `columns`: the column map (required).
+ * - `rls`: enable + FORCE row-level security on this table. **Defaults to
+ *   `true`**, and is forced on when `policies` is non-empty. A table with RLS
+ *   and no policies is deny-all, which is the starting state: nothing reads it
+ *   until a policy says who may. Set `rls: false` only for a genuinely public
+ *   table — it is an explicit opt-out that a reviewer can grep for, not
+ *   something you get by forgetting.
+ * - `policies`: the RLS policies for this table, authored with `policy(name)`.
+ *   Each entry may be a {@link PolicyBuilder} (the normal `policy(...)` chain)
+ *   or a raw {@link PolicyDef} object.
+ *
+ * The `C` type parameter preserves the precise per-column phantom types so the
+ * typed `Database.public.*` surface keeps inferring insert/row shapes.
+ */
+/** Arama metriği — tek kelime; opclass ve operatör bundan türetilir, asla yüzeye çıkmaz (D-5/D-6). */
+type SearchMetric = "cosine" | "euclidean" | "inner_product";
+/** Bir vektör arama kolu. `model` varsa auto-embed: platform yazma+sorgu embedding'ini üstlenir (D-9). */
+interface VectorSearchDecl {
+    /** Hedef vector kolonu; tabloda TEK vector kolonu varsa atlanabilir (Go apply çözer, FR-010). */
+    column?: string;
+    /** Varsa auto-embed. Deskriptor düz veridir — şemayla serileşir (C-3). */
+    model?: EmbeddingModelRef;
+    /** model varsa ZORUNLU: embed kaynak kolonları = trigger'ın UPDATE OF listesi (C-2). */
+    from?: string[];
+    metric?: SearchMetric;
+    /** Kaynak metin değişince ara-dönem davranışı (yalnız auto-embed'de):
+     * "null" (vars.) — embedding anında NULL'lanır; satır yeni vektör yazılana
+     *   dek anlamsal aramada aday değildir. Bayat eşleşme asla servis edilmez.
+     * "keep" — eski vektör aramada kalır, platform yenisini yazınca sessizce
+     *   değişir. Görünürlük penceresi sıfır; bedeli saniyeler süren bayat
+     *   eşleşme riski (Confluence-tipi sync yükleri için). */
+    staleness?: "null" | "keep";
+}
+/** Tablonun arama beyanı — İKİ biçim (D-007, tek yüzey):
+ *
+ * YENİ (önerilen): `{ from, model, ... }` — `from` kolonları hem FTS'e hem
+ * embed'e girer. Tabloda vector kolonu declare edilmişse SATIR-modu; yoksa
+ * CHUNK-modu otomatiktir (D-010): vektörler türev `__palbase_chunks`
+ * tablosunda yaşar, içerik otomatik bölünür. `text: false` FTS'i kapatır,
+ * `text: [..]` FTS kolonlarını from'dan ayırır. `chunks` yalnız ince ayar.
+ *
+ * ESKİ: `text: string[]` + `vector: {...}` — aynen çalışır, wire çıktısı
+ * bayt-aynı kalır (NFR-B1). İki biçim KARIŞTIRILAMAZ. */
+interface SearchDecl {
+    text?: string[] | boolean;
+    vector?: VectorSearchDecl | VectorSearchDecl[];
+    /** Yeni biçim: arama kaynağı kolonlar (FTS + embed). Varlığı yeni biçimi seçer. */
+    from?: string[];
+    /** Yeni biçim: auto-embed modeli (zorunlu — BYO için eski biçimi kullanın). */
+    model?: EmbeddingModelRef;
+    metric?: SearchMetric;
+    staleness?: "null" | "keep";
+    /** Chunk-modu ince ayarı (yalnız vector kolonsuz tabloda anlamlı). */
+    chunks?: {
+        size?: number;
+        overlap?: number;
+    };
+    /** Sorgu-yeniden-yazımı: tek yönlü eş anlamlı haritası (FR-026). */
+    synonyms?: Record<string, string[]>;
+    /** Geçerlilik kolonları türetilir; arama varsayılan yalnız günceli tarar (FR-029). */
+    validity?: boolean;
+}
+/** Hafıza beyanı (FR-032, D-019): kaynak tablonun yazımlarından platform
+ * fact damıtır ve `into` tablosuna yazar. Hedef NORMAL declared tablodur —
+ * kendi search/unique/validity beyanlarıyla. Okuma = Database.$search(into).
+ * subject default "owner": fact'in kime ait olduğu kolonu (iki tabloda da). */
+interface MemoryDecl {
+    from: string[];
+    into: string;
+    extract: ChatModelRef;
+    subject?: string;
+}
+/**
+ * Bir index bildiriminin girdi şekli (FR-041…043).
+ *
+ * `columns` ile `expression` birbirinin alternatifidir: biri kolon listesi,
+ * diğeri `lower(email)` gibi bir ifade. `where` partial index koşuludur ve
+ * filtre şekli sorgu tarafındaki `WhereFilter` ile aynıdır — iki ayrı filtre
+ * dili olmaz.
+ */
+/**
+ * Bir index'in TEL şekli — `IndexJSON` ile aynı alanlar (T002).
+ *
+ * Bildirilmeyen alan HİÇ yazılmaz: sıfır değer yazmak, bildirmeyen her index'i
+ * diff'te değişmiş gösterir ve her deploy'a boş bir migration ekler.
+ */
+interface IndexDef {
+    name: string;
+    columns?: string[];
+    expression?: string;
+    where?: PolicyExpr;
+    sort?: "asc" | "desc";
+    nulls?: "first" | "last";
+    include?: string[];
+}
+/**
+ * `index("<ad>")` — C-5 (FR-041…043).
+ *
+ * ```ts
+ * indexes: (c) => [
+ *   index("orders_open")
+ *     .on(c.col("status"))                    // kolon TİPLİ
+ *     .where(c.col("deleted_at").isNull())    // partial
+ *     .include(["total"]),                    // covering
+ * ]
+ * ```
+ *
+ * `policy()` ile AYNI dili konuşur: `where` politika ifade yapısının ta kendisi.
+ * Üçüncü bir filtre lehçesi açmak, aynı sorunun iki yazımı demekti.
+ *
+ * Kolon bağlamı callback'ten geliyor çünkü index tablo tanımının İÇİNDE
+ * bildiriliyor — `orders.status` yazmak, `orders` bağlaması o noktada henüz
+ * kurulmadığı için mümkün değil (T015'te `policies` için ölçülen aynı kısıt).
+ */
+declare class IndexBuilder {
+    readonly _def: IndexDef;
+    constructor(name: string);
+    /** Index'in kolonları. SIRA KORUNUR — çok kolonlu bir index'in anlamı sırasıdır. */
+    on(...cols: PolicyExprRef[]): this;
+    /**
+     * İfade index'i (`lower(email)`), kolon yerine.
+     *
+     * Metin VERBATIM emit ediliyor — `policy().using("…")` ile aynı güven duruşu.
+     * Tipli yapı bunu ifade edemiyor ve kaçış kapağını kapatmak, yazarı elle
+     * migration yazmaya iterdi.
+     */
+    onExpression(expr: string): this;
+    /** Partial index koşulu — politika ifade dilinin ta kendisi. */
+    where(expr: PolicyExprRef): this;
+    /** Sıra. Tek yönlü index'te sıra genelde önemsizdir; ORDER BY ile eşleşen
+     * bir index arandığında değildir. */
+    desc(): this;
+    asc(): this;
+    /** NULL'ların yeri — `ORDER BY … NULLS LAST` ile eşleşmesi için. */
+    nulls(where: "first" | "last"): this;
+    /** Covering index (`INCLUDE`): index-only scan için taşınan ama
+     * ARANMAYAN kolonlar. */
+    include(cols: string[]): this;
+}
+declare function index(name: string): IndexBuilder;
+interface TableInput<C extends ColumnMap = ColumnMap> {
+    columns: C;
+    rls?: boolean;
+    /**
+     * Bu tablonun RLS politikaları — TABLONUN KENDİ KOLONLARININ bir fonksiyonu
+     * olarak (FR-022).
+     *
+     * Callback olmasının sebebi tip: `columns`'tan çıkarılan `C`, TypeScript
+     * tarafından buraya bağlamlandırılıyor, yani `p.col("ownerr")` yazım hatası
+     * DERLEME hatası oluyor. Düz bir dizide `policy("x")` tek başına çağrıldığı
+     * için hangi tabloda olduğunu bilemez, ve yanlış kolon adı ancak deploy
+     * anında `CREATE POLICY` çalışırken Postgres'ten dönerdi. Bir RLS
+     * politikasında yanlış kolon adı yetki hatasıdır; derlemede yakalanır.
+     *
+     * ```ts
+     * policies: (p) => [
+     *   policy("owner_read").for("select").using(p.col("owner").eq(p.auth.uid())),
+     * ]
+     * ```
+     */
+    policies?: (p: PolicyExprCtx<Extract<keyof C, string>>) => (PolicyBuilder | PolicyDef)[];
+    /** Composite/named primary key (ordered column names). Omit for single-column inline .primaryKey(). */
+    primaryKey?: string[];
+    /** Named multi-column UNIQUE constraints. */
+    unique?: {
+        name: string;
+        columns: string[];
+    }[];
+    /** Named raw-SQL DDL objects (EXCLUDE, triggers, views) that the typed DSL cannot express. */
+    raw?: RawConstraintDef[];
+    /**
+     * Named first-class CHECK constraints. Diffed by NAME with a BODY compare:
+     * a changed `expr` (after pg normalization) recreates the constraint
+     * (DROP + ADD). `expr` is trusted SQL emitted verbatim (like policy USING),
+     * `name` is identifier-validated.
+     */
+    checks?: {
+        name: string;
+        expr: string;
+    }[];
+    /**
+     * Plain (non-unique) btree indexes over an ordered column list, emitted as
+     * standalone `CREATE INDEX [IF NOT EXISTS] name ON table (col1, col2)`
+     * statements (NOT a table clause — a separate migration statement category).
+     * Structural compare by NAME (no expression normalization). `name` and each
+     * column are identifier-validated by the Go differ.
+     *
+     * Scope: columns-only plain btree. Partial (`where`) and expression indexes
+     * are a deliberate follow-up — modelling them needs the same raw-SQL
+     * normalization round-trip CHECK uses (Task 10), so they are NOT in this
+     * type yet to avoid a half-working partial-index path.
+     */
+    indexes?: (p: PolicyExprCtx<Extract<keyof C, string>>) => (IndexBuilder | IndexDef)[];
+    /**
+     * appendOnly (FR-030): tablo yalnız INSERT kabul eder — UPDATE/DELETE hem
+     * veritabanı yetkisiyle hem üretilen tipte reddedilir (T017/T018).
+     * Ledger deseninin veri katmanından istediği TEK şey budur: bakiye türetilmiş
+     * bir değerdir ve entry log'u değiştirilebilirse doğruluğunu kaybeder.
+     */
+    appendOnly?: boolean;
+    /** Arama beyanı — bkz. SearchDecl. */
+    search?: SearchDecl;
+    /** Hafıza beyanı — bkz. MemoryDecl (FR-032). */
+    memory?: MemoryDecl;
+}
+/**
+ * A table definition — the runtime value the Go runtime's `schema_extract.js`
+ * reads. It keys tables by `tableDef.name`, reads `tableDef.columns` for the
+ * column DDL, and `tableDef.rls` + `tableDef.policies` for RLS.
+ *
+ * `defineSchema` derives `name` from the object key, so authors never repeat
+ * the table name. `rls`/`policies` are always present after normalization
+ * (defaulted to `true`/`[]`).
+ *
+ * The `C` type parameter preserves the precise per-column phantom types so that
+ * downstream mapped types (InsertShape, RowShape) can discriminate on them.
+ */
+interface TableDef<C extends ColumnMap = ColumnMap> {
+    name: string;
+    columns: C;
+    rls: boolean;
+    policies: PolicyDef[];
+    primaryKey?: string[];
+    unique?: {
+        name: string;
+        columns: string[];
+    }[];
+    /** Named raw-SQL DDL objects emitted verbatim on deploy. Tracked by name. */
+    raw?: RawConstraintDef[];
+    /** Named first-class CHECK constraints. Diffed by name + (normalized) body. */
+    checks?: {
+        name: string;
+        expr: string;
+    }[];
+    /** Index bildirimleri; partial/expression/sıra/covering alanlarıyla (FR-041…043). */
+    indexes?: IndexDef[];
+    /** appendOnly (FR-030) — bkz. TableInput. */
+    appendOnly?: boolean;
+    /** Arama beyanı, doğrulanmış ve taşınmış hali. */
+    search?: SearchDecl;
+    /** Hafıza beyanı, doğrulanmış ve taşınmış hali (FR-032). */
+    memory?: MemoryDecl;
+}
+/**
+ * A schema definition containing multiple tables, keyed by table name.
+ *
+ * The `T` type parameter preserves the exact `TableDef<...>` type for each
+ * table so that `SchemaDef["tables"]["rooms"]` resolves to the precise
+ * `TableDef<{ id: ColumnBuilder<'uuid', false, true, never>; ... }>`.
+ */
+interface SchemaDef<T extends Record<string, TableDef> = Record<string, TableDef>> {
+    /** The schema's own name — `public`, `billing`, … Declared, never derived. */
+    name: string;
+    /** Reachable over HTTP? False unless the author opts in. */
+    exposed: boolean;
+    tables: T;
+    /** Postgres extensions to install on deploy. Normalized to `[]` when absent. */
+    extensions: PalbaseExtension[];
+}
+/** Map the author's `{ tables: { <name>: { columns } } }` input to the
+ * `{ tables: { <name>: TableDef<columns> } }` runtime/type shape, threading the
+ * per-table column map `T[K]["columns"]` so column-level inference survives. */
+type TablesByName<T extends readonly TableHandle[]> = {
+    [K in T[number] as K[typeof TABLE_META]["name"]]: K[typeof TABLE_META];
+};
+/**
+ * How a schema file reads. One file per schema — `db/public.ts`, `db/billing.ts`
+ * — and the schema says its own name:
+ *
+ *   const todos = defineTable("todos", {
+ *     columns: {
+ *       id:    uuid().primaryKey().defaultRandom(),
+ *       owner: text().notNull(),
+ *       title: text().notNull(),
+ *     },
+ *     rls: true,
+ *     policies: [
+ *       policy("owner_all").for("all").to("authenticated")
+ *         .using("owner = (select auth.uid())")
+ *         .withCheck("owner = (select auth.uid())"),
+ *     ],
+ *   });
+ *
+ *   export default defineSchema("public", { tables: [todos] });
+ *
+ * The dictionary form `defineSchema({ tables: { todos: {…} } })` is RETIRED and
+ * refused by name: a table whose name comes from a key does not know what it is
+ * called while it is being built, so it cannot resolve `references(() =>
+ * other.id)`, and a schema that does not say its own name cannot tell one
+ * `invoices` from another schema's `invoices`.
+ *
+ * The returned value is `{ name, tables: { todos: { name, columns, rls,
+ * policies } }, extensions, exposed }` — the exact shape the runtime schema
+ * extractor parses. Per-column phantom types are preserved so
+ * `Database.public.todos.insert({...})` stays typed.
+ *
+ * RLS normalization: `rls` defaults to **`true`**, `policies` to `[]`. A table
+ * that declares neither is therefore deny-all — nothing reads it until a policy
+ * says who may, which is the safe starting point rather than a bug. Declare
+ * `rls: false` for a genuinely public table; that is an explicit, greppable
+ * statement of intent instead of an omission. When `policies` is non-empty,
+ * `rls` is forced on (ENABLE + FORCE) regardless of the declared flag — a table
+ * with policies must have RLS enabled or the policies would be inert.
+ */
+/**
+ * Where a table's metadata lives.
+ *
+ * The table VALUE is its columns, so `lists.id` is the column — which means a
+ * column called `name` would overwrite the table's own name if metadata sat in
+ * a plain field. Measured, not imagined: the existing `users` / `rooms` tests
+ * (both declare a `name` column) produced an `[object Object]` table key.
+ * `columns`, `rls`, `search`, `memory`, `unique` and `indexes` are all plausible
+ * column names too. A column cannot collide with a symbol.
+ */
+declare const TABLE_META: unique symbol;
+/** A value produced by `defineTable`: the columns, plus metadata behind the symbol. */
+type TableHandle<C extends ColumnMap = ColumnMap, N extends string = string> = C & {
+    readonly [TABLE_META]: TableDef<C> & {
+        name: N;
+    };
+};
+/**
+ * Declare one table as a standalone value that KNOWS ITS OWN NAME.
+ *
+ * The name lives here, not in a dictionary key. A table whose name comes from a
+ * key cannot resolve `references(() => other.id)` when it is built — it does not
+ * know what to call itself — which forces a two-phase resolution with an
+ * empty-name intermediate state. One name source, no empty identity.
+ *
+ * The returned object spreads its own columns, so a sibling can point at it:
+ * `references(() => lists.id)`.
+ */
+declare function defineTable<const N extends string, C extends ColumnMap>(name: N, input: TableInput<C>): TableHandle<C, N>;
+/**
+ * Collect declared tables into one schema.
+ *
+ * Takes an ARRAY, not a dictionary: the tables already carry their names, and a
+ * second name source is a second thing that can disagree.
+ */
+declare function defineSchema<const T extends readonly TableHandle[]>(name: string, input: {
+    tables: T;
+    exposed?: boolean;
+    extensions?: PalbaseExtension[];
+}): SchemaDef<TablesByName<T>>;
+
+/**
+ * Local typed interfaces for the 9 Palbase module clients injected into
+ * every endpoint context via `ctx.auth`, `ctx.storage`, etc.
+ *
+ * Design intent
+ * ─────────────
+ * • @palbase/backend owns this contract — no runtime or type dependency on
+ *   @palbase/server or any module package.
+ * • These interfaces are STRUCTURALLY compatible with the runtime's
+ *   ServerClient module objects so assignment is valid without a cast.
+ * • All parameter and return types are defined LOCALLY here (not imported
+ *   from modules/) to keep the package self-contained.
+ *
+ * Privilege note
+ * ──────────────
+ * These clients run with the project's managed-runtime (privileged) key —
+ * they bypass end-user RLS; intentional for server handlers. Treat every
+ * call as if it has admin access to the project's data.
+ */
+
+/** A user as returned by auth verifyUserToken. */
+interface PalbaseUser {
+    id: string;
+    email: string;
+    emailVerified?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A session as returned by auth.getSession(). */
+interface PalbaseSession {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+/** MFA enroll result. */
+interface PalbaseMFAEnrollResult {
+    enrollment_id?: string;
+    secret?: string;
+    otp_url?: string;
+    qr_code?: string;
+    recovery_codes?: string[];
+    status?: string;
+}
+/** MFA token response. */
+interface PalbaseTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_in: number;
+}
+/** MFA factor. */
+interface PalbaseMFAFactor {
+    id: string;
+    type: string;
+    verified: boolean;
+    created_at: string;
+}
+/** Device token view returned by registerDevice. */
+interface PalbaseDeviceTokenView {
+    id: string;
+    device_id: string;
+    platform: "android" | "ios" | "web";
+    status: "active" | "inactive";
+    created_at: string;
+    updated_at: string;
+}
+/** Device info item returned by device.list(). */
+interface PalbaseDeviceInfo {
+    id: string;
+    platform: string;
+    attestation_status: string;
+    bound: boolean;
+    created_at: string;
+}
+/** Params for device.attestAndroid(). */
+interface PalbaseAttestAndroidParams {
+    verdict_token: string;
+}
+/** Result of device.attestAndroid(). */
+interface PalbaseAttestAndroidResult {
+    device_id: string;
+    attestation_status: string;
+    device_integrity?: string;
+}
+/** Params for device.attestiOS(). */
+interface PalbaseAttestiOSParams {
+    attestation_object: string;
+    key_id: string;
+    challenge: string;
+}
+/** Result of device.attestiOS(). */
+interface PalbaseAttestiOSResult {
+    device_id: string;
+    attestation_status: string;
+}
+/** Params for device.bind(). */
+interface PalbaseBindDeviceParams {
+    device_id: string;
+    public_key: string;
+    platform_attestation?: string;
+}
+/** Params for device.verifyRequestSignature() (server-only). */
+interface PalbaseVerifyRequestSignatureParams {
+    payload: string;
+    signature: string;
+}
+/** Flag context (user targeting). */
+interface PalbaseFlagContext {
+    userId?: string;
+    properties?: Record<string, unknown>;
+}
+/** Feature flag variant. */
+interface PalbaseFlagVariant {
+    name: string;
+    payload?: unknown;
+}
+/** Feature flag (getAll result item). */
+interface PalbaseFlag {
+    name: string;
+    enabled: boolean;
+    variant?: PalbaseFlagVariant;
+}
+/**
+ * Any JSON value a feature flag (or per-user override) can hold once resolved.
+ * Mirrors the wire shape the user-flags module stores and returns.
+ */
+type PalbaseFlagValue = boolean | number | string | null | PalbaseFlagValue[] | {
+    [key: string]: PalbaseFlagValue;
+};
+/** Where a resolved flag value came from. */
+type PalbaseFlagSource = "system" | "user";
+/** Result of {@link PalbaseFlagsClient.setOverride} /
+ * {@link PalbaseFlagsServiceClient.setOverrideForUser}. */
+interface PalbaseSetOverrideResult {
+    key: string;
+    value: PalbaseFlagValue;
+    source: PalbaseFlagSource;
+}
+/** Result of {@link PalbaseFlagsServiceClient.setOverridesForUser}. */
+interface PalbaseSetOverridesResult {
+    values: Record<string, PalbaseFlagValue>;
+}
+/** Result of {@link PalbaseFlagsServiceClient.clearOverrideForUser} — `value`
+ * is the system default the user falls back to. */
+interface PalbaseClearOverrideResult {
+    key: string;
+    value: PalbaseFlagValue;
+    source: PalbaseFlagSource;
+}
+/** Result of {@link PalbaseFlagsServiceClient.clearAllOverridesForUser}. */
+interface PalbaseClearAllOverridesResult {
+    deleted: number;
+}
+/** One cross-user operation for {@link PalbaseFlagsServiceClient.batchSetOverrides}. */
+interface PalbaseBatchOverrideOperation {
+    userId: string;
+    values: Record<string, PalbaseFlagValue>;
+}
+/** Result of {@link PalbaseFlagsServiceClient.batchSetOverrides}. */
+interface PalbaseBatchSetOverridesResult {
+    applied: number;
+}
+/** File object returned by storage operations. */
+interface PalbaseFileObject {
+    /** The object's path inside its bucket. `name` is the same value. */
+    path: string;
+    name: string;
+    bucket: string;
+    size: number;
+    contentType: string;
+    /** SHA-256 of the stored bytes, computed as they were written. */
+    checksum: string;
+    /** Present for images: the decoded dimensions of the ORIGINAL. */
+    width?: number;
+    height?: number;
+    /**
+     * A ThumbHash — a few dozen bytes that render as a blurred preview while the
+     * real image loads, with no second request to fetch it.
+     */
+    thumbhash?: string;
+    /**
+     * Declared rendition name → the URL that serves it. Produced at upload from
+     * what `config/storage.ts` declared, so this is a lookup rather than a
+     * transform anyone pays for per request.
+     */
+    variants: Record<string, string>;
+}
+/** Storage signed URL response. */
+interface PalbaseSignedUrlResponse {
+    signedUrl: string;
+}
+/** Storage upload options. */
+interface PalbaseUploadOptions {
+    contentType?: string;
+    upsert?: boolean;
+}
+/** Storage transform options for public URLs. */
+interface PalbaseTransformOptions {
+    width?: number;
+    height?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
+}
+/** Storage list options. */
+interface PalbaseListOptions {
+    limit?: number;
+    offset?: number;
+    sortBy?: {
+        column: string;
+        order: "asc" | "desc";
+    };
+}
+/** Edge-function invoke options. */
+interface PalbaseInvokeOptions {
+    body?: unknown;
+    headers?: Record<string, string>;
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+}
+/** Push recipient — user ID, array of user IDs, or a topic. */
+type PalbasePushRecipient = string | string[] | {
+    topic: string;
+};
+/** Localized text (plain or locale map). */
+type PalbaseLocalizedText = string | Record<string, string>;
+/** Push send params. */
+interface PalbasePushSendParams {
+    to: PalbasePushRecipient;
+    title?: PalbaseLocalizedText;
+    body?: PalbaseLocalizedText;
+    variables?: Record<string, string>;
+    default_locale?: string;
+    data?: Record<string, string>;
+    image?: string;
+    badge?: number;
+    sound?: string;
+    deep_link?: string;
+    collapse_key?: string;
+    priority?: "high" | "normal";
+    ttl?: number;
+    silent?: boolean;
+    content_available?: boolean;
+    category?: string;
+    metadata?: unknown;
+    channels?: Array<"push" | "inbox">;
+    inbox_action_url?: string;
+}
+/** Push send response. */
+interface PalbasePushSendResponse {
+    message_id?: string;
+    message_ids?: string[];
+    recipients: number;
+}
+/** Email send params. */
+interface PalbaseEmailSendParams {
+    to: string | string[];
+    subject?: string;
+    /**
+     * @deprecated The server reads `template_slug`, not `template` — this
+     * field is forwarded as-is and ignored by palnotify. Use `templateSlug`
+     * instead. Retained for source-compat with older callers.
+     */
+    template?: string;
+    /**
+     * Server email-template slug. The notifications client maps this to the
+     * wire field `template_slug` (mutually exclusive with `subject` + body
+     * fields when not overriding template output).
+     */
+    templateSlug?: string;
+    /**
+     * Which locale of `templateSlug` to render — a BCP47 short tag ("tr").
+     * Falls back to "en" when the slug has no row for it. Declaring a locale in
+     * config/notifications.ts is only half the feature: without this the extra
+     * rows exist and are unreachable.
+     */
+    locale?: string;
+    variables?: Record<string, unknown>;
+    html?: string;
+    text?: string;
+    from?: {
+        email: string;
+        name?: string;
+    };
+    reply_to?: string;
+    category?: string;
+}
+/** Email send response. */
+interface PalbaseEmailSendResponse {
+    message_id?: string;
+    message_ids?: string[];
+}
+/** SMS send params. */
+interface PalbaseSmsSendParams {
+    to: string | string[];
+    /**
+     * SMS body text. Either `body` OR `templateSlug` must be supplied —
+     * the two are mutually exclusive at the server.
+     */
+    body?: string;
+    /**
+     * Server SMS-template slug. The notifications client maps this to the
+     * wire field `template_slug`. When provided, palnotify renders the
+     * template with `variables` and uses the result as the SMS body.
+     */
+    templateSlug?: string;
+    /** Which locale of `templateSlug` to render — see PalbaseEmailSendParams.locale. */
+    locale?: string;
+    variables?: Record<string, unknown>;
+    category?: string;
+}
+/**
+ * Phone-verification start parameters.
+ *
+ * There is no body field, by construction: the provider generates the code AND
+ * the message text from its own template. A caller-supplied body would be
+ * silently dropped — a send that reports success while delivering something the
+ * caller never wrote.
+ */
+interface PalbaseVerificationStartParams {
+    /** E.164 recipient, e.g. "+14155551212". */
+    to: string;
+    /** Template language (e.g. "tr", "en"). Empty uses the service default. */
+    locale?: string;
+    /** Optional user attribution for the message log. */
+    user_id?: string;
+}
+/** Phone-verification start response. The code is never included. */
+interface PalbaseVerificationStartResponse {
+    /** Provider-side handle for this attempt. Not a secret, and not the code. */
+    verification_sid: string;
+    /** Provider lifecycle value, typically "pending". */
+    status: string;
+    to: string;
+    /** palnotify message-log row id, so the send appears in message history. */
+    message_id?: string;
+}
+/** Phone-verification check parameters. */
+interface PalbaseVerificationCheckParams {
+    to: string;
+    code: string;
+}
+/**
+ * Phone-verification verdict. A wrong or expired code is `approved: false` with
+ * a successful HTTP status — a mismatch is a normal outcome, not an error.
+ */
+interface PalbaseVerificationCheckResponse {
+    approved: boolean;
+}
+/** SMS send response. */
+interface PalbaseSmsSendResponse {
+    message_id?: string;
+    message_ids?: string[];
+}
+/** Inbox send params (managed-runtime: create inbox row for a user). */
+interface PalbaseInboxSendParams {
+    to: string;
+    title?: string;
+    body: string;
+    data?: unknown;
+    action_url?: string;
+    category?: string;
+    channels?: Array<"push" | "inbox">;
+    push_deep_link?: string;
+}
+/** Inbox send response. */
+interface PalbaseInboxSendResponse {
+    message_id?: string;
+    skipped?: boolean;
+}
+/** A per-channel status entry in a multi-channel response. */
+interface PalbaseChannelOutcome {
+    status: "queued" | "sent" | "skipped" | "failed";
+    message_id?: string;
+    message_ids?: string[];
+    recipients?: number;
+    error?: string;
+}
+/** Multi-channel fan-out response. */
+interface PalbaseMultiChannelResponse {
+    channels: Record<string, PalbaseChannelOutcome>;
+}
+/** An inbox message as returned by inbox.list. */
+interface PalbaseInboxMessage {
+    id: string;
+    user_id?: string;
+    title?: string;
+    body: string;
+    data?: unknown;
+    action_url?: string;
+    category?: string;
+    is_read: boolean;
+    read_at?: string;
+    created_at: string;
+}
+/** Inbox list options. */
+interface PalbaseInboxListOptions {
+    cursor?: string;
+    limit?: number;
+    is_read?: boolean;
+    category?: string;
+    include_archived?: boolean;
+}
+/** Inbox list result. */
+interface PalbaseInboxListResult {
+    messages: PalbaseInboxMessage[];
+    next_cursor?: string;
+}
+/** Notification preferences (channel × category opt-in/out). */
+type PalbasePreferences = Partial<Record<"push" | "email" | "sms" | "inbox", Record<string, boolean>>>;
+/** Register device params. */
+interface PalbaseRegisterDeviceParams {
+    device_id: string;
+    token: string;
+    platform: "android" | "ios" | "web";
+    app_version?: string;
+    locale?: string;
+}
+/** Email template view (camelCase). */
+interface PalbaseEmailTemplate {
+    id: string;
+    slug: string;
+    locale: string;
+    subject: string;
+    htmlBody: string;
+    textBody?: string;
+    variables: string[];
+    isDefault: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Payload for templates.email.create. */
+interface PalbaseCreateEmailTemplateInput {
+    slug: string;
+    locale?: string;
+    subject: string;
+    htmlBody: string;
+    textBody?: string;
+    variables?: string[];
+}
+/** Payload for templates.email.update — patch semantics. */
+interface PalbaseUpdateEmailTemplateInput {
+    subject?: string;
+    htmlBody?: string;
+    textBody?: string;
+    variables?: string[];
+}
+/** SMS template view (camelCase). No subject / html / text distinction. */
+interface PalbaseSMSTemplate {
+    id: string;
+    slug: string;
+    locale: string;
+    body: string;
+    variables: string[];
+    isDefault: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Payload for templates.sms.create. */
+interface PalbaseCreateSMSTemplateInput {
+    slug: string;
+    locale?: string;
+    body: string;
+    variables?: string[];
+}
+/** Payload for templates.sms.update — patch semantics. */
+interface PalbaseUpdateSMSTemplateInput {
+    body?: string;
+    variables?: string[];
+}
+/** Analytics event properties. */
+type PalbaseAnalyticsProperties = Record<string, unknown>;
+/** Analytics identify traits. */
+type PalbaseIdentifyTraits = Record<string, unknown>;
+/** Analytics count query input. */
+interface PalbaseCountQueryInput {
+    eventName?: string;
+    eventNames?: string[];
+    from: number;
+    to: number;
+    interval?: "hour" | "day";
+    filters?: Record<string, string>;
+    breakdown?: string;
+}
+/** A single time-bucket in a count result. */
+interface PalbaseCountBucket {
+    t: number;
+    count: number;
+    breakdown?: string;
+}
+/** Count query result. */
+interface PalbaseCountResult {
+    series: PalbaseCountBucket[];
+    from_mv: boolean;
+}
+/** Events query input. */
+interface PalbaseEventsQueryInput {
+    from: number;
+    to: number;
+    eventName?: string;
+    distinctId?: string;
+    limit?: number;
+    cursor?: string;
+}
+/** A single event row. */
+interface PalbaseEventRow {
+    event_id: string;
+    timestamp: number;
+    event_name: string;
+    distinct_id: string;
+    properties: Record<string, unknown>;
+}
+/** Events query result. */
+interface PalbaseEventsResult {
+    events: PalbaseEventRow[];
+    next_cursor?: string;
+}
+/** Properties query input. */
+interface PalbasePropertiesQueryInput {
+    eventName?: string;
+    from?: number;
+    to?: number;
+}
+/** Property descriptor (from /query/properties). */
+interface PalbasePropertyDescriptor {
+    name: string;
+    value_count: number;
+}
+/** Users query input. */
+interface PalbaseUsersQueryInput {
+    from: number;
+    to: number;
+    filters?: Record<string, string>;
+    limit?: number;
+    cursor?: string;
+}
+/** A single user row. */
+interface PalbaseUserRow {
+    distinct_id: string;
+    first_seen: number;
+    last_seen: number;
+    event_count: number;
+    properties?: Record<string, unknown>;
+}
+/** Users query result. */
+interface PalbaseUsersResult {
+    users: PalbaseUserRow[];
+    next_cursor?: string;
+}
+/** Funnel query input. */
+interface PalbaseFunnelQueryInput {
+    steps: Array<{
+        event_name: string;
+        filters?: Record<string, string>;
+    }>;
+    from: number;
+    to: number;
+    conversionWindowSeconds?: number;
+    breakdown?: string;
+}
+/** Funnel step result. */
+interface PalbaseFunnelStepResult {
+    event_name: string;
+    count: number;
+    conversion_rate: number;
+}
+/** Funnel query result. */
+interface PalbaseFunnelResult {
+    steps: PalbaseFunnelStepResult[];
+    overall_conversion_rate: number;
+}
+/** Retention query input. */
+interface PalbaseRetentionQueryInput {
+    firstEvent: string;
+    returnEvent: string;
+    from: number;
+    to: number;
+    periodDays?: number;
+    periods?: number;
+}
+/** Retention cohort result item. */
+interface PalbaseRetentionCohort {
+    cohort_start: number;
+    size: number;
+    periods: number[];
+}
+/** Retention query result. */
+interface PalbaseRetentionResult {
+    cohorts: PalbaseRetentionCohort[];
+}
+/** Cohort query input. */
+interface PalbaseCohortQueryInput {
+    name: string;
+    rules: Array<{
+        event_name: string;
+        filters?: Record<string, string>;
+    }>;
+    from: number;
+    to: number;
+}
+/** Cohort query result. */
+interface PalbaseCohortResult {
+    size: number;
+    distinct_ids_sample: string[];
+}
+/** Analytics overview result. */
+interface PalbaseOverviewResult {
+    dau: number;
+    wau: number;
+    mau: number;
+    total_events: number;
+    top_events: Array<{
+        event_name: string;
+        count: number;
+    }>;
+}
+/** Event names result. */
+interface PalbaseEventNamesResult {
+    names: string[];
+}
+/** User detail result. */
+interface PalbaseUserDetailResult {
+    distinct_id: string;
+    first_seen: number;
+    last_seen: number;
+    event_count: number;
+    properties: Record<string, unknown>;
+    recent_events: PalbaseEventRow[];
+}
+/** Create link params. */
+interface PalbaseCreateLinkParams {
+    url: string;
+    title?: string;
+    description?: string;
+    imageUrl?: string;
+    ios?: {
+        bundleId: string;
+        appStoreId?: string;
+        fallbackUrl?: string;
+        minimumVersion?: string;
+    };
+    android?: {
+        packageName: string;
+        fallbackUrl?: string;
+        minimumVersion?: number;
+    };
+    web?: {
+        fallbackUrl?: string;
+    };
+    social?: {
+        title?: string;
+        description?: string;
+        imageUrl?: string;
+    };
+    expiresAt?: string;
+    customShortCode?: string;
+}
+/** Update link params. */
+interface PalbaseUpdateLinkParams {
+    url?: string;
+    title?: string;
+    description?: string;
+    imageUrl?: string;
+    ios?: {
+        bundleId?: string;
+        appStoreId?: string;
+        fallbackUrl?: string;
+        minimumVersion?: string;
+    };
+    android?: {
+        packageName?: string;
+        fallbackUrl?: string;
+        minimumVersion?: number;
+    };
+    web?: {
+        fallbackUrl?: string;
+    };
+    social?: {
+        title?: string;
+        description?: string;
+        imageUrl?: string;
+    };
+    expiresAt?: string;
+}
+/** A link object. */
+interface PalbaseLink {
+    id: string;
+    shortCode: string;
+    shortUrl: string;
+    url: string;
+    title?: string;
+    clickCount: number;
+    createdAt: string;
+}
+/** Link details (extended link). */
+interface PalbaseLinkDetails extends PalbaseLink {
+    description?: string;
+    imageUrl?: string;
+    ios?: Record<string, unknown>;
+    android?: Record<string, unknown>;
+    web?: Record<string, unknown>;
+    social?: Record<string, unknown>;
+    expiresAt?: string;
+}
+/** Link analytics. */
+interface PalbaseLinkAnalytics {
+    totalClicks: number;
+    clicksByPlatform: Record<string, number>;
+    clicksByCountry: Record<string, number>;
+    clicksByDay: Array<{
+        date: string;
+        clicks: number;
+    }>;
+}
+/** QR code options. */
+interface PalbaseQrCodeOptions {
+    size?: number;
+    format?: "png" | "svg";
+}
+/** Match params for deferred deep link resolution. */
+interface PalbaseMatchParams {
+    fingerprintHash: string;
+}
+/** Initial deep link. */
+interface PalbaseInitialLink {
+    url: string;
+    params?: Record<string, string>;
+}
+/** List links options. */
+interface PalbaseListLinksOptions {
+    limit?: number;
+    offset?: number;
+}
+/** List links result. */
+interface PalbaseListLinksResult {
+    links: PalbaseLink[];
+    total: number;
+}
+/**
+ * Auth client surface available on `ctx.auth`.
+ * Exposes server-relevant methods only. Browser-only patterns are omitted:
+ * — signUp / signIn / signOut / refresh / requestPasswordReset / confirmPasswordReset
+ *   / changePassword / resendVerification / verifyEmail (client flow helpers)
+ * — onAuthStateChange / onTokenChange (subscription callbacks)
+ * — getOAuthURL / signInWithCredential (OAuth browser redirects)
+ * — requestMagicLink / verifyMagicLink (client flow helpers)
+ * — setTokens / getAccessToken (internal token management)
+ * — listSessions / revokeSession / revokeAllSessions (user-self management)
+ * — listIdentities / linkIdentity / unlinkIdentity (user-self management)
+ * — listTrustedDevices / registerTrustedDevice / revokeTrustedDevice (user-self management)
+ */
+interface PalbaseAuthClient {
+    /**
+     * Verify a user's JWT by calling GET /auth/user. Returns the user if the
+     * token is valid; error otherwise. Service-role privileged.
+     */
+    verifyUserToken(jwt: string): Promise<PalbaseResult<PalbaseUser>>;
+    /**
+     * Get the current session held by the client (synchronous — no network
+     * call). On the server the managed-runtime client does not hold a user
+     * session; this always returns `{ data: null, error: null }`.
+     */
+    getSession(): {
+        data: PalbaseSession | null;
+        error: null;
+    };
+    /** MFA admin surface — enroll/verify/manage factors on behalf of users. */
+    mfa: {
+        /** Enroll a new MFA factor (TOTP or email). */
+        enroll(params: {
+            type: "totp" | "email";
+        }): Promise<PalbaseResult<PalbaseMFAEnrollResult>>;
+        /** Verify an enrollment code. */
+        verifyEnrollment(code: string): Promise<PalbaseResult<{
+            status: string;
+        }>>;
+        /** Challenge an MFA factor (verify code, obtain token). */
+        challenge(params: {
+            mfa_token: string;
+            type: "totp" | "email";
+            code: string;
+        }): Promise<PalbaseResult<PalbaseTokenResponse>>;
+        /** Recover via backup code. */
+        recovery(params: {
+            mfa_token: string;
+            code: string;
+        }): Promise<PalbaseResult<PalbaseTokenResponse>>;
+        /** List enrolled factors. */
+        listFactors(): Promise<PalbaseResult<{
+            factors: PalbaseMFAFactor[];
+        }>>;
+        /** Remove a factor. Requires current password. */
+        removeFactor(factorId: string, currentPassword: string): Promise<PalbaseResult<{
+            status: string;
+        }>>;
+        /** Regenerate recovery codes. */
+        regenerateRecoveryCodes(): Promise<PalbaseResult<{
+            recovery_codes: string[];
+        }>>;
+        /** Email MFA: start enrollment. */
+        emailEnroll(): Promise<PalbaseResult<{
+            status: string;
+        }>>;
+        /** Email MFA: send challenge. */
+        emailChallenge(params: {
+            mfa_token: string;
+        }): Promise<PalbaseResult<{
+            status: string;
+        }>>;
+        /** Email MFA: verify code. */
+        emailVerify(params: {
+            mfa_token: string;
+            code: string;
+        }): Promise<PalbaseResult<PalbaseTokenResponse>>;
+    };
+    /** Device attestation surface (App Attest / Play Integrity). */
+    device: {
+        /** Generate a device attestation challenge. */
+        generateChallenge(): Promise<PalbaseResult<{
+            challenge: string;
+        }>>;
+        /** Attest an Android device with a Play Integrity verdict token. */
+        attestAndroid(params: PalbaseAttestAndroidParams): Promise<PalbaseResult<PalbaseAttestAndroidResult>>;
+        /** Attest an iOS device with App Attest attestation data. */
+        attestiOS(params: PalbaseAttestiOSParams): Promise<PalbaseResult<PalbaseAttestiOSResult>>;
+        /** Bind a verified device with a public key for request signing. */
+        bind(params: PalbaseBindDeviceParams): Promise<PalbaseResult<{
+            success: boolean;
+        }>>;
+        /** List all devices for the current user. */
+        list(): Promise<PalbaseResult<{
+            devices: PalbaseDeviceInfo[];
+        }>>;
+        /** Delete a device by ID. */
+        delete(deviceId: string): Promise<PalbaseResult<{
+            success: boolean;
+        }>>;
+        /**
+         * Verify a request signature from a device (server-only).
+         * Not exposed in the client SDK.
+         */
+        verifyRequestSignature(deviceId: string, params: PalbaseVerifyRequestSignatureParams): Promise<PalbaseResult<{
+            verified: boolean;
+        }>>;
+        /** Get the cached App Check token, or null if not available / expired. */
+        getToken(): string | null;
+        /** Whether App Check is active (token cached and not expired). */
+        readonly isActive: boolean;
+        /** Set a cached App Check token manually (e.g. after attest flow). */
+        setCachedToken(token: string, expiresInMs: number): void;
+        /** Clean up timers and cached state. */
+        dispose(): void;
+    };
+}
+/**
+ * Bucket-level file operations available via `ctx.storage.bucket(name)`.
+ * `getPublicUrl` is synchronous (no network call — constructs URL locally).
+ */
+interface PalbaseBucketClient {
+    /** Upload a file. */
+    upload(path: string, file: Blob | ArrayBuffer | ReadableStream, options?: PalbaseUploadOptions): Promise<PalbaseResult<PalbaseFileObject>>;
+    /** Download a file as a Blob. */
+    download(path: string): Promise<PalbaseResult<Blob>>;
+    /**
+     * The public URL for an object, or for one of its declared renditions.
+     *
+     * `variant` names a rendition from `config/storage.ts` — NOT arbitrary
+     * dimensions. Renditions are produced at upload and served as immutable
+     * objects, so a URL here costs nothing to serve and caches forever; an
+     * arbitrary size would be a transform on the request path, one public URL
+     * away from a CPU amplification attack.
+     *
+     * Asking for a variant the bucket does not declare is an error rather than a
+     * silent fall back to the original: an app that requested a 200px thumbnail
+     * and quietly received a 5 MB photograph works, looks right, and is found
+     * months later on a bandwidth bill.
+     */
+    getPublicUrl(path: string, options?: {
+        variant?: string;
+    }): string;
+    /**
+     * A time-limited URL for a private object.
+     *
+     * The duration is NAMED (`{ expiresIn: "1h" }`) rather than a bare number,
+     * because "3600" reads as seconds to whoever wrote it and as minutes to
+     * whoever maintains it. Same human spelling `fileSizeLimit` takes.
+     */
+    createSignedUrl(path: string, options: {
+        expiresIn: string;
+    }): Promise<PalbaseResult<PalbaseSignedUrlResponse>>;
+    /** List objects in the bucket (optionally filtered by prefix). */
+    list(prefix?: string, options?: PalbaseListOptions): Promise<PalbaseResult<PalbaseFileObject[]>>;
+    /** Delete one or more objects. */
+    remove(paths: string[]): Promise<PalbaseResult<PalbaseFileObject[]>>;
+    /** Move / rename an object. */
+    move(from: string, to: string): Promise<PalbaseResult<void>>;
+    /** Copy an object. */
+    copy(from: string, to: string): Promise<PalbaseResult<void>>;
+}
+/**
+ * Storage client available on `ctx.storage`.
+ * Only `bucket()` is exposed — managed-runtime callers select a bucket first.
+ */
+interface PalbaseStorageClient {
+    /** Get a bucket-scoped client for file operations. */
+    bucket(name: string): PalbaseBucketClient;
+}
+/**
+ * Functions client available on `ctx.functions`.
+ * Invoke edge functions from a backend endpoint.
+ */
+interface PalbaseFunctionsClient {
+    /** Invoke a named edge function. */
+    invoke<T = unknown>(fnName: string, options?: PalbaseInvokeOptions): Promise<PalbaseResult<T>>;
+}
+/**
+ * Cross-user admin write surface, reached via `Flags.asService()`.
+ *
+ * These five methods set/clear overrides for an ARBITRARY user (named
+ * explicitly), so they bypass the current-request-user scope that `Flags.*`
+ * reads and `Flags.setOverride(...)` are bound to. Mirrors the
+ * `Database` / `Database.$asService()` split: the privileged, cross-user path
+ * is moved OFF the default surface so it is greppable and intentional — a
+ * handler that calls `Flags.setOverrideForUser(...)` on the default surface is
+ * a compile error and must reach for `Flags.asService()` first.
+ *
+ * @example
+ * await Flags.asService().setOverrideForUser("user_123", "new_checkout", true);
+ */
+interface PalbaseFlagsServiceClient {
+    /**
+     * Set (or replace) a single feature-flag override for one user. The override
+     * shadows the project (system) default for that user until cleared.
+     */
+    setOverrideForUser(userId: string, key: PalbaseFlagKey, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
+    /** Set multiple overrides for one user in a single call. */
+    setOverridesForUser(userId: string, values: Record<string, PalbaseFlagValue>): Promise<PalbaseResult<PalbaseSetOverridesResult>>;
+    /** Clear one override for a user, restoring the project (system) default. */
+    clearOverrideForUser(userId: string, key: PalbaseFlagKey): Promise<PalbaseResult<PalbaseClearOverrideResult>>;
+    /** Clear all overrides for a user, restoring project (system) defaults. */
+    clearAllOverridesForUser(userId: string): Promise<PalbaseResult<PalbaseClearAllOverridesResult>>;
+    /** Apply override writes across many users in one request (max 1000 ops). */
+    batchSetOverrides(operations: ReadonlyArray<PalbaseBatchOverrideOperation>): Promise<PalbaseResult<PalbaseBatchSetOverridesResult>>;
+}
+/**
+ * Flags client available as the `Flags` singleton (and on `ctx.flags`).
+ * Evaluate feature flags server-side (managed-runtime key — user targeting
+ * is optional via context).
+ *
+ * Writes follow the `Database` model:
+ * — `setOverride(key, value)` (default) overrides the flag for the CURRENT
+ *   request user; no userId argument, no admin power required. It errors when
+ *   there is no signed-in user (an anonymous request).
+ * — `asService()` returns the {@link PalbaseFlagsServiceClient} carrying the
+ *   cross-user admin writes (`setOverrideForUser`, …) for an arbitrary target
+ *   user. Greppable + explicit, exactly like `Database.$asService()`.
+ *
+ * Reads (`isEnabled`/`getVariant`/`get`/`getAll`) stay on this default surface
+ * and are already current-user-scoped via the request identity.
+ */
+interface PalbaseFlagsClient {
+    /** Is a flag enabled for the given context? */
+    isEnabled(flagName: PalbaseFlagKey, context?: PalbaseFlagContext): Promise<PalbaseResult<boolean>>;
+    /** Get the active variant of a multivariate flag. */
+    getVariant(flagName: PalbaseFlagKey, context?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagVariant>>;
+    /** Get all flags for the project. */
+    getAll(context?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlag[]>>;
+    /**
+     * Resolve a flag's value, with an optional fallback.
+     *
+     * `get(key)` · `get(key, default)` · `get(key, ctx)` · `get(key, default, ctx)`.
+     * The default is substituted when the flag is absent AND when the flags
+     * service is unreachable — a product that hides a feature because a lookup
+     * timed out is behaving correctly.
+     *
+     * Declared here as of 2026-08-15. The client has always had it and its tests
+     * have always covered it, but the interface did not: `Flags.get("x")` was a
+     * type error in a handler and worked at runtime. That is the same gap as
+     * `Documents.doc(...)` — declared and never implemented — seen from the other
+     * side, and moving the implementation into this package is what surfaced it.
+     */
+    get(flagName: PalbaseFlagKey, defaultOrContext?: PalbaseFlagValue | PalbaseFlagContext, maybeContext?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlagValue>>;
+    /**
+     * Set (or replace) a single feature-flag override for the CURRENT REQUEST
+     * USER. No userId argument — the override is bound to the signed-in user the
+     * handler is serving, so a handler can flip a flag for that user without
+     * admin power. The override shadows the project (system) default for that
+     * user until cleared.
+     *
+     * Errors when there is no signed-in user (an anonymous request); reach for
+     * `Flags.asService().setOverrideForUser(userId, key, value)` to write a flag
+     * for an arbitrary (cross-user) target.
+     *
+     * @example
+     * await Flags.setOverride("new_checkout", true);
+     */
+    setOverride(key: PalbaseFlagKey, value: PalbaseFlagValue): Promise<PalbaseResult<PalbaseSetOverrideResult>>;
+    /**
+     * Return the cross-user admin write surface ({@link PalbaseFlagsServiceClient}).
+     * Use sparingly and explicitly — the default `Flags.setOverride(...)` path is
+     * bound to the current request user; `asService()` is how you write a flag
+     * override for an ARBITRARY user. Mirrors `Database.$asService()`.
+     */
+    asService(): PalbaseFlagsServiceClient;
+}
+/**
+ * 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
+ * the backend — a stateless request handler can't hold a socket; it fires an
+ * HTTP broadcast and returns. Delivery is fire-and-forget: `broadcast` resolves
+ * 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 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:
+ * await Realtime.broadcast("room:42", "message", { text, from: user.id });
+ */
+interface PalbaseRealtimeClient {
+    /**
+     * A channel's SHARED STATE — a keyed map every subscriber sees, including
+     * the ones that join later.
+     *
+     * That is the whole difference from `broadcast`: a broadcast reaches whoever
+     * is listening at that instant, and a client connecting a second afterwards
+     * learns nothing until the next one. State is handed to every joiner in the
+     * snapshot they get, so "the score is 3-1" or "this flag is now on" arrives
+     * even for a client that was not there when it changed.
+     */
+    state: {
+        /** Write one entry. Fire-and-forget, like `broadcast`. */
+        set(topic: string, key: string, value: Record<string, unknown>): Promise<PalbaseResult<void>>;
+        /** Remove one entry. */
+        clear(topic: string, key: string): Promise<PalbaseResult<void>>;
+    };
+    /**
+     * Broadcast `event` with `payload` to everyone subscribed to `channel`.
+     *
+     * Fire-and-forget: resolves `{ data: undefined, error: null }` when the
+     * broadcast was accepted, or `{ data: null, error }` when it could not be
+     * sent (e.g. realtime not provisioned). A failed broadcast never throws and
+     * never fails the handler.
+     *
+     * @param channel App-defined channel name (e.g. `"room:42"`). Do NOT prefix
+     *   with `"realtime:"` — that prefix is internal to the transport.
+     * @param event  Event name subscribers filter on (e.g. `"message"`).
+     * @param payload JSON-serializable event body.
+     */
+    broadcast(channel: string, event: string, payload?: Record<string, unknown>): Promise<PalbaseResult<void>>;
+}
+/**
+ * Push sub-client surface (server-only: fan-out to users / topics).
+ */
+interface PalbasePushClient {
+    /** Send a push notification to one or more users, or a topic. */
+    send(params: PalbasePushSendParams): Promise<PalbaseResult<PalbasePushSendResponse | PalbaseMultiChannelResponse>>;
+}
+/**
+ * Email sub-client surface (managed-runtime).
+ */
+interface PalbaseEmailClient {
+    /** Send a transactional email. */
+    send(params: PalbaseEmailSendParams): Promise<PalbaseResult<PalbaseEmailSendResponse>>;
+}
+/**
+ * SMS sub-client surface (managed-runtime).
+ */
+interface PalbaseSmsClient {
+    /** Send an SMS message. */
+    send(params: PalbaseSmsSendParams): Promise<PalbaseResult<PalbaseSmsSendResponse>>;
+}
+/**
+ * Phone-verification (OTP) sub-client surface (managed-runtime).
+ *
+ * Separate from `sms` because a verification carries no caller-authored text.
+ * It is also the rail that works without a registered sender: a verification
+ * service owns its own sender identity, which plain SMS requires you to
+ * provision (and, in many countries, register) yourself.
+ */
+interface PalbaseVerificationsClient {
+    /** Send a verification code over SMS. */
+    start(params: PalbaseVerificationStartParams): Promise<PalbaseResult<PalbaseVerificationStartResponse>>;
+    /** Check a submitted code. A wrong code resolves to `approved: false`. */
+    check(params: PalbaseVerificationCheckParams): Promise<PalbaseResult<PalbaseVerificationCheckResponse>>;
+}
+/**
+ * Inbox sub-client surface (managed-runtime send + user read operations).
+ */
+interface PalbaseInboxClient {
+    /** Service-role: create an inbox notification row for a user. */
+    send(params: PalbaseInboxSendParams): Promise<PalbaseResult<PalbaseInboxSendResponse | PalbaseMultiChannelResponse>>;
+    /** List inbox messages (user-scoped or admin). */
+    list(options?: PalbaseInboxListOptions): Promise<PalbaseResult<PalbaseInboxListResult>>;
+    /** Count unread messages. */
+    unreadCount(): Promise<PalbaseResult<{
+        count: number;
+    }>>;
+    /** Mark a message as read. */
+    markRead(id: string): Promise<PalbaseResult<void>>;
+    /** Mark all messages read. */
+    markAllRead(): Promise<PalbaseResult<void>>;
+    /** Archive (soft-delete) a message. */
+    archive(id: string): Promise<PalbaseResult<void>>;
+}
+/**
+ * Preferences sub-client surface.
+ */
+interface PalbasePreferencesClient {
+    /** Get notification preferences. */
+    get(): Promise<PalbaseResult<PalbasePreferences>>;
+    /** Update notification preferences. */
+    update(params: PalbasePreferences): Promise<PalbaseResult<PalbasePreferences>>;
+}
+/**
+ * Email-template CRUD sub-client (managed-runtime gated server-side).
+ */
+interface PalbaseEmailTemplatesClient {
+    /** List all email templates. */
+    list(): Promise<PalbaseResult<PalbaseEmailTemplate[]>>;
+    /** Get one email template by ID. */
+    get(id: string): Promise<PalbaseResult<PalbaseEmailTemplate>>;
+    /** Create an email template. */
+    create(input: PalbaseCreateEmailTemplateInput): Promise<PalbaseResult<PalbaseEmailTemplate>>;
+    /** Update an email template (patch semantics). */
+    update(id: string, input: PalbaseUpdateEmailTemplateInput): Promise<PalbaseResult<PalbaseEmailTemplate>>;
+    /** Delete an email template. */
+    delete(id: string): Promise<PalbaseResult<void>>;
+}
+/**
+ * SMS-template CRUD sub-client (managed-runtime gated server-side).
+ */
+interface PalbaseSMSTemplatesClient {
+    /** List all SMS templates. */
+    list(): Promise<PalbaseResult<PalbaseSMSTemplate[]>>;
+    /** Get one SMS template by ID. */
+    get(id: string): Promise<PalbaseResult<PalbaseSMSTemplate>>;
+    /** Create an SMS template. */
+    create(input: PalbaseCreateSMSTemplateInput): Promise<PalbaseResult<PalbaseSMSTemplate>>;
+    /** Update an SMS template (patch semantics). */
+    update(id: string, input: PalbaseUpdateSMSTemplateInput): Promise<PalbaseResult<PalbaseSMSTemplate>>;
+    /** Delete an SMS template. */
+    delete(id: string): Promise<PalbaseResult<void>>;
+}
+/**
+ * Templates sub-client — parallel CRUD for email and SMS templates.
+ * Service-role gated server-side; both surfaces map TS camelCase to
+ * wire snake_case in the runtime client.
+ */
+interface PalbaseTemplatesClient {
+    /** Email template CRUD. */
+    email: PalbaseEmailTemplatesClient;
+    /** SMS template CRUD. */
+    sms: PalbaseSMSTemplatesClient;
+}
+/**
+ * Notifications client available on `ctx.notifications`.
+ * Service-role: all send operations require privileged access.
+ * Omits ClientNotificationsClient (browser-only narrowed surface).
+ */
+interface PalbaseNotificationsClient {
+    /** Push notification sender. */
+    push: PalbasePushClient;
+    /** Email sender. */
+    email: PalbaseEmailClient;
+    /** SMS sender. */
+    sms: PalbaseSmsClient;
+    /** Phone verification (OTP) sender and checker. */
+    verifications: PalbaseVerificationsClient;
+    /** Inbox (in-app) message sender and reader. */
+    inbox: PalbaseInboxClient;
+    /** Notification preferences manager. */
+    preferences: PalbasePreferencesClient;
+    /** Email + SMS template CRUD (managed-runtime). */
+    templates: PalbaseTemplatesClient;
+    /** Register a device for push notifications. */
+    registerDevice(params: PalbaseRegisterDeviceParams): Promise<PalbaseResult<PalbaseDeviceTokenView>>;
+    /** Remove a device registration. */
+    unregisterDevice(deviceId: string): Promise<PalbaseResult<void>>;
+}
+/**
+ * Analytics query namespace (read-side endpoints).
+ */
+interface PalbaseAnalyticsQueryNamespace {
+    /** Count events over time. */
+    count(input: PalbaseCountQueryInput): Promise<PalbaseResult<PalbaseCountResult>>;
+    /** List raw events. */
+    events(input: PalbaseEventsQueryInput): Promise<PalbaseResult<PalbaseEventsResult>>;
+    /** List event property descriptors. */
+    properties(input?: PalbasePropertiesQueryInput): Promise<PalbaseResult<PalbasePropertyDescriptor[]>>;
+    /** Query users by filters. */
+    users(input: PalbaseUsersQueryInput): Promise<PalbaseResult<PalbaseUsersResult>>;
+    /** Run a funnel query. */
+    funnel(input: PalbaseFunnelQueryInput): Promise<PalbaseResult<PalbaseFunnelResult>>;
+    /** Run a retention query. */
+    retention(input: PalbaseRetentionQueryInput): Promise<PalbaseResult<PalbaseRetentionResult>>;
+    /** Run a cohort query. */
+    cohort(input: PalbaseCohortQueryInput): Promise<PalbaseResult<PalbaseCohortResult>>;
+}
+/**
+ * Analytics management namespace (meta-level endpoints).
+ */
+interface PalbaseAnalyticsManagementNamespace {
+    /** Get project-level overview stats. */
+    overview(): Promise<PalbaseResult<PalbaseOverviewResult>>;
+    /** Get all event names seen by the project. */
+    eventNames(): Promise<PalbaseResult<PalbaseEventNamesResult>>;
+    /** Get details for a specific user. */
+    userDetail(distinctId: string): Promise<PalbaseResult<PalbaseUserDetailResult>>;
+    /** Delete all data for a user (GDPR erasure). */
+    deleteUser(distinctId: string): Promise<PalbaseResult<void>>;
+}
+/**
+ * Analytics client available on `ctx.analytics`.
+ * Capture events server-side and run analytical queries.
+ */
+interface PalbaseAnalyticsClient {
+    /** Capture a custom event. */
+    capture(event: string, properties?: PalbaseAnalyticsProperties, distinctId?: string): Promise<PalbaseResult<void>>;
+    /** Identify a user with traits. */
+    identify(distinctId: string, traits?: PalbaseIdentifyTraits): Promise<PalbaseResult<void>>;
+    /** Track a screen view. */
+    screen(screenName: string, properties?: PalbaseAnalyticsProperties, distinctId?: string): Promise<PalbaseResult<void>>;
+    /** Query namespace for analytics read operations. */
+    query: PalbaseAnalyticsQueryNamespace;
+    /** Management namespace for meta-level operations. */
+    management: PalbaseAnalyticsManagementNamespace;
+}
+/**
+ * Deep-links client available on `ctx.links`.
+ * Create, manage, and resolve deep links from server endpoints.
+ * Omits `getInitialLink()` (client SDK convenience — browser/app only).
+ */
+interface PalbaseLinksClient {
+    /** Create a short link. */
+    create(params: PalbaseCreateLinkParams): Promise<PalbaseResult<PalbaseLink>>;
+    /** List links (paginated). */
+    list(options?: PalbaseListLinksOptions): Promise<PalbaseResult<PalbaseListLinksResult>>;
+    /** Get link details + analytics summary. */
+    get(linkId: string): Promise<PalbaseResult<PalbaseLinkDetails>>;
+    /** Update a link. */
+    update(linkId: string, params: PalbaseUpdateLinkParams): Promise<PalbaseResult<PalbaseLink>>;
+    /** Delete a link. */
+    delete(linkId: string): Promise<PalbaseResult<{
+        success: boolean;
+    }>>;
+    /** Get click analytics for a link. */
+    analytics(linkId: string): Promise<PalbaseResult<PalbaseLinkAnalytics>>;
+    /** Generate a QR code for a link (returns PNG or SVG Blob). */
+    qrCode(linkId: string, options?: PalbaseQrCodeOptions): Promise<PalbaseResult<Blob>>;
+    /** Match a deferred deep link by device fingerprint. */
+    match(params: PalbaseMatchParams): Promise<PalbaseResult<PalbaseInitialLink | null>>;
+}
+
+/**
+ * runtime.ts — request-scoped service singletons.
+ *
+ * The backend SDK no longer threads a `ctx` god-object through every handler.
+ * Instead, controller methods import PascalCase service singletons directly:
+ *
+ *   import { Controller, Post, Body, Database } from "@palbase/backend";
+ *
+ *   \@Controller("/todos")
+ *   export default class TodosController {
+ *     \@Post("") create(\@Body(CreateTodoBody) body: CreateTodoBody): unknown {
+ *       return Database.insert("todos", { title: body.title });
+ *     }
+ *   }
+ *
+ * The singletons are thin Proxies. Every property access forwards to the live
+ * client for the CURRENT request scope, resolved through {@link __getRuntime}.
+ *
+ * # Request-scope resolution (persistent app-server)
+ *
+ * The runtime is a long-running Node process that serves many concurrent
+ * requests on one event loop (NOT a fresh subprocess per request). A single
+ * module-global slot would let one in-flight request's services bleed into
+ * another's. So the services are carried in an {@link AsyncLocalStorage} store
+ * ({@link __requestALS}) that the runtime sets per request with
+ * {@link __runWithRuntime}; every async continuation of that request reads its
+ * own store. `__getRuntime` reads the ALS store first; the module-global slot
+ * (set by {@link __setRuntime}) is only a fallback for callers that run OUTSIDE
+ * an ALS scope (dev-server, unit tests, the legacy single-shot path). Because
+ * each `br-<ref>` pod is single-tenant, there is no cross-tenant leakage; the
+ * ALS store is what prevents cross-REQUEST leakage within the shared process.
+ *
+ * The seam that makes `import { Database } from "@palbase/backend"` resolve to
+ * the runtime-injected client: `@palbase/backend` is marked esbuild-EXTERNAL
+ * when the tenant bundle is built, and the package is installed globally in the
+ * pod (NODE_PATH=/usr/local/lib/node_modules). So worker.js's
+ * `require('@palbase/backend')` and the bundle's `import` resolve to ONE shared
+ * module instance — the ALS store and `__setRuntime` slot on that instance are
+ * visible to the singletons the bundle imported.
+ */
+
+/** The set of live clients the runtime injects per request scope.
+ *
+ * Realtime is BROADCAST-ONLY here (a stateless handler can push an event but
+ * cannot hold a subscription socket — `subscribe()` lives on the client SDK).
+ *
+ * EXCLUDED on purpose: Functions, Links, Analytics, Auth. They are not
+ * exposed as backend handler singletons (auth lives on the client SDK; the rest
+ * are out of scope for backend endpoints). */
+interface RuntimeServices {
+    Database: DBClient;
+    Secrets: SecretsService;
+    Documents: PalbaseDocsClient;
+    Storage: PalbaseStorageClient;
+    Cache: CacheClient;
+    Log: Logger;
+    Notifications: PalbaseNotificationsClient;
+    Flags: PalbaseFlagsClient;
+    Realtime: PalbaseRealtimeClient;
+}
+/**
+ * The per-request ALS box.
+ *
+ * `runtime` is the service bundle. `userId` is the request's authenticated user
+ * id, written by the runtime immediately after it assembles the request object
+ * (worker.js: `requestALS.getStore().userId = pbReq.user?.id || null`) and
+ * `null` on an anonymous request. It was already being written there for the
+ * Flags client's auto-bind; declaring it here makes the existing contract typed
+ * instead of implicit, which is what lets `currentSubjectId()` read a
+ * server-owned identity rather than trusting anything the caller sent.
+ */
+interface RequestStore {
+    runtime: RuntimeServices;
+    userId?: string | null;
+    /** This request's id (`req_…`), written by the runtime. Used as the spend
+     * idempotency scope when the caller supplied no `Idempotency-Key`. */
+    requestId?: string;
+    /** The caller's `Idempotency-Key` header, or `null` when absent. What makes a
+     * client's retry replay its first result instead of charging twice. */
+    idempotencyKey?: string | null;
+}
+/**
+ * Per-request store. The persistent runtime runs each request inside
+ * {@link __runWithRuntime}, so every async continuation of that request reads
+ * its OWN `runtime` (and any other request-scoped fields the runtime adds).
+ *
+ * Exported with a `__` prefix so the runtime (worker.js) shares the SAME ALS
+ * instance across the one module instance — two ALS instances would silently
+ * not see each other's stores. NOT part of the public author-facing API.
+ */
+declare const __requestALS: AsyncLocalStorage<RequestStore>;
+/** Install the live clients in the process-global fallback slot.
+ *
+ * Persistent-server requests should use {@link __runWithRuntime} instead; this
+ * remains for dev-server / tests / the legacy single-shot path that run without
+ * an ALS scope. NOT part of the public author-facing API. */
+declare function __setRuntime(services: RuntimeServices): void;
+/** Run `fn` with `services` bound as the request-scoped runtime.
+ *
+ * The persistent worker calls this once per request so concurrent requests
+ * never share a services slot. NOT part of the public author-facing API. */
+declare function __runWithRuntime<T>(services: RuntimeServices, fn: () => T): T;
+/** Read the live clients, throwing if accessed outside a request scope.
+ *
+ * Resolves the ALS store first (persistent server, per-request), then the
+ * process-global fallback (dev-server / tests). NOT part of the public
+ * author-facing API — used by the runtime and the singleton Proxies. */
+declare function __getRuntime(): RuntimeServices;
+/** A lifecycle hook. Sync or async; the runtime awaits what it returns. */
+type LifecycleHook = () => void | Promise<void>;
+/** Runs one release's shutdown hooks. Handed back by {@link __runStartHooks}
+ * and called by the engine's `app.shutdown()`. Idempotent. */
+type ShutdownRunner = () => Promise<void>;
+/**
+ * Run `hook` ONCE while the application comes up, before it serves anything.
+ *
+ * Call it at MODULE SCOPE in a file the application imports — the same rule
+ * `defineDefaultAuth` and `@Controller` follow, and for the same reason: the
+ * declaration is claimed when the app boots, which is after module loading and
+ * before the first request. `name` is not decoration: a hook that throws is
+ * reported by that name and the boot is REFUSED, so it is what tells an
+ * operator which resource did not come up.
+ *
+ * There is no request scope yet, so the `Database`/`Secrets`/… singletons are
+ * NOT available inside a start hook. A secret is read from `process.env` here
+ * (the runtime mirrors the vault into it at boot).
+ *
+ * @example
+ * // resources/graph.ts
+ * import neo4j from "neo4j-driver";
+ * import { onStart, onShutdown } from "@palbase/backend";
+ *
+ * export let graph: Driver;
+ * onStart("graph", () => {
+ *   graph = neo4j.driver(process.env.NEO4J_URL!, neo4j.auth.basic("neo4j", process.env.NEO4J_PASSWORD!));
+ * });
+ * onShutdown("graph", () => graph.close());
+ */
+declare function onStart(name: string, hook: LifecycleHook): void;
+/**
+ * Run `hook` while the application shuts down — the place a pool opened in
+ * {@link onStart} is closed.
+ *
+ * Shutdown is BEST-EFFORT by design: a hook that throws is reported by name and
+ * the rest still run. A drain that abandoned the remaining hooks on the first
+ * failure would leak exactly what this exists to release, and the process is
+ * leaving anyway.
+ *
+ * Hooks run in REVERSE declaration order, so a resource is released before what
+ * it was built on.
+ */
+declare function onShutdown(name: string, hook: LifecycleHook): void;
+/**
+ * CLAIM what has been declared, run the start hooks, and hand back the runner
+ * for this release's shutdown hooks. Called by the engine's `createApp`; the
+ * `App.shutdown()` it builds calls what comes back. NOT part of the public
+ * author-facing API.
+ *
+ * IT CLAIMS RATHER THAN READS, which is what makes it correct in this runtime:
+ * a candidate release is loaded BESIDE the live one in one process
+ * (`v2/runtime/src/registry-scope.ts`), and both bundles append to the one
+ * shared slot above. If each app read the whole list, the live app's shutdown
+ * would close the candidate's pool and the candidate's would close the live
+ * app's. Taking the declarations leaves each app holding exactly its own.
+ *
+ * A start hook that throws REFUSES THE BOOT — with the hook's name in the
+ * message — after releasing whatever the earlier hooks already opened. Serving
+ * from a half-initialised app is the silence this whole surface replaces, and a
+ * boot that dies holding an open pool is the leak it replaces.
+ */
+declare function __runStartHooks(): Promise<ShutdownRunner>;
+/** Drop every declaration. For tests, which declare repeatedly in one process.
+ * NOT part of the public author-facing API. */
+declare function __resetLifecycleHooks(): void;
+/**
+ * Build the `.tables` accessor for the top-level `Database`. Each
+ * `tables.<name>` access returns a small object that forwards the five CRUD ops
+ * to the underlying client using `name` as the string table identifier. The
+ * shapes are typed against the generated `palbase-env.d.ts` (`EnvTables`); at
+ * runtime they are plain string-keyed calls, so no schema value is needed here.
+ *
+ * Returns `EnvTables` — TS cannot infer the mapped type through the Proxy, so
+ * a single structural narrowing names the surface (the proxy returns a
+ * correctly-shaped accessor for whatever string member is read).
+ */
+/** T018 (C-8): similar/recommend'in string-keyed yüzü. DBOps'a (endpoint.ts)
+ * BİLEREK eklenmedi — search-param imza üçlüsü (engine/db + typed-db +
+ * endpoint) büyümesin: proxy dispatch runtime'da engine ops'una zaten ulaşır,
+ * derleme güvenliğini typed yüzey (EnvTypedTable) verir. */
+interface RecoOps {
+    similar(table: string, id: string, params?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    recommend(table: string, params: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+}
+/**
+ * The project's own Postgres (pgx, schema `env_<envId>`).
+ *
+ * Typed by default: `Database.tables.<name>.insert({...})` is typed against
+ * the project's generated `palbase-env.d.ts` with NO import and NO generic.
+ * The raw string ops (`query`/`insert`/`update`/`delete`/`findById`/`findMany`)
+ * are also available for dynamic table names and read-only SQL.
+ *
+ * RLS is enforced by default (the runtime runs each op as `authenticated` with
+ * the verified user's claims). To bypass RLS, call `Database.asService()` —
+ * explicit and greppable — which runs as the `service_role` (BYPASSRLS).
+ *
+ * @example
+ * import { Database } from "@palbase/backend";
+ *
+ * const todo = await Database.public.todos.insert({ title: req.input.title });
+ * todo.id; // string ✓
+ * const rows = await Database.$query("SELECT id FROM todos WHERE done = $1", [false]);
+ * const all  = await Database.$asService().public.todos.findMany({}); // RLS bypass
+ */
+declare const Database: EnvTypedDatabase;
+/** Firestore-like document client (PalDocs). */
+declare const Documents: PalbaseDocsClient;
+/**
+ * `buckets.<name>` — the storage twin of `Database.tables.<name>`, and the same
+ * mechanism: `config/storage.ts` generates a `Buckets` augmentation into
+ * `palbase-env.d.ts`, so a bucket name is a property with no import and no
+ * generic, and a typo is a compile error.
+ *
+ * The intermediate `.buckets` is there for the reason `.tables` is: bucket
+ * names must not share a namespace with the client's own methods, or the day
+ * somebody declares a bucket called `bucket` the surface breaks.
+ */
+type EnvBuckets = {
+    [K in keyof Buckets]: TypedBucketClient<Buckets[K] extends BucketTypes ? Buckets[K] : BucketTypes>;
+};
+/** One bucket, with its declared variant names in the type. */
+interface TypedBucketClient<B extends BucketTypes> extends Omit<PalbaseBucketClient, "getPublicUrl"> {
+    /** The public URL for the object, or for one of THIS bucket's declared
+     * renditions. A name the bucket does not declare is a compile error. */
+    getPublicUrl(path: string, options?: {
+        variant?: B["variants"];
+    }): string;
+}
+/**
+ * Object storage: buckets, objects, renditions and signed URLs.
+ *
+ * `Storage.buckets.posts.upload(...)` is the typed path. `Storage.bucket(name)`
+ * remains for a name computed at runtime — rare, and it gives up the typing,
+ * which is the honest trade rather than a second blessed way to do it.
+ */
+declare const Storage: PalbaseStorageClient & {
+    buckets: EnvBuckets;
+};
+/** JSON-typed cache (get/set/incr/getOrSet). */
+declare const Cache: CacheClient;
+/**
+ * This tenant's secrets — API keys, provider credentials, signing material the
+ * BACKEND owns.
+ *
+ * `await Secrets.get("STRIPE_KEY")` in a handler. There is no `.env` to read
+ * and no file to mount: a secret is written through the vault's authenticated
+ * API (or the CLI/MCP that calls it), and this is how the deployed code reads
+ * it back. A name this tenant has not set answers null — as does every name
+ * the STACK holds, because no route returns a platform secret's value at all.
+ */
+declare const Secrets: SecretsService;
+/** Structured logger. */
+declare const Log: Logger;
+/** Push / email / SMS / in-app notifications. */
+declare const Notifications: PalbaseNotificationsClient;
+/**
+ * Feature flags.
+ *
+ * Mirrors the `Database` / `Database.asService()` model. The default surface is
+ * RLS-equivalent for flags: reads resolve against the CURRENT request user and
+ * `Flags.setOverride(key, value)` writes an override for that same signed-in
+ * user (no userId argument, no admin power). Cross-user admin writes
+ * (`setOverrideForUser`, …) live behind `Flags.asService()` — explicit and
+ * greppable, just like `Database.asService()`.
+ *
+ * @example
+ * import { Flags } from "@palbase/backend";
+ *
+ * if (await Flags.isEnabled("new_checkout")) { ... }            // current user
+ * await Flags.setOverride("new_checkout", true);                // current user
+ * await Flags.asService().setOverrideForUser("u_9", "x", true); // cross-user
+ */
+declare const Flags: PalbaseFlagsClient;
+/**
+ * The Realtime broadcast singleton for the current request scope. Backend-side
+ * Realtime is BROADCAST-ONLY (a stateless handler can push but not subscribe —
+ * `subscribe()` lives on the client SDK's `pb.realtime`). Fire-and-forget:
+ * `broadcast` resolves once accepted (or with an `error`), never blocking the
+ * handler on subscribers.
+ *
+ * @example
+ * import { Realtime } from "@palbase/backend";
+ *
+ * await Realtime.broadcast("room:42", "message", { text, from: user.id });
+ */
+declare const Realtime: PalbaseRealtimeClient;
+
+/**
+ * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.
+ *
+ * Derives INSERT and full-row TypeScript types from a `defineSchema()` result
+ * and wraps the untyped runtime `DBClient` with a typed facade.
+ *
+ * No value-any. No `as unknown as X`. The two narrow `as` casts in
+ * `makeTypedTable` are safe because:
+ *  - `data as Record<string, unknown>`: InsertShape<T> maps string keys to
+ *    typed values; all value types are subsets of `unknown`, so the cast is
+ *    structurally sound.
+ *  - `result as RowShape<T>`: The runtime DBClient returns `Record<string,
+ *    unknown>` which is the erased form of the typed row; we're narrowing back
+ *    to the precise shape that the schema declared.
+ * Both casts are narrowing only (not widening) and correctness is guaranteed
+ * by the schema the caller provides.
+ */
+
+/** Keys of C whose columns are required on INSERT (not nullable, no default). */
+type RequiredKeys<C> = {
+    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? never : K;
+}[keyof C];
+/** Keys of C whose columns are optional on INSERT (nullable or has a default). */
+type OptionalKeys<C> = {
+    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? K : never;
+}[keyof C];
+/**
+ * The TypeScript type for an INSERT payload for table `T`.
+ * - Required: columns that are NOT NULL and have no DB-level default.
+ * - Optional: columns that are nullable or carry a default.
+ *
+ * When all columns are optional, `RequiredKeys<C>` resolves to `never` and
+ * the first part becomes `{}`, which is a neutral element for `&`.
+ */
+type InsertShape<T extends TableDef> = {
+    [K in RequiredKeys<T["columns"]>]: ColValue<T["columns"][K]>;
+} & {
+    [K in OptionalKeys<T["columns"]>]?: ColValue<T["columns"][K]>;
+};
+/**
+ * The TypeScript type for a full row returned by the DB for table `T`.
+ * Every column is present; nullable columns resolve to `T | null`.
+ */
+type RowShape<T extends TableDef> = {
+    [K in keyof T["columns"]]: ColValue<T["columns"][K]>;
+};
+/** A typed table accessor that mirrors the runtime DBClient surface. */
+interface TypedTable<T extends TableDef> {
+    insert(data: InsertShape<T>): Promise<RowShape<T>>;
+    put(q: {
+        data: InsertShape<T>;
+        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. */
+    update(q: {
+        where: {
+            id: string;
+        };
+        set: Partial<InsertShape<T>>;
+    }): Promise<RowShape<T> | null>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<RowShape<T> | null>;
+    /** Rows matching the filter. Operators, ordering and paging are the ENGINE's
+     * surface — this declaration is what makes them callable. */
+    findMany<K extends keyof RowShape<T> = keyof RowShape<T>>(q?: QueryInput<RowShape<T>, K>): Promise<Pick<RowShape<T>, K>[]>;
+    /**
+     * Update every matching row in one statement; an empty filter is refused.
+     *
+     * **0 satır dönmesi hata DEĞİL, başarı da değil** (FR-014): koşulu `where`'e
+     * koyup dönen diziyi kontrol etmek, "önce oku sonra yaz"ın yarış koşulu
+     * olmayan hâlidir.
+     *
+     * ```ts
+     * const [row] = await Database.public.accounts.updateMany({
+     *   where: { id, balance: { gte: amount } },
+     *   set: { balance: decrement(amount) },
+     * });
+     * if (row === undefined) throw new Conflict("yetersiz bakiye");
+     * ```
+     */
+    updateMany(q: MutateInput<RowShape<T>, InsertShape<T>>): Promise<RowShape<T>[]>;
+    /** Delete every matching row; resolves to how many. Empty filter refused. */
+    deleteMany(q: {
+        where: WhereFilter<RowShape<T>> | SqlFragment;
+    }): Promise<number>;
+    /** How many rows match. An empty filter is legitimate: counting is a read. */
+    count(q?: {
+        where?: WhereFilter<RowShape<T>> | SqlFragment;
+    }): Promise<number>;
+}
+/** A typed DB facade covering all tables declared in schema `S`. */
+interface TypedDB<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.
+ *
+ * YALNIZ `tables`, ve ÇALIŞMA ZAMANI DA yalnız onu veriyor.
+ *
+ * Bir süre runtime `{ tables, public }` döndürüyordu ama tip yalnız `tables`
+ * söylüyordu: `tx.public.x` derlenmiyor, koşsaydı çalışacaktı — tipin çalışma
+ * zamanından AZ söylemesi (gözcü M-8). Tipe `public` EKLEMEK yanlış düzeltmeydi
+ * ve `check:api` onu adıyla reddetti: `TypedTx` dışa açık, ve zorunlu bir üye
+ * eklemek onu İNŞA EDEN müşterinin kodunu kırar — "the new shape demands more
+ * than the recorded one". Yalan runtime'dan kaldırılarak kapatıldı; ikisi artık
+ * aynı şeyi söylüyor. `Database.$transaction`'ın `tx.public`'i ayrı bir yüzey
+ * (`TxPlan`) ve orada tip de runtime da onu taşıyor. */
+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 for the direct ops — all calls
+ * delegate to `raw` with the table name as a plain string.
+ *
+ * `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.
+ *
+ * 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>;
+/** Bir where değeri: düz eşitlik YA DA operatör nesnesi (FR-016). */
+/**
+ * Metin operatörleri YALNIZ metin kolonlarında görünür (FR-005).
+ *
+ * `contains` bir sayı kolonunda anlamsızdır ve onu tipte sunmak "ifade edilemez
+ * kıl" ilkesinin tersidir: derleme anında yakalanabilecek bir hata çalışma
+ * zamanına ertelenir. Koşullu tip ÖZYİNELEMESİZDİR (N-2).
+ */
+/**
+ * Bir KOLONA yapılan referans (FR-011) — karşılaştırmanın sağ tarafında değer
+ * yerine durabilen tek şey.
+ *
+ * Şekli okunabilir (`{ $col: "…" }`) ama KİMLİĞİ şekli değil: nesne
+ * `Symbol.for("palbase.db.ref")` ile markalanır. Şekil tek başına yetseydi
+ * güvenilmeyen bir istek gövdesi `{"$col":"tenant_id"}` gönderip kiracılık
+ * predikatını `t."tenant_id" = t."tenant_id"` totolojisine çevirebilirdi —
+ * ölçüldü (W2-A/C1). Marka enumerable olmadığı için JSON round-trip'i onu
+ * düşürür; süreç içinde (transaction planı dahil) korunur.
+ */
+type ColRef<N extends string = string> = {
+    readonly $col: N;
+};
+
+/**
+ * `total > amount_paid` — bugün bunu yazmanın tek yolu ham SQL'e düşmekti,
+ * çünkü sağ taraf bir DEĞER değil.
+ *
+ * Ad literal olarak yakalanır (`const N`), ve doğruluğu ÇAĞRIDA değil
+ * KULLANIM YERİNDE kanıtlanır: filtre `WhereFilter<Row>` beklediği için
+ * `ColRef<"yok_boyle">` oraya atanamaz. Yani `col()`'a satır tipini elle
+ * vermek gerekmiyor, yanlış ad yine de derleme hatası (P5).
+ *
+ * Dönen nesne MARKALIDIR (`brandRef`): telden gelen `{"$col":"x"}` bir kolon
+ * referansı SAYILMAZ, "bilinmeyen operatör" diye reddedilir. Gerekçe
+ * `db/input-guards.ts`'te ölçümüyle birlikte yazılı.
+ */
+declare function col<const N extends string>(name: N): ColRef<N>;
+/** Bu satırın kolonlarından birine referans. `Row` bilinmiyorsa hiçbiri. */
+/**
+ * Bir kolonun karşılaştırma AİLESİ — ve neden PG tipi değil de bu.
+ *
+ * ÖLÇÜLDÜ (gözcü, canlı pg16): TS tarafı PG tipini TAŞIMIYOR. `numeric`,
+ * `bigint`, `text`, `uuid` ve `timestamp` hepsi `string`'e, `integer` `number`'a
+ * düşüyor (`env-gen.ts:30-60`). Bu yüzden TS tipine kurulan HİÇBİR kural doğru
+ * olamaz — kural ne olursa olsun bir taraf yanlışa düşer:
+ *
+ *   { qty: { gt: col("amount") } }   integer ↔ numeric   PG: GEÇERLİ
+ *   { total: { gt: col("note") } }   integer ↔ text      PG: GEÇERSİZ
+ *
+ * İkisi de TS'te "number ↔ string". Ayırt edecek bilgi tipte YOK.
+ *
+ * YANLIŞ RET, YANLIŞ KABULDEN KÖTÜDÜR — ve tercih buna göre yapıldı. Yanlış bir
+ * ret meşru bir sorguyu İFADE EDİLEMEZ kılar, yani yazarı `$query`'ye düşürür:
+ * bu yüzeyin kapatmak için var olduğu şey. Yanlış bir kabul ise Postgres'in
+ * GÜRÜLTÜLÜ hatasına çıkar (`operator does not exist: integer > text`) — kötü
+ * ama sessiz değil.
+ *
+ * O yüzden aile ayrımı yalnız TS'in GERÇEKTEN ayırdığı yerlerde yapılıyor:
+ * `boolean`, vektör dizisi ve `Date` kendi başlarına; metin ve sayı ise TEK
+ * ailede, çünkü aralarındaki PG ayrımı tipte yok.
+ *
+ * KALICI ÇÖZÜM tipte değil ÜRETİMDE: `env-gen` kolon başına bir PG-tip markası
+ * bassın (`string & { readonly __pg?: "numeric" }`). O zaman `numeric ↔ integer`
+ * kabul, `numeric ↔ text` ret olur ve ikisi de DOĞRU olur. Defterde teklif.
+ */
+type PgFamily<V> = [NonNullable<V>] extends [boolean] ? "bool" : [NonNullable<V>] extends [readonly (number | string)[]] ? "array" : [NonNullable<V>] extends [Date] ? "date" : [NonNullable<V>] extends [string | number] ? "scalar" : "opaque";
+/** `Row`'un `V` ile karşılaştırılabilir kolonları — aynı aileden olanlar. */
+type ColumnsComparableTo<Row, V> = {
+    [K in keyof Row]-?: PgFamily<Row[K]> extends PgFamily<V> ? K : never;
+}[keyof Row];
+/**
+ * Bu satırın kolonlarından birine referans. `Row` bilinmiyorsa hiçbiri.
+ *
+ * İKİNCİ PARAMETRE kolonun tipi. Verilmezse (`unknown`) KISIT YOKTUR — bu
+ * `findMany`'nin `Row`'u bilmediği yolların ve jsonb kolonlarının hâli, ve
+ * ikisinde de tipin söyleyebileceği bir şey yok.
+ */
+type ColRefOf<Row, V = unknown> = [keyof Row] extends [never] ? never : [unknown] extends [V] ? ColRef<Extract<keyof Row, string>> : ColRef<Extract<ColumnsComparableTo<Row, V>, string>>;
+/**
+ * Doğrulanmış, GÖMÜLEBİLİR bir SQL parçası (FR-018, FR-019).
+ *
+ * Wire şekli `{ $sql: { text, values } }`: `text` parçalar hâlinde tutulur ve
+ * değerler ARADA durur, çünkü birleştirilmiş tek bir string'in içinden hangi
+ * kısmın kullanıcı verisi olduğunu bir daha kimse çıkaramaz — enjeksiyonun
+ * doğduğu yer tam olarak orasıdır.
+ */
+type SqlFragment = {
+    readonly $sql: {
+        readonly text: readonly string[];
+        readonly values: readonly unknown[];
+    };
+};
+/**
+ * Retryable bir hatada işlemi yeniden dener (FR-037).
+ *
+ * D-016: retry'SIZ bir izolasyon yükseltmesi sunmak defect'tir — kullanıcıya
+ * çalışmayan bir düğme vermektir. `SerializationFailure`'ın metni
+ * *"{ retry: n } verebilirsiniz"* diyor; bu fonksiyon o düğmenin gerçekten
+ * çalışan yarısı.
+ *
+ * VARSAYILAN SIFIR. Sessiz bir varsayılan retry, idempotent OLMAYAN bir işlemi
+ * çağıranın haberi olmadan iki kez çalıştırırdı — bir para transferini iki kez.
+ * Tekrar denemek çağıranın kararı.
+ *
+ * Yalnız `isRetryable(e)` olan hatalar tekrarlanır. Küme dar tutuluyor: `23505`
+ * buraya girseydi tekrar denemek aynı cevabı verir ve döngü boşuna dönerdi.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, opts?: {
+    retry?: number;
+}): Promise<T>;
+/**
+ * K3: sorgudan KAÇMAK için değil, sorgunun İÇİNE girmek için kaçış kapağı.
+ *
+ * ```ts
+ * Database.public.notes.findMany({
+ *   where: sqlFragment`similarity(title, ${q}) > 0.3`,
+ *   orderBy: { column: "created_at", direction: "desc" },
+ *   limit: 20,
+ * })
+ * ```
+ *
+ * `select` / `orderBy` / `limit` / RLS aynen çalışmaya devam eder — "yetmedi,
+ * ham SQL'e geçeyim" anının bugünkü maliyeti tam olarak bunları kaybetmekti.
+ *
+ * TANIMLAYICI GÖMME YÜZEYİ YOK (`.raw` / `.unsafe` / `.identifier`). Drizzle'ın
+ * CVE-2026-39356'sı ve Knex'in CVE-2019-10757'si tam o kapakta doğdu.
+ *
+ * Ve kapak fonksiyonun ÜSTÜNDE olmakla bitmiyordu: parça MARKALI değilken
+ * `{"$sql":{"text":["1=1 -- pwned"],"values":[]}}` düz JSON'dan uydurulup
+ * guard'ın tamamını atlıyordu (W2-B/C3, ölçüldü). Marka o kapağı wire ŞEKLİNE
+ * de koyuyor — parça yalnız bu template tag'inden çıkabilir.
+ */
+declare function sqlFragment(strings: TemplateStringsArray, ...values: unknown[]): SqlFragment;
+type TextOps<V> = V extends string ? {
+    contains?: string;
+    icontains?: string;
+    startsWith?: string;
+    endsWith?: string;
+} : Record<never, never>;
+/** Operatör gövdesi, kolon-referans tipi DIŞARIDAN verilmiş hâliyle.
+ *
+ * `C` bir parametre, çünkü `ColRefOf<Row, V>` aksi hâlde altı operatör
+ * konumunda AYRI AYRI instantiate edilirdi — kolon başına altı mapped type.
+ * Böyle kolon başına BİR tane (N-2). */
+type WhereOpBody<V, C> = {
+    gt?: V | C;
+    gte?: V | C;
+    lt?: V | C;
+    lte?: V | C;
+    neq?: V | C;
+    in?: V[];
+    /** `IS NULL` / `IS NOT NULL` (FR-006) — `= NULL` SQL'de her zaman UNKNOWN'dır. */
+    isNull?: boolean;
+} & TextOps<V>;
+type WhereOp<V, Row = unknown> = WhereOpWith<V, ColRefOf<Row, V>>;
+/**
+ * Operatör sözlüğü, kolon-referans/plan-tutamağı konumu DIŞARIDAN verilmiş.
+ *
+ * `export`, çünkü plan yüzeyi (`tx-plan.ts`) aynı sözlüğü `C = ColRefOf<…> |
+ * Ref<…>` ile kuruyor: bir plan filtresi ÖNCEKİ bir işlemin sonucuna
+ * bakabiliyor, `findMany` bakamıyor. Ref'i `V`'ye eklemek YANLIŞ olurdu —
+ * `TextOps<V>` `V extends string` diye soruyor ve `string | Ref<string>` o
+ * soruya HAYIR der, yani `contains`/`startsWith` sessizce KAYBOLURDU.
+ */
+type WhereOpWith<V, C> = V | C | WhereOpBody<V, C>;
+/**
+ * A filter over a row: every field optional, each one a plain value (equality)
+ * or an operator object. THE filter language — `findMany`, `updateMany`,
+ * `deleteMany` and `count` all take this one, because two spellings of a filter
+ * is how the two come to disagree.
+ */
+type WhereFilter<Row> = {
+    [K in keyof Row]?: WhereOp<Row[K], Row>;
+} & {
+    /**
+     * Boolean bileşimi (FR-007). Dallar aynı filtre dilidir — iki yazım olmaz.
+     *
+     * ÖZYİNELEME BURADA BAŞLIYOR ve N-2'nin izlediği şey tam olarak budur:
+     * Kysely'nin TS7'de 9,8M instantiation üreten vakası derin generic
+     * özyinelemeydi. Burada derinlik yazarın filtresi kadardır ve pratikte
+     * bir-iki seviyedir; tip maliyeti T001'in tavanına karşı ölçülür.
+     */
+    OR?: WhereFilter<Row>[];
+    AND?: WhereFilter<Row>[];
+    NOT?: WhereFilter<Row>;
+};
+/**
+ * Ordering and paging for a read.
+ *
+ * `column` is `keyof Row`, not `string`: a mistyped column name is a compile
+ * error here rather than a runtime rejection three layers down. `offset`
+ * without `limit` is refused by the engine — a page with no size is not a page.
+ */
+type OrderBySpec<Row> = {
+    column: Extract<keyof Row, string>;
+    direction?: "asc" | "desc";
+    /** NULL'ların yeri (FR-008). Verilmezse Postgres varsayılanı geçerlidir ve o
+     * varsayılan YÖNE GÖRE DEĞİŞİR: ASC'de NULLS LAST, DESC'te NULLS FIRST. */
+    nulls?: "first" | "last";
+};
+type FindManyOpts<Row> = {
+    /** Tek sıralama ya da SIRALI liste — sıra korunur (FR-008). */
+    orderBy?: OrderBySpec<Row> | OrderBySpec<Row>[];
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Bir okumanın TEK parametresi (FR-004b).
+ *
+ * `where` bir ALAN, konumsal bir argüman değil. Kullanıcının kararı: "deterministik
+ * olması lazım, tek düzlem" — aynı bilginin iki yere dağılması, alanlar çoğaldıkça
+ * (select/include/orderBy) "hangisi nereye" sorusunu ezberlenecek bir şeye çevirir.
+ * Prisma ve Drizzle de tek obje kullanıyor. Bedeli açık ve kabul edildi: en sık
+ * kullanım uzuyor — `findMany({ where: { owner: uid } })`.
+ *
+ * ÖZYİNELEMESİZ kalmak zorunda (N-2): tip maliyeti şekilden değil özyineleme
+ * derinliğinden geliyor (Kysely'nin TS7'de 9,8M instantiation vakası).
+ */
+/**
+ * `has` — İLİŞKİ ÜZERİNDEN SÜZME, JOIN'in ihtiyaç duyulmayan hâli.
+ *
+ * ```ts
+ * Database.public.interests.findMany({
+ *   where: { has: { user_interests: { user_id: uid } } },
+ *   orderBy: [{ column: "sort_order" }, { column: "name" }],
+ * })
+ * ```
+ * →  `… WHERE t."id" IN (SELECT r1."interest_id" FROM "user_interests" r1
+ *                        WHERE r1."user_id" = $1)`
+ *
+ * İlişki ADLARI ve gittikleri kolonlar `palbase-env.d.ts`'in ZATEN bastığı
+ * `relations` bloğundan geliyor — yabancı anahtarlardan türetiliyorlar, yazar
+ * hiçbir kolon adı yazmıyor. O blok üretiliyordu ve HİÇBİR okuma onu
+ * kullanmıyordu; `has` onun karşılığı.
+ *
+ * İç filtre AYNI dil: bir tablo ötesinde de `gt`, `icontains`, `OR`, ve iç içe
+ * `has` yazılabiliyor.
+ */
+/**
+ * İlişkinin HEDEF TABLOSU — anahtar ŞEMA NİTELİKLİ gelir.
+ *
+ * `buildRelations` `to`'yu `qualifiedTableKey` ile yazıyor: public için düz ad
+ * (`"interests"`), başka şema için noktalı (`"billing.invoices"`). `Tables`
+ * yalnız public'i taşır, diğerleri `Schemas`'tadır — noktalı anahtarı doğrudan
+ * `Tables`'ta aramak HER ZAMAN ıskalar ve iç filtre sessizce `Record<string,
+ * unknown>`'a düşerdi: bilinmeyen kolon da, yanlış tip de derlenirdi (ölçüldü).
+ */
+type RelatedTable<To> = To extends `${infer S}.${infer T}` ? S extends keyof Schemas ? T extends keyof Schemas[S] ? Schemas[S][T] : never : never : To extends keyof Tables ? Tables[To] : never;
+type RelatedRow<To> = RelatedTable<To> extends {
+    row: infer R;
+} ? R : Record<string, unknown>;
+type RelatedRels<To> = RelatedTable<To> extends {
+    relations: infer R;
+} ? R : unknown;
+/**
+ * İç içe `has` ÜÇ seviyeyle sınırlı.
+ *
+ * Üretilen `relations` bloğu ÇİFT YÖNLÜ: `customers.invoices` ile
+ * `invoices.customer` birbirini gösteriyor, yani grafiğin kendisi döngülü.
+ * Sınırsız açılım bu döngüyü sonsuz bir tipe çevirirdi — TypeScript'in
+ * "excessively deep" hatası, yazılan sorgunun karmaşıklığından değil ŞEMANIN
+ * şeklinden gelirdi. Üç seviye, ölçtüğümüz tüm gerçek sorguların üstünde.
+ */
+type HasDepth = 0 | 1 | 2 | 3;
+type HasDec = [0, 0, 1, 2];
+type HasNest<Rels, D extends HasDepth> = [keyof Rels] extends [never] ? unknown : D extends 0 ? unknown : {
+    has?: HasFilter<Rels, HasDec[D]>;
+};
+type HasFilter<Rels, D extends HasDepth = 3> = {
+    [R in keyof Rels]?: Rels[R] extends {
+        to: infer To;
+    } ? WhereFilter<RelatedRow<To>> & HasNest<RelatedRels<To>, D> : never;
+};
+/** İlişki bilgisi taşıyan bir tablo tipinin filtre yüzeyi. */
+type WhereWithRelations<Row, Rels> = WhereFilter<Row> & {
+    has?: HasFilter<Rels>;
+};
+/**
+ * `has` dalı — SADECE `has`, satır filtresi olmadan.
+ *
+ * Plan yolunun filtre dili (`TxWhere`) düz op'unkiyle aynı değil: orada bir
+ * alan ÖNCEKİ bir işlemin satırına referans (`Ref`) taşıyabiliyor. `has`'ı
+ * plana taşımak için o dili kopyalamak gerekmiyor — kesişimle EKLENİYOR.
+ * İlişki yoksa `unknown` dönüyor, çünkü `X & unknown = X`: dal yok olur ve
+ * `has` fazla-alan denetimine takılır.
+ */
+type HasOnly<Rels> = [unknown] extends [Rels] ? unknown : [keyof Rels] extends [never] ? unknown : {
+    has?: HasFilter<Rels>;
+};
+/**
+ * `has` dalı NE ZAMAN var olur.
+ *
+ * İlişkisi OLMAYAN bir tabloda `has` hiç yazılamamalı. `HasFilter<{}>` boş bir
+ * nesne tipidir ve boş nesne tipi HER nesneyi kabul eder — yani dalı koşulsuz
+ * eklemek, ilişkisiz bir tabloda `has: { neyse_ne: {} }`'yi SESSİZCE geçirirdi
+ * (ölçüldü: kapı yeşil, çalışma anında "böyle bir ilişki yok" hatası).
+ */
+type HasBranch<Row, Rels> = [unknown] extends [Rels] ? never : [keyof Rels] extends [never] ? never : WhereWithRelations<Row, Rels>;
+type QueryInput<Row, K extends keyof Row = keyof Row, Rels = unknown> = {
+    /**
+     * Filtre — ya tipli filtre dili ya da bir `sqlFragment` (FR-018). İkisi de
+     * AYNI alandır: kademe atlamak bir parametre değişikliği, ayrı bir çağrı
+     * yolu değil (P1).
+     */
+    where?: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels>;
+    /**
+     * Projeksiyon (FR-009): yalnız bu kolonlar çekilir ve DÖNÜŞ TİPİ buna daralır.
+     *
+     * Tip `Pick<Row, K>` ile TÜRETİLİR, üretilmez: `select` kombinasyonları için
+     * tip basmak, üretilen `.d.ts`'i kombinatoryal olarak şişirirdi (N-1: tablo
+     * başına ≤ 25 satır).
+     */
+    select?: readonly K[];
+} & FindManyOpts<Row>;
+/** Bir yazmanın TEK parametresi: neyi (`where`) neye çevirdiğin (`set`). */
+type MutateInput<Row, Insert, Rels = unknown> = {
+    where: WhereFilter<Row> | SqlFragment | HasBranch<Row, Rels>;
+    set: SetShape<Insert>;
+};
+/**
+ * `set`'e yazılabilen değer (FR-012): kolonun kendi tipi ya da — sayısal
+ * kolonlarda — kolonun ŞU ANKİ değerini okuyan bir ifade.
+ *
+ * `increment()` metin ya da boolean kolonda YOK: "kolona ekle"nin orada bir
+ * anlamı olmadığı için ifade edilemez kılınıyor (P5 — anlatmak değil, ifade
+ * edilemez kılmak). `numeric` kolonlar TypeScript'te `string` taşır, o yüzden
+ * string de sayısal sayılır; ayrımı burada yapamayız, ama D-007 zaten miktarın
+ * JS `number`'a hiç uğramamasını istiyor.
+ */
+type SetValue<V> = V | (NonNullable<V> extends number | string ? TxColumnExpr : never) | (NonNullable<V> extends Date ? TxNow : never);
+/** Bir update'in `set`'i: insert şeklinin herhangi bir alt kümesi, ifadelerle. */
+type SetShape<Insert> = {
+    [K in keyof Insert]?: SetValue<Insert[K]>;
+};
+/** search() parametreleri, satır tipiyle koşullanmış (FR-013). `offset` BİLEREK yok (UD-013). */
+interface SearchParamsTyped<T extends TableTypes> {
+    /** Metin sorgusu: FTS kolunu besler; embed beyanlıysa sorgu vektörü de bundan üretilir. */
+    query?: string;
+    /** Hazır sorgu vektörü — verilirse embed çağrısı olmaz (FR-025). */
+    vector?: number[];
+    /** `findMany`'nin filtre dili — İKİNCİ tip argümanıyla, yoksa `Row` sessizce
+     *  `unknown`'a düşer ve `col()` burada ifade edilemez olurdu. Motor `search`
+     *  için aynı `compileWhereBare`'i kullanıyor; yetenek orada (gözcü I7). */
+    where?: {
+        [K in keyof T["row"]]?: WhereOp<T["row"][K], T["row"]>;
+    };
+    /** default 20, tavan 100 (engine uygular). */
+    limit?: number;
+    /** Birden çok vektör kolonunda hedef seçimi (model geçişi, FR-013/using). */
+    using?: string;
+    mode?: "hybrid" | "text" | "vector";
+    /** Nihai (RRF-sonrası) skor alt eşiği — süzme LIMIT'ten önce uygulanır (FR-001). */
+    minScore?: number;
+    /** Chunk-modunda satır başına en iyi blok sayısı (1..10, vars. 3; FR-015). */
+    blocksPerRow?: number;
+    /** Tazelik çürümesi: nihai skor RRF-sonrası exp(-ln(2)*yaş/halfLife) ile çarpılır;
+     * field bir timestamp kolonu, halfLife "90s" | "15m" | "12h" | "30d" biçiminde (FR-004). */
+    recency?: {
+        field: Extract<keyof T["row"], string>;
+        halfLife: string;
+    };
+    /** Satır-modunda FTS eşleşme vurgusu: sonuç satırına `_highlight` ekler;
+     * chunk-modda no-op — bloklar zaten eşleşen kesittir (FR-025). */
+    highlight?: boolean;
+    /** Validity'li tabloda zaman penceresi: varsayılan yalnız güncel versiyon;
+     * "all" tüm versiyonlar; {asOf} o anda geçerli olan (FR-029). */
+    validity?: "all" | {
+        asOf: string;
+    };
+    /** Alan-boost (FR-030): skor * (1 + w·x/(1+x)) — sayısal kolonla sınırlı
+     * çarpan, dış servissiz; bileşim RRF → boost → recency → minScore. */
+    boost?: {
+        field: Extract<keyof T["row"], string>;
+        weight: number;
+    };
+}
+/**
+ * `facets()` dönüşü (FR-027, FR-058): kolon adı → o kolonun top-20 değeri ve
+ * sayacı.
+ *
+ * Bu tip bir zamanlar `search()` dönüş DİZİSİNİN üstünde taşınıyordu; dizi-üstü
+ * özellik `JSON.stringify`'da kayboluyor, yani bir kontrolcü onu döndürmeye
+ * çalıştığında yanıt gövdesinde hiç görünmüyordu. Sayaçlar artık BAĞIMSIZ
+ * dönüşle geliyor ve tip de o dönüşü adlandırıyor.
+ */
+type SearchFacets = Record<string, {
+    value: string | null;
+    count: number;
+}[]>;
+/** similar()/recommend() taşıyıcı opsiyonları (T018, FR-022): search'ün
+ * paramlarından query/vector/mode düşer — hedef vektörü metodun kendisi
+ * DB'den kurar; facets/highlight de düşer (T020) — engine bu ikisini
+ * similar/recommend'e geçirmez, tip vaadi gerçekle aynı kalır. */
+type SimilarParamsTyped<T extends TableTypes> = Omit<SearchParamsTyped<T>, "query" | "vector" | "mode" | "facets" | "highlight">;
+/** recommend() parametreleri (T018, FR-023). */
+type RecommendParamsTyped<T extends TableTypes> = SimilarParamsTyped<T> & {
+    /** Kaynak beğeniler — hedef vektör bunların DB-içi avg'ı; boş olamaz. */
+    positive: string[];
+    /** İtilen örnekler — hedef pos.v + (pos.v - neg.v) ile yönlenir. */
+    negative?: string[];
+};
+/**
+ * Tablonun ilişki bloğu — env `Tables` girdisinden.
+ *
+ * TEK yerde türetiliyor ve HER op'a aynısı veriliyor: `has` yalnız `findMany`'de
+ * olsaydı, "aynı filtre dili her op'ta" sözü ilk `deleteMany`'de kırılırdı.
+ */
+type RelsOf<T> = T extends {
+    relations: infer R;
+} ? R : unknown;
+/** Temel tablo erişimcisi — search'süz beş op. */
+interface EnvTypedTableBase<T extends TableTypes> {
+    insert(data: T["insert"]): Promise<T["row"]>;
+    /**
+     * Bir idempotency anahtarını sahiplen (FR-033).
+     *
+     * ```ts
+     * const { inserted, row } = await Database.public.payments.claim(
+     *   { idem_key: req.headers["idempotency-key"] },
+     *   { amount, user_id },
+     * );
+     * if (!inserted) return row;   // aynı istek ikinci kez geldi
+     * ```
+     *
+     * `inserted: false` bir HATA DEĞİL: dönen satır ilk çağrının satırıdır.
+     * İlk argüman satırı BULAN alanlar, ikincisi yalnız yazılanlar — ikinci çağrı
+     * farklı bir yük gönderse bile satır anahtarla bulunur.
+     */
+    claim(unique: Partial<T["insert"]>, extra?: Partial<T["insert"]>): Promise<{
+        inserted: boolean;
+        row: T["row"];
+    }>;
+    /**
+     * Satırı yaz; `onConflict` kolonlarında çakışırsa ÜZERİNE yaz (FR-034).
+     *
+     * ```ts
+     * await Database.public.settings.put({
+     *   data: { user_id, theme: "dark" },
+     *   onConflict: ["user_id"],
+     * });
+     * ```
+     *
+     * `onConflict` kolonları benzersiz bir kısıt ya da index taşımalı — Postgres
+     * onlarla eşleştirir — ve güncellemeden dışlanırlar, çünkü eşleşen şey onlar.
+     *
+     * **`upsert`'ün yerine geldi ve adı bilerek değişti.** `upsert` tek isim
+     * altında iki niyet taşıyordu: "yoksa ekle varsa güncelle" (bu) ve "idempotent
+     * yaz" (artık {@link EnvTypedTableBase.claim}). İkincisi için ÖLÇÜLMÜŞ biçimde
+     * yanlıştı: `DO UPDATE` ikinci çağrının verisiyle birincininkini EZİYOR
+     * (10.00 → 999.00 ölçüldü). İki niyeti tek isimde tutmak, yanlış olanı
+     * seçmeyi kolay yapıyordu.
+     */
+    put(q: {
+        data: T["insert"];
+        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. */
+    update(q: {
+        where: {
+            id: string;
+        };
+        set: Partial<T["insert"]>;
+    }): Promise<T["row"] | null>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<T["row"] | null>;
+    /** Rows matching the filter. See {@link WhereFilter} / {@link FindManyOpts} —
+     * this declaration is what makes the engine's operators callable. */
+    findMany<K extends keyof T["row"] = keyof T["row"]>(q?: QueryInput<T["row"], K, RelsOf<T>>): Promise<Pick<T["row"], K>[]>;
+    /**
+     * Update every matching row in one statement; an empty filter is refused.
+     *
+     * **0 satır dönmesi hata DEĞİL, başarı da değil** (FR-014): koşulu `where`'e
+     * koyup dönen diziyi kontrol etmek, "önce oku sonra yaz"ın yarış koşulu
+     * olmayan hâlidir.
+     *
+     * ```ts
+     * const [row] = await Database.public.accounts.updateMany({
+     *   where: { id, balance: { gte: amount } },
+     *   set: { balance: decrement(amount) },
+     * });
+     * if (row === undefined) throw new Conflict("yetersiz bakiye");
+     * ```
+     */
+    updateMany(q: MutateInput<T["row"], T["insert"], RelsOf<T>>): Promise<T["row"][]>;
+    /** Delete every matching row; resolves to how many. Empty filter refused. */
+    deleteMany(q: {
+        where: WhereFilter<T["row"]> | SqlFragment | HasBranch<T["row"], RelsOf<T>>;
+    }): Promise<number>;
+    /** How many rows match. An empty filter is legitimate: counting is a read. */
+    count(q?: {
+        where?: WhereFilter<T["row"]> | SqlFragment | HasBranch<T["row"], RelsOf<T>>;
+    }): Promise<number>;
+    /** Validity'li tabloda satırın yeni versiyonu (FR-029, C-9): eski satır
+     * kapanır (valid_to/superseded_by), yenisi TEK savepoint'te eklenir; dönüş
+     * yeni satır. Validity beyanı olmayan tabloda adlandırılmış çalışma-zamanı
+     * hatası — tip düzeyinde ayrım env `Tables` bayrağı taşımadığından yapılamaz. */
+    supersede(id: string, row: T["insert"]): Promise<T["row"]>;
+}
+/** Tablo erişimcisi: env girdisi `searchable: true` taşıyorsa (vector kolonu ya da
+ * search beyanı — env-gen üretir) `search()` üyesi VARDIR; yoksa üye hiç yoktur ve
+ * çağrı derleme hatasıdır (FR-013). Yapısal koşul TableTypes'ı genişletmeden çalışır. */
+/**
+ * `appendOnly` tabloda YAYIMLANMAYAN üyeler (FR-031).
+ *
+ * Altısı da ayrı ayrı: biri unutulursa append-only sözü o üye üzerinden sessizce
+ * delinir. `insert` ve okuma üyeleri kalır — düzeltme SİLMEKLE değil, telafi
+ * kaydı EKLEMEKLE yapılır (FR-032).
+ */
+type AppendOnlyForbidden = "update" | "updateMany" | "delete" | "deleteMany" | "put" | "supersede";
+type EnvTypedTable<T extends TableTypes> = (T extends {
+    appendOnly: true;
+} ? Omit<EnvTypedTableBase<T>, AppendOnlyForbidden> : EnvTypedTableBase<T>) & (T extends {
+    searchable: true;
+} ? {
+    search(params: SearchParamsTyped<T>): Promise<Array<T["row"] & {
+        _score: number;
+        _highlight?: string;
+    }>>;
+    /** "Bu satıra benzeyenler" (FR-022): hedef vektör DB'den okunur,
+     * kaynak satır sonuçta yoktur; id yoksa adlandırılmış hata. */
+    similar(id: string, params?: SimilarParamsTyped<T>): Promise<Array<T["row"] & {
+        _score: number;
+    }>>;
+    /** D-021: sayaçlar bağımsız dönüşle — search'ün dizi-üstü _facets'i
+     * JSON.stringify'da kaybolur; ciddi sözleşme budur. */
+    facets(params: {
+        facets: Array<keyof T["row"] & string>;
+        where?: Partial<T["row"]>;
+        validity?: "all" | {
+            asOf: string;
+        };
+    }): Promise<SearchFacets>;
+    /** positive/negative beğenilerden öneri (FR-023): hedef vektör DB-içi
+     * avg CTE'leriyle; kaynak id'ler sonuçta yoktur. */
+    recommend(params: RecommendParamsTyped<T>): Promise<Array<T["row"] & {
+        _score: number;
+    }>>;
+} : Record<never, never>);
+/** The `tables` map exposed on `Database`/`tx`, keyed by the env `Tables`
+ * interface. When no schema is declared `Tables` is empty, so `tables` is an
+ * empty object — accessing `.tables.foo` is then a compile error (no member). */
+type EnvTables = {
+    [K in keyof Tables]: EnvTypedTable<Tables[K]>;
+};
+/**
+ * The project's NON-public schemas, keyed by schema name, each exposing its own
+ * `tables` map — the shape `Database.schema("billing")` returns.
+ *
+ * The intermediate `tables` is there for the reason {@link EnvTables} sits under
+ * `.tables`: a schema's table names must not share a namespace with anything the
+ * accessor itself might grow.
+ *
+ * Empty by default. The generated `palbase-env.d.ts` augments `Schemas` with one
+ * member per declared schema other than `public`, so a project that declares
+ * none has `keyof Schemas = never` and every `schema(...)` call is a compile
+ * error rather than a runtime surprise.
+ */
+/**
+ * @deprecated ARTIK VAR OLMAYAN BİR ŞEKLİ tarif ediyor. Bu tip her şemayı
+ * `{ tables: … }` altında gösteriyor; yüzey FR-001 ile `Database.<şema>.<tablo>`
+ * oldu ve `.tables` ara katmanı KALKTI. Güncel şekil: {@link EnvSchemaSurface}.
+ *
+ * Kaldırılmadı çünkü dışa açık bir tip ve kaldırmak SEKİZİNCİ bir kırıcı olurdu;
+ * ama bir tip, çalışma zamanının ÜRETMEDİĞİ bir şekli tarif ediyorsa yalan
+ * söylüyor demektir — `const x: EnvSchemas["billing"] = Database.billing`
+ * açıklanamayan bir derleme hatası verir. Bir sonraki kırıcı sürümde silinmeli
+ * (defter D-18).
+ *
+ * Bu tipi ÜRETEN iki fonksiyon (`makeTablesAccessor`, `makeSchemaAccessor`)
+ * ölçüldü: hiçbir yerden çağrılmıyorlardı ve silindiler. Canlı yol
+ * `makeTypedSurface`'ın proxy'si.
+ */
+type EnvSchemas = {
+    [S in keyof Schemas]: {
+        tables: {
+            [T in keyof Schemas[S]]: EnvTypedTable<Extract<Schemas[S][T], TableTypes>>;
+        };
+    };
+};
+/** The project's tables as PLAN operations, keyed by the env `Tables`
+ * interface. The transaction twin of {@link EnvTables}. */
+/** `appendOnly` bir tabloda transaction planının da kaybettiği üyeler. Doğrudan
+ *  yüzeyin `AppendOnlyForbidden`'ının plan-yolu ikizi; adlar farklı çünkü plan
+ *  yüzeyinin üye adları farklı. */
+type TxAppendOnlyForbidden = "put" | "updateWhere" | "deleteWhere";
+/**
+ * Plan yüzeyi de `appendOnly`'yi UYGULUYOR — ve uygulamıyor olması bir kusurdu.
+ *
+ * `EnvTypedTable` altı üyeyi Omit ediyordu, ama `TxTables` hiçbirini: yani
+ * `tx.tables.entries.updateWhere(…)` ve `.put(…)` DERLENİYORDU. Tip bir şeyi
+ * "ifade edilemez" ilan edip ikinci bir kapıda ifade edilebilir bırakırsa,
+ * ilan yalandır (doğrulayıcı gözcü, FR-031).
+ *
+ * Motor da aynı üçünü adıyla reddediyor — tip atlanınca susmaması için.
+ */
+type TxTables = {
+    [K in keyof Tables]: Tables[K] extends {
+        appendOnly: true;
+    } ? Omit<TxTable<Tables[K]["row"], Tables[K]["insert"], RelsOf<Tables[K]>>, TxAppendOnlyForbidden> : TxTable<Tables[K]["row"], Tables[K]["insert"], RelsOf<Tables[K]>>;
+};
+/** Bir şemanın tabloları PLAN operasyonları olarak — `TxTables`'ın public
+ *  DIŞI şemalar için ikizi. */
+type TxTablesOf<S> = {
+    [T in keyof S]: Extract<S[T], TableTypes> extends {
+        appendOnly: true;
+    } ? Omit<TxTable<Extract<S[T], TableTypes>["row"], Extract<S[T], TableTypes>["insert"], RelsOf<Extract<S[T], TableTypes>>>, TxAppendOnlyForbidden> : TxTable<Extract<S[T], TableTypes>["row"], Extract<S[T], TableTypes>["insert"], RelsOf<Extract<S[T], TableTypes>>>;
+};
+/**
+ * Plan tutamağının şema yüzeyi — `EnvSchemaSurface`'ın BİREBİR ikizi.
+ *
+ * NEDEN AYNI ŞEKİL: `Database.billing.invoices` yazılabiliyorken
+ * `tx.billing.invoices` yazılamıyordu, yani `billing` şemasındaki iki tabloyu
+ * TEK ATOMİK PLANDA yazmak imkânsızdı — yazar `$query`'ye düşüyor, tipi ve RLS
+ * yardımını kaybediyordu. Bu yüzeyin kapatmak için var olduğu düşüşün ta
+ * kendisi, ve GOAL'ün "ciddi ölçekli fintech" yarısının tam ortasında
+ * (nihai inceleme I-6).
+ */
+type TxSchemaSurface = {
+    public: TxTables;
+} & {
+    [S in keyof Schemas]: TxTablesOf<Schemas[S]>;
+};
+/**
+ * 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.
+ *
+ * `tx.public.x` ve `tx.<şema>.x`, `Database` ile aynı şekil. `tx.tables.x`
+ * public'in TAKMA ADI olarak duruyor: bu run'ın göç notu onu öğretiyor ve her
+ * mevcut çağrı onu kullanıyor — kaldırmak sekizinci bir kırıcı olurdu ve
+ * hiçbir şey kazandırmazdı.
+ */
+type TxPlan = TxPlanHandle<TxTables> & TxSchemaSurface;
+/**
+ * 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).
+ */
+type EnvServiceDatabase = EnvSchemaSurface & {
+    /** Ham SQL. Generic verilmezse `unknown[]` döner (FR-021). */
+    $query: DBClient["query"];
+    $insert: DBClient["insert"];
+    $update: DBClient["update"];
+    $delete: DBClient["delete"];
+    $findById: DBClient["findById"];
+    $findMany: DBClient["findMany"];
+    $put: DBClient["put"];
+    $updateMany: DBClient["updateMany"];
+    $deleteMany: DBClient["deleteMany"];
+    $count: DBClient["count"];
+    $search: DBClient["search"];
+    $similar: RecoOps["similar"];
+    $recommend: RecoOps["recommend"];
+    $facets: DBClient["facets"];
+    $supersede: DBClient["supersede"];
+    $claim: DBClient["claim"];
+    $lockRows: DBClient["lockRows"];
+    $advisoryXactLock: DBClient["advisoryXactLock"];
+    $attempt: DBClient["attempt"];
+    /** Bkz. {@link EnvTypedDatabase.$transaction}. */
+    /**
+     * `opts.retry` verilirse, `SerializationFailure` / `DeadlockDetected`
+     * alındığında plan BAŞTAN kurulup yeniden çalıştırılır (FR-037).
+     * Varsayılan 0 — sessiz bir retry, idempotent olmayan bir işlemi çağıranın
+     * haberi olmadan iki kez çalıştırırdı.
+     */
+    $transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T, opts?: {
+        retry?: number;
+    }): 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` that runs a whole plan in one request, and `asService()` for
+ * the explicit RLS-bypass 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.
+ */
+type EnvSchemaSurface = {
+    public: EnvTables;
+} & {
+    [S in keyof Schemas]: {
+        [T in keyof Schemas[S]]: EnvTypedTable<Extract<Schemas[S][T], TableTypes>>;
+    };
+};
+/**
+ * Projenin veri yüzeyi: `Database.<şema>.<tablo>` + `$` önekli sistem üyeleri.
+ *
+ * Bugünkü `tables` ve `schema("x")` ikilisinin yerine geçer (FR-001). İki yol
+ * tek yola iner: `public` de diğer şemalar gibi adıyla anılır, ara katman yoktur.
+ *
+ * @example
+ * await Database.public.notes.findMany({ where: { owner: uid } });
+ * await Database.billing.invoices.findMany({ where: { paid: false } });
+ * await Database.$transaction((tx) => { … });
+ */
+type EnvTypedDatabase = EnvSchemaSurface & {
+    /** Ham SQL. Generic verilmezse `unknown[]` döner (FR-021). */
+    $query: DBClient["query"];
+    $insert: DBClient["insert"];
+    $update: DBClient["update"];
+    $delete: DBClient["delete"];
+    $findById: DBClient["findById"];
+    $findMany: DBClient["findMany"];
+    $put: DBClient["put"];
+    $updateMany: DBClient["updateMany"];
+    $deleteMany: DBClient["deleteMany"];
+    $count: DBClient["count"];
+    $search: DBClient["search"];
+    $similar: RecoOps["similar"];
+    $recommend: RecoOps["recommend"];
+    $facets: DBClient["facets"];
+    $supersede: DBClient["supersede"];
+    $claim: DBClient["claim"];
+    $lockRows: DBClient["lockRows"];
+    $advisoryXactLock: DBClient["advisoryXactLock"];
+    $attempt: DBClient["attempt"];
+    /** RLS'i bypass eden kardeş yüzey. Kendisi `$asService` TAŞIMAZ — çift bypass yok. */
+    $asService(): EnvServiceDatabase;
+    /**
+     * Bir transaction çalıştırır. Callback işlemleri TARİF eder; tarifin tamamı
+     * tek istekte gider ve broker onu tek bir transaction içinde koşturur.
+     * Callback SENKRONDUR: döndüğünde hiçbir şey çalışmamıştır.
+     */
+    /**
+     * `opts.retry` verilirse, `SerializationFailure` / `DeadlockDetected`
+     * alındığında plan BAŞTAN kurulup yeniden çalıştırılır (FR-037).
+     * Varsayılan 0 — sessiz bir retry, idempotent olmayan bir işlemi çağıranın
+     * haberi olmadan iki kez çalıştırırdı.
+     */
+    $transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T, opts?: {
+        retry?: number;
+    }): Promise<Materialized<T>>;
+};
+
+/**
+ * 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
+ * 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:
+ *
+ *   - `$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 | string;
+    } | {
+        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 {
+    /** upsert and insertMany: the columns Postgres matches on. */
+    onConflict?: readonly string[];
+    /** insertMany only: what a collision does. Absent means no ON CONFLICT clause
+     * at all, which is what every insertMany did before this option existed. */
+    action?: "ignore" | "update";
+    op: "insert" | "insertMany" | "upsert" | "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 plan the engine executes on the request's own transaction. */
+interface TxPlanBody {
+    ops: TxWireOp[];
+}
+/** One op's outcome, positionally matched to the plan's ops. */
+interface TxPlanOpResult {
+    rows: Record<string, unknown>[];
+    rows_affected: number;
+}
+/** One result per op, in plan order. */
+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 | string;
+    };
+}
+/**
+ * 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. */
+/**
+ * TEK KURAL: ifade tutamağı yalnız sayısal-benzeri kolonlarda.
+ *
+ * Bu tip KOŞULSUZDU ve doğrudan yolun `SetValue<V>`'si koşulluydu, yani aynı
+ * nesne için İKİ tip kuralı vardı: `tx.tables.todos.updateWhere({id}, { done:
+ * increment(1) })` (boolean kolon!) DERLENİYOR, `updateMany`'nin aynısı derleme
+ * hatası veriyordu. Bu run'ın kapatmak için var olduğu şey "aynı iş için iki
+ * uyumsuz yazım"dı; tip kuralı ikinci yazımın kendisi olmuştu (gözcü I6/I-1).
+ */
+type TxSetValue<V> = V | Ref<V> | TxNow | (NonNullable<V> extends number | string ? TxColumnExpr : never);
+/** 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.
+ */
+/**
+ * Plan filtresinin tipi — `WhereFilter<Row>` ile AYNI sözlük, artı `Ref`.
+ *
+ * Eskiden yalnız eşitlikti (`Row[K] | Ref<Row[K]>`), ve iki şeye mal oluyordu:
+ * FR-014'ün amiral deseni (`{ balance: { gte: amount } }`) `$transaction`
+ * İÇİNDE yazılamıyordu — koşullu bir yazmayı plana koyamayan yazar `$query`'ye
+ * düşüyordu — ve motor tarafında tip atlandığında aynı nesne SESSİZCE parametre
+ * olarak bağlanıyordu.
+ *
+ * `Ref` fazladan üye ve öyle kalmalı: bir plan filtresi ÖNCEKİ bir işlemin
+ * döndürdüğü değere bakabilir, `findMany` bakamaz — plan dışında böyle bir
+ * "önceki işlem" yok.
+ */
+type TxWhereField<Row, K extends keyof Row> = WhereOpWith<Row[K], ColRefOf<Row, Row[K]> | Ref<Row[K]>>;
+type TxWhere<Row, Rels = unknown> = {
+    [K in keyof Row]?: TxWhereField<Row, K>;
+} & {
+    OR?: TxWhere<Row, Rels>[];
+    AND?: TxWhere<Row, Rels>[];
+    NOT?: TxWhere<Row, Rels>;
+} & HasOnly<Rels>;
+/** 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, Rels = unknown> {
+    /** 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.
+     */
+    /**
+     * Insert many rows in ONE statement, optionally choosing what a collision does.
+     *
+     * Without `opts` this is a plain multi-row INSERT and a collision aborts the
+     * transaction — the behaviour every call had before the option existed.
+     *
+     * `action: "ignore"` emits `ON CONFLICT DO NOTHING`, which is how "insert the
+     * ones that are new" becomes one round-trip instead of one per row with a
+     * 23505 caught around each. **The returned rows are the ones actually
+     * INSERTED**: a row that collided is skipped, so it is absent from the result
+     * — Postgres does not return what it did not write.
+     *
+     * `action: "update"` emits `ON CONFLICT DO UPDATE`, setting every non-conflict
+     * column from the incoming row, and every row comes back.
+     */
+    insertMany(rows: readonly TxInsertShape<Insert>[], opts?: {
+        onConflict: readonly Extract<keyof Row, string>[];
+        action?: "ignore" | "update";
+    }): TxRows<Row>;
+    /**
+     * Satırı yaz, `onConflict` kolonlarında çakışırsa üzerine yaz — planın
+     * savepoint'i içinde, `Database.<şema>.<tablo>.put()` ile AYNI anlamda.
+     *
+     * Adı bilerek aynı: aynı iş için transaction içinde ve dışında iki farklı
+     * yazım, bu run'ın kapatmak için var olduğu şeydir (P1). TEL şekli
+     * (`op: "upsert"`) değişmedi — o iç sözleşme, yazarın gördüğü ad değil.
+     *
+     * Bir operasyon olmasının sebebi: alternatifi burada yazılamaz — başarısız
+     * bir insert tüm transaction'ı abort eder, yani "dene, sonra geri düş" iki
+     * plan adımı olamaz.
+     */
+    put(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
+     * never looked at. The server refuses an update with no `where` at all.
+     */
+    updateWhere(where: TxWhere<Row, Rels>, set: TxSetShape<Insert>): TxRows<Row>;
+    /** Delete every row matching `where`. The server refuses an unfiltered delete. */
+    deleteWhere(where: TxWhere<Row, Rels>): TxRows<Row>;
+    /** Read rows, optionally locking them for the rest of the transaction. */
+    select(where?: TxWhere<Row, Rels>, 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> {
+    /**
+     * @deprecated `tx.public` kullanın. Bu ad public'in takma adı olarak DURUYOR
+     * (göç notu onu öğretiyor ve her mevcut çağrı onu kullanıyor), ama ARTIK
+     * ÖĞRETİLMİYOR: doğrudan yüzeyde `Database.tables` FR-001 ile kaldırıldı, ve
+     * plan yüzeyinin onu öğretmeye devam etmesi yazarı bir yüzeyde çalışıp
+     * diğerinde derlenmeyen bir yazıma alıştırıyordu (gözcü M-6).
+     */
+    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 increment(by: number | string): TxColumnExpr;
+/**
+ * `increment`'in eski adı. AYNI fabrikadır — iki uygulama değil, iki ad.
+ *
+ * @deprecated `increment()` kullanın; bu ad geriye dönük uyumluluk için duruyor.
+ */
+declare const inc: typeof increment;
+/** Subtract `by` from the column's current value. Only valid in an update's `set`. */
+declare function decrement(by: number | string): TxColumnExpr;
+/**
+ * `decrement`'in eski adı. AYNI fabrikadır.
+ *
+ * @deprecated `decrement()` kullanın.
+ */
+declare const dec: typeof decrement;
+
+/**
+ * The brand that identifies an HttpError ACROSS SDK instances.
+ *
+ * A process legitimately holds more than one copy of this SDK — the runtime
+ * loads the engine from its own node_modules while the tenant's bundle carries
+ * an inlined copy, which is why the controller registry and the error registry
+ * are both anchored on `Symbol.for`. The one place that did not follow the
+ * pattern was the engine's catch: `err instanceof HttpError` compares CLASS
+ * IDENTITY, so a `throw new NotFound()` from the bundle's copy did not match
+ * the engine's copy and every typed error in every deployed backend degraded to
+ * `500 internal_error`. Measured through the edge on a real deploy: a route
+ * throwing `NotFound` answered 500 while the runtime's own log printed the
+ * error object with `status: 404` right beside it.
+ *
+ * `Symbol.for` puts this in the cross-realm registry, so every copy of the SDK
+ * agrees on it by VALUE rather than by identity.
+ */
+declare const HTTP_ERROR_BRAND: unique symbol;
+/** HTTP error with structured error response format.
+ *
+ * The base class for the throwable error classes (`PalError`, `Conflict`,
+ * `NotFound`, …). Construct one directly with `throw new HttpError(404,
+ * "todo_not_found", "No such todo")`, or throw a named subclass
+ * (`throw new NotFound("todo not found")`). The runtime catches any `HttpError`
+ * and emits the standard envelope; on the wire (and to iOS) it surfaces as
+ * `BackendError.server(code, status, message, requestId)`.
+ *
+ * The optional `data` field carries a structured payload alongside the
+ * standard envelope — for errors that need to ship extra context
+ * (e.g. `new Conflict("locked", "title_locked", { retryAfter: 30 })`). It rides
+ * through to the iOS typed enum's associated value.
+ */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly error: string;
+    readonly errorDescription: string;
+    readonly data?: unknown;
+    /** See {@link HTTP_ERROR_BRAND} — how the engine recognises this across SDK copies. */
+    readonly [HTTP_ERROR_BRAND] = true;
+    constructor(status: number, error: string, errorDescription: string, data?: unknown);
+    /**
+     * Serialize to the standard Palbase error response format.
+     * The `requestId` is injected by the runtime layer from the request context.
+     * When called without arguments (e.g. JSON.stringify), request_id is omitted.
+     * When `data` is set, it is appended as a strict-superset field.
+     */
+    toJSON(requestId?: string): {
+        error: string;
+        error_description: string;
+        status: number;
+        request_id?: string;
+        data?: unknown;
+    };
+}
+/**
+ * Throw with a custom HTTP status + wire code. The general-purpose escape hatch
+ * when none of the named classes (`Conflict`/`NotFound`/…) fits.
+ *
+ * @example
+ * throw new PalError(418, "teapot", "I'm a teapot");
+ */
+declare class PalError extends HttpError {
+    constructor(status: number, code: string, description: string, data?: unknown);
+}
+/** Base for the named status classes. Each subclass fixes its HTTP status; the
+ * `code` defaults to the class's canonical wire code (overridable), and the
+ * `message` defaults to a human-readable label (overridable). */
+declare abstract class NamedHttpError extends HttpError {
+    protected constructor(status: number, defaultCode: string, name: string, message?: string, code?: string, data?: unknown);
+}
+/**
+ * 400 — the request was malformed or failed validation. Carries a fixed typed
+ * payload: `new BadRequest({ fields: [{ field: "email", message: "invalid" }] })`.
+ * The shape is declared once in the SDK so codegen surfaces `error.data.fields`
+ * typed on the client.
+ */
+declare class BadRequest extends NamedHttpError {
+    readonly data: BadRequestData;
+    constructor(data: BadRequestData, message?: string);
+}
+/** 401 — the caller is not authenticated. */
+declare class Unauthorized extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 403 — the caller is authenticated but not allowed. */
+declare class Forbidden extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 404 — the requested resource does not exist. */
+declare class NotFound extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 409 — the request conflicts with the current state. */
+declare class Conflict extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/**
+ * 409 — a write was refused because it would duplicate an existing row.
+ * Carries the NAME of the unique constraint Postgres named (`users_email_key`).
+ *
+ * The engine produces it: a statement rejected with SQLSTATE `23505` is
+ * converted here rather than surfacing as an opaque driver error (see
+ * `engine/db.ts`, `diagnosingDriver`). What that removes is the string match —
+ * before this, the only way to act on a duplicate was to test the driver
+ * message for "duplicate key value violates unique constraint", a contract
+ * nobody signed that breaks on a Postgres upgrade, a locale, or a constraint
+ * rename, silently and in production.
+ *
+ * THE NAME IS A FIELD AND STAYS OUT OF THE DEFAULT MESSAGE. The two are not
+ * the same audience. `constraint` is read by the code that catches this — the
+ * developer, who already knows the schema. `errorDescription` is the HTTP
+ * response body, and an UNCAUGHT duplicate puts it in front of the
+ * application's end user: `users_email_key` there discloses how the schema is
+ * built to whoever sent the request. The platform's own data API took the same
+ * decision one surface over and wrote down why —
+ * `v2/internal/modules/database/internal/handler/pgerror.go:83-87` collapses
+ * every 23xxx to a generic conflict, "never disclose the constraint/column
+ * name". A thrower who WANTS the name on the wire passes it deliberately
+ * (`new UniqueViolation(c, \`\${c} already exists\`)`, or through `data`).
+ *
+ * @example
+ * try {
+ *   await Database.public.users.insert({ email });
+ * } catch (e) {
+ *   if (UniqueViolation.is(e) && e.constraint === "users_email_key") {
+ *     throw new Conflict("That email is taken", "email_taken");
+ *   }
+ *   throw e;
+ * }
+ */
+declare class UniqueViolation extends Conflict {
+    /**
+     * Whether `e` is a unique violation — REGARDLESS of which copy of this SDK
+     * constructed it.
+     *
+     * Use this instead of `instanceof`. Measured on a live stack: a controller
+     * bundle INLINES its own copy of `@palbase/backend`, and the engine that
+     * raises this error is the runtime's copy. Two copies, two class identities,
+     * and `e instanceof UniqueViolation` is false in the one place a caller
+     * writes it — a check that reads as correct and silently never matches.
+     */
+    static is(e: unknown): e is UniqueViolation;
+    /** The unique constraint the statement violated, as Postgres named it.
+     * `""` when the driver did not say which — see `engine/db.ts`. */
+    readonly constraint: string;
+    constructor(constraint: string, message?: string, code?: string, data?: unknown);
+}
+/**
+ * Eşzamanlılık yüzünden BAŞARISIZ OLAN, ama TEKRAR DENENİRSE başarılı olabilecek
+ * hataların ortak yüzeyi (FR-036).
+ *
+ * `retryable: true` bir tahmin değil, Postgres'in söylediği şey: `40001` ve
+ * `40P01` "bu işlemi baştan çalıştır" anlamına gelir. Kümenin DAR tutulması
+ * kasıtlı — `23505` buraya girseydi, tekrar denemek aynı cevabı verir ve
+ * döngü sonsuza kadar dönerdi.
+ */
+interface RetryableError extends Error {
+    readonly retryable: true;
+    /** Beş karakterlik SQLSTATE — hangi eşzamanlılık hatası olduğunu SÖYLER. */
+    readonly sqlstate: string;
+}
+/**
+ * `e` tekrar denenebilir mi?
+ *
+ * `instanceof` DEĞİL şekil kontrolü — ve sebebi ÖLÇÜLMÜŞ (bkz. {@link
+ * UniqueViolation.is}): bir controller bundle'ı kendi `@palbase/backend`
+ * kopyasını inline'lıyor, hatayı fırlatan motor ise runtime'ın kopyası. İki
+ * sınıf kimliği, ve `e instanceof SerializationFailure` yazan tek yerde
+ * sessizce hiç eşleşmiyor.
+ */
+declare function isRetryable(e: unknown): e is RetryableError;
+/**
+ * `40001 serialization_failure` — SERIALIZABLE ya da REPEATABLE READ altında
+ * eşzamanlı bir işlem bu işlemi geçersiz kıldı.
+ *
+ * D-016: bu hata BLOKLANMIYOR, FIRLATILIYOR. Retry'sız bir izolasyon
+ * yükseltmesi sunmak defect'tir — kullanıcıya çalışmayan bir düğme vermektir:
+ * SERIALIZABLE'a çıkıp `40001`'i yakalamayan kod, önceden çalışan işlemleri
+ * rastgele kaybetmeye başlar.
+ */
+declare class SerializationFailure extends Conflict implements RetryableError {
+    readonly retryable: true;
+    readonly sqlstate: string;
+    static is(e: unknown): e is SerializationFailure;
+    constructor(sqlstate?: string, message?: string, data?: unknown);
+}
+/**
+ * `40P01 deadlock_detected` — iki işlem birbirinin kilidini bekliyordu;
+ * Postgres birini seçip iptal etti.
+ *
+ * Bu hatayı GÖRMEK bir tasarım sinyali: kilit sırası deterministik değilse
+ * tekrar denemek yalnız maliyeti öteler. `Database.$lockRows(...)` (FR-035)
+ * ya da çok satırlı yazmanın CTE'si (FR-015) sırayı sabitler.
+ */
+declare class DeadlockDetected extends Conflict implements RetryableError {
+    readonly retryable: true;
+    readonly sqlstate: string;
+    static is(e: unknown): e is DeadlockDetected;
+    constructor(sqlstate?: string, message?: string, data?: unknown);
+}
+/** A single field-level validation failure carried by {@link BadRequest}. */
+interface FieldError {
+    /** The offending field's name (dotted path for nested fields). */
+    field: string;
+    /** Human-readable reason the field failed. */
+    message: string;
+}
+/** The fixed, typed payload {@link BadRequest} ships. */
+interface BadRequestData {
+    /** The fields that failed validation. */
+    fields: FieldError[];
+}
+/** The fixed, typed payload {@link TooManyRequests} ships. */
+interface TooManyRequestsData {
+    /** Seconds the caller should wait before retrying. */
+    retryAfter: number;
+}
+/**
+ * 429 — the caller has exceeded the rate limit. Carries a fixed typed payload:
+ * `new TooManyRequests({ retryAfter: 30 })`. The shape is declared once in the
+ * SDK (error-registry pre-seed) so codegen surfaces `error.data.retryAfter`
+ * typed on the client — no per-project definition needed.
+ */
+declare class TooManyRequests extends NamedHttpError {
+    readonly data: TooManyRequestsData;
+    constructor(data: TooManyRequestsData, message?: string);
+}
+
+/** Uploaded file metadata injected into endpoint context when a file is present.
+ * `data` is typed as `Uint8Array` for SDK portability (Buffer extends Uint8Array in Node).
+ */
+interface FileContext {
+    filename: string;
+    contentType: string;
+    size: number;
+    data: Uint8Array;
+}
+/** Rate limit configuration for an endpoint. */
+interface RateLimitConfig {
+    /** Maximum number of requests in the window. */
+    max: number;
+    /** Window duration in seconds. */
+    window: number;
+}
+/** The six raw string-keyed DB operations shared by `DBClient` and the
+ * transaction-scoped client. */
+interface DBOps {
+    /**
+     * 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>.put()`
+     * 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 a put was impossible from
+     * here, abandoned `ON CONFLICT` and wrote a database trigger instead.
+     */
+    /**
+     * Ham SQL. Generic VERİLMEZSE `unknown[]` döner (FR-021).
+     *
+     * Eskiden `Record<string, unknown>[]` dönüyordu ve bu bir YALANDI: ham SQL'in
+     * sonucunu tipleyen tek şey geliştiricinin iddiasıdır, ve hiçbir iddia
+     * yapılmamışsa doğru cevap "bilmiyorum"dur. Drizzle aynı durumda `unknown`
+     * döndürüp yalanı görünür kılıyor; bir satırın alanına erişmek istiyorsanız
+     * tipi açıkça yazın — o zaman iddia sizin, ve okunabilir.
+     *
+     * BU OP READ-ONLY DEĞİLDİR. Adı "query" olduğu için okuma yaptığı varsayılır;
+     * motor bu transaction'ı READ ONLY işaretlemez (`engine/db.ts`), yani buradan
+     * yazma da yapılabilir. Nothing marks that transaction READ ONLY — okuyan
+     * tersini varsaymasın diye açıkça yazılıdır.
+     */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+    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`.
+     */
+    put(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
+     * an idempotent outcome, not an error — it mirrors `findById`. Map `null` to
+     * a 404 in your service if a missing row should be a client error.
+     */
+    update(table: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    delete(table: string, id: string): Promise<void>;
+    findById(table: string, id: string): Promise<Record<string, unknown> | null>;
+    /** Hibrit arama (FR-013/014) — tek SQL, RRF; engine implement eder (T017). */
+    search(table: string, params?: {
+        query?: string;
+        vector?: number[];
+        where?: Record<string, unknown>;
+        limit?: number;
+        using?: string;
+        mode?: "hybrid" | "text" | "vector";
+        /** Nihai (RRF-sonrası) skor alt eşiği (FR-001). */
+        minScore?: number;
+        /** RRF-sonrası üstel tazelik çürümesi (FR-004; feed/haber düğmesi). */
+        recency?: {
+            field: string;
+            halfLife: string;
+        };
+        /** Chunk-modunda satır başına en iyi blok sayısı (FR-015). */
+        blocksPerRow?: number;
+        /** @deprecated FR-058: search'ün parametresi DEĞİL — facets() kullanın. */
+        facets?: string[];
+        /** Satır-modunda ts_headline vurgusu: satırlara `_highlight` (FR-025; chunk-modda no-op). */
+        highlight?: boolean;
+        /** Validity'li tabloda zaman penceresi: vars. yalnız güncel; "all" tümü; {asOf} o an (FR-029). */
+        validity?: "all" | {
+            asOf: string;
+        };
+        /** Alan-boost (FR-030): skor * (1 + w·x/(1+x)) — sınırlı çarpan, dış servissiz. */
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Record<string, unknown>[]>;
+    /** 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>>;
+    /**
+     * Update every row the filter matches, in one statement; resolves to them.
+     * An EMPTY filter is refused — a whole-table write is not something to reach
+     * by accident.
+     *
+     * **0 satır dönmesi bir hata değildir, ve BAŞARI da değildir.** Koşullu bir
+     * update'in tamamı burada saklı:
+     *
+     * ```ts
+     * const [row] = await db.updateMany("accounts",
+     *   { id, balance: { gte: amount } },     // koşul WHERE'de
+     *   { balance: decrement(amount) });      // tek statement
+     * if (row === undefined) throw new Conflict("yetersiz bakiye");
+     * ```
+     *
+     * 1 satır = uygulandı. **0 satır = koşul tutmadı** (satır yok ya da bakiye
+     * yetmedi) — ikisini ayıran tek şey dönen dizidir. Çağrı hata fırlatmadı diye
+     * işlem oldu SAYILAMAZ; kontrol çağıranın işi.
+     */
+    updateMany(table: string, where: Record<string, unknown>, set: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    /**
+     * Bir idempotency anahtarını sahiplen (FR-033).
+     *
+     * `{ inserted: true, row }` bu çağrı yazdı; `{ inserted: false, row }` başkası
+     * önce yazdı ve dönen satır ONUN satırı. İkisi de BAŞARILI sonuçtur —
+     * "zaten vardı" bir hata değil, idempotency'nin tanımıdır.
+     *
+     * `unique` satırı BULAN alanlar, `extra` yalnız yazılanlar. Ayrım şart:
+     * ikinci çağrı farklı bir yük gönderirse satır yine anahtarla bulunur.
+     *
+     * Altında `ON CONFLICT` YOKTUR — ölçüldü (pg16): `DO UPDATE` ikincinin
+     * verisiyle birincininkini EZER (10.00 → 999.00), `DO NOTHING` hiçbir satır
+     * DÖNDÜRMEZ. Plain INSERT + 23505 yakalama, birincinin satırını koruyan
+     * tek dal.
+     */
+    /**
+     * Bu satırları kilitle — sırayı KATMAN koyar (FR-035).
+     *
+     * Uygulama dokunacağı kümeyi önden bildirir; hangi sırayla kilitleneceğine
+     * katman karar verir. Çağıranın sırasına güvenmek, iki çağıranın aynı iki
+     * satıra ters sırayla girmesi ve deadlock demektir — `deadlock_timeout`
+     * varsayılanı 1 saniye, yani kaybeden bir saniye bekleyip hata alır.
+     *
+     * `FOR NO KEY UPDATE` — `updateMany`'nin CTE'siyle aynı mod.
+     */
+    lockRows(table: string, ids: readonly string[]): Promise<void>;
+    /**
+     * Bir ADI kilitle — satırı değil (FR-054). Kilitlenecek satırı olmayan
+     * işler için ("aynı anda tek bir fatura kapanışı koşsun").
+     *
+     * YALNIZ transaction kapsamlı: commit/rollback'te Postgres bırakır. Oturum
+     * kapsamlı sürüm bağlantı havuza dönerken kilit üstünde kalacağı için
+     * SUNULMUYOR — bir sonraki isteği hiç bitmeyecek şekilde bekletirdi.
+     */
+    advisoryXactLock(key: string): Promise<void>;
+    claim(table: string, unique: Record<string, unknown>, extra?: Record<string, unknown>): Promise<{
+        inserted: boolean;
+        row: Record<string, unknown>;
+    }>;
+    /** Delete every row the filter matches; resolves to how many. Empty filter
+     * refused, for the same reason and more so. */
+    deleteMany(table: string, where: Record<string, unknown>): Promise<number>;
+    /** How many rows match — the half of pagination limit/offset cannot supply.
+     * An empty filter is legitimate here: counting is a read. */
+    count(table: string, where?: Record<string, unknown>): Promise<number>;
+    /** Filtre + sıralama + sayfa. `offset` yalnız `limit` ile birlikte geçerlidir
+     * (limitsiz offset sayfa değildir; motor adıyla reddeder — FR-004). */
+    findMany(table: string, query?: Record<string, unknown>, opts?: {
+        orderBy?: {
+            column: string;
+            direction?: "asc" | "desc";
+        };
+        limit?: number;
+        offset?: 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?: {
+        limit?: number;
+        where?: Record<string, unknown>;
+        minScore?: number;
+        blocksPerRow?: number;
+        validity?: "all" | {
+            asOf: string;
+        };
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Record<string, unknown>[]>;
+    /** D-021 (FR-027): kolon sayaçları bağımsız dönüşle — search'ün dizi-üstü
+     * `_facets` özelliği serileşmede kaybolur; ciddi sözleşme budur. */
+    facets(table: string, params: {
+        facets: string[];
+        where?: Record<string, unknown>;
+        validity?: "all" | {
+            asOf: string;
+        };
+    }): Promise<Record<string, {
+        value: string | null;
+        count: number;
+    }[]>>;
+    /** Çok-örnekli öneri (FR-023): avg(pos) + (avg(pos) − avg(neg)); positive'ler sonuç dışı. */
+    recommend(table: string, opts: {
+        positive: string[];
+        negative?: string[];
+        limit?: number;
+        where?: Record<string, unknown>;
+        minScore?: number;
+        blocksPerRow?: number;
+        validity?: "all" | {
+            asOf: string;
+        };
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Record<string, unknown>[]>;
+}
+/** Database client interface injected into endpoint context. */
+interface DBClient extends DBOps {
+    /**
+     * Run a whole transaction as ONE plan, executed on the request's own
+     * transaction inside a savepoint.
+     *
+     * The low-level seam behind `Database.$transaction(plan)`: the SDK builds the
+     * plan, this sends it, and the broker executes every operation inside a single
+     * transaction that commits or rolls back before the response is written.
+     * Nothing pins a Postgres backend across round trips, because there is only
+     * one round trip.
+     *
+     * 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.
+     */
+    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
+     * `Database.*` path is RLS-enforced. The returned client exposes the same op
+     * surface (`query`/`insert`/.../`txPlan`) but never re-exposes `asService`
+     * (no double-bypass).
+     */
+    asService(): Omit<DBClient, "asService">;
+}
+/** Logger interface injected into endpoint context. */
+interface Logger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+/**
+ * Cache client interface injected into endpoint context.
+ *
+ * The cache is JSON-typed: values are serialized to/from JSON, so any JSON
+ * value (objects, arrays, numbers, booleans, strings) round-trips. `get<T>`
+ * therefore returns `T | null` rather than `string | null`.
+ */
+/**
+ * The tenant's secrets, as a controller sees them.
+ *
+ * `get` answers null for a name this tenant has not set — including every name
+ * the STACK holds, which is not an accident of storage but the shape of the
+ * surface: the runtime is handed a tenant client, and there is no route that
+ * returns a platform secret's value at all. Tenant code cannot read the keys
+ * the stack signs with, by mistake or on purpose.
+ *
+ * Reads are cheap. The value is held in the process and dropped when the deploy
+ * pointer reports a new secrets generation, so a rotated secret arrives without
+ * a restart and a hot path pays a map lookup.
+ */
+interface SecretsService {
+    /**
+     * A secret's value, or `null` when this backend's vault holds no value under
+     * that name.
+     *
+     * The name is a `PalbaseSecretName`, not a `string`: it comes from the
+     * generated `palbase-stack.d.ts`, so a secret the stack does not hold cannot
+     * be spelled here at all. THE GATE IS THE COMPILER.
+     *
+     * That gate replaced a declaration. `config/secrets.ts` used to restate, in
+     * the repo, names the vault already held, and the push compared the two lists
+     * — a check that only ran at deploy, and only if the author remembered to
+     * declare. The type runs on every keystroke and cannot be forgotten.
+     */
+    get(name: PalbaseSecretName): Promise<string | null>;
+}
+interface CacheClient {
+    /** Read a value. Returns `null` on a cache miss. */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** Write a JSON-serializable value with an optional TTL (seconds). */
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    /** Delete a key. */
+    del(key: string): Promise<void>;
+    /** Atomically increment an integer counter, returning the new value. */
+    incr(key: string): Promise<number>;
+    /**
+     * Stampede-safe read-through cache fill. On a hit, returns the cached value.
+     * On a miss, a single caller (across all pod replicas, coordinated by a
+     * distributed lock) runs `fn`, caches the result for `ttl` seconds, and
+     * returns it; concurrent callers wait for that result instead of also
+     * running `fn`. If no value lands within the lock's TTL, the call rejects —
+     * it does NOT run `fn` on timeout (that would reintroduce the stampede).
+     *
+     * @param ttl value TTL in seconds.
+     */
+    getOrSet<T>(key: string, ttl: number, fn: () => Promise<T> | T): Promise<T>;
+}
+/** Result envelope used across the Palbase Server SDK clients. */
+interface PalbaseResult<T> {
+    data: T | null;
+    error: {
+        message?: string;
+        code?: string;
+    } | null;
+    status?: number;
+}
+/** Document snapshot returned by docs.get(). */
+interface PalbaseDocumentSnapshot<T = Record<string, unknown>> {
+    id: string;
+    exists: boolean;
+    data(): T | undefined;
+    ref: {
+        path: string;
+    };
+}
+/** Collection query snapshot returned by collection.get(). */
+interface PalbaseQuerySnapshot<T = Record<string, unknown>> {
+    docs: PalbaseDocumentSnapshot<T>[];
+    empty: boolean;
+    size: number;
+    /** Firestore-shaped change list. Every document of a one-shot read is "added". */
+    docChanges(): Array<{
+        type: "added";
+        doc: PalbaseDocumentSnapshot<T>;
+    }>;
+}
+/** Comparison operators supported by docs.where(). */
+type PalbaseWhereOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "array-contains";
+/** Document reference exposed by Documents.collection(...).doc(...). */
+interface PalbaseDocumentRef<T = Record<string, unknown>> {
+    readonly path: string;
+    set(data: T): Promise<PalbaseResult<void>>;
+    get(): Promise<PalbaseResult<PalbaseDocumentSnapshot<T>>>;
+    update(data: Partial<T>): Promise<PalbaseResult<void>>;
+    delete(): Promise<PalbaseResult<void>>;
+    /** A subcollection of this document — `rooms/1` → `rooms/1/messages`. */
+    collection<C extends Record<string, unknown> = Record<string, unknown>>(name: string): PalbaseCollectionRef<C>;
+}
+/** Collection reference exposed by Documents.collection(...). */
+interface PalbaseCollectionRef<T = Record<string, unknown>> {
+    readonly path: string;
+    doc(id: string): PalbaseDocumentRef<T>;
+    add(data: T): Promise<PalbaseResult<PalbaseDocumentRef<T>>>;
+    where(field: string, op: PalbaseWhereOperator, value: unknown): PalbaseCollectionRef<T>;
+    orderBy(field: string, direction?: "asc" | "desc"): PalbaseCollectionRef<T>;
+    limit(n: number): PalbaseCollectionRef<T>;
+    get(): Promise<PalbaseResult<PalbaseQuerySnapshot<T>>>;
+}
+/** Docs client surface available on the Documents singleton. */
+interface PalbaseDocsClient {
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(path: string): PalbaseCollectionRef<T>;
+    doc<T extends Record<string, unknown> = Record<string, unknown>>(path: string): PalbaseDocumentRef<T>;
+    /**
+     * Apply up to 500 writes in one call.
+     *
+     * Declared here because the client has always offered it: an interface that
+     * described less than the implementation is how `Documents.doc(...)` came to
+     * be declared and never implemented — the gap this whole move exists to close.
+     */
+    batch(operations: Array<{
+        op: "set" | "update" | "delete";
+        ref: {
+            path: string;
+        };
+        data?: unknown;
+    }>): Promise<PalbaseResult<void>>;
+}
+/** Calling-client metadata, derived from request headers.
+ *
+ * Every header is named here, because the previous version of this comment named
+ * only two of the four and the next reader invented `X-Palbase-Platform` for the
+ * third. The four are canonical across the platform — the same names the Go
+ * side reads in user-flags/internal/middleware/clientcontext.go — and the deploy
+ * gate REFUSES an `@Headers` schema that declares an `x-palbase-*` key, which
+ * makes `@Client()` the only sanctioned way to read them.
+ *
+ * All fields are nullable: a request may come from a non-SDK caller (curl,
+ * server-to-server) that sends none of them. Note that the web SDK does not
+ * send `X-Palbase-Sdk-Version` at all, so `sdkVersion` is null for every browser
+ * caller. The semver comparison helpers (`appVersionAtLeast`, …) arrive in
+ * Phase 2 — Phase 1 surfaces only the raw data fields. */
+interface ClientInfo {
+    /** Palbase SDK version (`X-Palbase-Sdk-Version`), or null. */
+    sdkVersion: string | null;
+    /** Calling app's own version (`X-Palbase-Client-Version`), or null. */
+    appVersion: string | null;
+    /** Platform identifier (`X-Platform`, e.g. "ios", "android", "web"), or null. */
+    platform: string | null;
+    /** OS version string (`X-OS-Version`), or null. */
+    osVersion: string | null;
+}
+/** Palbase module clients, as a structural bundle.
+ *
+ * NOT part of the endpoint surface anymore — endpoint handlers reach services
+ * via the PascalCase singletons (`Database`, `Documents`, …). This type is
+ * retained as an INTERNAL shape for the sibling contexts that still carry a
+ * `ctx` (middleware, jobs, workers, hooks, webhooks — out of Phase 1 scope).
+ * It is intentionally not re-exported from `index.ts`.
+ *
+ * Structurally typed against the runtime's `ServerClient`; the runtime injects
+ * the real client, so mismatched names would surface as `undefined is not a
+ * function` at call time — keep these in sync with `ServerClient`. */
+interface PalbaseModuleClients {
+    auth: PalbaseAuthClient;
+    storage: PalbaseStorageClient;
+    docs: PalbaseDocsClient;
+    realtime: PalbaseRealtimeClient;
+    functions: PalbaseFunctionsClient;
+    flags: PalbaseFlagsClient;
+    notifications: PalbaseNotificationsClient;
+    analytics: PalbaseAnalyticsClient;
+    links: PalbaseLinksClient;
+}
+/** Declared-error definition.
+ *
+ * `code` is the stable snake_case identifier that lands on the wire envelope's
+ * `error` field. `status` is the HTTP status code returned. `data`, if set,
+ * is a Zod schema whose value rides on the envelope's `data` field — the CLI
+ * codegen lowers it to the typed enum's associated value on iOS.
+ *
+ * `description` is optional human-readable text; the OpenAPI generator uses it
+ * for the response description and the iOS codegen surfaces it in the
+ * generated method's doc-comment.
+ */
+interface ErrorDef<TData extends ZodSchema = ZodSchema> {
+    status: number;
+    code: string;
+    description?: string;
+    data?: TData;
+}
+/** Map of declared errors keyed by their TypeScript-side names.
+ *
+ * Keys are the friendly names the handler uses (`req.errors.todoLocked`);
+ * `code` on each value is the wire identifier. The TS name is what the iOS
+ * codegen lowers to (camelCase enum cases), and the wire `code` is what the
+ * envelope's `error` field carries.
+ */
+type ErrorMap = Record<string, ErrorDef>;
+/** Throwable proxy projected onto `req.errors` when `errors` is declared.
+ *
+ * Each entry is a constructor: declared errors with a `data` schema demand
+ * the payload as a required argument; declared errors without `data` take
+ * none. Throwing the result emits the standard envelope (with `data` when
+ * present).
+ *
+ *   throw req.errors.todoNotFound();
+ *   throw req.errors.todoLocked({ retryAfter: 30 });
+ */
+type ErrorThrowers<TErrors extends ErrorMap | undefined> = TErrors extends ErrorMap ? {
+    [K in keyof TErrors]: TErrors[K]["data"] extends ZodSchema ? (data: z.infer<NonNullable<TErrors[K]["data"]>>) => HttpError : () => HttpError;
+} : Record<string, never>;
+/** The request-scoped object passed to every endpoint handler.
+ *
+ * Replaces the old `ctx` god-object. `PBRequest` carries ONLY request-scoped
+ * data — the typed `input`, route/query params, headers, the authenticated
+ * `user`, calling-client metadata, trace ids, and the endpoint's declared
+ * error throwers. Services (`Database`, `Documents`, `Cache`, …) are NOT on
+ * the request: import them directly from `@palbase/backend` as singletons.
+ *
+ *   import { Controller, Get, Req, Database } from "@palbase/backend";
+ *
+ *   \@Controller("/todos")
+ *   export class TodosController {
+ *     \@Get("") list(\@Req() req: PBRequest): unknown {
+ *       return Database.$findMany("todos");
+ *     }
+ *   }
+ *
+ * Most controller methods reach individual request slices via their own
+ * parameter decorator (`@Body`/`@QueryParams`/`@Param`/`@User`/…); `@Req()` is the
+ * escape hatch that injects this whole object.
+ *
+ * Generic parameters:
+ * - `TInput` — the validated `input` type (the `@Body` schema's `z.infer`). The
+ *   user-facing form is single-generic: `PBRequest<TodoInput>`.
+ * - `TAuthed` — whether `user` is non-null. DEFAULTS to `true` (the common
+ *   case; the auth pipeline returns 401 before the handler when auth is
+ *   required, so a non-null `user` is runtime-honest). A route whose effective
+ *   auth is `false` yields `User | null`.
+ * - `TErrors` — RETAINED for back-compat of the `errors` thrower shape; the
+ *   class-controller model throws global error classes
+ *   (`Conflict`/`NotFound`/…) instead, so `req.errors` is empty in practice.
+ */
+interface PBRequest<TInput = unknown, TAuthed extends boolean = true, TErrors extends ErrorMap | undefined = undefined> {
+    /** Validated request input (body for POST/PUT/PATCH; `{}` otherwise). */
+    input: TInput;
+    /** Matched route params (e.g. `{ id }` for `/todos/[id]`). */
+    params: Record<string, string>;
+    /** Parsed query-string params. */
+    query: Record<string, string>;
+    /** Request headers (lowercase keys). */
+    headers: Record<string, string>;
+    /** Authenticated user. Non-null (`User`) by default; `User | null` only when
+     * the route's effective auth disables enforcement (driven by `TAuthed`, which
+     * the runtime resolves from the route/controller `auth` cascade via
+     * {@link IsAuthed}). */
+    user: TAuthed extends true ? User : User | null;
+    /** Calling-client metadata derived from request headers (all nullable). */
+    client: ClientInfo;
+    /** Uploaded file, or null when the request has no file part. */
+    file: FileContext | null;
+    /** HTTP method of the incoming request (e.g. "GET", "POST"). */
+    method: string;
+    /** Per-request id (`req_<…>`), preserved for back-compat correlation. */
+    requestId: string;
+    /** W3C trace id (primary correlation key across modules). */
+    traceId: string;
+    /** W3C span id for this handler invocation. */
+    spanId: string;
+    /** Typed throwers for the endpoint's declared errors. RETAINED for the
+     * `@Req()` escape-hatch shape; the class-controller model throws global error
+     * classes (`Conflict`/`NotFound`/…) instead, so this is empty in practice. */
+    errors: ErrorThrowers<TErrors>;
+}
+/** Middleware function signature — uses MiddlewareContext (no input, not yet validated). */
+type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+/** The shape an endpoint's `auth` config may take.
+ *
+ * Either a bare boolean (`true`/`false`) or an object form (`{ required?,
+ * role? }`). The object form is `Partial<AuthConfig>` so `required` may be
+ * omitted — which the runtime treats as `required: true` (see {@link IsAuthed}).
+ */
+type AuthSpec = boolean | Partial<AuthConfig>;
+
+export { Notifications as $, type AuthSpec as A, BadRequest as B, type CacheClient as C, type DBClient as D, EXTENSION_DEPENDENCIES as E, type ErrorThrowers as F, type FileContext as G, HttpError as H, Flags as I, Forbidden as J, type HttpMethod as K, IndexBuilder as L, type IndexDef as M, type InsertShape as N, type LifecycleHook as O, type PalbaseResult as P, Log as Q, type RateLimitConfig as R, type SchemaDef as S, type TxPlanBody as T, type Logger as U, type Materialized as V, type Middleware as W, type MiddlewareContext as X, type MiddlewareHandler as Y, NotFound as Z, __runWithRuntime as _, type DBOps as a, type PalbaseListOptions as a$, type OnDeleteAction as a0, PALBASE_EXTENSIONS as a1, type PBRequest as a2, PalError as a3, type PalbaseAnalyticsClient as a4, type PalbaseAnalyticsManagementNamespace as a5, type PalbaseAnalyticsProperties as a6, type PalbaseAnalyticsQueryNamespace as a7, type PalbaseAttestAndroidParams as a8, type PalbaseAttestAndroidResult as a9, type PalbaseExtension as aA, type PalbaseFileObject as aB, type PalbaseFlag as aC, type PalbaseFlagContext as aD, type PalbaseFlagSource as aE, type PalbaseFlagValue as aF, type PalbaseFlagVariant as aG, type PalbaseFlagsClient as aH, type PalbaseFlagsServiceClient as aI, type PalbaseFunctionsClient as aJ, type PalbaseFunnelQueryInput as aK, type PalbaseFunnelResult as aL, type PalbaseIdentifyTraits as aM, type PalbaseInboxClient as aN, type PalbaseInboxListOptions as aO, type PalbaseInboxListResult as aP, type PalbaseInboxMessage as aQ, type PalbaseInboxSendParams as aR, type PalbaseInboxSendResponse as aS, type PalbaseInitialLink as aT, type PalbaseInvokeOptions as aU, type PalbaseLink as aV, type PalbaseLinkAnalytics as aW, type PalbaseLinkDetails as aX, type PalbaseLinksClient as aY, type PalbaseListLinksOptions as aZ, type PalbaseListLinksResult as a_, type PalbaseAttestiOSParams as aa, type PalbaseAttestiOSResult as ab, type PalbaseAuthClient as ac, type PalbaseBatchOverrideOperation as ad, type PalbaseBatchSetOverridesResult as ae, type PalbaseBindDeviceParams as af, type PalbaseBucketClient as ag, type PalbaseClearAllOverridesResult as ah, type PalbaseClearOverrideResult as ai, type PalbaseCohortQueryInput as aj, type PalbaseCohortResult as ak, type PalbaseCollectionRef as al, type PalbaseCountQueryInput as am, type PalbaseCountResult as an, type PalbaseCreateLinkParams as ao, type PalbaseDeviceInfo as ap, type PalbaseDeviceTokenView as aq, type PalbaseDocsClient as ar, type PalbaseDocumentRef as as, type PalbaseDocumentSnapshot as at, type PalbaseEmailClient as au, type PalbaseEmailSendParams as av, type PalbaseEmailSendResponse as aw, type PalbaseEventNamesResult as ax, type PalbaseEventsQueryInput as ay, type PalbaseEventsResult as az, type TxPlanResponse as b, TxPlanError as b$, type PalbaseMatchParams as b0, type PalbaseMultiChannelResponse as b1, type PalbaseNotificationsClient as b2, type PalbaseOverviewResult as b3, type PalbasePreferences as b4, type PalbasePreferencesClient as b5, type PalbasePushClient as b6, type PalbasePushSendParams as b7, type PalbasePushSendResponse as b8, type PalbaseQrCodeOptions as b9, type PolicyExprCtx as bA, PolicyExprRef as bB, type PolicyMode as bC, type PolicyOperand as bD, type RawConstraintDef as bE, Realtime as bF, type Ref as bG, type RequestStore as bH, type RowShape as bI, Secrets as bJ, type SecretsService as bK, SerializationFailure as bL, type SetShape as bM, type SetValue as bN, type ShutdownRunner as bO, type SqlFragment as bP, Storage as bQ, TABLE_META as bR, type TableDef as bS, type TableHandle as bT, type TableInput as bU, TooManyRequests as bV, type TxColumnExpr as bW, type TxInsertShape as bX, type TxInsertValue as bY, type TxNow as bZ, type TxPlan as b_, type PalbaseQuerySnapshot as ba, type PalbaseRealtimeClient as bb, type PalbaseRegisterDeviceParams as bc, type PalbaseRetentionQueryInput as bd, type PalbaseRetentionResult as be, type PalbaseSession as bf, type PalbaseSetOverrideResult as bg, type PalbaseSetOverridesResult as bh, type PalbaseSignedUrlResponse as bi, type PalbaseSmsClient as bj, type PalbaseSmsSendParams as bk, type PalbaseSmsSendResponse as bl, type PalbaseStorageClient as bm, type PalbaseTransformOptions as bn, type PalbaseUpdateLinkParams as bo, type PalbaseUploadOptions as bp, type PalbaseUser as bq, type PalbaseUserDetailResult as br, type PalbaseUsersQueryInput as bs, type PalbaseUsersResult as bt, type PalbaseVerifyRequestSignatureParams as bu, type PalbaseWhereOperator as bv, type PolicyBinOp as bw, PolicyBuilder as bx, type PolicyCommand as by, type PolicyDef as bz, type RuntimeServices as c, type TxPlanHandle as c0, type TxPlanOpResult as c1, type TxPlanRejection as c2, TxRefError as c3, type TxRow as c4, type TxRows as c5, type TxSelectOptions as c6, type TxSetShape as c7, type TxSetValue as c8, type TxTable as c9, enumType as cA, exprCtx as cB, inc as cC, increment as cD, index as cE, installationRef as cF, integer as cG, isPalbaseExtension as cH, isRetryable as cI, jsonb as cJ, makeTypedDB as cK, now as cL, numeric as cM, onShutdown as cN, onStart as cO, openai as cP, ownedByUser as cQ, policy as cR, raw as cS, sqlFragment as cT, text as cU, timestamp as cV, userRef as cW, uuid as cX, vector as cY, withRetry as cZ, type TxTables as ca, type TxWhere as cb, type TxWireExpr as cc, type TxWireGuard as cd, type TxWireOp as ce, type TxWireRef as cf, type TxWireValue as cg, type TypedDB as ch, type TypedTable as ci, type TypedTx as cj, Unauthorized as ck, UniqueViolation as cl, type User as cm, type VerifiedDevice as cn, __getRuntime as co, __resetLifecycleHooks as cp, __runStartHooks as cq, __setRuntime as cr, bigint as cs, boolean as ct, col as cu, dec as cv, decrement as cw, defineMiddleware as cx, defineSchema as cy, defineTable as cz, __requestALS as d, type PolicyExpr as e, type AnyColumn as f, type AuthConfig as g, Cache as h, type ClientInfo as i, type ColRef as j, ColumnBuilder as k, type ColumnDef as l, type ColumnMap as m, type ColumnType as n, Conflict as o, Database as p, DeadlockDetected as q, Documents as r, type EmbeddingModelRef as s, type EnvSchemas as t, type EnvServiceDatabase as u, type EnvTables as v, type EnvTypedDatabase as w, type EnvTypedTable as x, type ErrorDef as y, type ErrorMap as z };