@palbase/backend 22.0.1 → 23.0.0

package/dist/bin/palbase-backend.cjs

@@ -425,7 +425,11 @@ function makeTablesAccessor(ops) {
           update: (id, data) => ops().update(name, id, data),
           delete: (id) => ops().delete(name, id),
           findById: (id) => ops().findById(name, id),
-          findMany: (query) => ops().findMany(name, query)
+          findMany: (query) => ops().findMany(name, query),
+          search: (params) => ops().search(name, params),
+          similar: (id, params) => ops().similar(name, id, params),
+          recommend: (params) => ops().recommend(name, params),
+          supersede: (id, row) => ops().supersede(name, id, row)
         };
       }
     }
@@ -434,16 +438,21 @@ function makeTablesAccessor(ops) {
 }
 var rawDatabase = makeServiceProxy("Database");
 function makeTypedSurface(raw) {
+  const reco = raw;
   const ops = {
     query: (sql, params) => raw.query(sql, params),
     insert: (table, data) => raw.insert(table, data),
     update: (table, id, data) => raw.update(table, id, data),
     delete: (table, id) => raw.delete(table, id),
     findById: (table, id) => raw.findById(table, id),
-    findMany: (table, query) => raw.findMany(table, query)
+    findMany: (table, query) => raw.findMany(table, query),
+    search: (table, params) => raw.search(table, params),
+    similar: (table, id, params) => reco.similar(table, id, params),
+    recommend: (table, params) => reco.recommend(table, params),
+    supersede: (table, id, row) => raw.supersede(table, id, row)
   };
   return Object.assign(ops, {
-    tables: makeTablesAccessor(() => raw),
+    tables: makeTablesAccessor(() => reco),
     transaction(fn) {
       const builder = new TxPlanBuilder();
       return runTxPlan(raw, makeTxTablesAccessor(builder), builder, fn);
@@ -506,7 +515,6 @@ var Cache = makeServiceProxy("Cache");
 var Secrets = makeServiceProxy("Secrets");
 var Log = makeServiceProxy("Log");
 var Notifications = makeServiceProxy("Notifications");
-var Purchases = makeServiceProxy("Purchases");
 var rawFlags = makeServiceProxy("Flags");
 var Flags = Object.assign(
   {
@@ -971,6 +979,305 @@ function asWireRow(row) {
 function asWireRows(rows) {
   return rows.map((row) => asWireRow(row));
 }
+function toVectorLiteral(v) {
+  return `[${v.join(",")}]`;
+}
+function vectorColumnsOf(schema, table) {
+  const out = /* @__PURE__ */ new Set();
+  for (const [key, def] of Object.entries(schema.tables ?? {})) {
+    if ((def.name ?? key) !== table) continue;
+    for (const [col, c] of Object.entries(def.columns ?? {})) {
+      const d = c !== null && typeof c === "object" && "_def" in c ? c._def : c;
+      if (d !== null && typeof d === "object" && d.type === "vector") out.add(col);
+    }
+  }
+  return out;
+}
+function reviveVectors(row, vectorCols) {
+  if (row === null || typeof row !== "object" || vectorCols.size === 0) return row;
+  const out = row;
+  for (const col of vectorCols) {
+    const v = out[col];
+    if (typeof v === "string") out[col] = JSON.parse(v);
+  }
+  return row;
+}
+function asTableRow(table, row) {
+  return reviveVectors(asWireRow(row), vectorColumnsOf(currentSchema, table));
+}
+function asTableRows(table, rows) {
+  const vectorCols = vectorColumnsOf(currentSchema, table);
+  return rows.map((row) => reviveVectors(asWireRow(row), vectorCols));
+}
+function asBindParams(table, cols, data) {
+  const vectorCols = vectorColumnsOf(currentSchema, table);
+  return cols.map((c) => {
+    const v = data[c];
+    return Array.isArray(v) && vectorCols.has(c) ? toVectorLiteral(v) : v;
+  });
+}
+var SELECTIVITY_EXACT_THRESHOLD = 1e4;
+var METRIC_OPERATOR = {
+  cosine: "<=>",
+  euclidean: "<->",
+  inner_product: "<#>"
+};
+function searchConfigFor(table) {
+  const t = currentSchema.tables?.[table];
+  if (!t) return null;
+  const columns = t.columns ?? {};
+  const defOf = (c) => c !== null && typeof c === "object" && "_def" in c ? c._def : c ?? {};
+  const cols = Object.keys(columns);
+  const vectorCols = cols.filter((c) => defOf(columns[c]).type === "vector");
+  const defOfFull = (c) => c !== null && typeof c === "object" && "_def" in c ? c._def : c ?? {};
+  const pkCols = cols.filter((c) => defOfFull(columns[c]).primaryKey === true);
+  const pk = pkCols.length === 1 ? pkCols[0] : cols.includes("id") ? "id" : null;
+  if (pk === null) {
+    throw new Error(
+      `search(${table}): tek-kolon primary key bulunamad\u0131 \u2014 arama s\u0131ralamas\u0131 ve sat\u0131r birle\u015Fimi PK ister (FR-020)`
+    );
+  }
+  const search = t.search;
+  const synonyms = search?.synonyms !== void 0 && Object.keys(search.synonyms).length > 0 ? { synonyms: search.synonyms } : {};
+  const validity = search?.validity === true ? { validity: true } : {};
+  if (search?.from !== void 0 && search.model !== void 0) {
+    const m = search.model;
+    const embed = {
+      model: m.model,
+      apiKeyName: m.apiKeyName ?? "OPENAI_API_KEY",
+      ...m.baseURL !== void 0 ? { baseURL: m.baseURL } : {},
+      ...m.dimensions !== void 0 ? { dimensions: m.dimensions } : {}
+    };
+    const metric = search.metric ?? "cosine";
+    const ftsOn = search.text !== false;
+    const ftsColsNew = ftsOn ? Array.isArray(search.text) && search.text.length > 0 ? search.text : search.from : [];
+    if (vectorCols.length > 0) {
+      return {
+        pk,
+        cols,
+        colSet: new Set(cols),
+        ftsCols: ftsColsNew,
+        legs: [{ column: vectorCols[0], metric, embed }],
+        ...synonyms,
+        ...validity
+      };
+    }
+    return {
+      pk,
+      cols,
+      colSet: new Set(cols),
+      ftsCols: ftsColsNew,
+      legs: [],
+      chunk: { table: `${table}__palbase_chunks`, metric, embed, fts: ftsOn },
+      ...synonyms,
+      ...validity
+    };
+  }
+  const ftsCols = (Array.isArray(search?.text) ? search.text : void 0) ?? [];
+  const rawLegs = search?.vector === void 0 ? [] : Array.isArray(search.vector) ? search.vector : [search.vector];
+  let legs;
+  if (rawLegs.length > 0) {
+    legs = rawLegs.map((leg) => {
+      const l = leg;
+      const column = l.column ?? (vectorCols.length === 1 ? vectorCols[0] : void 0);
+      if (column === void 0) {
+        throw new Error(`search(${table}): birden \xE7ok vector kolonu var \u2014 beyanda 'column' zorunlu (FR-010)`);
+      }
+      const model = l.model;
+      return {
+        column,
+        metric: l.metric ?? "cosine",
+        ...model !== void 0 ? { embed: {
+          model: model.model,
+          apiKeyName: model.apiKeyName ?? "OPENAI_API_KEY",
+          ...model.baseURL !== void 0 ? { baseURL: model.baseURL } : {},
+          ...model.dimensions !== void 0 ? { dimensions: model.dimensions } : {}
+        } } : {}
+      };
+    });
+  } else {
+    legs = vectorCols.map((column) => ({ column, metric: "cosine" }));
+  }
+  if (ftsCols.length === 0 && legs.length === 0) return null;
+  return { pk, cols, colSet: new Set(cols), ftsCols, legs, ...synonyms, ...validity };
+}
+function pickLeg(table, legs, using) {
+  if (legs.length === 0) return null;
+  if (using !== void 0) {
+    const hit = legs.find((l) => l.column === using);
+    if (!hit) {
+      throw new Error(
+        `search(${table}): using "${using}" bir vekt\xF6r kolunu adlam\u0131yor \u2014 mevcut: ${legs.map((l) => l.column).join(", ")}`
+      );
+    }
+    return hit;
+  }
+  if (legs.length === 1) return legs[0];
+  throw new Error(`search(${table}): birden \xE7ok vekt\xF6r kolu var \u2014 'using' ile se\xE7in (FR-013) \u2014 salt metin ar\u0131yorsan mode:"text" kullan`);
+}
+var HALF_LIFE_UNIT_SECONDS = { s: 1, m: 60, h: 3600, d: 86400 };
+function parseHalfLife(s) {
+  const m = /^(\d+)(s|m|h|d)$/.exec(s);
+  const sec = m === null ? 0 : Number(m[1]) * HALF_LIFE_UNIT_SECONDS[m[2]];
+  if (!Number.isFinite(sec) || sec <= 0) {
+    throw new Error(`recency.halfLife "${s}" \xE7\xF6z\xFCmlenemedi \u2014 beklenen: pozitif <say\u0131>+(s|m|h|d), \xF6rn. "30d" (FR-004)`);
+  }
+  return sec;
+}
+var WHERE_OPS = { gt: ">", gte: ">=", lt: "<", lte: "<=", neq: "<>" };
+function ftsExprOf(ftsCols) {
+  return [...ftsCols].sort().map((c) => `coalesce(t.${quoteIdent(c)},'')`).join(" || ' ' || ");
+}
+function expandSynonyms(query, map) {
+  const lower = {};
+  for (const [word, alts] of Object.entries(map)) lower[word.toLowerCase()] = alts;
+  return query.split(/("[^"]*")/).map((seg) => {
+    if (seg.startsWith('"')) return seg;
+    return seg.split(/(\s+)/).map((tok) => {
+      if (tok === "" || /^\s+$/.test(tok)) return tok;
+      const alts = lower[tok.toLowerCase()];
+      return alts !== void 0 && alts.length > 0 ? `(${tok} OR ${alts.join(" OR ")})` : tok;
+    }).join("");
+  }).join("");
+}
+var searchLogger = null;
+function logNoResults(table, query, mode, n) {
+  if (n === 0) {
+    searchLogger?.("palbase.search.no_results", {
+      table,
+      query: (query ?? "").slice(0, 200),
+      mode: mode ?? "hybrid"
+    });
+  }
+}
+async function fetchFacets(live, table, colSet, facets, where, extraWhere = () => "") {
+  const bind = [];
+  const add = (v) => {
+    bind.push(v);
+    return `$${bind.length}`;
+  };
+  const whereSql = compileWhere(table, colSet, where, add) + extraWhere(add);
+  const parts = facets.map(
+    (col) => `(SELECT '${col.replace(/'/g, "''")}' AS f, t.${quoteIdent(col)}::text AS v, count(*) AS n FROM ${quoteIdent(table)} t WHERE true${whereSql} GROUP BY 2 ORDER BY 3 DESC LIMIT 20)`
+  );
+  const rows = await live.unsafe(parts.join(" UNION ALL "), bind);
+  const out = {};
+  for (const col of facets) out[col] = [];
+  for (const r of rows) {
+    if (typeof r.f === "string" && out[r.f] !== void 0) {
+      out[r.f].push({ value: r.v ?? null, count: Number(r.n) });
+    }
+  }
+  return out;
+}
+function validitySql(v, add) {
+  if (v === "all") return "";
+  if (v !== void 0) {
+    const p = add(v.asOf);
+    return ` AND t."valid_from" <= ${p} AND (t."valid_to" IS NULL OR t."valid_to" > ${p})`;
+  }
+  return ` AND t."valid_to" IS NULL`;
+}
+function excludeSql(pk, ids, add) {
+  if (ids.length === 0) return "";
+  if (ids.length === 1) return ` AND t.${quoteIdent(pk)} <> ${add(ids[0])}`;
+  return ` AND t.${quoteIdent(pk)} <> ALL(ARRAY[${ids.map((x) => add(x)).join(", ")}])`;
+}
+function compileWhere(table, colSet, where, add) {
+  const parts = [];
+  for (const [col, cond] of Object.entries(where)) {
+    if (!colSet.has(col)) {
+      throw new Error(`search(${table}): where kolonu "${col}" tabloda yok (FR-016)`);
+    }
+    const q = `t.${quoteIdent(col)}`;
+    if (cond !== null && typeof cond === "object" && !Array.isArray(cond)) {
+      for (const [op, v] of Object.entries(cond)) {
+        if (op === "in") {
+          if (!Array.isArray(v)) throw new Error(`search(${table}): where.${col}.in bir dizi olmal\u0131`);
+          if (v.length === 0) {
+            parts.push("false");
+            continue;
+          }
+          parts.push(`${q} IN (${v.map((x) => add(x)).join(", ")})`);
+        } else if (op in WHERE_OPS) {
+          parts.push(`${q} ${WHERE_OPS[op]} ${add(v)}`);
+        } else {
+          throw new Error(`search(${table}): where.${col} bilinmeyen operat\xF6r "${op}" (gt/gte/lt/lte/neq/in)`);
+        }
+      }
+    } else {
+      parts.push(`${q} = ${add(cond)}`);
+    }
+  }
+  return parts.length === 0 ? "" : ` AND ${parts.join(" AND ")}`;
+}
+var cachedVectorSchema = null;
+var cachedTrgmSchema = null;
+async function trgmSchemaOf(live) {
+  if (cachedTrgmSchema !== null) return cachedTrgmSchema;
+  const rows = await live.unsafe(
+    "select n.nspname from pg_extension e join pg_namespace n on n.oid = e.extnamespace where e.extname = 'pg_trgm'"
+  );
+  cachedTrgmSchema = rows?.[0]?.nspname ?? "public";
+  return cachedTrgmSchema;
+}
+async function vectorSchemaWithGuc(runner) {
+  if (cachedVectorSchema !== null) {
+    await runner.unsafe(
+      "select set_config('hnsw.iterative_scan','relaxed_order',true), set_config('hnsw.max_scan_tuples','200000',true), set_config('hnsw.ef_search','200',true)"
+    );
+    return cachedVectorSchema;
+  }
+  const rows = await runner.unsafe(
+    "select set_config('hnsw.iterative_scan','relaxed_order',true), set_config('hnsw.max_scan_tuples','200000',true), set_config('hnsw.ef_search','200',true), (select n.nspname from pg_extension e join pg_namespace n on n.oid = e.extnamespace where e.extname = 'vector') as nspname"
+  );
+  const name = rows?.[0]?.nspname;
+  if (typeof name !== "string" || name === "") {
+    throw new Error("pgvector extension kurulu de\u011Fil \u2014 vector aramas\u0131 \xE7al\u0131\u015Famaz (extensions beyan\u0131 deploy'dan ge\xE7ti mi?)");
+  }
+  cachedVectorSchema = name;
+  return name;
+}
+var secretReader = null;
+function setSecretReader(fn) {
+  secretReader = fn;
+}
+var embedFetch = (url, init) => fetch(url, init);
+async function embedQuery(embed, text) {
+  if (secretReader === null) {
+    throw new Error(`query embed: secret reader ba\u011Flanmam\u0131\u015F \u2014 ${embed.apiKeyName} okunam\u0131yor`);
+  }
+  const key = await secretReader(embed.apiKeyName);
+  if (key === null || key === "") {
+    throw new Error(`query embed: vault'ta ${embed.apiKeyName} yok (FR-021/FR-025)`);
+  }
+  const url = (embed.baseURL ?? "https://api.openai.com/v1").replace(/\/$/, "") + "/embeddings";
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 1e4);
+  try {
+    const res = await embedFetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
+      body: JSON.stringify({
+        model: embed.model,
+        input: [text],
+        ...embed.dimensions !== void 0 ? { dimensions: embed.dimensions } : {}
+      }),
+      signal: controller.signal
+    });
+    if (!res.ok) {
+      throw new Error(`query embed: sa\u011Flay\u0131c\u0131 ${res.status} d\xF6nd\xFC (${embed.apiKeyName} ile) \u2014 anahtar/model do\u011Fru mu?`);
+    }
+    const data = await res.json();
+    const vec = data.data?.[0]?.embedding;
+    if (!Array.isArray(vec)) {
+      throw new Error("query embed: sa\u011Flay\u0131c\u0131 yan\u0131t\u0131nda data[0].embedding yok (CLAIM-N1 \u015Fekli)");
+    }
+    return vec;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function createOps(tx) {
   const at = () => resolveTx(tx);
   const ops = {
@@ -982,22 +1289,22 @@ function createOps(tx) {
       if (cols.length === 0) throw new Error(`insert into ${table}: no columns given`);
       const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
       const sql = `INSERT INTO ${quoteIdent(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) RETURNING *`;
-      const rows = await (await at()).unsafe(sql, cols.map((c) => data[c]));
+      const rows = await (await at()).unsafe(sql, asBindParams(table, cols, data));
       const inserted = rows[0];
       if (!inserted) {
         throw new Error(
           `insert into ${table} returned no row \u2014 the write was rejected (an RLS policy, most likely).`
         );
       }
-      return asWireRow(inserted);
+      return asTableRow(table, inserted);
     },
     async update(table, id, data) {
       const cols = Object.keys(data);
       if (cols.length === 0) return ops.findById(table, id);
       const assignments = cols.map((c, i) => `${quoteIdent(c)} = $${i + 1}`).join(", ");
       const sql = `UPDATE ${quoteIdent(table)} SET ${assignments} WHERE id = $${cols.length + 1} RETURNING *`;
-      const rows = await (await at()).unsafe(sql, [...cols.map((c) => data[c]), id]);
-      return rows[0] ? asWireRow(rows[0]) : null;
+      const rows = await (await at()).unsafe(sql, [...asBindParams(table, cols, data), id]);
+      return rows[0] ? asTableRow(table, rows[0]) : null;
     },
     async delete(table, id) {
       await (await at()).unsafe(`DELETE FROM ${quoteIdent(table)} WHERE id = $1`, [id]);
@@ -1007,16 +1314,400 @@ function createOps(tx) {
         `SELECT * FROM ${quoteIdent(table)} WHERE id = $1`,
         [id]
       );
-      return rows[0] ? asWireRow(rows[0]) : null;
+      return rows[0] ? asTableRow(table, rows[0]) : null;
     },
     async findMany(table, query = {}) {
       const cols = Object.keys(query);
       const where = cols.length ? ` WHERE ${cols.map((c, i) => `${quoteIdent(c)} = $${i + 1}`).join(" AND ")}` : "";
-      return asWireRows(await (await at()).unsafe(
+      return asTableRows(table, await (await at()).unsafe(
         `SELECT * FROM ${quoteIdent(table)}${where}`,
         cols.map((c) => query[c])
       ));
     },
+    /**
+     * 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.
+     */
+    async search(table, params = {}) {
+      const cfg = searchConfigFor(table);
+      if (!cfg) {
+        throw new Error(`search(${table}): tablo aranabilir de\u011Fil \u2014 ne vector kolonu ne search beyan\u0131 var (FR-013)`);
+      }
+      const excl = params.__excludeIds ?? [];
+      if (params.facets !== void 0) {
+        for (const col of params.facets) {
+          if (!cfg.colSet.has(col)) {
+            throw new Error(`search(${table}): facets kolonu "${col}" tabloda yok (FR-027)`);
+          }
+        }
+      }
+      if (params.validity !== void 0 && cfg.validity !== true) {
+        throw new Error(
+          `search(${table}): validity parametresi verildi ama tablo validity beyan\u0131 ta\u015F\u0131m\u0131yor (FR-029)`
+        );
+      }
+      const validityFor = (adder) => cfg.validity === true ? validitySql(params.validity, adder) : "";
+      const rawLimit = params.limit ?? 20;
+      if (typeof rawLimit !== "number" || !Number.isFinite(rawLimit)) {
+        throw new Error(`search(${table}): limit sonlu bir say\u0131 olmal\u0131, ${String(rawLimit)} verildi (FR-013)`);
+      }
+      const limit = Math.min(Math.max(1, Math.trunc(rawLimit)), 100);
+      const pool = Math.max(limit * 3, 30);
+      if (params.minScore !== void 0 && (typeof params.minScore !== "number" || !Number.isFinite(params.minScore))) {
+        throw new Error(`search(${table}): minScore sonlu bir say\u0131 olmal\u0131, ${String(params.minScore)} verildi (FR-001)`);
+      }
+      let recencyMul = "";
+      if (params.recency !== void 0) {
+        const { field, halfLife } = params.recency;
+        if (!cfg.colSet.has(field)) {
+          throw new Error(`search(${table}): recency.field "${field}" tabloda yok (FR-004)`);
+        }
+        recencyMul = ` * exp(-ln(2) * extract(epoch from (now() - t.${quoteIdent(field)})) / ${parseHalfLife(halfLife)})`;
+      }
+      let boostMul = "";
+      if (params.boost !== void 0) {
+        const { field, weight } = params.boost;
+        if (!cfg.colSet.has(field)) {
+          throw new Error(`search(${table}): boost.field "${field}" tabloda yok (FR-030)`);
+        }
+        if (typeof weight !== "number" || !Number.isFinite(weight)) {
+          throw new Error(`search(${table}): boost.weight sonlu bir say\u0131 olmal\u0131, ${String(weight)} verildi (FR-030)`);
+        }
+        const g = `greatest(t.${quoteIdent(field)},0)`;
+        boostMul = ` * (1 + ${weight} * ${g}/(1+${g}))`;
+      }
+      const scoreMul = boostMul + recencyMul;
+      if (cfg.chunk !== void 0) {
+        const ck = cfg.chunk;
+        const pidQ = quoteIdent(`parent_${cfg.pk}`);
+        const bpr = Math.min(Math.max(1, Math.trunc(params.blocksPerRow ?? 3)), 10);
+        const wantTextC = params.mode !== "vector" && ck.fts && typeof params.query === "string" && params.query !== "";
+        let qvC = Array.isArray(params.vector) ? params.vector : null;
+        if (qvC === null && ck.embed !== void 0 && params.mode !== "text" && typeof params.query === "string" && params.query !== "") {
+          try {
+            qvC = await embedQuery(ck.embed, params.query);
+          } catch (e) {
+            if (!wantTextC) throw e;
+            qvC = null;
+          }
+        }
+        if (!wantTextC && qvC === null) {
+          throw new Error(
+            `search(${table}): ko\u015Fulabilir kol yok \u2014 metin i\xE7in 'query' (FTS beyan\u0131 gerekir), semantik i\xE7in 'vector' verin (FR-015)`
+          );
+        }
+        const bindC = [];
+        const addC = (v) => {
+          bindC.push(v);
+          return `$${bindC.length}`;
+        };
+        const whereC = compileWhere(table, cfg.colSet, params.where ?? {}, addC) + excludeSql(cfg.pk, excl, addC) + validityFor(addC);
+        const liveC = await at();
+        const K2 = 50;
+        const cpool = Math.max(limit * 9, 90);
+        let semC = "";
+        let kwC = "";
+        if (qvC !== null) {
+          const sch = await vectorSchemaWithGuc(liveC);
+          const op = METRIC_OPERATOR[ck.metric] ?? METRIC_OPERATOR.cosine;
+          const vp = addC(toVectorLiteral(qvC));
+          semC = `SELECT c.${pidQ} AS pid, c.chunk_seq, ROW_NUMBER() OVER (ORDER BY (c.embedding OPERATOR(${quoteIdent(sch)}.${op}) ${vp}::${quoteIdent(sch)}.vector)) AS r FROM ${quoteIdent(ck.table)} c WHERE c.embedding IS NOT NULL ORDER BY r LIMIT ${cpool}`;
+        }
+        let qpC = "";
+        let qpCIdx = -1;
+        if (wantTextC) {
+          const qTextC = cfg.synonyms !== void 0 ? expandSynonyms(params.query, cfg.synonyms) : params.query;
+          qpC = addC(qTextC);
+          qpCIdx = bindC.length - 1;
+          kwC = `SELECT c.${pidQ} AS pid, c.chunk_seq, ROW_NUMBER() OVER (ORDER BY ts_rank_cd(c.palbase_fts, websearch_to_tsquery('simple', ${qpC})) DESC) AS r FROM ${quoteIdent(ck.table)} c WHERE c.palbase_fts @@ websearch_to_tsquery('simple', ${qpC}) ORDER BY r LIMIT ${cpool}`;
+        }
+        const msC = params.minScore === void 0 ? "" : addC(params.minScore);
+        const colListC = cfg.cols.map((c) => `t.${quoteIdent(c)}`).join(", ");
+        const scoreC = scoreMul === "" ? "g._score" : `(g._score)${scoreMul}`;
+        const assembleC = (kwIn, withKwn) => {
+          const kwnCol = withKwn ? `, (SELECT count(*) FROM kw)::int AS _kwn` : "";
+          let fusedSrc;
+          if (semC !== "" && kwIn !== "") {
+            fusedSrc = `WITH sem AS (${semC}), kw AS (${kwIn}), fused AS (SELECT COALESCE(sem.pid, kw.pid) AS pid, COALESCE(sem.chunk_seq, kw.chunk_seq) AS chunk_seq, (COALESCE(1.0/(${K2} + sem.r), 0) + COALESCE(1.0/(${K2} + kw.r), 0))::float8 AS cscore FROM sem FULL OUTER JOIN kw ON sem.pid = kw.pid AND sem.chunk_seq = kw.chunk_seq)`;
+          } else if (semC !== "") {
+            fusedSrc = `WITH sem AS (${semC}), fused AS (SELECT sem.pid, sem.chunk_seq, (1.0/(${K2} + sem.r))::float8 AS cscore FROM sem)`;
+          } else {
+            fusedSrc = `WITH kw AS (${kwIn}), fused AS (SELECT kw.pid, kw.chunk_seq, (1.0/(${K2} + kw.r))::float8 AS cscore FROM kw)`;
+          }
+          const inner = `${fusedSrc}, ranked AS (SELECT f.pid, f.chunk_seq, f.cscore, ROW_NUMBER() OVER (PARTITION BY f.pid ORDER BY f.cscore DESC, f.chunk_seq) AS rn FROM fused f), grouped AS (SELECT r.pid, MAX(r.cscore) AS _score, json_agg(json_build_object('content', c.content, 'score', r.cscore, 'chunkSeq', r.chunk_seq, 'charStart', c.char_start) ORDER BY r.cscore DESC, r.chunk_seq) FILTER (WHERE r.rn <= ${bpr}) AS blocks FROM ranked r JOIN ${quoteIdent(ck.table)} c ON c.${pidQ} = r.pid AND c.chunk_seq = r.chunk_seq GROUP BY r.pid) SELECT ${colListC}, ${scoreC}::float8 AS _score, g.blocks AS blocks${kwnCol} FROM grouped g JOIN ${quoteIdent(table)} t ON t.${quoteIdent(cfg.pk)} = g.pid WHERE true${whereC}`;
+          return msC === "" ? `SELECT * FROM (${inner}) q ORDER BY q._score DESC, q.${quoteIdent(cfg.pk)} LIMIT ${limit}` : `SELECT * FROM (${inner}) q WHERE q._score >= ${msC} ORDER BY q._score DESC, q.${quoteIdent(cfg.pk)} LIMIT ${limit}`;
+        };
+        let rowsC = await liveC.unsafe(assembleC(kwC, kwC !== ""), bindC);
+        if (wantTextC && kwC !== "" && (rowsC.length === 0 || rowsC[0]._kwn === 0)) {
+          const tsch = await trgmSchemaOf(liveC);
+          const trgmKwC = `SELECT c.${pidQ} AS pid, c.chunk_seq, ROW_NUMBER() OVER (ORDER BY ${quoteIdent(tsch)}.word_similarity(${qpC}, coalesce(c.content,'')) DESC) AS r FROM ${quoteIdent(ck.table)} c WHERE ${qpC} OPERATOR(${quoteIdent(tsch)}.<%) coalesce(c.content,'') ORDER BY r LIMIT ${cpool}`;
+          const retryBindC = bindC.slice();
+          if (qpCIdx >= 0) retryBindC[qpCIdx] = params.query;
+          rowsC = await liveC.unsafe(assembleC(trgmKwC, false), retryBindC);
+        }
+        for (const r of rowsC) delete r._kwn;
+        const outC = asTableRows(table, rowsC).map((r) => ({ ...r, blocks: r.blocks ?? [] }));
+        if (params.facets !== void 0 && params.facets.length > 0) {
+          Object.assign(outC, {
+            _facets: await fetchFacets(liveC, table, cfg.colSet, params.facets, params.where ?? {}, validityFor)
+          });
+        }
+        logNoResults(table, params.query, params.mode, outC.length);
+        return outC;
+      }
+      const wantText = params.mode !== "vector" && cfg.ftsCols.length > 0 && typeof params.query === "string" && params.query !== "";
+      const anyEmbed = cfg.legs.some((l) => l.embed !== void 0);
+      const vectorAsked = params.mode !== "text" && (Array.isArray(params.vector) || params.using !== void 0 || params.mode === "vector" || anyEmbed && typeof params.query === "string" && params.query !== "");
+      const leg = vectorAsked ? pickLeg(table, cfg.legs, params.using) : null;
+      let qv = Array.isArray(params.vector) ? params.vector : null;
+      if (qv === null && leg?.embed !== void 0 && typeof params.query === "string" && params.query !== "") {
+        try {
+          qv = await embedQuery(leg.embed, params.query);
+        } catch (e) {
+          if (!wantText) throw e;
+          qv = null;
+        }
+      }
+      const wantVector = leg !== null && qv !== null;
+      if (!wantText && !wantVector) {
+        throw new Error(
+          `search(${table}): ko\u015Fulabilir kol yok \u2014 metin i\xE7in 'query' (FTS beyan\u0131 gerekir), semantik i\xE7in 'vector' verin (FR-015)`
+        );
+      }
+      const bind = [];
+      const add = (v) => {
+        bind.push(v);
+        return `$${bind.length}`;
+      };
+      const userWhere = compileWhere(table, cfg.colSet, params.where ?? {}, add);
+      const whereSql = userWhere + excludeSql(cfg.pk, excl, add) + validityFor(add);
+      const live = await at();
+      const K = 50;
+      let semSql = "";
+      let kwSql = "";
+      if (wantVector && leg) {
+        const sch = await vectorSchemaWithGuc(live);
+        const op = METRIC_OPERATOR[leg.metric] ?? METRIC_OPERATOR.cosine;
+        let exactOrder = "";
+        if (userWhere !== "") {
+          const probeRows = await live.unsafe(
+            `SELECT count(*)::int AS n FROM (SELECT 1 FROM ${quoteIdent(table)} t WHERE t.${quoteIdent(leg.column)} IS NOT NULL${whereSql} LIMIT ${SELECTIVITY_EXACT_THRESHOLD + 1}) s`,
+            bind.slice()
+          );
+          const n = probeRows?.[0]?.n;
+          if (typeof n === "number" && n <= SELECTIVITY_EXACT_THRESHOLD) {
+            exactOrder = " + 0.0";
+          }
+        }
+        const vp = add(toVectorLiteral(qv));
+        semSql = `SELECT t.${quoteIdent(cfg.pk)} AS id, ROW_NUMBER() OVER (ORDER BY (t.${quoteIdent(leg.column)} OPERATOR(${quoteIdent(sch)}.${op}) ${vp}::${quoteIdent(sch)}.vector)${exactOrder}) AS r FROM ${quoteIdent(table)} t WHERE t.${quoteIdent(leg.column)} IS NOT NULL${whereSql} ORDER BY r LIMIT ${pool}`;
+      }
+      let qpRef = "";
+      let qpIdx = -1;
+      if (wantText) {
+        const qText = cfg.synonyms !== void 0 ? expandSynonyms(params.query, cfg.synonyms) : params.query;
+        const qp = add(qText);
+        qpIdx = bind.length - 1;
+        qpRef = qp;
+        kwSql = `SELECT t.${quoteIdent(cfg.pk)} AS id, ROW_NUMBER() OVER (ORDER BY ts_rank_cd(t.palbase_fts, websearch_to_tsquery('simple', ${qp})) DESC) AS r FROM ${quoteIdent(table)} t WHERE t.palbase_fts @@ websearch_to_tsquery('simple', ${qp})${whereSql} ORDER BY r LIMIT ${pool}`;
+      }
+      const colList = cfg.cols.map((c) => `t.${quoteIdent(c)}`).join(", ");
+      const msP = params.minScore === void 0 ? "" : add(params.minScore);
+      const hlCol = params.highlight === true && wantText ? `, ts_headline('simple', ${ftsExprOf(cfg.ftsCols)}, websearch_to_tsquery('simple', ${qpRef})) AS _highlight` : "";
+      const assemble = (kwIn, withKwn) => {
+        const kwnCol = withKwn ? `, (SELECT count(*) FROM kw)::int AS _kwn` : "";
+        let inner;
+        let orderScore;
+        if (semSql !== "" && kwIn !== "") {
+          const score = scoreMul === "" ? "fused._score" : `(fused._score)${scoreMul}`;
+          inner = `WITH sem AS (${semSql}), kw AS (${kwIn}), fused AS (SELECT COALESCE(sem.id, kw.id) AS id, (COALESCE(1.0/(${K} + sem.r), 0) + COALESCE(1.0/(${K} + kw.r), 0))::float8 AS _score FROM sem FULL OUTER JOIN kw ON sem.id = kw.id) SELECT ${colList}, ${score} AS _score${hlCol}${kwnCol} FROM fused JOIN ${quoteIdent(table)} t ON t.${quoteIdent(cfg.pk)} = fused.id`;
+          orderScore = scoreMul === "" ? "fused._score" : "_score";
+        } else {
+          const single = semSql !== "" ? `sem AS (${semSql})` : `kw AS (${kwIn})`;
+          const alias = semSql !== "" ? "sem" : "kw";
+          const base = `(1.0/(${K} + ${alias}.r))::float8`;
+          const score = scoreMul === "" ? base : `(${base})${scoreMul}`;
+          inner = `WITH ${single} SELECT ${colList}, ${score} AS _score${hlCol}${semSql !== "" ? "" : kwnCol} FROM ${alias} JOIN ${quoteIdent(table)} t ON t.${quoteIdent(cfg.pk)} = ${alias}.id`;
+          orderScore = "_score";
+        }
+        return msP === "" ? `${inner} ORDER BY ${orderScore} DESC, t.${quoteIdent(cfg.pk)} LIMIT ${limit}` : `SELECT * FROM (${inner}) q WHERE q._score >= ${msP} ORDER BY q._score DESC, q.${quoteIdent(cfg.pk)} LIMIT ${limit}`;
+      };
+      let rows = await live.unsafe(assemble(kwSql, kwSql !== ""), bind);
+      if (wantText && kwSql !== "" && (rows.length === 0 || rows[0]._kwn === 0)) {
+        const tsch = await trgmSchemaOf(live);
+        const expr = ftsExprOf(cfg.ftsCols);
+        const trgmKw = `SELECT t.${quoteIdent(cfg.pk)} AS id, ROW_NUMBER() OVER (ORDER BY ${quoteIdent(tsch)}.word_similarity(${qpRef}, ${expr}) DESC) AS r FROM ${quoteIdent(table)} t WHERE ${qpRef} OPERATOR(${quoteIdent(tsch)}.<%) ${expr}${whereSql} ORDER BY r LIMIT ${pool}`;
+        const retryBind = bind.slice();
+        if (qpIdx >= 0) retryBind[qpIdx] = params.query;
+        rows = await live.unsafe(assemble(trgmKw, false), retryBind);
+      }
+      for (const r of rows) delete r._kwn;
+      const out = asTableRows(table, rows).map((r) => ({ ...r, blocks: [] }));
+      if (params.facets !== void 0 && params.facets.length > 0) {
+        Object.assign(out, {
+          _facets: await fetchFacets(live, table, cfg.colSet, params.facets, params.where ?? {}, validityFor)
+        });
+      }
+      logNoResults(table, params.query, params.mode, out.length);
+      return out;
+    },
+    /**
+     * 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).
+     */
+    async similar(table, id, opts = {}) {
+      const cfg = searchConfigFor(table);
+      if (!cfg) {
+        throw new Error(`similar(${table}): tablo aranabilir de\u011Fil \u2014 ne vector kolonu ne search beyan\u0131 var (FR-013)`);
+      }
+      const live = await at();
+      let v;
+      if (cfg.chunk !== void 0) {
+        const sch = await vectorSchemaWithGuc(live);
+        const rows = await live.unsafe(
+          `SELECT ${quoteIdent(sch)}.avg(c.embedding) AS v FROM ${quoteIdent(cfg.chunk.table)} c WHERE c.${quoteIdent(`parent_${cfg.pk}`)} = $1 AND c.embedding IS NOT NULL`,
+          [id]
+        );
+        v = rows?.[0]?.v;
+      } else {
+        const leg = pickLeg(table, cfg.legs, opts.using);
+        if (leg === null) {
+          throw new Error(`similar(${table}): tabloda vekt\xF6r kolonu yok \u2014 benzerlik semantik vekt\xF6r ister (FR-022)`);
+        }
+        const rows = await live.unsafe(
+          `SELECT t.${quoteIdent(leg.column)} AS v FROM ${quoteIdent(table)} t WHERE t.${quoteIdent(cfg.pk)} = $1`,
+          [id]
+        );
+        v = rows?.[0]?.v;
+      }
+      if (typeof v !== "string") {
+        throw new Error(`similar(${table}): id "${String(id)}" bulunamad\u0131 ya da embedding'i yok (FR-022)`);
+      }
+      const p = {
+        vector: JSON.parse(v),
+        mode: "vector",
+        where: opts.where,
+        limit: opts.limit,
+        using: opts.using,
+        minScore: opts.minScore,
+        recency: opts.recency,
+        blocksPerRow: opts.blocksPerRow,
+        validity: opts.validity,
+        boost: opts.boost,
+        __excludeIds: [id]
+      };
+      return ops.search(table, p);
+    },
+    /**
+     * 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.
+     */
+    async recommend(table, opts) {
+      const positive = opts?.positive;
+      if (!Array.isArray(positive) || positive.length === 0) {
+        throw new Error(`recommend(${table}): positive bo\u015F olamaz \u2014 en az bir kaynak id gerekir (FR-023)`);
+      }
+      const negative = Array.isArray(opts.negative) ? opts.negative : [];
+      const cfg = searchConfigFor(table);
+      if (!cfg) {
+        throw new Error(`recommend(${table}): tablo aranabilir de\u011Fil \u2014 ne vector kolonu ne search beyan\u0131 var (FR-013)`);
+      }
+      let leg = null;
+      if (cfg.chunk === void 0) {
+        leg = pickLeg(table, cfg.legs, opts.using);
+        if (leg === null) {
+          throw new Error(`recommend(${table}): tabloda vekt\xF6r kolonu yok \u2014 \xF6neri semantik vekt\xF6r ister (FR-023)`);
+        }
+      }
+      const live = await at();
+      const sch = await vectorSchemaWithGuc(live);
+      const bind = [];
+      const add = (x) => {
+        bind.push(x);
+        return `$${bind.length}`;
+      };
+      const avgSel = (ids) => {
+        const inList = ids.map((x) => add(x)).join(", ");
+        return cfg.chunk !== void 0 ? `SELECT ${quoteIdent(sch)}.avg(c.embedding) AS v FROM ${quoteIdent(cfg.chunk.table)} c WHERE c.${quoteIdent(`parent_${cfg.pk}`)} IN (${inList}) AND c.embedding IS NOT NULL` : `SELECT ${quoteIdent(sch)}.avg(t.${quoteIdent(leg.column)}) AS v FROM ${quoteIdent(table)} t WHERE t.${quoteIdent(cfg.pk)} IN (${inList}) AND t.${quoteIdent(leg.column)} IS NOT NULL`;
+      };
+      const targetSql = negative.length === 0 ? `WITH pos AS (${avgSel(positive)}) SELECT pos.v AS v, (pos.v IS NULL) AS pos_missing FROM pos` : `WITH pos AS (${avgSel(positive)}), neg AS (${avgSel(negative)}) SELECT (pos.v OPERATOR(${quoteIdent(sch)}.+) (pos.v OPERATOR(${quoteIdent(sch)}.-) neg.v)) AS v, (pos.v IS NULL) AS pos_missing, (neg.v IS NULL) AS neg_missing FROM pos, neg`;
+      const rows = await live.unsafe(targetSql, bind);
+      const r0 = rows?.[0];
+      if (r0 === void 0 || r0.pos_missing === true) {
+        throw new Error(`recommend(${table}): positive id'lerin hi\xE7biri bulunamad\u0131 ya da embedding'i yok (FR-023)`);
+      }
+      if (negative.length > 0 && r0.neg_missing === true) {
+        throw new Error(`recommend(${table}): negative id'leri bulunamad\u0131 ya da embedding'i yok (FR-023)`);
+      }
+      if (typeof r0.v !== "string") {
+        throw new Error(`recommend(${table}): hedef vekt\xF6r hesaplanamad\u0131 (FR-023)`);
+      }
+      const p = {
+        vector: JSON.parse(r0.v),
+        mode: "vector",
+        where: opts.where,
+        limit: opts.limit,
+        using: opts.using,
+        minScore: opts.minScore,
+        recency: opts.recency,
+        blocksPerRow: opts.blocksPerRow,
+        validity: opts.validity,
+        boost: opts.boost,
+        __excludeIds: [...positive, ...negative]
+      };
+      return ops.search(table, p);
+    },
+    /**
+     * 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.
+     */
+    async supersede(table, id, row) {
+      const cfg = searchConfigFor(table);
+      if (cfg === null || cfg.validity !== true) {
+        throw new Error(`supersede(${table}): tablo validity beyan\u0131 ta\u015F\u0131m\u0131yor (FR-029)`);
+      }
+      const live = await at();
+      return live.savepoint(async (sp) => {
+        const newId = row[cfg.pk] ?? crypto.randomUUID();
+        const closed = await sp.unsafe(
+          `UPDATE ${quoteIdent(table)} SET "valid_to" = now(), "superseded_by" = $1 WHERE ${quoteIdent(cfg.pk)} = $2 AND "valid_to" IS NULL RETURNING ${quoteIdent(cfg.pk)}`,
+          [newId, id]
+        );
+        if (closed.length === 0) {
+          throw new Error(`supersede(${table}): id "${String(id)}" zaten superseded ya da yok (FR-029)`);
+        }
+        const data = { ...row, [cfg.pk]: newId };
+        const cols = Object.keys(data);
+        const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
+        const rows = await sp.unsafe(
+          `INSERT INTO ${quoteIdent(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) RETURNING *`,
+          asBindParams(table, cols, data)
+        );
+        if (!rows[0]) {
+          throw new Error(
+            `supersede(${table}): INSERT sat\u0131r d\xF6nd\xFCrmedi \u2014 yazma reddedildi (b\xFCy\xFCk olas\u0131l\u0131kla bir RLS policy'si)`
+          );
+        }
+        return asTableRow(table, rows[0]);
+      });
+    },
     /** A real SAVEPOINT inside the request's transaction. */
     async transaction(cb) {
       const live = await at();
@@ -1045,7 +1736,7 @@ function createOps(tx) {
       return live.savepoint(async (sp) => {
         const results = [];
         for (const op of plan.ops) {
-          const rows = await runPlanOp(sp, op, results);
+          const rows = asTableRows(op.table, await runPlanOp(sp, op, results));
           const result = { rows, rows_affected: rows.length };
           results.push(result);
           assertGuard(op, result);
@@ -1058,6 +1749,8 @@ function createOps(tx) {
 }
 var currentSchema = {};
 function setSchema(schema) {
+  cachedVectorSchema = null;
+  cachedTrgmSchema = null;
   const s = schema;
   currentSchema = (s && "default" in s ? s.default : s) ?? {};
 }
@@ -1144,7 +1837,7 @@ function isRef(v) {
 function isExpr(v) {
   return typeof v === "object" && v !== null && "$expr" in v;
 }
-function renderValue(value, column, args, results) {
+function renderValue(value, column, args, results, vectorCols) {
   if (isRef(value)) {
     const source = results[value.$ref.op];
     const row = source?.rows[0];
@@ -1153,15 +1846,15 @@ function renderValue(value, column, args, results) {
         error_code: "tx_ref_unresolved"
       });
     }
-    return args.bind(row[value.$ref.field]);
+    return bindMaybeVector(args, column, vectorCols, row[value.$ref.field]);
   }
   if (isExpr(value)) {
     const fn = value.$expr;
     if (fn.fn === "now") return "now()";
     const operator = fn.fn === "inc" ? "+" : "-";
-    return `${quoteIdent(column)} ${operator} ${args.bind(fn.by)}`;
+    return `${quoteIdent(column)} ${operator} ${bindMaybeVector(args, column, vectorCols, fn.by)}`;
   }
-  return args.bind(value);
+  return bindMaybeVector(args, column, vectorCols, value);
 }
 function renderWhere(where, args, results) {
   const cols = Object.keys(where ?? {});
@@ -1173,14 +1866,21 @@ function renderWhere(where, args, results) {
   });
   return ` WHERE ${terms.join(" AND ")}`;
 }
+function bindMaybeVector(args, column, vectorCols, value) {
+  if (column !== void 0 && vectorCols?.has(column) && Array.isArray(value)) {
+    return args.bind(toVectorLiteral(value));
+  }
+  return args.bind(value);
+}
 async function runPlanOp(sp, op, results) {
+  const opVectorCols = vectorColumnsOf(currentSchema, op.table);
   const args = new Args();
   const table = quoteIdent(op.table);
   let sql;
   switch (op.op) {
     case "insert": {
       const cols = Object.keys(op.values ?? {});
-      const rendered = cols.map((c) => renderValue(op.values[c], c, args, results));
+      const rendered = cols.map((c) => renderValue(op.values[c], c, args, results, opVectorCols));
       sql = cols.length ? `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) RETURNING *` : `INSERT INTO ${table} DEFAULT VALUES RETURNING *`;
       break;
     }
@@ -1189,7 +1889,7 @@ async function runPlanOp(sp, op, results) {
       if (rows.length === 0 || !rows[0]) return [];
       const cols = Object.keys(rows[0]);
       const tuples = rows.map(
-        (r) => `(${cols.map((c) => renderValue(r[c], c, args, results)).join(", ")})`
+        (r) => `(${cols.map((c) => renderValue(r[c], c, args, results, opVectorCols)).join(", ")})`
       );
       sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")} RETURNING *`;
       break;
@@ -1198,7 +1898,7 @@ async function runPlanOp(sp, op, results) {
       const cols = Object.keys(op.set ?? {});
       if (cols.length === 0) throw new Error(`update ${op.table}: nothing to set`);
       const assignments = cols.map(
-        (c) => `${quoteIdent(c)} = ${renderValue(op.set[c], c, args, results)}`
+        (c) => `${quoteIdent(c)} = ${renderValue(op.set[c], c, args, results, opVectorCols)}`
       );
       sql = `UPDATE ${table} SET ${assignments.join(", ")}${renderWhere(op.where, args, results)} RETURNING *`;
       break;
@@ -1345,7 +2045,8 @@ function grantFor(entry, ctx, bucketLimits) {
       filename: ctx.filename
     }),
     maxBytes: bucketLimits?.maxBytes ?? null,
-    mimeTypes: bucketLimits?.mimeTypes ?? null
+    mimeTypes: bucketLimits?.mimeTypes ?? null,
+    ownerUid: ctx.userId ?? null
   };
 }
 var CompletionLedger = class {
@@ -1381,6 +2082,23 @@ function verifySignature(presented, expected) {
 
 // src/engine/index.ts
 var JSON_HEADERS = { "content-type": "application/json" };
+function fieldErrors(err) {
+  return err.issues.map((i) => ({ field: i.path.join("."), message: i.message }));
+}
+function headersFor(raw, schema) {
+  const shape = schema.shape;
+  if (typeof shape !== "object" || shape === null) return raw;
+  let aliased = null;
+  for (const declared of Object.keys(shape)) {
+    const lower = declared.toLowerCase();
+    if (lower === declared) continue;
+    const value = raw[lower];
+    if (value === void 0) continue;
+    aliased ??= { ...raw };
+    aliased[declared] = value;
+  }
+  return aliased ?? raw;
+}
 function envelope(error, description, status, requestId, extra) {
   return new Response(
     JSON.stringify({ error, error_description: description, status, request_id: requestId, ...extra }),
@@ -1414,6 +2132,7 @@ async function defaultSqlDriver(config) {
 async function createApp(opts) {
   const { config, controllers } = opts;
   setSchema(opts.schema ?? {});
+  setSecretReader(opts.secretReader ?? null);
   const routes = buildRouteTable(controllers);
   if (routes.length === 0) {
     throw new BootRefused([], "boot refused: zero endpoints collected \u2014 nothing would answer.");
@@ -1439,7 +2158,6 @@ async function createApp(opts) {
       Notifications: modules.Notifications ?? stubModule("Notifications"),
       Flags: modules.Flags ?? stubModule("Flags"),
       Realtime: modules.Realtime ?? stubModule("Realtime"),
-      Purchases: modules.Purchases ?? stubModule("Purchases"),
       // Named, never undefined. A backend started without a secrets client
       // that returned `undefined` here would fail inside the handler as
       // "Cannot read properties of undefined", which says nothing about what
@@ -1526,7 +2244,8 @@ async function createApp(opts) {
           error: "too_many_requests",
           error_description: "Rate limit exceeded for this endpoint",
           status: 429,
-          request_id: requestId
+          request_id: requestId,
+          data: { retryAfter }
         }),
         { status: 429, headers: { ...JSON_HEADERS, "retry-after": String(retryAfter) } }
       );
@@ -1545,7 +2264,7 @@ async function createApp(opts) {
           const r = p.schema.safeParse(parsedBody);
           if (!r.success) {
             return envelope("bad_request", "Request body failed validation", 400, requestId, {
-              fields: r.error.issues.map((i) => ({ field: i.path.join("."), message: i.message }))
+              data: { fields: fieldErrors(r.error) }
             });
           }
           args[p.index] = r.data;
@@ -1555,7 +2274,7 @@ async function createApp(opts) {
           const r = p.schema.safeParse(Object.fromEntries(url.searchParams));
           if (!r.success) {
             return envelope("bad_request", "Query parameters failed validation", 400, requestId, {
-              fields: r.error.issues.map((i) => ({ field: i.path.join("."), message: i.message }))
+              data: { fields: fieldErrors(r.error) }
             });
           }
           args[p.index] = r.data;
@@ -1564,9 +2283,21 @@ async function createApp(opts) {
         case "param":
           args[p.index] = hit.params[p.name];
           break;
-        case "headers":
-          args[p.index] = Object.fromEntries(req.headers);
+        case "headers": {
+          const raw = Object.fromEntries(req.headers);
+          if (!p.schema) {
+            args[p.index] = raw;
+            break;
+          }
+          const r = p.schema.safeParse(headersFor(raw, p.schema));
+          if (!r.success) {
+            return envelope("bad_request", "Request headers failed validation", 400, requestId, {
+              data: { fields: fieldErrors(r.error) }
+            });
+          }
+          args[p.index] = r.data;
           break;
+        }
         case "user":
         case "optionalUser":
           args[p.index] = claims ? {
@@ -1615,6 +2346,14 @@ async function createApp(opts) {
         case "traceId":
           args[p.index] = requestId;
           break;
+        case "client":
+          args[p.index] = {
+            sdkVersion: req.headers.get("x-palbase-sdk-version"),
+            appVersion: req.headers.get("x-palbase-client-version"),
+            platform: req.headers.get("x-platform"),
+            osVersion: req.headers.get("x-os-version")
+          };
+          break;
         case "req":
           args[p.index] = req;
           break;