@palbase/backend 23.1.0 → 24.0.1

package/dist/bin/palbase-backend.cjs

@@ -231,7 +231,7 @@ var TxPlanBuilder = class {
           `${name}.upsert()`
         );
       },
-      insertMany: (rows) => {
+      insertMany: (rows, opts) => {
         if (rows.length === 0) {
           return new TxRowsImpl(this, SKIPPED_OP, `${name}.insertMany()`);
         }
@@ -242,7 +242,23 @@ var TxPlanBuilder = class {
         }
         const encoded = rows.map((row) => encodeMap(row, false));
         assertUniformRows(encoded, name);
-        return this.push({ op: "insertMany", table: name, rows: encoded }, `${name}.insertMany()`);
+        if (opts !== void 0 && opts.onConflict.length === 0) {
+          throw new TxPlanError(
+            `${name}.insertMany() was given a conflict action with no onConflict columns. Postgres matches a collision on columns, so name them.`
+          );
+        }
+        return this.push(
+          {
+            op: "insertMany",
+            table: name,
+            rows: encoded,
+            // Omitted entirely when no options were given, so the op a plain
+            // insertMany produces is byte-identical to the one it produced
+            // before this option existed.
+            ...opts !== void 0 ? { onConflict: opts.onConflict, action: opts.action ?? "ignore" } : {}
+          },
+          `${name}.insertMany()`
+        );
       },
       updateWhere: (where, set) => {
         const encodedWhere = encodeMap(where, false);
@@ -416,6 +432,42 @@ function __getRuntime() {
   }
   return runtime;
 }
+var LIFECYCLE = /* @__PURE__ */ Symbol.for("palbase.backend.lifecycleHooks");
+function declaredLifecycle() {
+  const g = globalThis;
+  return g[LIFECYCLE] ??= { start: [], shutdown: [] };
+}
+function reason(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function drain(hooks) {
+  for (const h of [...hooks].reverse()) {
+    try {
+      await h.run();
+    } catch (err) {
+      console.error(`[palbase] shutdown hook "${h.name}" failed: ${reason(err)}`, err);
+    }
+  }
+}
+async function __runStartHooks() {
+  const slot = declaredLifecycle();
+  const start = slot.start.splice(0);
+  const shutdown = slot.shutdown.splice(0);
+  for (const h of start) {
+    try {
+      await h.run();
+    } catch (err) {
+      await drain(shutdown);
+      throw new Error(`[palbase] start hook "${h.name}" failed: ${reason(err)}`, { cause: err });
+    }
+  }
+  let drained = false;
+  return async () => {
+    if (drained) return;
+    drained = true;
+    await drain(shutdown);
+  };
+}
 function makeServiceProxy(key) {
   const handler = {
     get(_target, prop, receiver) {
@@ -443,6 +495,7 @@ function makeTablesAccessor(ops) {
           search: (params) => ops().search(name, params),
           similar: (id, params) => ops().similar(name, id, params),
           recommend: (params) => ops().recommend(name, params),
+          facets: (params) => ops().facets(name, params),
           supersede: (id, row) => ops().supersede(name, id, row)
         };
       }
@@ -461,9 +514,13 @@ function makeTypedSurface(raw) {
     findById: (table, id) => raw.findById(table, id),
     findMany: (table, query, opts) => raw.findMany(table, query, opts),
     upsert: (table, data, opts) => raw.upsert(table, data, opts),
+    updateMany: (table, where, set) => raw.updateMany(table, where, set),
+    deleteMany: (table, where) => raw.deleteMany(table, where),
+    count: (table, where) => raw.count(table, where),
     search: (table, params) => raw.search(table, params),
     similar: (table, id, params) => reco.similar(table, id, params),
     recommend: (table, params) => reco.recommend(table, params),
+    facets: (table, params) => reco.facets(table, params),
     supersede: (table, id, row) => raw.supersede(table, id, row)
   };
   return Object.assign(ops, {
@@ -621,6 +678,44 @@ var HttpError = class extends Error {
     return result;
   }
 };
+var NamedHttpError = class extends HttpError {
+  constructor(status, defaultCode, name, message, code, data) {
+    super(status, code ?? defaultCode, message ?? defaultMessage(name), data);
+    this.name = name;
+  }
+};
+function defaultMessage(name) {
+  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
+}
+var Conflict = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(409, "conflict", "Conflict", message, code, data);
+  }
+};
+var UniqueViolation = class extends Conflict {
+  /**
+   * Whether `e` is a unique violation — REGARDLESS of which copy of this SDK
+   * constructed it.
+   *
+   * Use this instead of `instanceof`. Measured on a live stack: a controller
+   * bundle INLINES its own copy of `@palbase/backend`, and the engine that
+   * raises this error is the runtime's copy. Two copies, two class identities,
+   * and `e instanceof UniqueViolation` is false in the one place a caller
+   * writes it — a check that reads as correct and silently never matches.
+   */
+  static is(e) {
+    return typeof e === "object" && e !== null && e.name === "UniqueViolation" && typeof e.constraint === "string";
+  }
+  /** The unique constraint the statement violated, as Postgres named it.
+   * `""` when the driver did not say which — see `engine/db.ts`. */
+  constraint;
+  constructor(constraint, message, code, data) {
+    super(message ?? "Unique constraint violated", code ?? "unique_violation", data);
+    this.name = "UniqueViolation";
+    this.constraint = constraint;
+  }
+};
 
 // src/engine/config.ts
 var BootRefused = class extends Error {
@@ -983,9 +1078,9 @@ function createLazyTransaction(sql, role, claimsJson, options = {}) {
       release();
       await settled;
     },
-    async rollback(reason) {
+    async rollback(reason2) {
       if (!opening) return;
-      fail(reason);
+      fail(reason2);
       await settled?.catch(() => void 0);
     }
   };
@@ -1028,18 +1123,48 @@ function reviveVectors(row, vectorCols) {
   }
   return row;
 }
+function transformsOf(schema, table) {
+  const out = /* @__PURE__ */ new Map();
+  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;
+      const t = d?.transform;
+      if (t !== null && typeof t === "object") {
+        out.set(col, t);
+      }
+    }
+  }
+  return out;
+}
+function applyFromDb(row, transforms) {
+  if (transforms.size === 0) return row;
+  for (const [col, t] of transforms) {
+    if (t.fromDb === void 0) continue;
+    const v = row[col];
+    if (v === null || v === void 0) continue;
+    row[col] = t.fromDb(v);
+  }
+  return row;
+}
 function asTableRow(table, row) {
-  return reviveVectors(asWireRow(row), vectorColumnsOf(currentSchema, table));
+  const revived = reviveVectors(asWireRow(row), vectorColumnsOf(currentSchema, table));
+  return applyFromDb(revived, transformsOf(currentSchema, table));
 }
 function asTableRows(table, rows) {
   const vectorCols = vectorColumnsOf(currentSchema, table);
-  return rows.map((row) => reviveVectors(asWireRow(row), vectorCols));
+  const transforms = transformsOf(currentSchema, table);
+  return rows.map((row) => applyFromDb(reviveVectors(asWireRow(row), vectorCols), transforms));
 }
 function asBindParams(table, cols, data) {
   const vectorCols = vectorColumnsOf(currentSchema, table);
+  const transforms = transformsOf(currentSchema, table);
   return cols.map((c) => {
     const v = data[c];
-    return Array.isArray(v) && vectorCols.has(c) ? toVectorLiteral(v) : v;
+    if (Array.isArray(v) && vectorCols.has(c)) return toVectorLiteral(v);
+    const t = transforms.get(c);
+    if (t?.toDb !== void 0 && v !== null && v !== void 0) return t.toDb(v);
+    return v;
   });
 }
 var SELECTIVITY_EXACT_THRESHOLD = 1e4;
@@ -1233,13 +1358,33 @@ function limitClause(limit) {
   }
   return ` LIMIT ${limit}`;
 }
+function offsetClause(offset, limit) {
+  if (offset === void 0) return "";
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new Error(
+      `findMany: offset bir negatif olmayan tam say\u0131 olmal\u0131 (geldi: ${String(offset)})`
+    );
+  }
+  if (limit === void 0) {
+    throw new Error(
+      "findMany: offset yaln\u0131z limit ile birlikte verilir \u2014 limitsiz offset bir sayfa de\u011Fil, s\u0131n\u0131rs\u0131z bir kuyru\u011Fun kayd\u0131r\u0131lm\u0131\u015F\u0131d\u0131r"
+    );
+  }
+  return ` OFFSET ${offset}`;
+}
 function compileWhere(table, colSet, where, add, caller = "search") {
   const parts = [];
+  const transforms = transformsOf(currentSchema, table);
+  const bindFor = (col) => {
+    const t = transforms.get(col);
+    return t?.toDb === void 0 ? add : (v) => add(v === null || v === void 0 ? v : t.toDb(v));
+  };
   for (const [col, cond] of Object.entries(where)) {
     if (colSet !== null && !colSet.has(col)) {
       throw new Error(`${caller}(${table}): where kolonu "${col}" tabloda yok (FR-016)`);
     }
     const q = `t.${quoteIdent(col)}`;
+    const bind = bindFor(col);
     if (cond !== null && typeof cond === "object" && !Array.isArray(cond)) {
       for (const [op, v] of Object.entries(cond)) {
         if (op === "in") {
@@ -1248,19 +1393,26 @@ function compileWhere(table, colSet, where, add, caller = "search") {
             parts.push("false");
             continue;
           }
-          parts.push(`${q} IN (${v.map((x) => add(x)).join(", ")})`);
+          parts.push(`${q} IN (${v.map((x) => bind(x)).join(", ")})`);
         } else if (op in WHERE_OPS) {
-          parts.push(`${q} ${WHERE_OPS[op]} ${add(v)}`);
+          parts.push(`${q} ${WHERE_OPS[op]} ${bind(v)}`);
         } else {
           throw new Error(`${caller}(${table}): where.${col} bilinmeyen operat\xF6r "${op}" (gt/gte/lt/lte/neq/in)`);
         }
       }
     } else {
-      parts.push(`${q} = ${add(cond)}`);
+      parts.push(`${q} = ${bind(cond)}`);
     }
   }
   return parts.length === 0 ? "" : ` AND ${parts.join(" AND ")}`;
 }
+function onConflictTail(cols, conflict, action) {
+  const target = `ON CONFLICT (${conflict.map(quoteIdent).join(", ")})`;
+  if (action === "ignore") return `${target} DO NOTHING`;
+  const conflictSet = new Set(conflict);
+  const sets = cols.filter((c) => !conflictSet.has(c)).map((c) => `${quoteIdent(c)} = EXCLUDED.${quoteIdent(c)}`);
+  return sets.length ? `${target} DO UPDATE SET ${sets.join(", ")}` : `${target} DO UPDATE SET ${quoteIdent(conflict[0])} = EXCLUDED.${quoteIdent(conflict[0])}`;
+}
 var cachedVectorSchema = null;
 var cachedTrgmSchema = null;
 async function trgmSchemaOf(live) {
@@ -1370,6 +1522,39 @@ function createOps(tx) {
       }
       const cols = Object.keys(data);
       if (cols.length === 0) throw new Error(`upsert into ${table}: no columns given`);
+      if (searchConfigFor(table)?.validity) {
+        const ph = cols.map((_, i) => `$${i + 1}`).join(", ");
+        const insertSql = `INSERT INTO ${quoteIdent(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${ph}) ON CONFLICT (${conflict.map(quoteIdent).join(", ")}) WHERE "valid_to" IS NULL DO NOTHING RETURNING *`;
+        const live = await at();
+        const bindData = asBindParams(table, cols, data);
+        const first = await live.unsafe(insertSql, bindData);
+        if (first[0]) return asTableRow(table, first[0]);
+        const condSql = conflict.map((c, i) => `${quoteIdent(c)} = $${i + 1}`).join(" AND ");
+        const condBind = conflict.map((c) => data[c]);
+        const cur = await live.unsafe(
+          `SELECT * FROM ${quoteIdent(table)} WHERE ${condSql} AND "valid_to" IS NULL`,
+          condBind
+        );
+        const old = cur[0];
+        if (old === void 0) {
+          throw new Error(`upsert into ${table}: e\u015Fzamanl\u0131 supersede yar\u0131\u015F\u0131 \u2014 ge\xE7erli sat\u0131r bulunamad\u0131, iste\u011Fi yineleyin (D-020)`);
+        }
+        const pk = Object.keys(old).includes("id") ? "id" : Object.keys(old)[0];
+        await live.unsafe(
+          `UPDATE ${quoteIdent(table)} SET "valid_to" = now() WHERE ${quoteIdent(pk)} = $1 AND "valid_to" IS NULL`,
+          [old[pk]]
+        );
+        const second = await live.unsafe(insertSql, bindData);
+        if (!second[0]) {
+          throw new Error(`upsert into ${table}: e\u015Fzamanl\u0131 supersede yar\u0131\u015F\u0131 \u2014 yeni sat\u0131r a\xE7\u0131lamad\u0131, iste\u011Fi yineleyin (D-020)`);
+        }
+        const fresh = second[0];
+        await live.unsafe(
+          `UPDATE ${quoteIdent(table)} SET "superseded_by" = $2 WHERE ${quoteIdent(pk)} = $1`,
+          [old[pk], fresh[pk]]
+        );
+        return asTableRow(table, second[0]);
+      }
       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)}`);
@@ -1395,6 +1580,82 @@ function createOps(tx) {
     async delete(table, id) {
       await (await at()).unsafe(`DELETE FROM ${quoteIdent(table)} WHERE id = $1`, [id]);
     },
+    /**
+     * Update every row the filter matches, in ONE statement.
+     *
+     * The capability was already here and only reachable from inside a
+     * transaction plan (`tx.tables.x.updateWhere`, since 11.0.0). Outside it the
+     * only door was `update(id, …)`, so "mark every unapproved row in this
+     * household" was an N+1 loop or hand-written SQL — and hand-written SQL is
+     * where the typed surface and RLS both stop helping.
+     *
+     * The filter language is `findMany`'s, compiled by the same `compileWhere`:
+     * one filter language, or the two spellings drift.
+     *
+     * AN EMPTY FILTER IS REFUSED. `UPDATE … WHERE true` is a whole-table write,
+     * and the shape that produces it by accident — a filter object built from
+     * request input that happened to come back empty — is exactly the shape that
+     * should not silently succeed. Callers who mean every row say so with a
+     * predicate that is true for every row.
+     */
+    async updateMany(table, where, set) {
+      const cols = Object.keys(set);
+      if (cols.length === 0) {
+        throw new Error(
+          `updateMany(${table}): nothing to set. An update with no columns is not a no-op worth pretending happened \u2014 pass the columns to write.`
+        );
+      }
+      const params = [];
+      const add = (v) => {
+        params.push(v);
+        return `$${params.length}`;
+      };
+      const assignments = cols.map((c) => `${quoteIdent(c)} = ${add(asBindParams(table, [c], set)[0])}`).join(", ");
+      const known = schemaColumns(table);
+      const whereSql = compileWhere(table, known, where, add, "updateMany");
+      assertHasPredicate(whereSql, "updateMany", table);
+      const sql = `UPDATE ${quoteIdent(table)} AS t SET ${assignments} WHERE true${whereSql} RETURNING *`;
+      return asTableRows(table, await (await at()).unsafe(sql, params));
+    },
+    /**
+     * Delete every row the filter matches, in ONE statement; resolves to how
+     * many went. Same filter language, same empty-filter refusal as
+     * {@link updateMany} — and here the accident is worse.
+     */
+    async deleteMany(table, where) {
+      const params = [];
+      const add = (v) => {
+        params.push(v);
+        return `$${params.length}`;
+      };
+      const known = schemaColumns(table);
+      const whereSql = compileWhere(table, known, where, add, "deleteMany");
+      assertHasPredicate(whereSql, "deleteMany", table);
+      const sql = `DELETE FROM ${quoteIdent(table)} AS t WHERE true${whereSql} RETURNING 1`;
+      const rows = await (await at()).unsafe(sql, params);
+      return rows.length;
+    },
+    /**
+     * How many rows match — the half of pagination `limit`/`offset` cannot
+     * supply. Without it a page count is either a guess or "fetch everything and
+     * read .length", and the second one is the scale risk this surface exists to
+     * remove.
+     *
+     * An empty filter is legitimate HERE: counting a whole table is a read, and
+     * reads do not destroy anything.
+     */
+    async count(table, where = {}) {
+      const params = [];
+      const add = (v) => {
+        params.push(v);
+        return `$${params.length}`;
+      };
+      const known = schemaColumns(table);
+      const whereSql = compileWhere(table, known, where, add, "count");
+      const sql = `SELECT count(*) AS n FROM ${quoteIdent(table)} t WHERE true${whereSql}`;
+      const rows = await (await at()).unsafe(sql, params);
+      return Number(rows[0]?.n ?? 0);
+    },
     async findById(table, id) {
       const rows = await (await at()).unsafe(
         `SELECT * FROM ${quoteIdent(table)} WHERE id = $1`,
@@ -1412,7 +1673,8 @@ function createOps(tx) {
       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}`;
+      const offset = offsetClause(opts.offset, opts.limit);
+      const sql = `SELECT * FROM ${quoteIdent(table)} t WHERE true${whereSql}${order}${limit}${offset}`;
       return asTableRows(table, await (await at()).unsafe(sql, params));
     },
     /**
@@ -1495,7 +1757,9 @@ function createOps(tx) {
           bindC.push(v);
           return `$${bindC.length}`;
         };
-        const whereC = compileWhere(table, cfg.colSet, params.where ?? {}, addC) + excludeSql(cfg.pk, excl, addC) + validityFor(addC);
+        const userWhereC = compileWhere(table, cfg.colSet, params.where ?? {}, addC);
+        const whereC = userWhereC + excludeSql(cfg.pk, excl, addC) + validityFor(addC);
+        const parentJoinC = ` JOIN ${quoteIdent(table)} t ON t.${quoteIdent(cfg.pk)} = c.${pidQ} WHERE true${whereC} AND `;
         const liveC = await at();
         const K2 = 50;
         const cpool = Math.max(limit * 9, 90);
@@ -1504,8 +1768,19 @@ function createOps(tx) {
         if (qvC !== null) {
           const sch = await vectorSchemaWithGuc(liveC);
           const op = METRIC_OPERATOR[ck.metric] ?? METRIC_OPERATOR.cosine;
+          let exactOrderC = "";
+          if (userWhereC !== "") {
+            const probeRows = await liveC.unsafe(
+              `SELECT count(*)::int AS n FROM (SELECT 1 FROM ${quoteIdent(ck.table)} c${parentJoinC}c.embedding IS NOT NULL LIMIT ${SELECTIVITY_EXACT_THRESHOLD + 1}) s`,
+              bindC.slice()
+            );
+            const n = probeRows?.[0]?.n;
+            if (typeof n === "number" && n <= SELECTIVITY_EXACT_THRESHOLD) {
+              exactOrderC = " + 0.0";
+            }
+          }
           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}`;
+          semC = `SELECT c.${pidQ} AS pid, c.chunk_seq, ROW_NUMBER() OVER (ORDER BY (c.embedding OPERATOR(${quoteIdent(sch)}.${op}) ${vp}::${quoteIdent(sch)}.vector)${exactOrderC}) AS r FROM ${quoteIdent(ck.table)} c${parentJoinC}c.embedding IS NOT NULL ORDER BY r LIMIT ${cpool}`;
         }
         let qpC = "";
         let qpCIdx = -1;
@@ -1513,7 +1788,7 @@ function createOps(tx) {
           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}`;
+          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${parentJoinC}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(", ");
@@ -1528,13 +1803,13 @@ function createOps(tx) {
           } 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}`;
+          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`;
           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 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${parentJoinC}${quoteIdent(tsch)}.word_similarity(${qpC}, coalesce(c.content,'')) > 0.3 ORDER BY r LIMIT ${cpool}`;
           const retryBindC = bindC.slice();
           if (qpCIdx >= 0) retryBindC[qpCIdx] = params.query;
           rowsC = await liveC.unsafe(assembleC(trgmKwC, false), retryBindC);
@@ -1630,7 +1905,7 @@ function createOps(tx) {
       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 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 ${quoteIdent(tsch)}.word_similarity(${qpRef}, ${expr}) > 0.3${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);
@@ -1653,6 +1928,25 @@ function createOps(tx) {
      * 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).
      */
+    /** D-021 (FR-027 DX): sayaçlar BAĞIMSIZ op'la — search'ün dizi-üstü
+     * `_facets` özelliği JSON.stringify'da kaybolur (dizi özelliği), tenant
+     * yanıtına koyunca sessizce yok olurdu. Ayrı dönüş ciddi bir sözleşmedir;
+     * search'teki alan geriye-uyum için DURUR. where + validity default'u
+     * sayaçlara da uygulanır (sayaç, kullanıcının gördüğü kümeyi anlatır). */
+    async facets(table, params) {
+      const cfg = searchConfigFor(table);
+      if (!cfg) {
+        throw new Error(`facets(${table}): tablo aranabilir de\u011Fil \u2014 search beyan\u0131 yok (FR-027)`);
+      }
+      for (const col of params.facets) {
+        if (!cfg.colSet.has(col)) {
+          throw new Error(`facets(${table}): facets kolonu "${col}" tabloda yok (FR-027)`);
+        }
+      }
+      const live = await at();
+      const extra = cfg.validity ? (add) => validitySql(params.validity, add) : () => "";
+      return fetchFacets(live, table, cfg.colSet, params.facets, params.where ?? {}, extra);
+    },
     async similar(table, id, opts = {}) {
       const cfg = searchConfigFor(table);
       if (!cfg) {
@@ -1884,17 +2178,41 @@ function withTables(ops, schema = currentSchema) {
 }
 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);
+  return sqlstateOf(e) === "25P02" || /current transaction is aborted/i.test(message);
+}
+function assertHasPredicate(whereSql, op, table) {
+  if (whereSql.trim().length > 0) return;
+  throw new Error(
+    `${op}(${table}): the filter compiled to no condition, so this would have written EVERY row. An empty filter \u2014 or an operator object with no operators in it, like { col: {} } \u2014 is refused. Name a condition.`
+  );
+}
+function sqlstateOf(e) {
+  const err = e;
+  const isState = (v) => typeof v === "string" && /^[0-9A-Z]{5}$/.test(v);
+  if (isState(err?.code)) return err.code;
+  if (isState(err?.errno)) return err.errno;
+  if (typeof err?.errno === "number") {
+    const asText = String(err.errno);
+    if (isState(asText)) return asText;
+  }
+  return void 0;
 }
 function isForeignKeyViolation(e) {
-  return e?.code === "23503";
+  return sqlstateOf(e) === "23503";
+}
+function isUniqueViolation(e) {
+  return sqlstateOf(e) === "23505";
+}
+function constraintOf(e) {
+  const named = e?.constraint;
+  if (typeof named === "string" && named.length > 0) return named;
+  const message = String(e?.message ?? "");
+  return /violates unique constraint "([^"]+)"/.exec(message)?.[1] ?? "";
 }
 function isLockTimeout(e) {
-  const code = e?.code;
   const message = String(e?.message ?? "");
-  return code === "55P03" || /lock timeout/i.test(message);
+  return sqlstateOf(e) === "55P03" || /lock timeout/i.test(message);
 }
 function diagnosingDriver(sql, surface = "service") {
   const original = (e) => String(e?.message ?? e);
@@ -1904,6 +2222,9 @@ function diagnosingDriver(sql, surface = "service") {
         `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 (isUniqueViolation(e)) {
+      return new UniqueViolation(constraintOf(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)})`
@@ -1955,9 +2276,9 @@ function createRequestDatabase(sql, identity) {
       await tx.commit();
       await serviceTx?.commit();
     },
-    async rollback(reason) {
-      await tx.rollback(reason);
-      await serviceTx?.rollback(reason);
+    async rollback(reason2) {
+      await tx.rollback(reason2);
+      await serviceTx?.rollback(reason2);
     }
   };
 }
@@ -2032,10 +2353,7 @@ async function runPlanOp(sp, op, results) {
       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 *`;
+      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) ${onConflictTail(cols, conflict, "update")} RETURNING *`;
       break;
     }
     case "insertMany": {
@@ -2045,7 +2363,9 @@ async function runPlanOp(sp, op, results) {
       const tuples = rows.map(
         (r) => `(${cols.map((c) => renderValue(r[c], c, args, results, opVectorCols)).join(", ")})`
       );
-      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")} RETURNING *`;
+      const conflictCols = op.onConflict ?? [];
+      const tail = op.action !== void 0 && conflictCols.length > 0 ? ` ${onConflictTail(cols, conflictCols, op.action)}` : "";
+      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}${tail} RETURNING *`;
       break;
     }
     case "update": {
@@ -2120,6 +2440,38 @@ function getRoutes(ctor) {
   }));
 }
 
+// src/decorators/controller.ts
+var REGISTRY = /* @__PURE__ */ Symbol.for("palbase.backend.allControllers");
+function registry() {
+  const g = globalThis;
+  const existing = g[REGISTRY];
+  if (existing) return existing;
+  const fresh = [];
+  g[REGISTRY] = fresh;
+  return fresh;
+}
+function getRegisteredControllers() {
+  return registry().slice();
+}
+var APP_DEFAULT_AUTH = /* @__PURE__ */ Symbol.for("palbase.backend.appDefaultAuth");
+function appAuthSlot() {
+  return globalThis;
+}
+function getDefaultAuth() {
+  return appAuthSlot()[APP_DEFAULT_AUTH];
+}
+function resolveEffectiveAuth(routeAuth, controllerAuth) {
+  return routeAuth ?? controllerAuth ?? getDefaultAuth() ?? true;
+}
+function assertZeroArgConstructor(Ctrl, kind) {
+  const arity = Ctrl.length ?? 0;
+  if (arity === 0) return;
+  const name = Ctrl.name ?? "<anonymous>";
+  throw new Error(
+    `${kind} ${name} declares a constructor with ${arity} parameter(s). A ${kind} is constructed by the runtime with a zero-argument constructor \u2014 there is no injector to supply them, so every parameter would arrive as undefined. Hold the dependency as a module-level singleton the ${kind} imports (\`const repo = makeRepo()\` beside the class), and construct the service directly in tests (e.g. \`new TodoService(fakeDatabase().db)\`).`
+  );
+}
+
 // src/engine/router.ts
 var CONTROLLER_META = /* @__PURE__ */ Symbol.for("palbase.backend.controllerMeta");
 function toSegments(path) {
@@ -2138,6 +2490,7 @@ function buildRouteTable(controllers) {
         `controller ${name} collected zero routes. Either it declares no @Get/@Post/\u2026 , or its decorator metadata was erased at build time \u2014 check that the bundle was compiled with experimentalDecorators enabled.`
       );
     }
+    assertZeroArgConstructor(Ctrl, "controller");
     const instance = new ctor();
     for (const r of routes) {
       const full = `${basePath}${r.subpath ?? ""}` || "/";
@@ -2147,7 +2500,10 @@ function buildRouteTable(controllers) {
         meta: r,
         instance,
         id: `${r.method} ${full}`,
-        controllerAuth: meta?.defaultAuth
+        // The route's OWN spec is deliberately not folded in here: this field
+        // is what applies when the route is silent, and `effectiveAuth` puts
+        // the route level back on top per request.
+        controllerAuth: resolveEffectiveAuth(void 0, meta?.defaultAuth)
       });
     }
   }
@@ -2715,31 +3071,28 @@ async function createApp(opts) {
       return envelope("internal_error", "The request could not be completed", 500, requestId);
     }
   }
+  let runShutdownHooks;
+  try {
+    runShutdownHooks = await __runStartHooks();
+  } catch (err) {
+    await closeDriver(sql);
+    throw err;
+  }
   return {
     handle,
     routes,
     config,
     runInServiceScope,
     async shutdown() {
-      const closable = sql;
-      await closable.close?.();
-      await closable.end?.();
+      await runShutdownHooks();
+      await closeDriver(sql);
     }
   };
 }
-
-// src/decorators/controller.ts
-var REGISTRY = /* @__PURE__ */ Symbol.for("palbase.backend.allControllers");
-function registry() {
-  const g = globalThis;
-  const existing = g[REGISTRY];
-  if (existing) return existing;
-  const fresh = [];
-  g[REGISTRY] = fresh;
-  return fresh;
-}
-function getRegisteredControllers() {
-  return registry().slice();
+async function closeDriver(sql) {
+  const closable = sql;
+  await closable.close?.();
+  await closable.end?.();
 }
 
 // src/bin/palbase-backend.ts