@palbase/backend 34.0.0 → 34.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Palbase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin/palbase-backend.cjs

@@ -2812,10 +2812,10 @@ function applyFromDb(row, transforms) {
 __name(applyFromDb, "applyFromDb");
 function asTableRow(table, row) {
   const revived = reviveVectors(asWireRow(row), vectorColumnsOf(currentSchema, table));
-  return applyFromDb(revived, transformsOf(currentSchema, table));
+  return foldCan(table, applyFromDb(revived, transformsOf(currentSchema, table)), false);
 }
 __name(asTableRow, "asTableRow");
-function asTableRows(table, rows, withSpec) {
+function asTableRows(table, rows, withSpec, partial = false) {
   const vectorCols = vectorColumnsOf(currentSchema, table);
   const transforms = transformsOf(currentSchema, table);
   const result = rows.map((row) => applyFromDb(reviveVectors(asWireRow(row), vectorCols), transforms));
@@ -2831,6 +2831,7 @@ function asTableRows(table, rows, withSpec) {
       ], nested)[0];
     }
   }
+  for (const row of result) foldCan(table, row, partial);
   return result;
 }
 __name(asTableRows, "asTableRows");
@@ -3129,21 +3130,248 @@ function projectedColumn(table, column, alias) {
   return columnTypeOf(table, column) === "timestamp" ? `${expr} AS ${quoteIdent(column)}` : expr;
 }
 __name(projectedColumn, "projectedColumn");
+var CAN_PREFIX = "can:";
+var canMemo = /* @__PURE__ */ new WeakMap();
+function canRoleGate(roles) {
+  if (roles.length === 0) return null;
+  const names = roles.flatMap((r) => [
+    r,
+    `backend_${r}`
+  ]).map((r) => `'${r.replace(/'/g, "''")}'`);
+  return `(current_user = ANY (ARRAY[${names.join(", ")}]))`;
+}
+__name(canRoleGate, "canRoleGate");
+function canEntries(def, alias) {
+  const policies = def.policies ?? [];
+  const dropped = [];
+  const restrictive = [];
+  for (const p of policies) {
+    if (p.permissive !== false || p.command !== "update" && p.command !== "all") continue;
+    const r = renderCanUsing(p, alias, def.name);
+    if (r === null) {
+      return {
+        entries: [],
+        dropped: policies.filter((q) => q.command === "update" && q.permissive !== false).map((q) => ({
+          name: q.name,
+          reason: `restrictive policy "${p.name}" cannot be evaluated as a column`
+        }))
+      };
+    }
+    const rGate = canRoleGate(p.roles ?? []);
+    restrictive.push(rGate === null ? r : `((NOT ${rGate}) OR ${r})`);
+  }
+  const entries = [];
+  for (const p of policies) {
+    if (p.command !== "update" || p.permissive === false) continue;
+    if (Buffer.byteLength(CAN_PREFIX + p.name, "utf8") > 63) {
+      dropped.push({
+        name: p.name,
+        reason: "its name is longer than 59 bytes and Postgres would truncate the column alias"
+      });
+      continue;
+    }
+    const using = renderCanUsing(p, alias, def.name);
+    if (using === null) {
+      dropped.push({
+        name: p.name,
+        reason: "its using expression cannot be selected as a column (null; a raw string that is table-qualified, carries a comment or unbalanced parentheses, or calls auth.has_permission outside a (select \u2026) wrapper; or a shape this engine does not render)"
+      });
+      continue;
+    }
+    const gate = canRoleGate(p.roles ?? []);
+    const parts = [
+      ...gate === null ? [] : [
+        gate
+      ],
+      using,
+      ...restrictive
+    ];
+    entries.push({
+      name: p.name,
+      using: parts.length === 1 ? using : `(${parts.join(" AND ")})`
+    });
+  }
+  return {
+    entries,
+    dropped
+  };
+}
+__name(canEntries, "canEntries");
+var CanRenderError = class CanRenderError2 extends Error {
+  static {
+    __name(this, "CanRenderError");
+  }
+};
+var ENGINE_ALIASES = /^(t|locked|w\d+|wj\d+|x|q|g|p|upd)$/;
+function renderCanUsing(p, qualifier, tableName) {
+  if (p.using === null || p.using === void 0) return null;
+  if (typeof p.using === "string") {
+    const withoutLiterals = p.using.replace(/'(?:[^']|'')*'/g, "''");
+    if (/--|\/\*/.test(withoutLiterals)) return null;
+    if (withoutLiterals.replace(/''/g, "").includes("'")) return null;
+    let depth = 0;
+    for (const ch of withoutLiterals) {
+      if (ch === "(") depth++;
+      else if (ch === ")" && --depth < 0) return null;
+    }
+    if (depth !== 0) return null;
+    const tbl = tableName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const qualified = new RegExp(`(^|[^A-Za-z0-9_])(?:"?[A-Za-z_][A-Za-z0-9_]*"?\\s*\\.\\s*)?"?${tbl}"?\\s*\\.`);
+    if (qualified.test(withoutLiterals)) return null;
+    const calls = withoutLiterals.match(/auth\s*\.\s*"?has_permission"?\s*\(/gi) ?? [];
+    const wrapped = withoutLiterals.match(/\(\s*select\s*[(\s]*auth\s*\.\s*"?has_permission"?\s*\(/gi) ?? [];
+    if (calls.length !== wrapped.length) return null;
+    return `(${p.using})`;
+  }
+  try {
+    const rendered = canExprSql(p.using, qualifier);
+    const selfParenthesized = p.using.kind === "binop" || p.using.kind === "and" || p.using.kind === "or" || p.using.kind === "not" || p.using.kind === "isNull" || p.using.kind === "exists";
+    return selfParenthesized ? rendered : `(${rendered})`;
+  } catch (err) {
+    if (err instanceof CanRenderError) return null;
+    throw err;
+  }
+}
+__name(renderCanUsing, "renderCanUsing");
+var CAN_BINOPS = {
+  eq: "=",
+  neq: "<>",
+  gt: ">",
+  gte: ">=",
+  lt: "<",
+  lte: "<="
+};
+function canLiteral(v) {
+  if (v === null) return "NULL";
+  if (typeof v === "boolean") return v ? "TRUE" : "FALSE";
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new CanRenderError("can: non-finite literal");
+    return String(v);
+  }
+  return `'${v.replace(/'/g, "''")}'`;
+}
+__name(canLiteral, "canLiteral");
+function canExprSql(e, qualifier) {
+  switch (e.kind) {
+    case "col":
+      return e.alias !== void 0 && e.alias !== "" ? `${quoteIdent(e.alias)}.${quoteIdent(e.name)}` : `${qualifier}.${quoteIdent(e.name)}`;
+    case "authUid":
+      return "(SELECT auth.uid())";
+    case "lit":
+      return canLiteral(e.value);
+    case "binop": {
+      const op = CAN_BINOPS[e.op];
+      if (op === void 0) throw new CanRenderError(`can: unknown operator ${String(e.op)}`);
+      return `(${canExprSql(e.left, qualifier)} ${op} ${canExprSql(e.right, qualifier)})`;
+    }
+    case "and":
+      return e.parts.length === 0 ? "(true)" : `(${e.parts.map((p) => canExprSql(p, qualifier)).join(" AND ")})`;
+    case "or":
+      return e.parts.length === 0 ? "(false)" : `(${e.parts.map((p) => canExprSql(p, qualifier)).join(" OR ")})`;
+    case "not":
+      return `(NOT ${canExprSql(e.expr, qualifier)})`;
+    case "isNull":
+      return `(${canExprSql(e.expr, qualifier)} IS ${e.negated ? "NOT " : ""}NULL)`;
+    case "exists":
+      if (e.alias === "" || ENGINE_ALIASES.test(e.alias)) {
+        throw new CanRenderError(`can: exists alias "${e.alias}" collides with the engine's own aliases \u2014 the correlation would silently collapse`);
+      }
+      return `EXISTS (SELECT 1 FROM ${quoteTable(e.table)} ${quoteIdent(e.alias)} WHERE ${canExprSql(e.predicate, qualifier)})`;
+    default:
+      throw new CanRenderError(`can: unknown policy expression kind ${String(e.kind)}`);
+  }
+}
+__name(canExprSql, "canExprSql");
+function canEntriesOf(table, alias) {
+  const byAlias = memoTable(canMemo, currentSchema, table, () => /* @__PURE__ */ new Map());
+  const hit = byAlias.get(alias);
+  if (hit !== void 0) return hit;
+  const def = tableDefOf(table);
+  const warnOnce = /* @__PURE__ */ __name((msg) => {
+    if (byAlias.has("__warned")) return;
+    byAlias.set("__warned", []);
+    console.warn(msg);
+  }, "warnOnce");
+  if (def === null || def.policies === void 0) {
+    byAlias.set(alias, []);
+    return [];
+  }
+  if (hasCanColumn(table)) {
+    warnOnce(`can(${table}): the table declares a column or relation named "can", so the policy echo is disabled for it \u2014 rename it to get can`);
+    byAlias.set(alias, []);
+    return [];
+  }
+  const { entries, dropped } = canEntries(def, alias === "" ? quoteTable(table) : alias);
+  if (dropped.length > 0) {
+    warnOnce(dropped.map((d) => `can(${table}): policy "${d.name}" is not exposed in can \u2014 ${d.reason}; the database still enforces it`).join("\n"));
+  }
+  byAlias.set(alias, entries);
+  return entries;
+}
+__name(canEntriesOf, "canEntriesOf");
+function canOuter(table) {
+  const cols = canProjection(table, "q");
+  return cols.length === 0 ? "" : `, ${cols.join(", ")}`;
+}
+__name(canOuter, "canOuter");
+function canProjection(table, alias) {
+  return canEntriesOf(table, alias).map((e) => `${e.using} AS ${quoteIdent(CAN_PREFIX + e.name)}`);
+}
+__name(canProjection, "canProjection");
+function canJsonPairs(table, alias) {
+  return canEntriesOf(table, alias).map((e) => `${quoteLiteral(CAN_PREFIX + e.name)}, ${e.using}`);
+}
+__name(canJsonPairs, "canJsonPairs");
+function foldCan(table, row, partial) {
+  let can = null;
+  for (const key2 of Object.keys(row)) {
+    if (!key2.startsWith(CAN_PREFIX)) continue;
+    can ??= [];
+    if (row[key2] === true) can.push(key2.slice(CAN_PREFIX.length));
+    delete row[key2];
+  }
+  if (hasCanColumn(table)) return row;
+  if (can !== null) row.can = can;
+  else if (!partial && tableDefOf(table) !== null) {
+    if (canEntriesOf(table, "").length > 0) {
+      const flags = memoTable(canMemo, currentSchema, table, () => /* @__PURE__ */ new Map());
+      if (!flags.has("__missing_warned")) {
+        flags.set("__missing_warned", []);
+        console.warn(`can(${table}): a full-row read returned no "can:*" columns although the table declares update policies \u2014 this statement shape does not carry can; the row gets can: []`);
+      }
+    }
+    row.can = [];
+  }
+  return row;
+}
+__name(foldCan, "foldCan");
+function hasCanColumn(table) {
+  const cols = tableDefOf(table)?.columns;
+  if (cols !== void 0 && Object.prototype.hasOwnProperty.call(cols, "can")) return true;
+  return (currentRelations.get(table) ?? []).some((rel) => rel.name === "can");
+}
+__name(hasCanColumn, "hasCanColumn");
 function rowProjection(table, alias, wildcard = alias ? `${alias}.*` : "*") {
   const cols = schemaColumns(table);
-  if (!cols || !memoTable(timestampMemo, currentSchema, table, () => [
+  let base = wildcard;
+  if (cols && memoTable(timestampMemo, currentSchema, table, () => [
     ...cols
-  ].some((c) => columnTypeOf(table, c) === "timestamp"))) return wildcard;
-  const projections = memoTable(projectionMemo, currentSchema, table, () => /* @__PURE__ */ new Map());
-  const key2 = alias ?? "";
-  let sql = projections.get(key2);
-  if (sql === void 0) {
-    sql = [
-      ...cols
-    ].map((c) => projectedColumn(table, c, alias)).join(", ");
-    projections.set(key2, sql);
-  }
-  return sql;
+  ].some((c) => columnTypeOf(table, c) === "timestamp"))) {
+    const projections = memoTable(projectionMemo, currentSchema, table, () => /* @__PURE__ */ new Map());
+    const key2 = alias ?? "";
+    let sql = projections.get(key2);
+    if (sql === void 0) {
+      sql = [
+        ...cols
+      ].map((c) => projectedColumn(table, c, alias)).join(", ");
+      projections.set(key2, sql);
+    }
+    base = sql;
+  }
+  const can = canProjection(table, alias ?? "");
+  if (can.length === 0) return base;
+  const rows = base === "*" && alias !== void 0 ? `${alias}.*` : base;
+  return `${rows}, ${can.join(", ")}`;
 }
 __name(rowProjection, "rowProjection");
 function colRefSql(table, known, ref, caller, alias = "t") {
@@ -3564,7 +3792,10 @@ function withClauses(table, spec, add, caller, parentAlias = "t", depth = 0, cou
       jsonPairs: []
     } : withClauses(rel.to, nestedSpec, add, caller, childAlias, depth + 1, counter);
     const nestedJoins = nested.joins.length ? ` ${nested.joins.join(" ")}` : "";
-    const obj = jsonObjectFor(rel.to, childCols, childAlias, nested.jsonPairs);
+    const obj = jsonObjectFor(rel.to, childCols, childAlias, [
+      ...nested.jsonPairs,
+      ...canJsonPairs(rel.to, childAlias)
+    ]);
     const innerWhere = o["where"] !== void 0 && o["where"] !== null ? compileWhereBare(rel.to, childKnown, o["where"], add, caller, childAlias, i) : "";
     const link = `${childAlias}.${quoteIdent(theirCol)} = ${parentAlias}.${quoteIdent(ourCol)}`;
     const cond = innerWhere === "" ? link : `${link} AND ${innerWhere}`;
@@ -3957,8 +4188,8 @@ function createOps(tx, context = {}) {
       const wantRows = opts?.returning !== false;
       const tail = wantRows ? `RETURNING ${rowProjection(table, "t", "*")}` : "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 ${rowProjection(table, "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 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."__pb_lock" ` + (wantRows ? `RETURNING ${rowProjection(table, "t")}` : "RETURNING 1");
+      const lockedCte = simple ? "" : `WITH locked AS (SELECT t.${quoteIdent(pk)} AS "__pb_lock" 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);
@@ -4103,7 +4334,7 @@ function createOps(tx, context = {}) {
       const compiled = ops.compileQuery(query);
       return asTableRows(query.table, await (await at()).unsafe(compiled.sql, compiled.params, {
         name: query.name
-      }));
+      }), void 0, true);
     },
     async explainQuery(query) {
       const compiled = ops.compileQuery(query);
@@ -4113,7 +4344,7 @@ function createOps(tx, context = {}) {
     },
     async findMany(table, query = {}, opts = {}) {
       const compiled = compileFindMany(table, query, opts);
-      return asTableRows(table, await (await at()).unsafe(compiled.sql, compiled.params), opts.with);
+      return asTableRows(table, await (await at()).unsafe(compiled.sql, compiled.params), opts.with, opts.select !== void 0);
     },
     async page(table, query = {}, opts = {}) {
       const secret = cursorKey();
@@ -4181,7 +4412,7 @@ function createOps(tx, context = {}) {
         other
       ]) delete row[name];
       return {
-        rows: asTableRows(table, rows, opts.with),
+        rows: asTableRows(table, rows, opts.with, opts.select !== void 0),
         pageInfo
       };
     },
@@ -4288,7 +4519,9 @@ function createOps(tx, context = {}) {
           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 ${quoteTable(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) => columnTypeOf(table, c) === "timestamp" ? projectedColumn(table, c, "t") : `t.${quoteIdent(c)}`).join(", ");
+        const colListC = [
+          ...cfg.cols.map((c) => columnTypeOf(table, c) === "timestamp" ? projectedColumn(table, c, "t") : `t.${quoteIdent(c)}`)
+        ].join(", ");
         const scoreC = scoreMul === "" ? "g._score" : `(g._score)${scoreMul}`;
         const assembleC = /* @__PURE__ */ __name((kwIn, withKwn) => {
           const kwnCol = withKwn ? `, (SELECT count(*) FROM kw)::int AS _kwn` : "";
@@ -4301,7 +4534,7 @@ function createOps(tx, context = {}) {
             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 ${quoteTable(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 ${quoteTable(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}`;
+          return msC === "" ? `SELECT q.*${canOuter(table)} FROM (${inner}) q ORDER BY q._score DESC, q.${quoteIdent(cfg.pk)} LIMIT ${limit}` : `SELECT q.*${canOuter(table)} FROM (${inner}) q WHERE q._score >= ${msC} ORDER BY q._score DESC, q.${quoteIdent(cfg.pk)} LIMIT ${limit}`;
         }, "assembleC");
         let rowsC = await liveC.unsafe(assembleC(kwC, kwC !== ""), bindC);
         if (wantTextC && kwC !== "" && (rowsC.length === 0 || rowsC[0]._kwn === 0)) {
@@ -4370,26 +4603,26 @@ function createOps(tx, context = {}) {
         qpRef = qp;
         kwSql = `SELECT t.${quoteIdent(cfg.pk)} AS id, ROW_NUMBER() OVER (ORDER BY ts_rank_cd(t.palbase_fts, websearch_to_tsquery('simple', ${qp})) DESC) AS r FROM ${quoteTable(table)} t WHERE t.palbase_fts @@ websearch_to_tsquery('simple', ${qp})${whereSql} ORDER BY r LIMIT ${pool}`;
       }
-      const colList = cfg.cols.map((c) => columnTypeOf(table, c) === "timestamp" ? projectedColumn(table, c, "t") : `t.${quoteIdent(c)}`).join(", ");
+      const colList = [
+        ...cfg.cols.map((c) => columnTypeOf(table, c) === "timestamp" ? projectedColumn(table, c, "t") : `t.${quoteIdent(c)}`)
+      ].join(", ");
       const msP = params.minScore === void 0 ? "" : add(params.minScore);
       const hlCol = params.highlight === true && wantText ? `, ts_headline('simple', ${ftsExprOf(cfg.ftsCols)}, websearch_to_tsquery('simple', ${qpRef})) AS _highlight` : "";
       const assemble = /* @__PURE__ */ __name((kwIn, withKwn) => {
         const kwnCol = withKwn ? `, (SELECT count(*) FROM kw)::int AS _kwn` : "";
         let inner;
-        let orderScore;
         if (semSql !== "" && kwIn !== "") {
           const score = scoreMul === "" ? "fused._score" : `(fused._score)${scoreMul}`;
           inner = `WITH sem AS (${semSql}), kw AS (${kwIn}), fused AS (SELECT COALESCE(sem.id, kw.id) AS id, (COALESCE(1.0/(${K} + sem.r), 0) + COALESCE(1.0/(${K} + kw.r), 0))::float8 AS _score FROM sem FULL OUTER JOIN kw ON sem.id = kw.id) SELECT ${colList}, ${score} AS _score${hlCol}${kwnCol} FROM fused JOIN ${quoteTable(table)} t ON t.${quoteIdent(cfg.pk)} = fused.id`;
-          orderScore = scoreMul === "" ? "fused._score" : "_score";
         } else {
           const single = semSql !== "" ? `sem AS (${semSql})` : `kw AS (${kwIn})`;
           const alias = semSql !== "" ? "sem" : "kw";
           const base = `(1.0/(${K} + ${alias}.r))::float8`;
           const score = scoreMul === "" ? base : `(${base})${scoreMul}`;
           inner = `WITH ${single} SELECT ${colList}, ${score} AS _score${hlCol}${semSql !== "" ? "" : kwnCol} FROM ${alias} JOIN ${quoteTable(table)} t ON t.${quoteIdent(cfg.pk)} = ${alias}.id`;
-          orderScore = "_score";
         }
-        return msP === "" ? `${inner} ORDER BY ${orderScore} DESC, t.${quoteIdent(cfg.pk)} LIMIT ${limit}` : `SELECT * FROM (${inner}) q WHERE q._score >= ${msP} ORDER BY q._score DESC, q.${quoteIdent(cfg.pk)} LIMIT ${limit}`;
+        const ms = msP === "" ? "" : ` WHERE q._score >= ${msP}`;
+        return `SELECT q.*${canOuter(table)} FROM (${inner}) q${ms} ORDER BY q._score DESC, q.${quoteIdent(cfg.pk)} LIMIT ${limit}`;
       }, "assemble");
       let rows = await live.unsafe(assemble(kwSql, kwSql !== ""), bind);
       if (wantText && kwSql !== "" && (rows.length === 0 || rows[0]._kwn === 0)) {
@@ -5225,7 +5458,7 @@ function compilePlanOp(op, results) {
       const assignments = cols.map((c) => `${quoteIdent(c)} = ${renderValue(op.set[c], c, args, results, opVectorCols, opTransforms)}`);
       const planned = planWhere(op.table, op.where, args, results);
       const planPk = primaryKeyOf(op.table);
-      sql = isSinglePkEquality(planned.resolved, planPk) || planPk === null ? `UPDATE ${table} AS t SET ${assignments.join(", ")} WHERE true${planned.sql} RETURNING ${rowProjection(op.table, "t")}` : `WITH locked AS (SELECT t.${quoteIdent(planPk)} FROM ${table} t WHERE true${planned.sql} ORDER BY t.${quoteIdent(planPk)} FOR NO KEY UPDATE) UPDATE ${table} AS t SET ${assignments.join(", ")} FROM locked WHERE t.${quoteIdent(planPk)} = locked.${quoteIdent(planPk)} RETURNING ${rowProjection(op.table, "t")}`;
+      sql = isSinglePkEquality(planned.resolved, planPk) || planPk === null ? `UPDATE ${table} AS t SET ${assignments.join(", ")} WHERE true${planned.sql} RETURNING ${rowProjection(op.table, "t")}` : `WITH locked AS (SELECT t.${quoteIdent(planPk)} AS "__pb_lock" FROM ${table} t WHERE true${planned.sql} ORDER BY t.${quoteIdent(planPk)} FOR NO KEY UPDATE) UPDATE ${table} AS t SET ${assignments.join(", ")} FROM locked WHERE t.${quoteIdent(planPk)} = locked."__pb_lock" RETURNING ${rowProjection(op.table, "t")}`;
       break;
     }
     case "delete": {
@@ -6344,13 +6577,25 @@ async function refuseUnlessAuthorized(client, spec, requestId, rolesOfCaller) {
       spec.permission
     ]);
     if (row?.ok !== true) {
-      return envelope("forbidden", `This endpoint requires the "${spec.permission}" permission`, 403, requestId);
+      return envelope(
+        "forbidden",
+        `This endpoint requires the "${spec.permission}" permission`,
+        403,
+        requestId,
+        // FR-008 / D-7: reddin ÇARESİ gövdede — istemci `required`'ı görünce ilgili
+        // nesneyi yeniden çeker (Entra CAE deseni); cümle değişmez.
+        {
+          required: spec.permission
+        }
+      );
     }
   }
   if (spec.role !== void 0) {
     const held = await rolesOfCaller();
     if (!held.includes(spec.role)) {
-      return envelope("forbidden", `This endpoint requires the "${spec.role}" role`, 403, requestId);
+      return envelope("forbidden", `This endpoint requires the "${spec.role}" role`, 403, requestId, {
+        required_role: spec.role
+      });
     }
   }
   return null;