@palbase/backend 23.0.0 → 24.0.0

package/dist/bin/palbase-backend.cjs

@@ -218,7 +218,20 @@ var TxPlanBuilder = class {
         }
         return this.push({ op: "insert", table: name, values: encoded }, `${name}.insert()`);
       },
-      insertMany: (rows) => {
+      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, opts) => {
         if (rows.length === 0) {
           return new TxRowsImpl(this, SKIPPED_OP, `${name}.insertMany()`);
         }
@@ -229,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);
@@ -403,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) {
@@ -425,10 +490,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),
+          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),
+          facets: (params) => ops().facets(name, params),
           supersede: (id, row) => ops().supersede(name, id, row)
         };
       }
@@ -445,13 +512,21 @@ function makeTypedSurface(raw) {
     update: (table, id, data) => raw.update(table, id, data),
     delete: (table, id) => raw.delete(table, id),
     findById: (table, id) => raw.findById(table, id),
-    findMany: (table, query) => raw.findMany(table, query),
+    findMany: (table, query, 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, {
+    // 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();
@@ -603,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 {
@@ -920,6 +1033,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;
@@ -957,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);
     }
   };
@@ -1002,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;
@@ -1140,7 +1291,9 @@ function expandSynonyms(query, map) {
     }).join("");
   }).join("");
 }
-var searchLogger = null;
+var searchLogger = (evt, fields) => {
+  console.log(evt, JSON.stringify(fields));
+};
 function logNoResults(table, query, mode, n) {
   if (n === 0) {
     searchLogger?.("palbase.search.no_results", {
@@ -1181,19 +1334,55 @@ function validitySql(v, add) {
 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(", ")}])`;
+  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) {
+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 = [];
   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;
@@ -1202,7 +1391,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 {
@@ -1211,6 +1400,13 @@ function compileWhere(table, colSet, where, add) {
   }
   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) {
@@ -1282,7 +1478,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);
@@ -1298,6 +1495,74 @@ 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`);
+      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)}`);
+      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);
@@ -1309,6 +1574,86 @@ 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) return [];
+      if (Object.keys(where).length === 0) {
+        throw new Error(
+          `updateMany(${table}): bo\u015F filtre T\xDCM sat\u0131rlar\u0131 g\xFCncellerdi \u2014 bir filtre verin, ya da her sat\u0131ra uyan bir ko\u015Ful yaz\u0131n`
+        );
+      }
+      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");
+      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) {
+      if (Object.keys(where).length === 0) {
+        throw new Error(
+          `deleteMany(${table}): bo\u015F filtre T\xDCM sat\u0131rlar\u0131 silerdi \u2014 bir filtre verin, ya da her sat\u0131ra uyan bir ko\u015Ful yaz\u0131n`
+        );
+      }
+      const params = [];
+      const add = (v) => {
+        params.push(v);
+        return `$${params.length}`;
+      };
+      const known = schemaColumns(table);
+      const whereSql = compileWhere(table, known, where, add, "deleteMany");
+      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`,
@@ -1316,13 +1661,19 @@ 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 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));
     },
     /**
      * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
@@ -1404,7 +1755,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);
@@ -1413,8 +1766,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;
@@ -1422,7 +1786,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(", ");
@@ -1437,13 +1801,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);
@@ -1539,7 +1903,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);
@@ -1562,6 +1926,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) {
@@ -1713,6 +2096,27 @@ function createOps(tx) {
       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.
      *
@@ -1763,22 +2167,68 @@ 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 isLockTimeout(e) {
-  const code = e?.code;
+function isAbortedTransaction(e) {
   const message = String(e?.message ?? "");
-  return code === "55P03" || /lock timeout/i.test(message);
+  return sqlstateOf(e) === "25P02" || /current transaction is aborted/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 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 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 message = String(e?.message ?? "");
+  return sqlstateOf(e) === "55P03" || /lock timeout/i.test(message);
+}
+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 (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)})`
+      );
+    }
+    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 {
@@ -1797,13 +2247,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 }
@@ -1818,9 +2268,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);
     }
   };
 }
@@ -1884,6 +2334,20 @@ 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)
+      );
+      sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) ${onConflictTail(cols, conflict, "update")} RETURNING *`;
+      break;
+    }
     case "insertMany": {
       const rows = op.rows ?? [];
       if (rows.length === 0 || !rows[0]) return [];
@@ -1891,7 +2355,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": {
@@ -1966,6 +2432,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) {
@@ -1984,6 +2482,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 ?? ""}` || "/";
@@ -1993,7 +2492,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)
       });
     }
   }
@@ -2080,6 +2582,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/index.ts
 var JSON_HEADERS = { "content-type": "application/json" };
 function fieldErrors(err) {
@@ -2254,6 +2791,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": {
@@ -2357,6 +2901,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;
       }
@@ -2368,6 +2927,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) {
@@ -2426,31 +3063,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