@palbase/backend 27.1.0 → 29.0.0

package/dist/bin/palbase-backend.cjs

@@ -83,8 +83,11 @@ __name(isColumnExpr, "isColumnExpr");
 function assertNoExpressionHandles(caller, table, cols, data) {
   for (const c of cols) {
     const v = data[c];
+    if (isNowExpr(v)) {
+      throw new Error(`${caller}(${table}): "${c}" now() ald\u0131 \u2014 bu yolda de\u011Fer beklenir. Sat\u0131r EKLEN\u0130RKEN sunucu saatini yazman\u0131n yolu kolonu defaultNow() ile bildirmek (varsay\u0131lan kolonun yan\u0131nda durur, her \xE7a\u011Fr\u0131da tekrarlanmaz); var olan bir sat\u0131r\u0131 damgalamak i\xE7in updateMany({ where, set: { ${c}: now() } }) ya da $transaction i\xE7inde tx.public.${table}.updateWhere(where, { ${c}: now() }).`);
+    }
     if (isColumnExpr(v)) {
-      throw new Error(`${caller}(${table}): "${c}" bir ifade tutama\u011F\u0131 ald\u0131 (increment()/decrement()/now()). Bu yolda de\u011Fer beklenir. Saya\xE7 art\u0131\u015F\u0131 i\xE7in updateMany(where, { ${c}: increment(n) }) ya da $transaction i\xE7inde tx.tables.${table}.updateWhere(where, { ${c}: increment(n) }) kullan\u0131n.`);
+      throw new Error(`${caller}(${table}): "${c}" bir ifade tutama\u011F\u0131 ald\u0131 (increment()/decrement()). Bu yolda de\u011Fer beklenir. Saya\xE7 art\u0131\u015F\u0131 i\xE7in updateMany({ where, set: { ${c}: increment(n) } }) ya da $transaction i\xE7inde tx.public.${table}.updateWhere(where, { ${c}: increment(n) }) kullan\u0131n.`);
     }
     if (isColRef(v)) {
       throw new Error(`${caller}(${table}): "${c}" bir col() ald\u0131. Kolon referans\u0131 yaln\u0131z F\u0130LTREDE durabilir; bir kolonun de\u011Ferini ba\u015Fka bir kolona yazmak i\xE7in $query kullan\u0131n.`);
@@ -376,7 +379,9 @@ function encodeMap(map, allowColumnExpr) {
   const out = {};
   for (const key of Object.keys(map).sort()) {
     const value = map[key];
-    if (value === void 0) continue;
+    if (value === void 0) {
+      throw new TxPlanError(`${key} de\u011Feri undefined \u2014 bu bir yazma de\u011Feri de\u011Fil. Anahtar duruyor ama de\u011Feri yok, yani kolon sessizce YAZILMAZDI (istek g\xF6vdesinden gelen bir alan\u0131n eksik olmas\u0131 bu \u015Fekilde g\xF6r\xFCn\xFCr). Kolon varsay\u0131lan\u0131n\u0131 istiyorsan\u0131z anahtar\u0131 hi\xE7 koymay\u0131n; NULL yazmak istiyorsan\u0131z a\xE7\u0131k\xE7a null yaz\u0131n.`);
+    }
     out[key] = encodeValue(value, key, allowColumnExpr);
   }
   return out;
@@ -904,6 +909,11 @@ function makeTableProxy(ops, prefix) {
       const name = `${prefix}${prop}`;
       return {
         insert: /* @__PURE__ */ __name((data) => ops().insert(name, data), "insert"),
+        // DÖRDÜNCÜ FİİL, aynı gerekçeyle: tip söz veriyor, ops katmanı
+        // uyguluyor, ve bir handler'ın gerçekten dokunduğu yer BURASI.
+        // `runtime-table-verbs` kapısı bunu adıyla saydı.
+        aggregate: /* @__PURE__ */ __name((q) => ops().aggregate(name, q), "aggregate"),
+        insertMany: /* @__PURE__ */ __name((rows, opts) => ops().insertMany(name, rows, opts), "insertMany"),
         update: /* @__PURE__ */ __name((q) => ops().update(name, q.where.id, q.set), "update"),
         delete: /* @__PURE__ */ __name((id) => ops().delete(name, id), "delete"),
         findById: /* @__PURE__ */ __name((id) => ops().findById(name, id), "findById"),
@@ -960,6 +970,8 @@ function makeTypedSurface(raw) {
     $claim: /* @__PURE__ */ __name((table, unique, extra) => reco.claim(table, unique, extra), "$claim"),
     $lockRows: /* @__PURE__ */ __name((table, ids) => reco.lockRows(table, ids), "$lockRows"),
     $advisoryXactLock: /* @__PURE__ */ __name((key) => reco.advisoryXactLock(key), "$advisoryXactLock"),
+    $aggregate: /* @__PURE__ */ __name((table, q) => raw.aggregate(table, q), "$aggregate"),
+    $insertMany: /* @__PURE__ */ __name((table, rows, opts) => raw.insertMany(table, rows, opts), "$insertMany"),
     $supersede: /* @__PURE__ */ __name((table, id, row) => raw.supersede(table, id, row), "$supersede")
   };
   const base = Object.assign(ops, {
@@ -1149,6 +1161,20 @@ ${detail}`);
 }
 __name(loadConfig, "loadConfig");
 
+// src/refusals.ts
+var DECLARATION_REFUSAL = /* @__PURE__ */ Symbol.for("palbase.backend.declarationRefusal");
+var DeclarationRefused = class extends Error {
+  static {
+    __name(this, "DeclarationRefused");
+  }
+  /** @see DECLARATION_REFUSAL — realm-safe, unlike `instanceof`. */
+  [DECLARATION_REFUSAL] = true;
+  constructor(message) {
+    super(message);
+    this.name = "DeclarationRefused";
+  }
+};
+
 // src/engine/auth.ts
 function b64urlToBytes(s) {
   const pad = s.replace(/-/g, "+").replace(/_/g, "/");
@@ -1275,9 +1301,11 @@ function effectiveAuth(routeAuth, controllerAuth) {
   };
   const o = spec;
   const role = typeof o.role === "string" && o.role.trim() !== "" ? o.role.trim() : void 0;
+  const permission = typeof o.permission === "string" && o.permission.trim() !== "" ? o.permission.trim() : void 0;
   return {
     required: o.required !== false,
     role,
+    permission,
     verifiedEmail: o.verifiedEmail === true
   };
 }
@@ -1471,12 +1499,12 @@ function buildRelations(schemas) {
     const held = names.get(name);
     if (held !== void 0) {
       if (held.def.owns === true && origin.def.owns === true) {
-        throw new Error(`table "${tableKey}" declares TWO owner columns (${held.column}, ${origin.column}) \u2014 a table has at most ONE ownedByUser(). If the other column only POINTS at a user, declare it userRef({ onDelete: \u2026 }) instead.`);
+        throw new DeclarationRefused(`table "${tableKey}" declares TWO owner columns (${held.column}, ${origin.column}) \u2014 a table has at most ONE ownedByUser(). If the other column only POINTS at a user, declare it userRef({ onDelete: \u2026 }) instead.`);
       }
       const heldFix = renameCall(held);
       const originFix = renameCall(origin);
       const remedy = heldFix === originFix ? `rename one of them: ${heldFix}` : `rename one of them \u2014 "${held.table}.${held.column}": ${heldFix}; "${origin.table}.${origin.column}": ${originFix}`;
-      throw new Error(`table "${tableKey}": ${describeOrigin(held)} and ${describeOrigin(origin)} both resolve to the relation name "${name}" \u2014 ${remedy}.`);
+      throw new DeclarationRefused(`table "${tableKey}": ${describeOrigin(held)} and ${describeOrigin(origin)} both resolve to the relation name "${name}" \u2014 ${remedy}.`);
     }
     names.set(name, origin);
     out.get(tableKey)?.push(edge);
@@ -2054,7 +2082,7 @@ function compileWhereBare(table, colSet, where, add, caller = "search", alias =
         const rel = rels.find((r) => r.name === relName);
         if (rel === void 0) {
           const known = rels.map((r) => r.name).sort();
-          throw new Error(`${caller}(${table}): has.${relName} diye bir ili\u015Fki yok${known.length > 0 ? ` (bilinenler: ${known.join(", ")})` : " \u2014 bu tablonun hi\xE7 ili\u015Fkisi yok"}. \u0130li\u015Fkiler yabanc\u0131 anahtarlardan T\xDCRET\u0130L\u0130R; ad\u0131n\u0131 de\u011Fi\u015Ftirmek i\xE7in references(..., { as, reverseAs }).`);
+          throw new Error(`${caller}(${table}): has.${relName} diye bir ili\u015Fki yok` + (known.length > 0 ? ` (bilinenler: ${known.join(", ")}). \u0130li\u015Fkiler yabanc\u0131 anahtarlardan T\xDCRET\u0130L\u0130R; ad\u0131n\u0131 de\u011Fi\u015Ftirmek i\xE7in references(..., { as, reverseAs }).` : `. Bu tablo H\u0130\xC7 yabanc\u0131 anahtar bildirmiyor, ve ili\u015Fkiler onlardan T\xDCRET\u0130L\u0130R. Var olan bir veritaban\u0131ndan introspect edilmi\u015F \u015Femalarda bu s\u0131k olur: kolon \`text()\`/\`uuid()\` olarak durur, \`references(() => <tablo>.<kolon>)\` yoktur. Bildirdi\u011Finiz anda ili\u015Fki iki tarafta da adland\u0131r\u0131l\u0131r \u2014 ama bu CANLI veritaban\u0131na giden bir k\u0131s\u0131tt\u0131r ve mevcut yetim sat\u0131rlar onu d\xFC\u015F\xFCr\xFCr; \xF6nce onlar\u0131 say\u0131n.`));
         }
         const ourCol = rel.kind === "many" ? primaryKeyOf(table) : rel.via;
         const theirCol = rel.kind === "many" ? rel.via : primaryKeyOf(rel.to);
@@ -2234,6 +2262,57 @@ async function embedQuery(embed, text) {
   }
 }
 __name(embedQuery, "embedQuery");
+function buildSetAssignments(table, cols, set, add, caller) {
+  return cols.map((c) => {
+    const expr = columnExprOf(set[c]);
+    if (expr !== null && expr.fn === "now") {
+      return `${quoteIdent(c)} = now()`;
+    }
+    if (expr !== null) {
+      const operator = expr.fn === "inc" ? "+" : "-";
+      const t = transformsOf(currentSchema, table).get(c);
+      const amount = t?.toDb === void 0 || expr.by === null || expr.by === void 0 ? expr.by : t.toDb(expr.by);
+      return `${quoteIdent(c)} = ${quoteIdent(c)} ${operator} ${add(amount)}`;
+    }
+    return `${quoteIdent(c)} = ${add(asBindParams(table, [
+      c
+    ], set, caller)[0])}`;
+  }).join(", ");
+}
+__name(buildSetAssignments, "buildSetAssignments");
+function buildValueTuple(table, cols, data, add, caller) {
+  return cols.map((c) => {
+    const expr = columnExprOf(data[c]);
+    if (expr !== null && expr.fn === "now") return "now()";
+    if (expr !== null) {
+      throw new Error(`${caller}(${table}): "${c}" ${expr.fn === "inc" ? "increment()" : "decrement()"} ald\u0131 \u2014 sat\u0131r HEN\xDCZ YOK, yani "kolonun \u015Fu anki de\u011Feri" diye bir \u015Fey yok. Ba\u015Flang\u0131\xE7 de\u011Ferini yaz\u0131n; art\u0131rmak i\xE7in sat\u0131r olu\u015Ftuktan sonra updateMany({ where, set: { ${c}: ${expr.fn === "inc" ? "increment" : "decrement"}(n) } }).`);
+    }
+    return add(asBindParams(table, [
+      c
+    ], data, caller)[0]);
+  }).join(", ");
+}
+__name(buildValueTuple, "buildValueTuple");
+function columnTypeOf(table, col) {
+  const def = tableDefOf(table);
+  const c = def?.columns?.[col];
+  if (c === void 0 || c === null) return null;
+  const d = typeof c === "object" && "_def" in c ? c._def : c;
+  return d !== null && typeof d === "object" && typeof d.type === "string" ? d.type : null;
+}
+__name(columnTypeOf, "columnTypeOf");
+var NUMERIC_PG_TYPES = /* @__PURE__ */ new Set([
+  "integer",
+  "bigint",
+  "numeric"
+]);
+function aggregateExpr(table, fn, col, alias) {
+  const q = `t.${quoteIdent(col)}`;
+  const t = columnTypeOf(table, col);
+  if (fn === "sum" || fn === "avg") return `${fn}(${q})::text AS ${quoteIdent(alias)}`;
+  return t !== null && NUMERIC_PG_TYPES.has(t) && t !== "integer" ? `${fn}(${q})::text AS ${quoteIdent(alias)}` : `${fn}(${q}) AS ${quoteIdent(alias)}`;
+}
+__name(aggregateExpr, "aggregateExpr");
 function createOps(tx) {
   const at = /* @__PURE__ */ __name(() => resolveTx(tx), "at");
   const ops = {
@@ -2247,9 +2326,11 @@ function createOps(tx) {
     async insert(table, data) {
       const cols = Object.keys(data);
       if (cols.length === 0) throw new Error(`insert into ${table}: no columns given`);
-      const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
-      const sql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) RETURNING *`;
-      const rows = await (await at()).unsafe(sql, asBindParams(table, cols, data, "insert"));
+      const params = [];
+      const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
+      const tuple = buildValueTuple(table, cols, data, add, "insert");
+      const sql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${tuple}) RETURNING *`;
+      const rows = await (await at()).unsafe(sql, params);
       const inserted = rows[0];
       if (!inserted) {
         throw new Error(`insert into ${table} returned no row \u2014 the write was rejected (an RLS policy, most likely).`);
@@ -2257,6 +2338,41 @@ function createOps(tx) {
       return asTableRow(table, inserted);
     },
     /**
+    * Çok satırı TEK statement'la ekle.
+    *
+    * Motor bunu zaten yapıyordu ve yalnız PLAN yolundan erişilebiliyordu
+    * (`tx.public.x.insertMany`). Dışarıda tek kapı `insert(row)` olduğu için
+    * "şu 200 satırı yaz" ya 200 gidiş-dönüş ya da ham SQL oluyordu — ölçüldü:
+    * bir müşteri projesinde bir seed rutini satırları tek tek siliyor
+    * (`deleteMany` VARKEN) ve tek tek ekliyor.
+    *
+    * SATIRLARIN ANAHTAR KÜMESİ AYNI OLMAK ZORUNDA. Kolon listesi tek bir
+    * statement'ta paylaşıldığı için ilk satırdan türer; farklı anahtar taşıyan
+    * bir satırın fazla kolonu SESSİZCE YAZILMAZDI. Eksik kolon için `null`
+    * yazın ya da varsayılanı istiyorsanız o satırları ayrı çağrıda ekleyin.
+    */
+    async insertMany(table, rows, opts) {
+      if (rows.length === 0) return [];
+      const first = rows[0];
+      const cols = Object.keys(first);
+      if (cols.length === 0) throw new Error(`insertMany into ${table}: no columns given`);
+      for (let i = 1; i < rows.length; i++) {
+        const keys = Object.keys(rows[i]);
+        const missing = cols.filter((c) => !(c in rows[i]));
+        const extra = keys.filter((k) => !cols.includes(k));
+        if (missing.length > 0 || extra.length > 0) {
+          throw new Error(`insertMany(${table}): ${i}. sat\u0131r\u0131n kolonlar\u0131 ilk sat\u0131rla ayn\u0131 de\u011Fil` + (missing.length > 0 ? ` (eksik: ${missing.join(", ")})` : "") + (extra.length > 0 ? ` (fazla: ${extra.join(", ")})` : "") + `. Tek statement kolon listesini PAYLA\u015EIR, yani fazla kolon sessizce yaz\u0131lmaz ve eksik kolon yanl\u0131\u015F s\xFCtuna kayar. Eksikler i\xE7in null yaz\u0131n, ya da farkl\u0131 \u015Fekilli sat\u0131rlar\u0131 ayr\u0131 \xE7a\u011Fr\u0131larda ekleyin.`);
+        }
+      }
+      const params = [];
+      const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
+      const tuples = rows.map((r) => `(${buildValueTuple(table, cols, r, add, "insertMany")})`);
+      const tail = opts !== void 0 && opts.onConflict.length > 0 ? ` ${onConflictTail(cols, opts.onConflict, opts.action ?? "ignore")}` : "";
+      const sql = `INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}${tail} RETURNING *`;
+      const out = await (await at()).unsafe(sql, params);
+      return out.map((r) => asTableRow(table, r));
+    },
+    /**
     * Bir ADI kilitle — satırı değil (FR-054).
     *
     * "Aynı anda tek bir fatura kapanışı koşsun" gibi, kilitlenecek satırı
@@ -2342,8 +2458,10 @@ function createOps(tx) {
       const live = await at();
       try {
         return await live.savepoint(async (sp) => {
-          const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
-          const rows = await sp.unsafe(`INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) RETURNING *`, asBindParams(table, cols, data, "claim"));
+          const params = [];
+          const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
+          const tuple = buildValueTuple(table, cols, data, add, "claim");
+          const rows = await sp.unsafe(`INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${tuple}) RETURNING *`, params);
           if (!rows[0]) {
             throw new Error(`claim(${table}): INSERT sat\u0131r d\xF6nd\xFCrmedi \u2014 yazma reddedildi (b\xFCy\xFCk olas\u0131l\u0131kla bir RLS policy'si).`);
           }
@@ -2394,10 +2512,11 @@ 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 bindData = [];
+        const addPut = /* @__PURE__ */ __name((v) => `$${bindData.push(v)}`, "addPut");
+        const ph = buildValueTuple(table, cols, data, addPut, "put");
         const insertSql = `INSERT INTO ${quoteTable(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, "put");
         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 ");
@@ -2422,12 +2541,14 @@ function createOps(tx) {
         ]);
         return asTableRow(table, second[0]);
       }
-      const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
+      const params = [];
+      const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
+      const placeholders = buildValueTuple(table, cols, data, add, "put");
       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 ${quoteTable(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, "put"));
+      const rows = await (await at()).unsafe(sql, params);
       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).`);
@@ -2438,12 +2559,14 @@ function createOps(tx) {
       assertNotAppendOnly("update", table);
       const cols = Object.keys(data);
       if (cols.length === 0) return ops.findById(table, id);
-      const assignments = cols.map((c, i) => `${quoteIdent(c)} = $${i + 1}`).join(", ");
-      const sql = `UPDATE ${quoteTable(table)} SET ${assignments} WHERE id = $${cols.length + 1} RETURNING *`;
-      const rows = await (await at()).unsafe(sql, [
-        ...asBindParams(table, cols, data, "update"),
-        id
-      ]);
+      const params = [];
+      const add = /* @__PURE__ */ __name((v) => {
+        params.push(v);
+        return `$${params.length}`;
+      }, "add");
+      const assignments = buildSetAssignments(table, cols, data, add, "update");
+      const sql = `UPDATE ${quoteTable(table)} SET ${assignments} WHERE id = ${add(id)} RETURNING *`;
+      const rows = await (await at()).unsafe(sql, params);
       return rows[0] ? asTableRow(table, rows[0]) : null;
     },
     async delete(table, id) {
@@ -2470,7 +2593,7 @@ function createOps(tx) {
     * 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) {
+    async updateMany(table, where, set, opts) {
       assertNotAppendOnly("updateMany", table);
       const cols = Object.keys(set);
       if (cols.length === 0) {
@@ -2489,26 +2612,19 @@ function createOps(tx) {
         params.push(v);
         return `$${params.length}`;
       }, "add");
-      const assignments = cols.map((c) => {
-        const expr = columnExprOf(set[c]);
-        if (expr !== null && expr.fn === "now") {
-          return `${quoteIdent(c)} = now()`;
-        }
-        if (expr !== null) {
-          const operator = expr.fn === "inc" ? "+" : "-";
-          const t = transformsOf(currentSchema, table).get(c);
-          const amount = t?.toDb === void 0 || expr.by === null || expr.by === void 0 ? expr.by : t.toDb(expr.by);
-          return `${quoteIdent(c)} = ${quoteIdent(c)} ${operator} ${add(amount)}`;
-        }
-        return `${quoteIdent(c)} = ${add(asBindParams(table, [
-          c
-        ], set, "updateMany")[0])}`;
-      }).join(", ");
+      const assignments = buildSetAssignments(table, cols, set, add, "updateMany");
       const whereSql = compileWhere(table, known, where, add, "updateMany");
       assertHasPredicate(whereSql, "updateMany", table);
       const pk = primaryKeyOf(table);
-      const sql = isSinglePkEquality(where, pk) || pk === null ? `UPDATE ${quoteTable(table)} AS t SET ${assignments} WHERE true${whereSql} RETURNING *` : `WITH locked AS (SELECT t.${quoteIdent(pk)} FROM ${quoteTable(table)} t WHERE true${whereSql} ORDER BY t.${quoteIdent(pk)} FOR NO KEY UPDATE) UPDATE ${quoteTable(table)} AS t SET ${assignments} FROM locked WHERE t.${quoteIdent(pk)} = locked.${quoteIdent(pk)} RETURNING t.*`;
-      return asTableRows(table, await (await at()).unsafe(sql, params));
+      const wantRows = opts?.returning !== false;
+      const tail = wantRows ? "RETURNING *" : "RETURNING 1";
+      const simple = isSinglePkEquality(where, pk) || pk === null;
+      const body = simple ? `UPDATE ${quoteTable(table)} AS t SET ${assignments} WHERE true${whereSql} ${tail}` : `UPDATE ${quoteTable(table)} AS t SET ${assignments} FROM locked WHERE t.${quoteIdent(pk)} = locked.${quoteIdent(pk)} ` + (wantRows ? "RETURNING t.*" : "RETURNING 1");
+      const lockedCte = simple ? "" : `WITH locked AS (SELECT t.${quoteIdent(pk)} FROM ${quoteTable(table)} t WHERE true${whereSql} ORDER BY t.${quoteIdent(pk)} FOR NO KEY UPDATE) `;
+      const sql = wantRows ? `${lockedCte}${body}` : simple ? `WITH upd AS (${body}) SELECT count(*)::int AS n FROM upd` : `${lockedCte.replace(/ $/, "")}, upd AS (${body}) SELECT count(*)::int AS n FROM upd`;
+      const out = await (await at()).unsafe(sql, params);
+      if (!wantRows) return Number(out[0]?.["n"] ?? 0);
+      return asTableRows(table, out);
     },
     /**
     * Delete every row the filter matches, in ONE statement; resolves to how
@@ -2538,6 +2654,78 @@ function createOps(tx) {
     * An empty filter is legitimate HERE: counting a whole table is a read, and
     * reads do not destroy anything.
     */
+    /**
+    * Toplama — `count`'un yanına `sum`/`avg`/`min`/`max` ve `groupBy`.
+    *
+    * Var olma nedeni: bunlar olmadan "bu hesabın toplamı" ya `$query`'ye ya da
+    * TÜM satırları çekip JS'te toplamaya düşüyor. İkincisi hem N+1 hem de para
+    * için YANLIŞ — `numeric` JS `number`'ına uğradığı anda kesinliğini
+    * kaybeder.
+    *
+    * `groupBy` verilirse SATIRLAR döner, verilmezse TEK sonuç. Boş kümede
+    * Postgres NULL döndürür, 0 değil — ve bu SDK onu `null` olarak geçiriyor:
+    * "hiç satır yoktu" ile "toplam sıfırdı" farklı şeyler.
+    */
+    async aggregate(table, q = {}) {
+      const known = schemaColumns(table);
+      const check = /* @__PURE__ */ __name((col, where) => {
+        if (known !== null && !known.has(col)) {
+          throw new Error(`aggregate(${table}): ${where} kolonu "${col}" tabloda yok (FR-016)`);
+        }
+      }, "check");
+      const parts = [];
+      const wants = [];
+      for (const fn of [
+        "sum",
+        "avg",
+        "min",
+        "max"
+      ]) {
+        for (const col of q[fn] ?? []) {
+          check(col, fn);
+          if (fn === "sum" || fn === "avg") {
+            const t = columnTypeOf(table, col);
+            if (t !== null && !NUMERIC_PG_TYPES.has(t)) {
+              throw new Error(`aggregate(${table}): ${fn}("${col}") say\u0131sal olmayan bir kolonda \u2014 "${col}" bir ${t} kolonu. Toplama yaln\u0131z integer/bigint/numeric kolonlarda anlaml\u0131; ka\xE7 sat\u0131r oldu\u011Funu saymak i\xE7in count: true kullan\u0131n.`);
+            }
+          }
+          const alias = `${fn}__${col}`;
+          wants.push({
+            fn,
+            col,
+            alias
+          });
+          parts.push(aggregateExpr(table, fn, col, alias));
+        }
+      }
+      if (q.count === true) parts.push('count(*) AS "_count"');
+      if (parts.length === 0) {
+        throw new Error(`aggregate(${table}): hi\xE7bir toplama istenmedi \u2014 sonu\xE7 bo\u015F bir nesne olurdu. sum/avg/min/max kolonlar\u0131n\u0131 ya da count: true'yu verin.`);
+      }
+      const groups = q.groupBy ?? [];
+      for (const col of groups) check(col, "groupBy");
+      const groupSel = groups.map((c) => `t.${quoteIdent(c)} AS ${quoteIdent(`g__${c}`)}`);
+      const params = [];
+      const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
+      const whereSql = compileWhere(table, known, q.where ?? {}, add, "aggregate");
+      const groupSql = groups.length > 0 ? ` GROUP BY ${groups.map((c) => `t.${quoteIdent(c)}`).join(", ")}` : "";
+      const sql = `SELECT ${[
+        ...groupSel,
+        ...parts
+      ].join(", ")} FROM ${quoteTable(table)} t WHERE true${whereSql}${groupSql}`;
+      const rows = await (await at()).unsafe(sql, params);
+      const shape = /* @__PURE__ */ __name((r) => {
+        const out = {};
+        for (const c of groups) out[c] = r[`g__${c}`];
+        for (const w of wants) {
+          const bucket = out[w.fn] ??= {};
+          bucket[w.col] = r[w.alias] ?? null;
+        }
+        if (q.count === true) out["count"] = Number(r["_count"] ?? 0);
+        return out;
+      }, "shape");
+      return groups.length > 0 ? rows.map(shape) : shape(rows[0] ?? {});
+    },
     async count(table, where = {}) {
       const params = [];
       const add = /* @__PURE__ */ __name((v) => {
@@ -2961,8 +3149,10 @@ function createOps(tx) {
           [cfg.pk]: newId
         };
         const cols = Object.keys(data);
-        const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
-        const rows = await sp.unsafe(`INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) RETURNING *`, asBindParams(table, cols, data, "supersede"));
+        const params = [];
+        const add = /* @__PURE__ */ __name((v) => `$${params.push(v)}`, "add");
+        const tuple = buildValueTuple(table, cols, data, add, "supersede");
+        const rows = await sp.unsafe(`INSERT INTO ${quoteTable(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${tuple}) RETURNING *`, params);
         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)`);
         }
@@ -3918,6 +4108,14 @@ var DiError = class extends Error {
   path;
   at;
   fixes;
+  /**
+  * EVERY `DiKind` IS A FACT ABOUT THE AUTHOR'S DECLARATIONS — an unresolvable
+  * dependency, a cycle, a class no module owns. Not one of them is something
+  * the environment could change, so restarting re-reads the same bytes and
+  * fails identically. The cure is a new artifact, and the tag is how the
+  * runtime learns that without matching on wording.
+  */
+  [DECLARATION_REFUSAL] = true;
   constructor(kind, path, at, detail, fixes) {
     super(`
 Kind:  ${kind}
@@ -4316,6 +4514,26 @@ var AUTHOR_ANSWERED = /* @__PURE__ */ new Set([
   409,
   429
 ]);
+async function refuseUnlessAuthorized(client, spec, requestId) {
+  if (spec.permission !== void 0) {
+    const [row] = await client.query("select auth.has_permission($1) as ok", [
+      spec.permission
+    ]);
+    if (row?.ok !== true) {
+      return envelope("forbidden", `This endpoint requires the "${spec.permission}" permission`, 403, requestId);
+    }
+  }
+  if (spec.role !== void 0) {
+    const [row] = await client.query("select $1 = any(auth.app_roles()) as ok", [
+      spec.role
+    ]);
+    if (row?.ok !== true) {
+      return envelope("forbidden", `This endpoint requires the "${spec.role}" role`, 403, requestId);
+    }
+  }
+  return null;
+}
+__name(refuseUnlessAuthorized, "refuseUnlessAuthorized");
 async function createApp(opts) {
   const { config, controllers } = opts;
   const container = buildContainer();
@@ -4333,7 +4551,7 @@ async function createApp(opts) {
   assertNoOrphanEntryPoints(controllers, container.owned);
   const routes = buildRouteTable(controllers, liveContainer);
   if (routes.length === 0) {
-    throw new BootRefused([], "boot refused: zero endpoints collected \u2014 nothing would answer.");
+    throw new DeclarationRefused("boot refused: zero endpoints collected \u2014 nothing would answer.");
   }
   const sql = opts.sql ?? await defaultSqlDriver(config);
   await sql.unsafe("select 1");
@@ -4407,8 +4625,23 @@ async function createApp(opts) {
     if (spec.required && !callerClaims) {
       return envelope("unauthorized", "A valid access token is required", 401, requestId);
     }
-    if (callerClaims && spec.role && callerClaims.role !== spec.role) {
-      return envelope("forbidden", `This endpoint requires the "${spec.role}" role`, 403, requestId);
+    if (callerClaims) {
+      const uploadDb = createRequestDatabase(sql, {
+        role: config.dbRole,
+        serviceRole: config.dbServiceRole,
+        claimsJson: JSON.stringify(callerClaims)
+      });
+      try {
+        const refusal = await refuseUnlessAuthorized(uploadDb.client, spec, requestId);
+        if (refusal) {
+          await uploadDb.commit();
+          return refusal;
+        }
+        await uploadDb.commit();
+      } catch (err) {
+        await uploadDb.rollback(err);
+        throw err;
+      }
     }
     const grant = grantFor(target?.entry, {
       userId: typeof callerClaims?.sub === "string" ? callerClaims.sub : null,
@@ -4441,8 +4674,14 @@ async function createApp(opts) {
       return envelope("unauthorized", "A valid access token is required", 401, requestId);
     }
     const userId = typeof claims?.sub === "string" ? claims.sub : void 0;
-    if (claims && spec.role && claims.role !== spec.role) {
-      return envelope("forbidden", `This endpoint requires the "${spec.role}" role`, 403, requestId);
+    const db = createRequestDatabase(sql, {
+      role: config.dbRole,
+      serviceRole: config.dbServiceRole,
+      claimsJson: JSON.stringify(claims ?? {})
+    });
+    if (claims) {
+      const refusal = await refuseUnlessAuthorized(db.client, spec, requestId);
+      if (refusal) return refusal;
     }
     if (claims && spec.verifiedEmail && claims.email_verified !== true) {
       return envelope("email_not_verified", "A verified email address is required", 403, requestId);
@@ -4663,11 +4902,6 @@ async function createApp(opts) {
           args[p.index] = void 0;
       }
     }
-    const db = createRequestDatabase(sql, {
-      role: config.dbRole,
-      serviceRole: config.dbServiceRole,
-      claimsJson: JSON.stringify(claims ?? {})
-    });
     try {
       const services = buildServices(db);
       if (meta.options?.sseConfig !== void 0) {