@palbase/backend 22.1.0 → 23.1.0

package/dist/{index-vwHoS0l2.d.ts → index-CwAJ7HEe.d.ts}

@@ -1,5 +1,5 @@
 import { Tables, TableTypes } from './db/env.js';
-import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-BVT6jcVW.js';
+import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-CVWXh6oG.js';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -36,6 +36,17 @@ interface ColumnDef {
     enumName?: string;
     enumValues?: string[];
     unique?: boolean;
+    /**
+     * The value is written by the DATABASE — a trigger, a rule, an identity — not by
+     * the author and not by a DEFAULT this schema declares. It makes the column
+     * optional on INSERT without putting a DEFAULT in the DDL.
+     *
+     * Before this existed the only way to keep a trigger-filled column off the
+     * INSERT type was to give it a fake `default()`: a value the schema claimed to
+     * write and the trigger immediately overwrote. That made the schema lie about
+     * its own data.
+     */
+    dbAssigned?: boolean;
     /** vector(n): the declared dimension count — part of the TYPE (typmod), read
      * by the wire serializer and the deploy's auto-index (FR-001). */
     dimensions?: number;
@@ -80,6 +91,18 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
     defaultRandom(): ColumnBuilder<K, N, true, E, P>;
     /** Timestamp: default to now(). */
     defaultNow(): ColumnBuilder<K, N, true, E, P>;
+    /**
+     * The DATABASE assigns this column's value — a trigger, a rule, an identity.
+     *
+     * The column becomes optional on INSERT (the author has nothing to send) while
+     * the DDL stays free of a DEFAULT this schema would not honour. It is NOT
+     * `default()`: that declares a value the schema promises to write.
+     *
+     * Naming: deliberately not `generated()`. Postgres has GENERATED columns and
+     * they are a different thing; borrowing the word would send a reader — or a
+     * model writing a schema — to the wrong feature.
+     */
+    dbAssigned(): ColumnBuilder<K, N, true, E, P>;
     /** Add a foreign key reference. */
     /**
      * Declares that this column used to be called `previous`.
@@ -247,22 +270,6 @@ interface PolicyDef {
     withCheck: string | null;
     permissive: boolean;
 }
-/**
- * Fluent RLS policy builder.
- *
- * Defaults (documented, applied at construction):
- *  - `command`: `"all"` — applies to every SQL command unless `.for(...)` narrows it.
- *  - `roles`: `["authenticated"]` — the common case is "rule applies to signed-in
- *    users". Call `.to(...)` to override; pass `.to()` with no roles (or never
- *    call it after a reset) to target PUBLIC.
- *  - `using` / `withCheck`: `null` — no row filter / write check until set.
- *  - `permissive`: `true` — `AS PERMISSIVE` (policies OR together).
- *
- * Each method mutates `_def` in place and returns `this`, so the chain is a
- * single builder instance (no per-call allocation, like a tagged-template
- * compile target). The terminal `PolicyDef` is read directly off `_def` by
- * `schema_extract.js`.
- */
 declare class PolicyBuilder {
     readonly _def: PolicyDef;
     constructor(name: string);
@@ -280,6 +287,34 @@ declare class PolicyBuilder {
     to(...roles: string[]): this;
     /** Set the `USING (...)` row-visibility expression (raw SQL). */
     using(sqlExpr: string): this;
+    /**
+     * "Rows of THIS table whose owner the caller is a member of" — the membership
+     * pattern, written so it cannot recurse.
+     *
+     * THE TRAP IT EXISTS FOR. Written by hand, membership policies point at each
+     * other: `channels` is visible to members, so its policy reads
+     * `channel_members`; `channel_members` is visible to members, so its policy
+     * reads `channels`. Postgres refuses the pair at query time with `infinite
+     * recursion detected in policy for relation ...`, and the error names the
+     * relation but not the cycle. The way out is asymmetry — the MEMBERSHIP table
+     * is protected by `user_id = auth.uid()` and nothing else, and every other
+     * table subqueries INTO it. That shape was in the platform's own schema and
+     * written down nowhere; a customer recovered it by reading that schema.
+     *
+     * `(select auth.uid())` rather than a bare call: the scalar subquery is
+     * evaluated ONCE per statement instead of per row.
+     *
+     * @example
+     * // channels: visible to members. The membership table gets the simple one.
+     * policy("member_read").for("select").to("authenticated")
+     *   .memberOf("channel_members", "channel_id")
+     * // → id IN (SELECT "channel_id" FROM "channel_members"
+     * //          WHERE "user_id" = (select auth.uid()))
+     */
+    memberOf(membershipTable: string, foreignKey: string, options?: {
+        column?: string;
+        userColumn?: string;
+    }): this;
     /** Set the `WITH CHECK (...)` write-validation expression (raw SQL). */
     withCheck(sqlExpr: string): this;
     /** Set the policy mode: `"permissive"` (default, OR-combined) or
@@ -347,12 +382,20 @@ interface EmbeddingModelRef {
     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;
 };
 
 /**
@@ -400,12 +443,44 @@ interface VectorSearchDecl {
      *   eşleşme riski (Confluence-tipi sync yükleri için). */
     staleness?: "null" | "keep";
 }
-/** Tablonun arama beyanı. `text`: FTS kolonları (sabit 'simple' sözlük, D-4 — palbase_fts + GIN türetilir).
- * `vector`: bir ya da birden çok ANN kolu. İkisi de opsiyonel; blok yoksa tablo yine
- * vector kolonu varlığıyla aranabilir (D-3/FR-013). */
+/** 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[];
+    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;
 }
 interface TableInput<C extends ColumnMap = ColumnMap> {
     columns: C;
@@ -448,6 +523,8 @@ interface TableInput<C extends ColumnMap = ColumnMap> {
     }[];
     /** 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`
@@ -485,6 +562,8 @@ interface TableDef<C extends ColumnMap = ColumnMap> {
     }[];
     /** 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.
@@ -603,6 +682,9 @@ type RowShape<T extends TableDef> = {
 /** A typed table accessor that mirrors the runtime DBClient surface. */
 interface TypedTable<T extends TableDef> {
     insert(data: InsertShape<T>): Promise<RowShape<T>>;
+    upsert(data: InsertShape<T>, opts: {
+        onConflict: readonly string[];
+    }): Promise<RowShape<T>>;
     /** Update the row by id; resolves to the updated row, or `null` if no row
      * matched (absent or RLS-hidden) — an idempotent outcome, mirroring
      * `findById`. The runtime returns a null row rather than throwing. */
@@ -662,10 +744,65 @@ interface SearchParamsTyped<T extends TableTypes> {
     /** 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;
+    };
+    /** Filtrelenmiş küme üzerinde kolon başına top-20 değer sayacı — dönüş
+     * dizisinin `_facets` özelliği (FR-027). */
+    facets?: Extract<keyof T["row"], 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;
+    };
 }
+/** search() dönüş dizisinin sorgu-düzeyi ekleri (FR-027): `_facets` dizinin
+ * ÖZELLİĞİDİR, satırlara kopyalanmaz (JSON'a satır başına şişme olmasın). */
+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[];
+};
 /** Temel tablo erişimcisi — search'süz beş op. */
 interface EnvTypedTableBase<T extends TableTypes> {
     insert(data: T["insert"]): Promise<T["row"]>;
+    /**
+     * Insert the row, or update it when it collides on `onConflict`.
+     *
+     * The conflict columns must carry a unique constraint or index — that is what
+     * Postgres matches on — and they are excluded from the update, since they are
+     * what matched.
+     */
+    upsert(data: T["insert"], opts: {
+        onConflict: readonly Extract<keyof T["row"], string>[];
+    }): Promise<T["row"]>;
     /** Update the row by id; resolves to the updated row, or `null` if no row
      * matched (absent or RLS-hidden) — an idempotent outcome, mirroring
      * `findById`. The runtime returns a null row rather than throwing. */
@@ -673,6 +810,11 @@ interface EnvTypedTableBase<T extends TableTypes> {
     delete(id: string): Promise<void>;
     findById(id: string): Promise<T["row"] | null>;
     findMany(query?: Partial<T["row"]>): Promise<T["row"][]>;
+    /** 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
@@ -682,6 +824,18 @@ type EnvTypedTable<T extends TableTypes> = EnvTypedTableBase<T> & (T extends {
 } ? {
     search(params: SearchParamsTyped<T>): Promise<Array<T["row"] & {
         _score: number;
+    }> & {
+        _facets?: SearchFacets;
+    }>;
+    /** "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;
+    }>>;
+    /** 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`
@@ -750,6 +904,27 @@ interface EnvTypedDatabase extends Omit<DBClient, "txPlan" | "asService"> {
      * });
      */
     transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
+    /**
+     * Run `fn` inside a SAVEPOINT, so a write that fails in it does not poison the
+     * rest of the request.
+     *
+     * A request is ONE Postgres transaction: a failed statement aborts it and
+     * every later one answers `current transaction is aborted`. That is why
+     * "insert, catch the unique violation, update instead" cannot be written
+     * directly — and why {@link EnvTypedTableBase.upsert} exists for the common
+     * case. Reach for `attempt` when the recovery is not an upsert.
+     *
+     * The handle is a parameter, not the ambient `Database`: only what `tx` writes
+     * is inside the boundary, so a concurrent branch of the same request cannot be
+     * rolled back by someone else's failure.
+     *
+     * @example
+     * const claimed = await Database.attempt(async (tx) => {
+     *   await tx.insert("seats", { row: 4, seat: 12, user_id: user.id });
+     *   return true;
+     * }).catch(() => false);
+     */
+    attempt<T>(fn: (tx: Omit<DBClient, "attempt" | "txPlan" | "asService">) => Promise<T>): Promise<T>;
     /**
      * Return a sibling that bypasses RLS by running as the `service_role`. Use
      * sparingly and explicitly — the default `Database.*` path is RLS-enforced.

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

@@ -1,63 +1,8 @@
-import { Buckets, BucketTypes } from './db/env.js';
+import { Buckets, BucketTypes } from './stack.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, T as TxPlanBody, f as TxPlanResponse } from './endpoint-BVT6jcVW.js';
-import { E as EnvTypedDatabase } from './index-vwHoS0l2.js';
-import { R as RouteMeta } from './registry-Bsuf-orT.js';
-
-/**
- * The purchases surface the decorators need, declared as a NARROW STRUCTURAL
- * interface rather than an import of `@palstore/purchases`.
- *
- * `PurchasesClient` (palstore's `sk_` backend SDK) satisfies this shape as-is,
- * so the runtime injects the real client with no adapter — but `@palbase/backend`
- * itself gains no dependency on it. That matters: this package is published
- * public and baked into the br-pod image from a tarball, so a dependency on an
- * unpublished sibling would break `npm install palbase-backend.tgz`. It is also
- * the pattern `withSpend` already uses for the same reason (`SpendCapableClient`
- * in palstore's own spend.ts: "a narrow structural interface … so this file has
- * no dependency on client.ts").
- *
- * The methods here are a SUBSET of `PurchasesClient` — only what the two
- * decorators call. Grants, refunds, credits and customer-info reads stay off
- * this interface: a tenant that wants them imports the palstore SDK directly.
- */
-/** Store environment a subject is fixed to. Mirrors `StoreEnv` in `@palstore/purchases`. */
-type StoreEnv = "production" | "sandbox";
-/** Quota/credit state carried by a 429. Mirrors `LimitState` in `@palstore/purchases`
- * (SPEC-purchases-v1 §11) — re-declared, not imported, for the reason above. */
-interface LimitState {
-    key: string;
-    scope: string;
-    window: string;
-    used: number;
-    reserved: number;
-    max: number;
-    remaining: number;
-    resetAt: string;
-}
-/** Options for one spend. `idempotencyKey` is required by the server (§9). */
-interface SpendOptions {
-    /** Defaults to 1. */
-    count?: number;
-    idempotencyKey: string;
-}
-interface PurchasesService {
-    /** Map a tenant-side user reference to its palstore subject, creating one on
-     * first sight. Server-authoritative — the caller never names a subject. */
-    resolveSubject(input: {
-        userRef: string;
-        storeEnv: StoreEnv;
-    }): Promise<{
-        subjectId: string;
-    }>;
-    /** Resolve silently when `entitlementKey` is active for `subjectId`; throw
-     * `EntitlementRequiredError` otherwise. Consumes nothing. */
-    require(subjectId: string, entitlementKey: string): Promise<void>;
-    /** Reserve → run `handler` → commit on success, cancel on throw, always
-     * rethrowing the handler's own error. The whole reason the decorators are a
-     * thin layer: this lifecycle is already written and tested in palstore's SDK. */
-    withSpend<T>(subjectId: string, key: string, opts: SpendOptions, handler: () => Promise<T>): Promise<T>;
-}
+import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, f as DBOps, T as TxPlanBody, g as TxPlanResponse } from './endpoint-c9h5jriX.cjs';
+import { E as EnvTypedDatabase } from './index-By8Dle5U.cjs';
+import { R as RouteMeta } from './registry-CqPK2Qby.cjs';
 
 /**
  * runtime.ts — request-scoped service singletons.
@@ -118,7 +63,6 @@ interface RuntimeServices {
     Notifications: PalbaseNotificationsClient;
     Flags: PalbaseFlagsClient;
     Realtime: PalbaseRealtimeClient;
-    Purchases: PurchasesService;
 }
 /**
  * The per-request ALS box.
@@ -239,15 +183,6 @@ declare const Secrets: SecretsService;
 declare const Log: Logger;
 /** Push / email / SMS / in-app notifications. */
 declare const Notifications: PalbaseNotificationsClient;
-/**
- * Palstore purchases (entitlements + quota/credit spend).
- *
- * Reached by handlers through the `@RequireEntitlement` / `@Spend` decorators
- * rather than called directly in the common case; exposed as a singleton for
- * the cases the decorators deliberately do not cover (a dynamic spend count,
- * which must run BEFORE the billable side-effect).
- */
-declare const Purchases: PurchasesService;
 /**
  * Feature flags.
  *
@@ -426,14 +361,41 @@ declare function createLazyTransaction(sql: SqlDriver, role: string, claimsJson:
 type LazyTransaction = ReturnType<typeof createLazyTransaction>;
 /** Either a live driver transaction or the lazy holder above. */
 type TxLike = SqlTx | LazyTransaction;
+/** What `findMany` accepts beside its filter: an ordering and a row ceiling.
+ * Both used to require dropping to raw SQL, and the docs said so — which is how
+ * a tenant's controllers filled up with hand-written SELECTs. */
+interface FindManyOptions {
+    orderBy?: {
+        column: string;
+        direction?: "asc" | "desc";
+    };
+    limit?: number;
+}
 /** The six string-keyed operations, plus an interactive `transaction`. */
 declare function createOps(tx: TxLike): {
     query(sql: string, params?: unknown[]): Promise<Row[]>;
     insert(table: string, data: Row): Promise<Row>;
+    /**
+     * INSERT the row, or UPDATE it when it collides on `onConflict`.
+     *
+     * WHY IT IS AN OPERATION rather than a recipe. "Try the insert, catch the
+     * unique violation, update instead" does not work here: a request runs in ONE
+     * Postgres transaction, so the failed insert aborts it and every later
+     * statement answers `current transaction is aborted`. A tenant measured that
+     * as 7 of 8 concurrent requests returning 500, gave up on upsert, and had a
+     * trigger create the row instead — a workaround that needs a new trigger for
+     * every table with a unique row.
+     *
+     * The conflict columns are excluded from the SET list: they are what MATCHED,
+     * so writing them back is at best a no-op and at worst a surprise.
+     */
+    upsert(table: string, data: Row, opts: {
+        onConflict: readonly string[];
+    }): Promise<Row>;
     update(table: string, id: string, data: Row): Promise<Row | null>;
     delete(table: string, id: string): Promise<void>;
     findById(table: string, id: string): Promise<Row | null>;
-    findMany(table: string, query?: Row): Promise<Row[]>;
+    findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
     /**
      * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
      * (1/(50+rank), CLAIM-N4). Operatör şema-nitelikli (C-10, M-1); GUC
@@ -448,9 +410,117 @@ declare function createOps(tx: TxLike): {
         limit?: number;
         using?: string;
         mode?: "hybrid" | "text" | "vector";
+        /** Nihai (RRF-sonrası) skor alt eşiği — süzme LIMIT'ten ÖNCE (FR-001). */
+        minScore?: number;
+        /** RRF-sonrası üstel tazelik çürümesi: _score * exp(-ln(2)*yaş/halfLife) (FR-004). */
+        recency?: {
+            field: string;
+            halfLife: string;
+        };
+        /** Chunk-modunda satır başına dönen en iyi blok sayısı (1..10, vars. 3; FR-015). */
+        blocksPerRow?: number;
+        /** Filtrelenmiş küme üzerinde kolon başına top-20 değer sayacı —
+         * dönüş dizisinin `_facets` özelliği (FR-027). */
+        facets?: string[];
+        /** Satır-modunda FTS eşleşme vurgusu: ts_headline ile `_highlight`
+         * alanı; 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;
+         * "all" tüm versiyonlar; {asOf} o andaki geçerli versiyon (FR-029). */
+        validity?: "all" | {
+            asOf: string;
+        };
+        /** Alan-boost (FR-030): skor * (1 + w·x/(1+x)) — sınırlı, dış servissiz. */
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Row[]>;
+    /**
+     * similar (T018, FR-022): "bu satıra benzeyenler". Hedef vektör DB'den
+     * okunur — satır-modu satırın kendi kolonu, chunk-modu parent chunk'larının
+     * şema-nitelikli avg'ı — ve ana arama search'ün vector yoluyla koşar;
+     * kaynak satır sonuçtan düşer. İKİ tur BİLİNÇLİ (plan T018): target-CTE'li
+     * tek SQL'de "id yok" ile "0 komşu" ayrılamazdı; +1 küçük turla id-yokluğu
+     * adlandırılmış hataya çevrilir. Sonuç şekli search ile aynı (FR-015).
+     */
+    similar(table: string, id: string, opts?: {
+        where?: Record<string, unknown>;
+        limit?: number;
+        using?: string;
+        minScore?: number;
+        recency?: {
+            field: string;
+            halfLife: string;
+        };
+        blocksPerRow?: number;
+        validity?: "all" | {
+            asOf: string;
+        };
+        boost?: {
+            field: string;
+            weight: number;
+        };
     }): Promise<Row[]>;
+    /**
+     * recommend (T018, FR-023): positive/negative id kümelerinden öneri.
+     * Hedef vektör DB-İÇİ CTE'lerle türer: pos = avg(embedding of positives),
+     * negative varsa hedef = pos.v + (pos.v - neg.v) — pgvector avg agregası
+     * ve +/- operatörleri ŞEMA-NİTELİKLİ (M-1: search_path'e güvenilmez).
+     * Vektör matematiği istemciye inmez; bulunamayan positive/negative
+     * adlandırılmış hatadır ve kaynak id'ler sonuçtan düşer.
+     */
+    recommend(table: string, opts: {
+        positive: unknown[];
+        negative?: unknown[];
+        where?: Record<string, unknown>;
+        limit?: number;
+        using?: string;
+        minScore?: number;
+        recency?: {
+            field: string;
+            halfLife: string;
+        };
+        blocksPerRow?: number;
+        validity?: "all" | {
+            asOf: string;
+        };
+        boost?: {
+            field: string;
+            weight: number;
+        };
+    }): Promise<Row[]>;
+    /**
+     * supersede (T021, FR-029, C-9): validity'li tabloda satırın YENİ
+     * versiyonunu TEK savepoint'te yazar — eski satır kapatılır
+     * (valid_to = now(), superseded_by = yeni pk), yeni satır eklenir, dönüş
+     * yeni satırdır. Yeni pk CLIENT'ta üretilir (row'da verilmemişse
+     * randomUUID — declared şemaların uuid().defaultRandom() standardı) ki
+     * kapatma UPDATE'i INSERT'ten ÖNCE koşabilsin: 0 satır = zaten superseded
+     * ya da yok → INSERT hiç denenmez; INSERT hatası ise savepoint'le
+     * kapatmayı da geri sarar — yarım supersede diye bir durum yoktur.
+     */
+    supersede(table: string, id: string, row: Row): Promise<Row>;
     /** A real SAVEPOINT inside the request's transaction. */
     transaction<T>(cb: (t: unknown) => Promise<T>): Promise<T>;
+    /**
+     * Run `fn` against a handle bound to a SAVEPOINT, so a failure inside it
+     * rolls back only what that handle wrote and the request can keep writing.
+     *
+     * WHY THE HANDLE IS AN ARGUMENT. The obvious shape — `attempt(async () => {
+     * ... Database.insert(...) ... })`, with no parameter — would have to point
+     * the ambient `Database` at the savepoint for the duration, and a request is
+     * concurrent with itself: `Promise.all([Database.insert(a),
+     * Database.attempt(...)])` would put `a` inside the savepoint and roll it
+     * back with it. Silent data loss, and the same interleaving this file already
+     * refuses for `asService()`. Passing the handle makes the boundary something
+     * you can see in the code that crosses it.
+     *
+     * Postgres, not us: the savepoint is released on success and rolled back on
+     * failure by the driver, so an aborted statement inside `fn` does not poison
+     * the surrounding transaction.
+     */
+    attempt<T>(fn: (tx: DBOps) => Promise<T>): Promise<T>;
     /**
      * Execute a whole transaction plan — what `Database.transaction(fn)` builds.
      *
@@ -800,7 +870,7 @@ interface RuntimeHooks {
     __requestALS: typeof __requestALS;
 }
 /** The module singletons the engine injects, minus the two it owns itself. */
-type ModuleClients = Partial<Pick<RuntimeServices, "Documents" | "Storage" | "Notifications" | "Flags" | "Realtime" | "Purchases" | "Secrets">>;
+type ModuleClients = Partial<Pick<RuntimeServices, "Documents" | "Storage" | "Notifications" | "Flags" | "Realtime" | "Secrets">>;
 interface CreateAppOptions {
     /**
      * Vault'tan TEK secret okuma (FR-025): sorgu-anı embedding'in anahtarı
@@ -854,4 +924,4 @@ interface App {
  */
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
-export { type App as A, BootRefused as B, Cache as C, Database as D, type EgressPolicy as E, Flags as F, effectiveAuth as G, hostAllowed as H, installEgressFence as I, loadConfig as J, makeMemoryCache as K, type LimitState as L, type ModuleClients as M, Notifications as N, matchRoute as O, Purchases as P, quoteIdent as Q, Realtime as R, Secrets as S, scrubSecrets as T, withTables as U, __getRuntime as _, Documents as a, Log as b, type PurchasesService as c, type RequestStore as d, type RuntimeServices as e, type SpendOptions as f, Storage as g, type StoreEnv as h, __requestALS as i, __runWithRuntime as j, __setRuntime as k, AuthVerifier as l, type CreateAppOptions as m, type EngineConfig as n, RateLimiter as o, type RequestDatabase as p, type RouteEntry as q, type RuntimeHooks as r, type ScrubResult as s, type SqlDriver as t, type SqlTx as u, buildRouteTable as v, createApp as w, createLazyTransaction as x, createOps as y, createRequestDatabase as z };
+export { type App as A, BootRefused as B, Cache as C, Database as D, type EgressPolicy as E, Flags as F, makeMemoryCache as G, matchRoute as H, quoteIdent as I, scrubSecrets as J, withTables as K, Log as L, type ModuleClients as M, Notifications as N, Realtime as R, Secrets as S, __getRuntime as _, Documents as a, type RequestStore as b, type RuntimeServices as c, Storage as d, __requestALS as e, __runWithRuntime as f, __setRuntime as g, AuthVerifier as h, type CreateAppOptions as i, type EngineConfig as j, RateLimiter as k, type RequestDatabase as l, type RouteEntry as m, type RuntimeHooks as n, type ScrubResult as o, type SqlDriver as p, type SqlTx as q, buildRouteTable as r, createApp as s, createLazyTransaction as t, createOps as u, createRequestDatabase as v, effectiveAuth as w, hostAllowed as x, installEgressFence as y, loadConfig as z };