@palbase/backend 22.1.0 → 23.1.0

package/dist/engine/index.cjs

@@ -252,6 +252,19 @@ var TxPlanBuilder = class {
         }
         return this.push({ op: "insert", table: name, values: encoded }, `${name}.insert()`);
       },
+      upsert: (values, options) => {
+        const encoded = encodeMap(values, false);
+        if (Object.keys(encoded).length === 0) {
+          throw new TxPlanError(`${name}.upsert() needs at least one column`);
+        }
+        if (options.onConflict.length === 0) {
+          throw new TxPlanError(`${name}.upsert() needs at least one onConflict column`);
+        }
+        return this.push(
+          { op: "upsert", table: name, values: encoded, onConflict: options.onConflict },
+          `${name}.upsert()`
+        );
+      },
       insertMany: (rows) => {
         if (rows.length === 0) {
           return new TxRowsImpl(this, SKIPPED_OP, `${name}.insertMany()`);
@@ -459,8 +472,12 @@ 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),
-          search: (params) => ops().search(name, params)
+          findMany: (query, opts) => ops().findMany(name, query, opts),
+          upsert: (data, opts) => ops().upsert(name, data, opts),
+          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)
         };
       }
     }
@@ -469,17 +486,25 @@ 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),
-    search: (table, params) => raw.search(table, params)
+    findMany: (table, query, opts) => raw.findMany(table, query, opts),
+    upsert: (table, data, opts) => raw.upsert(table, data, opts),
+    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),
+    // Both surfaces get it: a savepoint on the service transaction is as useful
+    // as one on the request's, and each is bound to its own connection.
+    attempt: (fn) => raw.attempt(fn),
+    tables: makeTablesAccessor(() => reco),
     transaction(fn) {
       const builder = new TxPlanBuilder();
       return runTxPlan(raw, makeTxTablesAccessor(builder), builder, fn);
@@ -542,7 +567,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(
   {
@@ -948,6 +972,14 @@ function makeMemoryCache(opts = {}) {
 function quoteIdent(name) {
   return `"${name.replace(/"/g, '""')}"`;
 }
+function encodePgArray(value) {
+  const element = (x) => {
+    if (x === null || x === void 0) return "NULL";
+    if (Array.isArray(x)) return encodePgArray(x);
+    return `"${String(x).replace(/(["\\])/g, "\\$1")}"`;
+  };
+  return `{${value.map(element).join(",")}}`;
+}
 var BIND_SQL = "select set_config('role',$1,true), set_config('search_path','public',true), set_config('request.jwt.claims',$2,true)";
 function createLazyTransaction(sql, role, claimsJson, options = {}) {
   const { lockTimeout } = options;
@@ -1066,7 +1098,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) {
@@ -1092,7 +1159,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;
@@ -1108,18 +1175,109 @@ 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 compileWhere(table, colSet, where, add) {
+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 = (evt, fields) => {
+  console.log(evt, JSON.stringify(fields));
+};
+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)}::text <> ALL(ARRAY[${ids.map((x) => add(x)).join(", ")}])`;
+}
+function schemaColumns(table) {
+  const t = Object.values(currentSchema.tables ?? {}).find((x) => x?.name === table);
+  const cols = t?.columns ? Object.keys(t.columns) : [];
+  return cols.length > 0 ? new Set(cols) : null;
+}
+function orderClause(table, known, orderBy) {
+  if (!orderBy) return "";
+  const col = orderBy.column;
+  const shapeOK = /^[A-Za-z_][A-Za-z0-9_]*$/.test(col);
+  if (known !== null ? !known.has(col) : !shapeOK) {
+    throw new Error(`findMany(${table}): orderBy kolonu "${col}" tabloda yok`);
+  }
+  const dir = orderBy.direction === "desc" ? "DESC" : "ASC";
+  return ` ORDER BY ${quoteIdent(col)} ${dir}`;
+}
+function limitClause(limit) {
+  if (limit === void 0) return "";
+  if (!Number.isInteger(limit) || limit < 0) {
+    throw new Error(`findMany: limit bir negatif olmayan tam say\u0131 olmal\u0131 (geldi: ${String(limit)})`);
+  }
+  return ` LIMIT ${limit}`;
+}
+function compileWhere(table, colSet, where, add, caller = "search") {
   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)`);
+    if (colSet !== null && !colSet.has(col)) {
+      throw new Error(`${caller}(${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 (!Array.isArray(v)) throw new Error(`${caller}(${table}): where.${col}.in bir dizi olmal\u0131`);
           if (v.length === 0) {
             parts.push("false");
             continue;
@@ -1128,7 +1286,7 @@ function compileWhere(table, colSet, where, add) {
         } 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)`);
+          throw new Error(`${caller}(${table}): where.${col} bilinmeyen operat\xF6r "${op}" (gt/gte/lt/lte/neq/in)`);
         }
       }
     } else {
@@ -1138,6 +1296,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(
@@ -1199,7 +1366,8 @@ function createOps(tx) {
   const at = () => resolveTx(tx);
   const ops = {
     async query(sql, params = []) {
-      return asWireRows(await (await at()).unsafe(sql, params));
+      const bound = params.map((p) => Array.isArray(p) ? encodePgArray(p) : p);
+      return asWireRows(await (await at()).unsafe(sql, bound));
     },
     async insert(table, data) {
       const cols = Object.keys(data);
@@ -1215,6 +1383,41 @@ function createOps(tx) {
       }
       return asTableRow(table, inserted);
     },
+    /**
+     * INSERT the row, or UPDATE it when it collides on `onConflict`.
+     *
+     * WHY IT IS AN OPERATION rather than a recipe. "Try the insert, catch the
+     * unique violation, update instead" does not work here: a request runs in ONE
+     * Postgres transaction, so the failed insert aborts it and every later
+     * statement answers `current transaction is aborted`. A tenant measured that
+     * as 7 of 8 concurrent requests returning 500, gave up on upsert, and had a
+     * trigger create the row instead — a workaround that needs a new trigger for
+     * every table with a unique row.
+     *
+     * The conflict columns are excluded from the SET list: they are what MATCHED,
+     * so writing them back is at best a no-op and at worst a surprise.
+     */
+    async upsert(table, data, opts) {
+      const conflict = opts.onConflict;
+      if (conflict.length === 0) {
+        throw new Error(`upsert into ${table}: onConflict en az bir kolon ad\u0131 ister`);
+      }
+      const cols = Object.keys(data);
+      if (cols.length === 0) throw new Error(`upsert into ${table}: no columns given`);
+      const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
+      const conflictSet = new Set(conflict);
+      const assignments = cols.filter((c) => !conflictSet.has(c)).map((c) => `${quoteIdent(c)} = EXCLUDED.${quoteIdent(c)}`);
+      const action = assignments.length ? `DO UPDATE SET ${assignments.join(", ")}` : `DO UPDATE SET ${quoteIdent(conflict[0])} = EXCLUDED.${quoteIdent(conflict[0])}`;
+      const sql = `INSERT INTO ${quoteIdent(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) ON CONFLICT (${conflict.map(quoteIdent).join(", ")}) ${action} RETURNING *`;
+      const rows = await (await at()).unsafe(sql, asBindParams(table, cols, data));
+      const row = rows[0];
+      if (!row) {
+        throw new Error(
+          `upsert into ${table} returned no row \u2014 the write was rejected (an RLS policy, most likely).`
+        );
+      }
+      return asTableRow(table, row);
+    },
     async update(table, id, data) {
       const cols = Object.keys(data);
       if (cols.length === 0) return ops.findById(table, id);
@@ -1233,13 +1436,18 @@ function createOps(tx) {
       );
       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 asTableRows(table, await (await at()).unsafe(
-        `SELECT * FROM ${quoteIdent(table)}${where}`,
-        cols.map((c) => query[c])
-      ));
+    async findMany(table, query = {}, opts = {}) {
+      const params = [];
+      const add = (v) => {
+        params.push(v);
+        return `$${params.length}`;
+      };
+      const known = schemaColumns(table);
+      const whereSql = compileWhere(table, known, query, add, "findMany");
+      const order = orderClause(table, known, opts.orderBy);
+      const limit = limitClause(opts.limit);
+      const sql = `SELECT * FROM ${quoteIdent(table)} t WHERE true${whereSql}${order}${limit}`;
+      return asTableRows(table, await (await at()).unsafe(sql, params));
     },
     /**
      * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
@@ -1253,12 +1461,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 !== "");
@@ -1283,7 +1607,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 = "";
@@ -1292,7 +1617,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()
@@ -1305,27 +1630,235 @@ 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;
       }
-      const rows = await live.unsafe(sql, bind);
-      return asTableRows(table, rows);
+      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();
       return live.savepoint(async (sp) => cb(withTables(createOps(sp), currentSchema)));
     },
+    /**
+     * Run `fn` against a handle bound to a SAVEPOINT, so a failure inside it
+     * rolls back only what that handle wrote and the request can keep writing.
+     *
+     * WHY THE HANDLE IS AN ARGUMENT. The obvious shape — `attempt(async () => {
+     * ... Database.insert(...) ... })`, with no parameter — would have to point
+     * the ambient `Database` at the savepoint for the duration, and a request is
+     * concurrent with itself: `Promise.all([Database.insert(a),
+     * Database.attempt(...)])` would put `a` inside the savepoint and roll it
+     * back with it. Silent data loss, and the same interleaving this file already
+     * refuses for `asService()`. Passing the handle makes the boundary something
+     * you can see in the code that crosses it.
+     *
+     * Postgres, not us: the savepoint is released on success and rolled back on
+     * failure by the driver, so an aborted statement inside `fn` does not poison
+     * the surrounding transaction.
+     */
+    async attempt(fn) {
+      const live = await at();
+      return live.savepoint(async (sp) => fn(withTables(createOps(sp), currentSchema)));
+    },
     /**
      * Execute a whole transaction plan — what `Database.transaction(fn)` builds.
      *
@@ -1363,6 +1896,7 @@ function createOps(tx) {
 var currentSchema = {};
 function setSchema(schema) {
   cachedVectorSchema = null;
+  cachedTrgmSchema = null;
   const s = schema;
   currentSchema = (s && "default" in s ? s.default : s) ?? {};
 }
@@ -1375,22 +1909,47 @@ function withTables(ops, schema = currentSchema) {
       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, opts) => ops.findMany(name, query ?? {}, opts),
+      upsert: (data, opts) => ops.upsert(name, data, opts)
     };
   }
   const base = /* @__PURE__ */ Object.create(null);
   return Object.assign(base, ops, { tables });
 }
 var SERVICE_LOCK_TIMEOUT = "5s";
+function isAbortedTransaction(e) {
+  const code = e?.code;
+  const message = String(e?.message ?? "");
+  return code === "25P02" || /current transaction is aborted/i.test(message);
+}
+function isForeignKeyViolation(e) {
+  return e?.code === "23503";
+}
 function isLockTimeout(e) {
   const code = e?.code;
   const message = String(e?.message ?? "");
   return code === "55P03" || /lock timeout/i.test(message);
 }
-function diagnosingDriver(sql) {
-  const explain = (e) => isLockTimeout(e) ? new Error(
-    `Database.asService() waited too long for a row lock. It runs in its OWN transaction, so a row this request already wrote through Database.* is locked against it until the request commits \u2014 a wait that cannot end. Do that row's work on one surface or the other. (${String(e?.message ?? e)})`
-  ) : e;
+function diagnosingDriver(sql, surface = "service") {
+  const original = (e) => String(e?.message ?? e);
+  const explain = (e) => {
+    if (isAbortedTransaction(e)) {
+      return new Error(
+        `This request cannot write any more: an earlier write in it failed, and a request runs in ONE Postgres transaction, so every statement after the failure is refused. Nothing here is retryable in place. Wrap a write you expect to fail in \`Database.attempt(async (tx) => \u2026)\` \u2014 it takes a SAVEPOINT, so only that write rolls back \u2014 or use \`Database.tables.<t>.upsert(data, { onConflict: [...] })\` when the failure you were bracing for is a duplicate row. (${original(e)})`
+      );
+    }
+    if (surface === "service" && isForeignKeyViolation(e)) {
+      return new Error(
+        `Database.asService() hit a foreign key with nothing to point at. It runs in its OWN transaction on its OWN connection, so a row this request wrote through \`Database.*\` is not visible to it until the request commits \u2014 and the request cannot commit until the handler returns. If the row it needs is one this request just created, do both writes on ONE surface. (${original(e)})`
+      );
+    }
+    if (isLockTimeout(e)) {
+      return new Error(
+        `Database.asService() waited too long for a row lock. It runs in its OWN transaction, so a row this request already wrote through Database.* is locked against it until the request commits \u2014 a wait that cannot end. Do that row's work on one surface or the other. (${original(e)})`
+      );
+    }
+    return e;
+  };
   const wrapTx = (tx) => ({
     async unsafe(text, params) {
       try {
@@ -1409,13 +1968,13 @@ function diagnosingDriver(sql) {
   };
 }
 function createRequestDatabase(sql, identity) {
-  const tx = createLazyTransaction(sql, identity.role, identity.claimsJson);
+  const tx = createLazyTransaction(diagnosingDriver(sql, "user"), identity.role, identity.claimsJson);
   let serviceTx = null;
   let serviceClient = null;
   const asService = () => {
     if (serviceClient === null) {
       serviceTx = createLazyTransaction(
-        diagnosingDriver(sql),
+        diagnosingDriver(sql, "service"),
         identity.serviceRole,
         identity.claimsJson,
         { lockTimeout: SERVICE_LOCK_TIMEOUT }
@@ -1496,6 +2055,23 @@ async function runPlanOp(sp, op, results) {
       sql = cols.length ? `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) RETURNING *` : `INSERT INTO ${table} DEFAULT VALUES RETURNING *`;
       break;
     }
+    case "upsert": {
+      const cols = Object.keys(op.values ?? {});
+      const conflict = op.onConflict ?? [];
+      if (cols.length === 0 || conflict.length === 0) {
+        throw Object.assign(new Error(`upsert on ${op.table} needs columns and onConflict`), {
+          error_code: "tx_bad_upsert"
+        });
+      }
+      const rendered = cols.map(
+        (c) => renderValue(op.values[c], c, args, results, opVectorCols)
+      );
+      const conflictSet = new Set(conflict);
+      const sets = cols.filter((c) => !conflictSet.has(c)).map((c) => `${quoteIdent(c)} = EXCLUDED.${quoteIdent(c)}`);
+      const action = sets.length ? `DO UPDATE SET ${sets.join(", ")}` : `DO UPDATE SET ${quoteIdent(conflict[0])} = EXCLUDED.${quoteIdent(conflict[0])}`;
+      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) ON CONFLICT (${conflict.map(quoteIdent).join(", ")}) ${action} RETURNING *`;
+      break;
+    }
     case "insertMany": {
       const rows = op.rows ?? [];
       if (rows.length === 0 || !rows[0]) return [];
@@ -1692,6 +2268,41 @@ function verifySignature(presented, expected) {
   return diff === 0;
 }
 
+// src/engine/sse.ts
+var SSE_CONTENT_TYPE = "text/event-stream";
+function encodeFrame(value) {
+  return `data: ${JSON.stringify(value)}
+
+`;
+}
+function encodeErrorFrame(requestId) {
+  return `event: error
+data: ${JSON.stringify({ requestId })}
+
+`;
+}
+function makeSseWriter(opts) {
+  let begun = false;
+  let chain = Promise.resolve();
+  return {
+    write(value) {
+      const frame = encodeFrame(value);
+      if (!begun) {
+        begun = true;
+        chain = chain.then(() => opts.onFirstWrite()).then(() => opts.enqueue(frame));
+        return;
+      }
+      chain = chain.then(() => opts.enqueue(frame));
+    },
+    started() {
+      return begun;
+    },
+    drained() {
+      return chain;
+    }
+  };
+}
+
 // src/engine/fence.ts
 var SECRET_ENV = [
   "DATABASE_URL",
@@ -1831,7 +2442,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
@@ -1928,6 +2538,13 @@ async function createApp(opts) {
     const args = [];
     let parsedBody;
     let bodyRead = false;
+    let sseEnqueue = null;
+    let sseSettle = async () => {
+    };
+    const sseWriter = makeSseWriter({
+      enqueue: (chunk) => sseEnqueue?.(chunk),
+      onFirstWrite: () => sseSettle()
+    });
     for (const p of meta.params ?? []) {
       switch (p.kind) {
         case "body": {
@@ -2031,6 +2648,21 @@ async function createApp(opts) {
         case "req":
           args[p.index] = req;
           break;
+        // `@Signal()` — the raw request's AbortSignal, which enters the aborted
+        // state when the client disconnects. Measured on Bun: an infinite
+        // producer guarded by it stops within a few frames of the client dying.
+        // It is deliberately NOT reachable through `@Req()`: PBRequest carries
+        // request-scoped data and no signal.
+        case "signal":
+          args[p.index] = req.signal;
+          break;
+        // `@SseOut()` — the frame writer. Meaningful only on an `@Sse` route;
+        // on any other route it is an inert writer whose frames go nowhere,
+        // which is the same shape `@UploadedObject()` has off an `@Upload`
+        // route.
+        case "sseOut":
+          args[p.index] = sseWriter;
+          break;
         default:
           args[p.index] = void 0;
       }
@@ -2042,6 +2674,84 @@ async function createApp(opts) {
     });
     try {
       const services = buildServices(db);
+      if (meta.options?.sseConfig !== void 0) {
+        let sseController;
+        const sseEncoder = new TextEncoder();
+        const stream = new ReadableStream({
+          start(c) {
+            sseController = c;
+          }
+        });
+        sseEnqueue = (chunk) => {
+          try {
+            sseController.enqueue(sseEncoder.encode(chunk));
+          } catch {
+          }
+        };
+        let sawFirstFrame;
+        const firstFrame = new Promise((r) => sawFirstFrame = r);
+        sseSettle = async () => {
+          await db.commit();
+          sawFirstFrame();
+        };
+        const guarded = {
+          ...services,
+          Database: new Proxy(services.Database, {
+            get(target, prop, recv) {
+              if (sseWriter.started()) {
+                throw new Error(
+                  `sse_db_after_write: ${hit.entry.id} touched the database after its first write(). A streaming response settles its transaction with the first frame \u2014 do the database work before the first write.`
+                );
+              }
+              return Reflect.get(target, prop, recv);
+            }
+          })
+        };
+        let thrown = null;
+        const ran = Promise.resolve(runWithRuntime(guarded, () => {
+          const box = requestALS.getStore();
+          if (box) {
+            box.userId = userId ?? null;
+            box.requestId = requestId;
+            box.idempotencyKey = req.headers.get("idempotency-key");
+          }
+          const method = hit.entry.instance[meta.fnName];
+          if (typeof method !== "function") {
+            throw new Error(
+              `route ${hit.entry.id} names method ${meta.fnName}, which the controller does not define`
+            );
+          }
+          return method.apply(hit.entry.instance, args);
+        })).then(
+          () => void 0,
+          (err) => {
+            thrown = err;
+          }
+        );
+        await Promise.race([firstFrame, ran]);
+        if (!sseWriter.started()) {
+          await ran;
+          await db.commit();
+          if (thrown !== null) throw thrown;
+          return new Response(null, { status: 204 });
+        }
+        void (async () => {
+          await ran;
+          await sseWriter.drained();
+          try {
+            if (thrown !== null) {
+              log.error(`[engine] ${hit.entry.id} threw mid-stream`, thrown);
+              sseController.enqueue(sseEncoder.encode(encodeErrorFrame(requestId)));
+            }
+            sseController.close();
+          } catch {
+          }
+        })();
+        return new Response(stream, {
+          status: 200,
+          headers: { "content-type": SSE_CONTENT_TYPE, "cache-control": "no-cache" }
+        });
+      }
       const result = await runWithRuntime(services, () => {
         const box = requestALS.getStore();
         if (box) {