@palbase/backend 22.0.0 → 22.1.0

package/dist/bin/palbase-backend.cjs

@@ -425,7 +425,8 @@ 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) => ops().findMany(name, query),
+          search: (params) => ops().search(name, params)
         };
       }
     }
@@ -440,7 +441,8 @@ 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) => raw.findMany(table, query),
+    search: (table, params) => raw.search(table, params)
   };
   return Object.assign(ops, {
     tables: makeTablesAccessor(() => raw),
@@ -971,6 +973,194 @@ function asWireRow(row) {
 function asWireRows(rows) {
   return rows.map((row) => asWireRow(row));
 }
+function toVectorLiteral(v) {
+  return `[${v.join(",")}]`;
+}
+function vectorColumnsOf(schema, table) {
+  const out = /* @__PURE__ */ new Set();
+  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;
+      if (d !== null && typeof d === "object" && d.type === "vector") out.add(col);
+    }
+  }
+  return out;
+}
+function reviveVectors(row, vectorCols) {
+  if (row === null || typeof row !== "object" || vectorCols.size === 0) return row;
+  const out = row;
+  for (const col of vectorCols) {
+    const v = out[col];
+    if (typeof v === "string") out[col] = JSON.parse(v);
+  }
+  return row;
+}
+function asTableRow(table, row) {
+  return reviveVectors(asWireRow(row), vectorColumnsOf(currentSchema, table));
+}
+function asTableRows(table, rows) {
+  const vectorCols = vectorColumnsOf(currentSchema, table);
+  return rows.map((row) => reviveVectors(asWireRow(row), vectorCols));
+}
+function asBindParams(table, cols, data) {
+  const vectorCols = vectorColumnsOf(currentSchema, table);
+  return cols.map((c) => {
+    const v = data[c];
+    return Array.isArray(v) && vectorCols.has(c) ? toVectorLiteral(v) : v;
+  });
+}
+var SELECTIVITY_EXACT_THRESHOLD = 1e4;
+var METRIC_OPERATOR = {
+  cosine: "<=>",
+  euclidean: "<->",
+  inner_product: "<#>"
+};
+function searchConfigFor(table) {
+  const t = currentSchema.tables?.[table];
+  if (!t) return null;
+  const columns = t.columns ?? {};
+  const defOf = (c) => c !== null && typeof c === "object" && "_def" in c ? c._def : c ?? {};
+  const cols = Object.keys(columns);
+  const vectorCols = cols.filter((c) => defOf(columns[c]).type === "vector");
+  const defOfFull = (c) => c !== null && typeof c === "object" && "_def" in c ? c._def : c ?? {};
+  const pkCols = cols.filter((c) => defOfFull(columns[c]).primaryKey === true);
+  const pk = pkCols.length === 1 ? pkCols[0] : cols.includes("id") ? "id" : null;
+  if (pk === null) {
+    throw new Error(
+      `search(${table}): tek-kolon primary key bulunamad\u0131 \u2014 arama s\u0131ralamas\u0131 ve sat\u0131r birle\u015Fimi PK ister (FR-020)`
+    );
+  }
+  const search = t.search;
+  const ftsCols = search?.text ?? [];
+  const rawLegs = search?.vector === void 0 ? [] : Array.isArray(search.vector) ? search.vector : [search.vector];
+  let legs;
+  if (rawLegs.length > 0) {
+    legs = rawLegs.map((leg) => {
+      const l = leg;
+      const column = l.column ?? (vectorCols.length === 1 ? vectorCols[0] : void 0);
+      if (column === void 0) {
+        throw new Error(`search(${table}): birden \xE7ok vector kolonu var \u2014 beyanda 'column' zorunlu (FR-010)`);
+      }
+      const model = l.model;
+      return {
+        column,
+        metric: l.metric ?? "cosine",
+        ...model !== void 0 ? { embed: {
+          model: model.model,
+          apiKeyName: model.apiKeyName ?? "OPENAI_API_KEY",
+          ...model.baseURL !== void 0 ? { baseURL: model.baseURL } : {},
+          ...model.dimensions !== void 0 ? { dimensions: model.dimensions } : {}
+        } } : {}
+      };
+    });
+  } else {
+    legs = vectorCols.map((column) => ({ column, metric: "cosine" }));
+  }
+  if (ftsCols.length === 0 && legs.length === 0) return null;
+  return { pk, cols, colSet: new Set(cols), ftsCols, legs };
+}
+function pickLeg(table, legs, using) {
+  if (legs.length === 0) return null;
+  if (using !== void 0) {
+    const hit = legs.find((l) => l.column === using);
+    if (!hit) {
+      throw new Error(
+        `search(${table}): using "${using}" bir vekt\xF6r kolunu adlam\u0131yor \u2014 mevcut: ${legs.map((l) => l.column).join(", ")}`
+      );
+    }
+    return hit;
+  }
+  if (legs.length === 1) return legs[0];
+  throw new Error(`search(${table}): birden \xE7ok vekt\xF6r kolu var \u2014 'using' ile se\xE7in (FR-013) \u2014 salt metin ar\u0131yorsan mode:"text" kullan`);
+}
+var WHERE_OPS = { gt: ">", gte: ">=", lt: "<", lte: "<=", neq: "<>" };
+function compileWhere(table, colSet, where, add) {
+  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)`);
+    }
+    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 (v.length === 0) {
+            parts.push("false");
+            continue;
+          }
+          parts.push(`${q} IN (${v.map((x) => add(x)).join(", ")})`);
+        } 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)`);
+        }
+      }
+    } else {
+      parts.push(`${q} = ${add(cond)}`);
+    }
+  }
+  return parts.length === 0 ? "" : ` AND ${parts.join(" AND ")}`;
+}
+var cachedVectorSchema = null;
+async function vectorSchemaWithGuc(runner) {
+  if (cachedVectorSchema !== null) {
+    await runner.unsafe(
+      "select set_config('hnsw.iterative_scan','relaxed_order',true), set_config('hnsw.max_scan_tuples','200000',true), set_config('hnsw.ef_search','200',true)"
+    );
+    return cachedVectorSchema;
+  }
+  const rows = await runner.unsafe(
+    "select set_config('hnsw.iterative_scan','relaxed_order',true), set_config('hnsw.max_scan_tuples','200000',true), set_config('hnsw.ef_search','200',true), (select n.nspname from pg_extension e join pg_namespace n on n.oid = e.extnamespace where e.extname = 'vector') as nspname"
+  );
+  const name = rows?.[0]?.nspname;
+  if (typeof name !== "string" || name === "") {
+    throw new Error("pgvector extension kurulu de\u011Fil \u2014 vector aramas\u0131 \xE7al\u0131\u015Famaz (extensions beyan\u0131 deploy'dan ge\xE7ti mi?)");
+  }
+  cachedVectorSchema = name;
+  return name;
+}
+var secretReader = null;
+function setSecretReader(fn) {
+  secretReader = fn;
+}
+var embedFetch = (url, init) => fetch(url, init);
+async function embedQuery(embed, text) {
+  if (secretReader === null) {
+    throw new Error(`query embed: secret reader ba\u011Flanmam\u0131\u015F \u2014 ${embed.apiKeyName} okunam\u0131yor`);
+  }
+  const key = await secretReader(embed.apiKeyName);
+  if (key === null || key === "") {
+    throw new Error(`query embed: vault'ta ${embed.apiKeyName} yok (FR-021/FR-025)`);
+  }
+  const url = (embed.baseURL ?? "https://api.openai.com/v1").replace(/\/$/, "") + "/embeddings";
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 1e4);
+  try {
+    const res = await embedFetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
+      body: JSON.stringify({
+        model: embed.model,
+        input: [text],
+        ...embed.dimensions !== void 0 ? { dimensions: embed.dimensions } : {}
+      }),
+      signal: controller.signal
+    });
+    if (!res.ok) {
+      throw new Error(`query embed: sa\u011Flay\u0131c\u0131 ${res.status} d\xF6nd\xFC (${embed.apiKeyName} ile) \u2014 anahtar/model do\u011Fru mu?`);
+    }
+    const data = await res.json();
+    const vec = data.data?.[0]?.embedding;
+    if (!Array.isArray(vec)) {
+      throw new Error("query embed: sa\u011Flay\u0131c\u0131 yan\u0131t\u0131nda data[0].embedding yok (CLAIM-N1 \u015Fekli)");
+    }
+    return vec;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function createOps(tx) {
   const at = () => resolveTx(tx);
   const ops = {
@@ -982,22 +1172,22 @@ function createOps(tx) {
       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 ${quoteIdent(table)} (${cols.map(quoteIdent).join(", ")}) VALUES (${placeholders}) RETURNING *`;
-      const rows = await (await at()).unsafe(sql, cols.map((c) => data[c]));
+      const rows = await (await at()).unsafe(sql, asBindParams(table, cols, data));
       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).`
         );
       }
-      return asWireRow(inserted);
+      return asTableRow(table, inserted);
     },
     async update(table, id, data) {
       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 ${quoteIdent(table)} SET ${assignments} WHERE id = $${cols.length + 1} RETURNING *`;
-      const rows = await (await at()).unsafe(sql, [...cols.map((c) => data[c]), id]);
-      return rows[0] ? asWireRow(rows[0]) : null;
+      const rows = await (await at()).unsafe(sql, [...asBindParams(table, cols, data), id]);
+      return rows[0] ? asTableRow(table, rows[0]) : null;
     },
     async delete(table, id) {
       await (await at()).unsafe(`DELETE FROM ${quoteIdent(table)} WHERE id = $1`, [id]);
@@ -1007,16 +1197,96 @@ function createOps(tx) {
         `SELECT * FROM ${quoteIdent(table)} WHERE id = $1`,
         [id]
       );
-      return rows[0] ? asWireRow(rows[0]) : null;
+      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 asWireRows(await (await at()).unsafe(
+      return asTableRows(table, await (await at()).unsafe(
         `SELECT * FROM ${quoteIdent(table)}${where}`,
         cols.map((c) => query[c])
       ));
     },
+    /**
+     * Tek-SQL hibrit arama (FR-014): iki kol CTE + FULL OUTER JOIN + RRF
+     * (1/(50+rank), CLAIM-N4). Operatör şema-nitelikli (C-10, M-1); GUC
+     * hnsw.iterative_scan=relaxed_order aynı tx'te set_config ile (CLAIM-N3 —
+     * RLS/filtre altında LIMIT-altı dönüş açığını kapatır). Sorgu-anı embed
+     * T024'te gelir; o zamana dek vector kolu yalnız params.vector ile koşar.
+     */
+    async search(table, params = {}) {
+      const cfg = searchConfigFor(table);
+      if (!cfg) {
+        throw new Error(`search(${table}): tablo aranabilir de\u011Fil \u2014 ne vector kolonu ne search beyan\u0131 var (FR-013)`);
+      }
+      const rawLimit = params.limit ?? 20;
+      if (typeof rawLimit !== "number" || !Number.isFinite(rawLimit)) {
+        throw new Error(`search(${table}): limit sonlu bir say\u0131 olmal\u0131, ${String(rawLimit)} verildi (FR-013)`);
+      }
+      const limit = Math.min(Math.max(1, Math.trunc(rawLimit)), 100);
+      const pool = Math.max(limit * 3, 30);
+      const wantText = params.mode !== "vector" && cfg.ftsCols.length > 0 && typeof params.query === "string" && params.query !== "";
+      const anyEmbed = cfg.legs.some((l) => l.embed !== void 0);
+      const vectorAsked = params.mode !== "text" && (Array.isArray(params.vector) || params.using !== void 0 || params.mode === "vector" || anyEmbed && typeof params.query === "string" && params.query !== "");
+      const leg = vectorAsked ? pickLeg(table, cfg.legs, params.using) : null;
+      let qv = Array.isArray(params.vector) ? params.vector : null;
+      if (qv === null && leg?.embed !== void 0 && typeof params.query === "string" && params.query !== "") {
+        try {
+          qv = await embedQuery(leg.embed, params.query);
+        } catch (e) {
+          if (!wantText) throw e;
+          qv = null;
+        }
+      }
+      const wantVector = leg !== null && qv !== null;
+      if (!wantText && !wantVector) {
+        throw new Error(
+          `search(${table}): ko\u015Fulabilir kol yok \u2014 metin i\xE7in 'query' (FTS beyan\u0131 gerekir), semantik i\xE7in 'vector' verin (FR-015)`
+        );
+      }
+      const bind = [];
+      const add = (v) => {
+        bind.push(v);
+        return `$${bind.length}`;
+      };
+      const whereSql = compileWhere(table, cfg.colSet, params.where ?? {}, add);
+      const live = await at();
+      const K = 50;
+      let semSql = "";
+      let kwSql = "";
+      if (wantVector && leg) {
+        const sch = await vectorSchemaWithGuc(live);
+        const op = METRIC_OPERATOR[leg.metric] ?? METRIC_OPERATOR.cosine;
+        let exactOrder = "";
+        if (whereSql !== "") {
+          const probeRows = await live.unsafe(
+            `SELECT count(*)::int AS n FROM (SELECT 1 FROM ${quoteIdent(table)} t WHERE t.${quoteIdent(leg.column)} IS NOT NULL${whereSql} LIMIT ${SELECTIVITY_EXACT_THRESHOLD + 1}) s`,
+            bind.slice()
+          );
+          const n = probeRows?.[0]?.n;
+          if (typeof n === "number" && n <= SELECTIVITY_EXACT_THRESHOLD) {
+            exactOrder = " + 0.0";
+          }
+        }
+        const vp = add(toVectorLiteral(qv));
+        semSql = `SELECT t.${quoteIdent(cfg.pk)} AS id, ROW_NUMBER() OVER (ORDER BY (t.${quoteIdent(leg.column)} OPERATOR(${quoteIdent(sch)}.${op}) ${vp}::${quoteIdent(sch)}.vector)${exactOrder}) AS r FROM ${quoteIdent(table)} t WHERE t.${quoteIdent(leg.column)} IS NOT NULL${whereSql} ORDER BY r LIMIT ${pool}`;
+      }
+      if (wantText) {
+        const qp = add(params.query);
+        kwSql = `SELECT t.${quoteIdent(cfg.pk)} AS id, ROW_NUMBER() OVER (ORDER BY ts_rank_cd(t.palbase_fts, websearch_to_tsquery('simple', ${qp})) DESC) AS r FROM ${quoteIdent(table)} t WHERE t.palbase_fts @@ websearch_to_tsquery('simple', ${qp})${whereSql} ORDER BY r LIMIT ${pool}`;
+      }
+      const colList = cfg.cols.map((c) => `t.${quoteIdent(c)}`).join(", ");
+      let sql;
+      if (semSql !== "" && kwSql !== "") {
+        sql = `WITH sem AS (${semSql}), kw AS (${kwSql}), fused AS (SELECT COALESCE(sem.id, kw.id) AS id, (COALESCE(1.0/(${K} + sem.r), 0) + COALESCE(1.0/(${K} + kw.r), 0))::float8 AS _score FROM sem FULL OUTER JOIN kw ON sem.id = kw.id) SELECT ${colList}, fused._score AS _score FROM fused JOIN ${quoteIdent(table)} t ON t.${quoteIdent(cfg.pk)} = fused.id ORDER BY fused._score DESC, t.${quoteIdent(cfg.pk)} LIMIT ${limit}`;
+      } else {
+        const single = semSql !== "" ? `sem AS (${semSql})` : `kw AS (${kwSql})`;
+        const alias = semSql !== "" ? "sem" : "kw";
+        sql = `WITH ${single} SELECT ${colList}, (1.0/(${K} + ${alias}.r))::float8 AS _score FROM ${alias} JOIN ${quoteIdent(table)} t ON t.${quoteIdent(cfg.pk)} = ${alias}.id ORDER BY _score DESC, t.${quoteIdent(cfg.pk)} LIMIT ${limit}`;
+      }
+      const rows = await live.unsafe(sql, bind);
+      return asTableRows(table, rows);
+    },
     /** A real SAVEPOINT inside the request's transaction. */
     async transaction(cb) {
       const live = await at();
@@ -1045,7 +1315,7 @@ function createOps(tx) {
       return live.savepoint(async (sp) => {
         const results = [];
         for (const op of plan.ops) {
-          const rows = await runPlanOp(sp, op, results);
+          const rows = asTableRows(op.table, await runPlanOp(sp, op, results));
           const result = { rows, rows_affected: rows.length };
           results.push(result);
           assertGuard(op, result);
@@ -1058,6 +1328,7 @@ function createOps(tx) {
 }
 var currentSchema = {};
 function setSchema(schema) {
+  cachedVectorSchema = null;
   const s = schema;
   currentSchema = (s && "default" in s ? s.default : s) ?? {};
 }
@@ -1144,7 +1415,7 @@ function isRef(v) {
 function isExpr(v) {
   return typeof v === "object" && v !== null && "$expr" in v;
 }
-function renderValue(value, column, args, results) {
+function renderValue(value, column, args, results, vectorCols) {
   if (isRef(value)) {
     const source = results[value.$ref.op];
     const row = source?.rows[0];
@@ -1153,15 +1424,15 @@ function renderValue(value, column, args, results) {
         error_code: "tx_ref_unresolved"
       });
     }
-    return args.bind(row[value.$ref.field]);
+    return bindMaybeVector(args, column, vectorCols, row[value.$ref.field]);
   }
   if (isExpr(value)) {
     const fn = value.$expr;
     if (fn.fn === "now") return "now()";
     const operator = fn.fn === "inc" ? "+" : "-";
-    return `${quoteIdent(column)} ${operator} ${args.bind(fn.by)}`;
+    return `${quoteIdent(column)} ${operator} ${bindMaybeVector(args, column, vectorCols, fn.by)}`;
   }
-  return args.bind(value);
+  return bindMaybeVector(args, column, vectorCols, value);
 }
 function renderWhere(where, args, results) {
   const cols = Object.keys(where ?? {});
@@ -1173,14 +1444,21 @@ function renderWhere(where, args, results) {
   });
   return ` WHERE ${terms.join(" AND ")}`;
 }
+function bindMaybeVector(args, column, vectorCols, value) {
+  if (column !== void 0 && vectorCols?.has(column) && Array.isArray(value)) {
+    return args.bind(toVectorLiteral(value));
+  }
+  return args.bind(value);
+}
 async function runPlanOp(sp, op, results) {
+  const opVectorCols = vectorColumnsOf(currentSchema, op.table);
   const args = new Args();
   const table = quoteIdent(op.table);
   let sql;
   switch (op.op) {
     case "insert": {
       const cols = Object.keys(op.values ?? {});
-      const rendered = cols.map((c) => renderValue(op.values[c], c, args, results));
+      const rendered = cols.map((c) => renderValue(op.values[c], c, args, results, opVectorCols));
       sql = cols.length ? `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES (${rendered.join(", ")}) RETURNING *` : `INSERT INTO ${table} DEFAULT VALUES RETURNING *`;
       break;
     }
@@ -1189,7 +1467,7 @@ async function runPlanOp(sp, op, results) {
       if (rows.length === 0 || !rows[0]) return [];
       const cols = Object.keys(rows[0]);
       const tuples = rows.map(
-        (r) => `(${cols.map((c) => renderValue(r[c], c, args, results)).join(", ")})`
+        (r) => `(${cols.map((c) => renderValue(r[c], c, args, results, opVectorCols)).join(", ")})`
       );
       sql = `INSERT INTO ${table} (${cols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")} RETURNING *`;
       break;
@@ -1198,7 +1476,7 @@ async function runPlanOp(sp, op, results) {
       const cols = Object.keys(op.set ?? {});
       if (cols.length === 0) throw new Error(`update ${op.table}: nothing to set`);
       const assignments = cols.map(
-        (c) => `${quoteIdent(c)} = ${renderValue(op.set[c], c, args, results)}`
+        (c) => `${quoteIdent(c)} = ${renderValue(op.set[c], c, args, results, opVectorCols)}`
       );
       sql = `UPDATE ${table} SET ${assignments.join(", ")}${renderWhere(op.where, args, results)} RETURNING *`;
       break;
@@ -1345,7 +1623,8 @@ function grantFor(entry, ctx, bucketLimits) {
       filename: ctx.filename
     }),
     maxBytes: bucketLimits?.maxBytes ?? null,
-    mimeTypes: bucketLimits?.mimeTypes ?? null
+    mimeTypes: bucketLimits?.mimeTypes ?? null,
+    ownerUid: ctx.userId ?? null
   };
 }
 var CompletionLedger = class {
@@ -1381,6 +1660,23 @@ function verifySignature(presented, expected) {
 
 // src/engine/index.ts
 var JSON_HEADERS = { "content-type": "application/json" };
+function fieldErrors(err) {
+  return err.issues.map((i) => ({ field: i.path.join("."), message: i.message }));
+}
+function headersFor(raw, schema) {
+  const shape = schema.shape;
+  if (typeof shape !== "object" || shape === null) return raw;
+  let aliased = null;
+  for (const declared of Object.keys(shape)) {
+    const lower = declared.toLowerCase();
+    if (lower === declared) continue;
+    const value = raw[lower];
+    if (value === void 0) continue;
+    aliased ??= { ...raw };
+    aliased[declared] = value;
+  }
+  return aliased ?? raw;
+}
 function envelope(error, description, status, requestId, extra) {
   return new Response(
     JSON.stringify({ error, error_description: description, status, request_id: requestId, ...extra }),
@@ -1414,6 +1710,7 @@ async function defaultSqlDriver(config) {
 async function createApp(opts) {
   const { config, controllers } = opts;
   setSchema(opts.schema ?? {});
+  setSecretReader(opts.secretReader ?? null);
   const routes = buildRouteTable(controllers);
   if (routes.length === 0) {
     throw new BootRefused([], "boot refused: zero endpoints collected \u2014 nothing would answer.");
@@ -1526,7 +1823,8 @@ async function createApp(opts) {
           error: "too_many_requests",
           error_description: "Rate limit exceeded for this endpoint",
           status: 429,
-          request_id: requestId
+          request_id: requestId,
+          data: { retryAfter }
         }),
         { status: 429, headers: { ...JSON_HEADERS, "retry-after": String(retryAfter) } }
       );
@@ -1545,7 +1843,7 @@ async function createApp(opts) {
           const r = p.schema.safeParse(parsedBody);
           if (!r.success) {
             return envelope("bad_request", "Request body failed validation", 400, requestId, {
-              fields: r.error.issues.map((i) => ({ field: i.path.join("."), message: i.message }))
+              data: { fields: fieldErrors(r.error) }
             });
           }
           args[p.index] = r.data;
@@ -1555,7 +1853,7 @@ async function createApp(opts) {
           const r = p.schema.safeParse(Object.fromEntries(url.searchParams));
           if (!r.success) {
             return envelope("bad_request", "Query parameters failed validation", 400, requestId, {
-              fields: r.error.issues.map((i) => ({ field: i.path.join("."), message: i.message }))
+              data: { fields: fieldErrors(r.error) }
             });
           }
           args[p.index] = r.data;
@@ -1564,9 +1862,21 @@ async function createApp(opts) {
         case "param":
           args[p.index] = hit.params[p.name];
           break;
-        case "headers":
-          args[p.index] = Object.fromEntries(req.headers);
+        case "headers": {
+          const raw = Object.fromEntries(req.headers);
+          if (!p.schema) {
+            args[p.index] = raw;
+            break;
+          }
+          const r = p.schema.safeParse(headersFor(raw, p.schema));
+          if (!r.success) {
+            return envelope("bad_request", "Request headers failed validation", 400, requestId, {
+              data: { fields: fieldErrors(r.error) }
+            });
+          }
+          args[p.index] = r.data;
           break;
+        }
         case "user":
         case "optionalUser":
           args[p.index] = claims ? {
@@ -1615,6 +1925,14 @@ async function createApp(opts) {
         case "traceId":
           args[p.index] = requestId;
           break;
+        case "client":
+          args[p.index] = {
+            sdkVersion: req.headers.get("x-palbase-sdk-version"),
+            appVersion: req.headers.get("x-palbase-client-version"),
+            platform: req.headers.get("x-platform"),
+            osVersion: req.headers.get("x-os-version")
+          };
+          break;
         case "req":
           args[p.index] = req;
           break;