@palbase/backend 22.1.0 → 23.0.0

package/dist/bin/palbase-backend.cjs

@@ -426,7 +426,10 @@ function makeTablesAccessor(ops) {
           delete: (id) => ops().delete(name, id),
           findById: (id) => ops().findById(name, id),
           findMany: (query) => ops().findMany(name, query),
-          search: (params) => ops().search(name, params)
+          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)
         };
       }
     }
@@ -435,6 +438,7 @@ 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),
@@ -442,10 +446,13 @@ function makeTypedSurface(raw) {
     delete: (table, id) => raw.delete(table, id),
     findById: (table, id) => raw.findById(table, id),
     findMany: (table, query) => raw.findMany(table, query),
-    search: (table, params) => raw.search(table, params)
+    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);
@@ -508,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(
   {
@@ -1032,7 +1038,42 @@ function searchConfigFor(table) {
     );
   }
   const search = t.search;
-  const ftsCols = search?.text ?? [];
+  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) {
@@ -1058,7 +1099,7 @@ function searchConfigFor(table) {
     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 };
+  return { pk, cols, colSet: new Set(cols), ftsCols, legs, ...synonyms, ...validity };
 }
 function pickLeg(table, legs, using) {
   if (legs.length === 0) return null;
@@ -1074,7 +1115,74 @@ function pickLeg(table, legs, using) {
   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)) {
@@ -1104,6 +1212,15 @@ function compileWhere(table, colSet, where, add) {
   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(
@@ -1219,12 +1336,128 @@ function createOps(tx) {
       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 !== "");
@@ -1249,7 +1482,8 @@ function createOps(tx) {
         bind.push(v);
         return `$${bind.length}`;
       };
-      const whereSql = compileWhere(table, cfg.colSet, params.where ?? {}, add);
+      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 = "";
@@ -1258,7 +1492,7 @@ function createOps(tx) {
         const sch = await vectorSchemaWithGuc(live);
         const op = METRIC_OPERATOR[leg.metric] ?? METRIC_OPERATOR.cosine;
         let exactOrder = "";
-        if (whereSql !== "") {
+        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()
@@ -1271,21 +1505,208 @@ function createOps(tx) {
         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 qp = add(params.query);
+        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(", ");
-      let sql;
-      if (semSql !== "" && kwSql !== "") {
-        sql = `WITH sem AS (${semSql}), kw AS (${kwSql}), 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}, fused._score AS _score FROM fused JOIN ${quoteIdent(table)} t ON t.${quoteIdent(cfg.pk)} = fused.id ORDER BY fused._score DESC, t.${quoteIdent(cfg.pk)} LIMIT ${limit}`;
+      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 single = semSql !== "" ? `sem AS (${semSql})` : `kw AS (${kwSql})`;
-        const alias = semSql !== "" ? "sem" : "kw";
-        sql = `WITH ${single} SELECT ${colList}, (1.0/(${K} + ${alias}.r))::float8 AS _score FROM ${alias} JOIN ${quoteIdent(table)} t ON t.${quoteIdent(cfg.pk)} = ${alias}.id ORDER BY _score DESC, t.${quoteIdent(cfg.pk)} LIMIT ${limit}`;
+        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)`);
       }
-      const rows = await live.unsafe(sql, bind);
-      return asTableRows(table, rows);
+      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) {
@@ -1329,6 +1750,7 @@ function createOps(tx) {
 var currentSchema = {};
 function setSchema(schema) {
   cachedVectorSchema = null;
+  cachedTrgmSchema = null;
   const s = schema;
   currentSchema = (s && "default" in s ? s.default : s) ?? {};
 }
@@ -1736,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