@palbase/backend 22.0.1 → 23.0.0

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

@@ -1,5 +1,5 @@
 import { Tables, TableTypes } from './db/env.cjs';
-import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-B0LpZixz.cjs';
+import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-i8TTCohk.cjs';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -13,7 +13,7 @@ type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
  */
 type AuthUserOnDelete = Extract<OnDeleteAction, 'cascade' | 'set null'>;
 /** Column type identifiers. */
-type ColumnType = 'uuid' | 'text' | 'integer' | 'bigint' | 'numeric' | 'boolean' | 'timestamp' | 'jsonb' | 'enum';
+type ColumnType = 'uuid' | 'text' | 'integer' | 'bigint' | 'numeric' | 'boolean' | 'timestamp' | 'jsonb' | 'enum' | 'vector';
 /** Base column definition shared by all column types. */
 interface ColumnDef {
     type: ColumnType;
@@ -36,6 +36,9 @@ interface ColumnDef {
     enumName?: string;
     enumValues?: string[];
     unique?: 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;
 }
 declare const __colKind: unique symbol;
 declare const __colNullable: unique symbol;
@@ -147,7 +150,7 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
  * - "jsonb" → P (the dev-supplied payload shape from jsonb<T>(), else unknown)
  * - "enum" → E (the union of literal values)
  */
-type ColValue<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<'enum', infer N, infer _D, infer E, infer _P> ? N extends true ? E | null : E : never;
+type ColValue<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
@@ -198,6 +201,10 @@ declare function jsonb<T = unknown>(): ColumnBuilder<'jsonb', false, false, neve
  *               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[]>;
 
 /**
  * policy.ts — the RLS policy authoring DSL.
@@ -301,7 +308,7 @@ declare function policy(name: string): PolicyBuilder;
  * 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", "postgis", "cube", "earthdistance", "hstore", "ltree", "btree_gist", "pg_cron", "pgcrypto", "uuid-ossp"];
+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];
 /**
@@ -329,6 +336,33 @@ 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 `defineSchema({ tables: { <name>: { columns } } })`.
@@ -355,6 +389,64 @@ type ColumnMap = Record<string, ColumnBuilder>;
  * The `C` type parameter preserves the precise per-column phantom types so the
  * typed `Database.tables.*` 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;
+}
 interface TableInput<C extends ColumnMap = ColumnMap> {
     columns: C;
     rls?: boolean;
@@ -394,6 +486,10 @@ interface TableInput<C extends ColumnMap = ColumnMap> {
         name: string;
         columns: string[];
     }[];
+    /** 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`
@@ -429,6 +525,10 @@ interface TableDef<C extends ColumnMap = ColumnMap> {
         name: string;
         columns: string[];
     }[];
+    /** 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.
@@ -583,8 +683,77 @@ type TypedTx<S extends SchemaDef> = TxPlanHandle<{
  * through `Object.keys` iteration) — see the module-level doc comment.
  */
 declare function makeTypedDB<S extends SchemaDef>(schema: S, raw: DBClient): TypedDB<S>;
-/** A typed table accessor derived from one env `Tables` entry's flat shapes. */
-interface EnvTypedTable<T extends TableTypes> {
+/** Bir where değeri: düz eşitlik YA DA operatör nesnesi (FR-016). */
+type WhereOp<V> = V | {
+    gt?: V;
+    gte?: V;
+    lt?: V;
+    lte?: V;
+    neq?: V;
+    in?: V[];
+};
+/** 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[];
+    where?: {
+        [K in keyof T["row"]]?: WhereOp<T["row"][K]>;
+    };
+    /** 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;
+    };
+    /** 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"]>;
     /** Update the row by id; resolves to the updated row, or `null` if no row
      * matched (absent or RLS-hidden) — an idempotent outcome, mirroring
@@ -593,7 +762,34 @@ interface EnvTypedTable<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
+ * çağrı derleme hatasıdır (FR-013). Yapısal koşul TableTypes'ı genişletmeden çalışır. */
+type EnvTypedTable<T extends TableTypes> = EnvTypedTableBase<T> & (T extends {
+    searchable: true;
+} ? {
+    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`
  * 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). */
@@ -671,4 +867,4 @@ interface EnvTypedDatabase extends Omit<DBClient, "txPlan" | "asService"> {
     asService(): EnvServiceDatabase;
 }
 
-export { jsonb as A, makeTypedDB as B, ColumnBuilder as C, numeric as D, type EnvTypedDatabase as E, policy as F, raw as G, text as H, type InsertShape as I, timestamp as J, uuid as K, type OnDeleteAction as O, PALBASE_EXTENSIONS as P, type RawConstraintDef as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, EXTENSION_DEPENDENCIES as d, type EnvServiceDatabase as e, type EnvTables as f, type EnvTypedTable as g, type PalbaseExtension as h, PolicyBuilder as i, type PolicyCommand as j, type PolicyDef as k, type PolicyMode as l, type RowShape as m, type SchemaInput as n, type TableInput as o, type TxPlan as p, type TxTables as q, type TypedDB as r, type TypedTable as s, type TypedTx as t, bigint as u, boolean as v, defineSchema as w, enumType as x, integer as y, isPalbaseExtension as z };
+export { isPalbaseExtension as A, jsonb as B, ColumnBuilder as C, makeTypedDB as D, type EnvTypedDatabase as E, numeric as F, openai as G, policy as H, type InsertShape as I, raw as J, text as K, timestamp as L, uuid as M, vector as N, type OnDeleteAction as O, PALBASE_EXTENSIONS as P, type RawConstraintDef as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, EXTENSION_DEPENDENCIES as d, type EmbeddingModelRef as e, type EnvServiceDatabase as f, type EnvTables as g, type EnvTypedTable as h, type PalbaseExtension as i, PolicyBuilder as j, type PolicyCommand as k, type PolicyDef as l, type PolicyMode as m, type RowShape as n, type SchemaInput as o, type TableInput as p, type TxPlan as q, type TxTables as r, type TypedDB as s, type TypedTable as t, type TypedTx as u, bigint as v, boolean as w, defineSchema as x, enumType as y, integer as z };

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

@@ -1,63 +1,8 @@
-import { Buckets, BucketTypes } from './db/env.cjs';
+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-B0LpZixz.cjs';
-import { E as EnvTypedDatabase } from './index-BGSCWlUa.cjs';
-import { R as RouteMeta } from './registry-Cw0YEYCg.cjs';
-
-/**
- * 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, T as TxPlanBody, f as TxPlanResponse } from './endpoint-i8TTCohk.cjs';
+import { E as EnvTypedDatabase } from './index-Bmvx1EvJ.cjs';
+import { R as RouteMeta } from './registry-C3H2uPeZ.cjs';
 
 /**
  * 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.
  *
@@ -434,6 +369,111 @@ declare function createOps(tx: TxLike): {
     delete(table: string, id: string): Promise<void>;
     findById(table: string, id: string): Promise<Row | null>;
     findMany(table: string, query?: Row): 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
+     * hnsw.iterative_scan=relaxed_order aynı tx'te set_config ile (CLAIM-N3 —
+     * RLS/filtre altında LIMIT-altı dönüş açığını kapatır). Sorgu-anı embed
+     * T024'te gelir; o zamana dek vector kolu yalnız params.vector ile koşar.
+     */
+    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 — 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>;
     /**
@@ -779,36 +819,20 @@ declare function hostAllowed(host: string, allow: readonly string[]): boolean;
  */
 declare function installEgressFence(policy: EgressPolicy): typeof fetch;
 
-/**
- * engine/index.ts — the engine: a backend that boots itself.
- *
- * `createApp` turns a set of `@Controller` classes into a `fetch(Request)`
- * handler. No V8 isolate, no capability hop: this process owns its database
- * pool, verifies its own tokens, applies its own rate limits, and calls the
- * modules directly.
- *
- *   import { createApp, loadConfig } from "@palbase/backend/engine";
- *
- *   const app = await createApp({
- *     config: loadConfig(process.env),
- *     controllers: [TodosController],
- *     schema,
- *   });
- *   Bun.serve({ port: app.config.port, fetch: app.handle });
- *
- * The Web-standard `fetch` signature is the point: the same handler runs under
- * Bun, Deno and any host that speaks Request/Response, so "works locally" and
- * "works in the cloud" are the same code path rather than two.
- */
-
 /** The `__`-prefixed request-scope seam, as re-exported by a deployed bundle. */
 interface RuntimeHooks {
     __runWithRuntime: typeof __runWithRuntime;
     __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ı
+     * buradan akar. Verilmezse auto-embed'li search({query}) adlandırılmış
+     * hatayla düşer — sessiz boş sonuç asla (FR-015).
+     */
+    secretReader?: (name: string) => Promise<string | null>;
     config: EngineConfig;
     /** `@Controller` classes. A class that collected zero routes is fatal. */
     controllers: readonly unknown[];
@@ -855,4 +879,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 };