@niscorp/vex 0.4.4 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/CHANGELOG.md +90 -0
  2. package/DESIGN.md +72 -45
  3. package/DOCS.md +219 -21
  4. package/README.md +18 -0
  5. package/dist/adapters/express/index.cjs +606 -173
  6. package/dist/adapters/express/index.cjs.map +1 -1
  7. package/dist/adapters/express/index.d.cts +6 -2
  8. package/dist/adapters/express/index.d.ts +6 -2
  9. package/dist/adapters/express/index.js +16 -3
  10. package/dist/adapters/express/index.js.map +1 -1
  11. package/dist/adapters/hono/index.cjs +597 -173
  12. package/dist/adapters/hono/index.cjs.map +1 -1
  13. package/dist/adapters/hono/index.d.cts +5 -2
  14. package/dist/adapters/hono/index.d.ts +5 -2
  15. package/dist/adapters/hono/index.js +7 -3
  16. package/dist/adapters/hono/index.js.map +1 -1
  17. package/dist/agent/index.cjs +12 -12
  18. package/dist/agent/index.cjs.map +1 -1
  19. package/dist/agent/index.d.cts +1 -1
  20. package/dist/agent/index.d.ts +1 -1
  21. package/dist/agent/index.js +12 -12
  22. package/dist/agent/index.js.map +1 -1
  23. package/dist/{chunk-W5MYFJKT.js → chunk-F7OXXJIH.js} +562 -192
  24. package/dist/chunk-F7OXXJIH.js.map +1 -0
  25. package/dist/{chunk-F7RDSWYF.js → chunk-VHNCSQPO.js} +2 -2
  26. package/dist/{chunk-F7RDSWYF.js.map → chunk-VHNCSQPO.js.map} +1 -1
  27. package/dist/{handler-CoJxInw-.d.ts → handler-DdfaWN_J.d.ts} +7 -1
  28. package/dist/{handler-CsFbanZA.d.cts → handler-kvZkxwaN.d.cts} +7 -1
  29. package/dist/index.cjs +667 -259
  30. package/dist/index.cjs.map +1 -1
  31. package/dist/index.d.cts +5 -3
  32. package/dist/index.d.ts +5 -3
  33. package/dist/index.js +290 -248
  34. package/dist/index.js.map +1 -1
  35. package/dist/migrations/index.cjs.map +1 -1
  36. package/dist/migrations/index.js +1 -1
  37. package/dist/{types-B2HEmyNq.d.cts → types-BxkRxTTx.d.cts} +38 -2
  38. package/dist/{types-DC68ZUuq.d.ts → types-DgUZNKii.d.ts} +38 -2
  39. package/package.json +8 -8
  40. package/dist/chunk-W5MYFJKT.js.map +0 -1
package/dist/index.cjs CHANGED
@@ -19,6 +19,12 @@ var QueryRequestSchema = zod.z.object({
19
19
  shape: zod.z.unknown().optional(),
20
20
  context: ContextSchema.default({})
21
21
  });
22
+ var dropNullIntentAndFingerprint = (body) => {
23
+ if (body === null || typeof body !== "object" || Array.isArray(body)) return body;
24
+ const isNullAt = (key) => Reflect.get(body, key) === null;
25
+ if (!isNullAt("intent") && !isNullAt("fingerprint")) return body;
26
+ return Object.fromEntries(Object.entries(body).filter(([key, value]) => value !== null || key !== "intent" && key !== "fingerprint"));
27
+ };
22
28
  var ContextRefSchema = zod.z.object({
23
29
  $context: zod.z.string().describe("Key to look up in the request context object")
24
30
  }).strict().describe("Reference to a caller-provided context value");
@@ -457,28 +463,24 @@ var VexScopeError = class extends VexError {
457
463
  this.entity = entity;
458
464
  }
459
465
  };
460
- var matchesFor = (entity, rule, def) => {
461
- if (rule === void 0) {
462
- if (def === "deny") throw new VexScopeError(entity, `Entity "${entity}" is not allowed by scope policy (default: deny)`);
463
- return [];
464
- }
466
+ var readRulesOf = (policy, table) => {
467
+ const rule = policy.entities[table];
468
+ if (rule === void 0) return policy.default === "deny" ? "unlisted" : [];
465
469
  if ("public" in rule) return [];
466
- if ("deny" in rule) throw new VexScopeError(entity, `Entity "${entity}" is denied by scope policy`);
467
- if (rule.read === void 0) {
468
- if (def === "deny") throw new VexScopeError(entity, `Reads of "${entity}" are not allowed by scope policy (default: deny)`);
469
- return [];
470
- }
470
+ if ("deny" in rule) return "denied";
471
+ if (rule.read === void 0) return policy.default === "deny" ? "ungranted" : [];
471
472
  return rule.read;
472
473
  };
473
- var canReadTable = (policy, table) => {
474
- const rule = policy.entities[table];
475
- if (rule === void 0) return policy.default === "allow";
476
- if ("public" in rule) return true;
477
- if ("deny" in rule) return false;
478
- return rule.read !== void 0 || policy.default === "allow";
474
+ var matchesFor = (policy, entity) => {
475
+ const rules = readRulesOf(policy, entity);
476
+ if (rules === "unlisted") throw new VexScopeError(entity, `Entity "${entity}" is not allowed by scope policy (default: deny)`);
477
+ if (rules === "denied") throw new VexScopeError(entity, `Entity "${entity}" is denied by scope policy`);
478
+ if (rules === "ungranted") throw new VexScopeError(entity, `Reads of "${entity}" are not allowed by scope policy (default: deny)`);
479
+ return rules;
479
480
  };
481
+ var canReadTable = (policy, table) => Array.isArray(readRulesOf(policy, table));
480
482
  var checkScope = (entities, policy) => {
481
- for (const entity of entities) matchesFor(entity, policy.entities[entity], policy.default);
483
+ for (const entity of entities) matchesFor(policy, entity);
482
484
  };
483
485
  var andMerge = (existing, additions) => {
484
486
  if (additions.length === 0) return existing;
@@ -491,7 +493,7 @@ var andMerge = (existing, additions) => {
491
493
  var predicateFor = (entityName, alias, match, fields) => {
492
494
  const field = fields.find((f) => f.name === match.match);
493
495
  if (field === void 0) throw new VexScopeError(entityName, `Scope rule for "${entityName}" names column "${match.match}", which the table does not have`);
494
- const path = `${entityName}.${match.match}`;
496
+ const path = `${alias}.${match.match}`;
495
497
  const original = isSetMatch(match) ? { in: [path, { $scope: match.in }] } : { eq: [path, { $scope: match.to }] };
496
498
  return { original, resolvedPaths: /* @__PURE__ */ new Map([[path, { alias, column: match.match, schema: field }]]) };
497
499
  };
@@ -501,10 +503,10 @@ var placeInto = (level, policy) => {
501
503
  const entity = source.entity;
502
504
  if (entity === void 0) continue;
503
505
  const join = level.joins.find((j) => j.toAlias === source.alias);
504
- for (const match of matchesFor(entity.name, policy.entities[entity.name], policy.default)) {
506
+ for (const match of matchesFor(policy, entity.name)) {
505
507
  const predicate = predicateFor(entity.name, source.alias, match, entity.fields);
506
508
  if (predicate === void 0) continue;
507
- level.aliasMap.set(`${entity.name}.${match.match}`, `${source.alias}.${match.match}`);
509
+ level.aliasMap.set(`${source.alias}.${match.match}`, `${source.alias}.${match.match}`);
508
510
  if (join !== void 0 && join.kind === "left") join.on = [...join.on ?? [], predicate];
509
511
  else whereAdditions.push(predicate);
510
512
  }
@@ -588,11 +590,24 @@ var createScopePolicy = (grants, behaviors = {}, scoping) => {
588
590
  return { default: "deny", entities };
589
591
  };
590
592
  var matchCount = (rules) => (rules ?? []).filter((r) => "match" in r).length;
593
+ var phasesOf = (rule) => {
594
+ if (rule === void 0 || "deny" in rule) return {};
595
+ if ("public" in rule) return { read: [], insert: [], update: [], delete: [] };
596
+ const { read, write, insert, update, delete: del } = rule;
597
+ const withWrite = (common, own) => [...common ?? [], ...own ?? []];
598
+ return {
599
+ ...read !== void 0 ? { read } : {},
600
+ ...write !== void 0 || insert !== void 0 ? { insert: withWrite(write, insert) } : {},
601
+ ...write !== void 0 || update !== void 0 ? { update: withWrite(write, update) } : {},
602
+ ...write !== void 0 || del !== void 0 ? { delete: withWrite(write && onlyMatches(write), del) } : {}
603
+ };
604
+ };
591
605
  var mergeScopePolicies = (policies) => {
592
606
  const entities = {};
593
607
  for (const policy of policies) {
594
- for (const [table, rule] of Object.entries(policy.entities)) {
595
- if (rule === void 0 || "public" in rule || "deny" in rule) continue;
608
+ for (const [table, listed] of Object.entries(policy.entities)) {
609
+ const rule = phasesOf(listed);
610
+ if (Object.keys(rule).length === 0) continue;
596
611
  const into = entities[table] ??= {};
597
612
  for (const phase of ["read", "insert", "update", "delete"]) {
598
613
  const incoming = rule[phase];
@@ -645,9 +660,9 @@ var findClosest = (target, candidates) => {
645
660
  };
646
661
  var generateAlias = (name, counter) => {
647
662
  const prefix = name.charAt(0).toLowerCase();
648
- const current = counter.get(prefix) ?? 0;
649
- const next = current + 1;
650
- counter.set(prefix, next);
663
+ let next = (counter.counts.get(prefix) ?? 0) + 1;
664
+ while (counter.taken.has(`${prefix}${next}`)) next += 1;
665
+ counter.counts.set(prefix, next);
651
666
  return `${prefix}${next}`;
652
667
  };
653
668
  var findEntity = (name, schema) => {
@@ -896,7 +911,10 @@ var extractSemantic = (filter, entityLookup, schema) => {
896
911
  return void 0;
897
912
  };
898
913
  var resolve = (dsl, schema) => {
899
- const aliasCounter = /* @__PURE__ */ new Map();
914
+ const aliasCounter = {
915
+ counts: /* @__PURE__ */ new Map(),
916
+ taken: /* @__PURE__ */ new Set([...schema.entities.map((e) => e.name), ...dsl.from.flatMap((source) => typeof source === "string" ? [] : [source.as])])
917
+ };
900
918
  const entityLookup = /* @__PURE__ */ new Map();
901
919
  const aliasMap = /* @__PURE__ */ new Map();
902
920
  const sources = [];
@@ -993,7 +1011,7 @@ var resolve = (dsl, schema) => {
993
1011
  for (const [name, expr] of Object.entries(dsl.aggregate)) {
994
1012
  if (expr !== void 0) {
995
1013
  assertName(name, "aggregate name");
996
- resolveAggregatePaths(expr, entityLookup, schema, aliasMap);
1014
+ resolveAggregatePaths(expr, entityLookup, schema, aliasMap, existsMap, aliasCounter);
997
1015
  aggregates.push({ name, expression: expr });
998
1016
  }
999
1017
  }
@@ -1072,11 +1090,11 @@ var resolveComputePaths = (expr, entityLookup, schema, aliasMap, existsOut, alia
1072
1090
  resolveFieldOrValue(expr.case.else);
1073
1091
  }
1074
1092
  };
1075
- var resolveAggregatePaths = (expr, entityLookup, schema, aliasMap) => {
1093
+ var resolveAggregatePaths = (expr, entityLookup, schema, aliasMap, existsOut, aliasCounter) => {
1076
1094
  const arg = "count" in expr ? expr.count : "countDistinct" in expr ? expr.countDistinct : "sum" in expr ? expr.sum : "avg" in expr ? expr.avg : "min" in expr ? expr.min : expr.max;
1077
1095
  if (arg === "*") return;
1078
1096
  if (typeof arg !== "string") {
1079
- resolveComputePaths(arg, entityLookup, schema, aliasMap);
1097
+ resolveComputePaths(arg, entityLookup, schema, aliasMap, existsOut, aliasCounter);
1080
1098
  return;
1081
1099
  }
1082
1100
  if (!aliasMap.has(arg)) {
@@ -1124,8 +1142,8 @@ var hasCartesianProduct = (resolved) => {
1124
1142
  };
1125
1143
  var findUnindexedFilterColumns = (resolved) => {
1126
1144
  if (resolved.filter === void 0) return [];
1127
- const unindexed = [];
1128
- for (const [path, res] of resolved.filter.resolvedPaths) {
1145
+ const unindexed = /* @__PURE__ */ new Set();
1146
+ for (const res of resolved.filter.resolvedPaths.values()) {
1129
1147
  const source = resolved.sources.find((s) => s.alias === res.alias);
1130
1148
  if (source === void 0 || source.entity === void 0) continue;
1131
1149
  const isIndexed = source.entity.indexes.some(
@@ -1135,10 +1153,10 @@ var findUnindexedFilterColumns = (resolved) => {
1135
1153
  (f) => f.name === res.column && f.primaryKey
1136
1154
  );
1137
1155
  if (!isIndexed && !isPrimaryKey) {
1138
- unindexed.push(path);
1156
+ unindexed.add(`${source.entity.name}.${res.column}`);
1139
1157
  }
1140
1158
  }
1141
- return unindexed;
1159
+ return [...unindexed];
1142
1160
  };
1143
1161
  var hasAggregatesWithoutGroupBy = (resolved) => resolved.aggregates.length > 0 && resolved.groupBy.length === 0;
1144
1162
  var analyze = (resolved, config) => {
@@ -1215,16 +1233,17 @@ var resolveParams = async (slots, context, scope, embed) => {
1215
1233
  results.push(context[slot.key]);
1216
1234
  continue;
1217
1235
  }
1218
- if (slot.kind === "scope") {
1236
+ if (slot.kind === "scope" && slot.embed !== true) {
1219
1237
  results.push(scope[slot.key]);
1220
1238
  continue;
1221
1239
  }
1240
+ const from = slot.kind === "scope" ? "scope" : "context";
1222
1241
  if (embed === void 0) {
1223
1242
  throw new Error(`Semantic parameter "${slot.key}" requires an embed function`);
1224
1243
  }
1225
- const text = context[slot.key];
1244
+ const text = (from === "scope" ? scope : context)[slot.key];
1226
1245
  if (typeof text !== "string") {
1227
- throw new Error(`Semantic parameter "${slot.key}" requires a string value in context`);
1246
+ throw new Error(`Semantic parameter "${slot.key}" requires a string value in ${from}`);
1228
1247
  }
1229
1248
  const vector = await embed(text, slot.dimensions);
1230
1249
  results.push(`[${vector.join(",")}]`);
@@ -1294,7 +1313,11 @@ var createMemoryCache = () => {
1294
1313
  const entries = async () => {
1295
1314
  return [...store.entries()].map(([key, entry]) => ({ key, entry }));
1296
1315
  };
1297
- return { get, set, delete: del, clear, keys, entries };
1316
+ const touch = async (key, lastUsedAt) => {
1317
+ const entry = store.get(key);
1318
+ if (entry !== void 0) store.set(key, { ...entry, lastUsedAt });
1319
+ };
1320
+ return { get, set, delete: del, clear, keys, entries, touch };
1298
1321
  };
1299
1322
 
1300
1323
  // src/utils/sha256.ts
@@ -1525,6 +1548,7 @@ var fireAndForget = (p, onError) => {
1525
1548
  };
1526
1549
  var TOUCH_EVERY_MS = 6e4;
1527
1550
  var isTouchDue = (entry, now) => entry.lastUsedAt === void 0 || now - entry.lastUsedAt >= TOUCH_EVERY_MS;
1551
+ var touchEntry = (cache, key, entry, now) => cache.touch !== void 0 ? cache.touch(key, now) : cache.set(key, { ...entry, lastUsedAt: now });
1528
1552
  var isEntryFresh = (entry, currentFingerprint) => {
1529
1553
  const expired = entry.expiresAt !== void 0 && entry.expiresAt <= Date.now();
1530
1554
  const stale = entry.schemaFingerprint !== void 0 && currentFingerprint !== void 0 && entry.schemaFingerprint !== currentFingerprint;
@@ -1742,6 +1766,128 @@ var createLiveRows = (config = {}, emit = () => {
1742
1766
  };
1743
1767
  return { read, follow, invalidate, stats, stop };
1744
1768
  };
1769
+ var UNREADABLE_MODES = ["refuse", "omit", "null"];
1770
+ var UpgradedColumnSchema = zod.z.object({
1771
+ stamp: zod.z.string(),
1772
+ kind: zod.z.union([zod.z.string(), zod.z.object({ grammar: zod.z.string(), column: zod.z.string() }).strict()]),
1773
+ unreadable: zod.z.enum(UNREADABLE_MODES).optional()
1774
+ }).strict();
1775
+ var UpgradedColumnsSchema = zod.z.record(zod.z.string(), zod.z.record(zod.z.string(), UpgradedColumnSchema));
1776
+ var outputOf = (ref) => typeof ref === "string" ? { path: ref, key: ref.slice(ref.indexOf(".") + 1) } : { path: ref.field, key: ref.as };
1777
+ var outputsOf = (dsl, path) => (dsl.fields ?? []).map(outputOf).flatMap((out) => out.path === path ? [out.key] : []);
1778
+ var count = (value, path) => {
1779
+ if (value === path) return 1;
1780
+ if (Array.isArray(value)) return value.reduce((sum, item) => sum + count(item, path), 0);
1781
+ if (typeof value === "object" && value !== null) return Object.values(value).reduce((sum, item) => sum + count(item, path), 0);
1782
+ return 0;
1783
+ };
1784
+ var usesOutsideFields = (dsl, path, outer) => Object.entries(dsl).reduce((sum, [part, value]) => {
1785
+ if (part === "filter" || part === "sort" || outer && part === "fields") return sum;
1786
+ if (part !== "from") return sum + count(value, path);
1787
+ return sum + dsl.from.reduce((inner, source) => inner + (typeof source === "string" ? 0 : usesOutsideFields(source.query, path, false)), 0);
1788
+ }, 0);
1789
+ var selected = (dsl, path, upgraded) => {
1790
+ const [first, ...rest] = outputsOf(dsl, path);
1791
+ if (first === void 0) throw new VexError("invalid_dsl", `This read returns ${upgraded}, which is upgraded where it is read, without ${path}: add ${path} to its fields.`);
1792
+ return [first, ...rest];
1793
+ };
1794
+ var refuseSharedKeys = (dsl, upgrades) => {
1795
+ const sourcesByKey = /* @__PURE__ */ new Map();
1796
+ const note = (key, source) => {
1797
+ sourcesByKey.set(key, (sourcesByKey.get(key) ?? /* @__PURE__ */ new Set()).add(source));
1798
+ };
1799
+ for (const { path, key } of (dsl.fields ?? []).map(outputOf)) note(key, path);
1800
+ for (const key of [...Object.keys(dsl.compute ?? {}), ...Object.keys(dsl.aggregate ?? {})]) note(key, `the computed ${key}`);
1801
+ const used = upgrades.flatMap((upgrade) => [upgrade.key, ...upgrade.stampKeys, ...typeof upgrade.kind === "string" ? [] : [upgrade.kind.key]]);
1802
+ const shared = [...new Set(used)].filter((key) => (sourcesByKey.get(key)?.size ?? 0) > 1);
1803
+ if (shared.length > 0) {
1804
+ throw new VexError("invalid_dsl", `This read returns two values under one key (${shared.join(", ")}), and one is an upgraded column, its stamp or its kind: give each its own key with \`as\`.`);
1805
+ }
1806
+ };
1807
+ var declared = (columns) => Object.entries(columns).flatMap(([table, byColumn]) => Object.entries(byColumn).map(([column, upgraded]) => ({ table, column, upgraded })));
1808
+ var columnUpgrades = (dsl, columns) => {
1809
+ const upgrades = declared(columns).flatMap(({ table, column, upgraded }) => {
1810
+ const path = `${table}.${column}`;
1811
+ if (usesOutsideFields(dsl, path, true) > 0) {
1812
+ throw new VexError(
1813
+ "invalid_dsl",
1814
+ `${path} is upgraded where it is read, so a read returns it only as one of its own fields, never through a subquery, a compute, an aggregate or a groupBy. A filter or a sort on it compares the stored value.`
1815
+ );
1816
+ }
1817
+ const keys = outputsOf(dsl, path);
1818
+ if (keys.length === 0) return [];
1819
+ const stampKeys = selected(dsl, `${table}.${upgraded.stamp}`, path);
1820
+ const kind = typeof upgraded.kind === "string" ? upgraded.kind : { grammar: upgraded.kind.grammar, key: selected(dsl, `${table}.${upgraded.kind.column}`, path)[0] };
1821
+ return keys.map((key) => ({ path, key, stampKeys, kind, unreadable: upgraded.unreadable ?? "refuse" }));
1822
+ });
1823
+ refuseSharedKeys(dsl, upgrades);
1824
+ return upgrades;
1825
+ };
1826
+ var unknownKinds = (columns, upgrader) => declared(columns).flatMap(({ table, column, upgraded: { kind } }) => {
1827
+ if (typeof kind !== "string") return kind.grammar in upgrader.stamp ? [] : [`${table}.${column} names the grammar "${kind.grammar}"`];
1828
+ try {
1829
+ upgrader.locate({}, kind);
1830
+ return [];
1831
+ } catch {
1832
+ return [`${table}.${column} names the kind "${kind}"`];
1833
+ }
1834
+ });
1835
+ var mistypedColumns = (columns, schema) => declared(columns).flatMap(({ table, column, upgraded }) => {
1836
+ const fields = schema.entities.find((e) => e.name === table)?.fields ?? [];
1837
+ const json = (name) => {
1838
+ const field = fields.find((f) => f.name === name);
1839
+ if (field === void 0) return [`${table}.${name} is not in the database`];
1840
+ return ["json", "jsonb"].includes(field.type.toLowerCase()) ? [] : [`${table}.${name} is ${field.type}, not json`];
1841
+ };
1842
+ const { kind } = upgraded;
1843
+ const kindColumn = typeof kind === "string" || fields.some((f) => f.name === kind.column) ? [] : [`${table}.${kind.column} is not in the database`];
1844
+ return [...json(column), ...json(upgraded.stamp), ...kindColumn];
1845
+ });
1846
+ var StampSchema = zod.z.union([zod.z.null(), zod.z.undefined(), zod.z.record(zod.z.string(), zod.z.number().int().nonnegative())]);
1847
+ var stampOf = (value, path) => {
1848
+ const parsed = StampSchema.safeParse(value);
1849
+ if (!parsed.success) throw new VexError("execution_error", `The stamp beside ${path} is not a stamp: it must be null or an object of grammar names to whole numbers.`);
1850
+ return parsed.data ?? {};
1851
+ };
1852
+ var kindOf = (upgrade, row) => {
1853
+ if (typeof upgrade.kind === "string") return upgrade.kind;
1854
+ const name = row[upgrade.kind.key];
1855
+ if (typeof name !== "string") throw new VexError("execution_error", `The row's ${upgrade.kind.key} is not text, so it names no kind in ${upgrade.kind.grammar}.`);
1856
+ return `${upgrade.kind.grammar}/${name}`;
1857
+ };
1858
+ var reasonOf = (error) => {
1859
+ const message = error instanceof Error ? error.message.split("\n")[0] ?? "" : String(error);
1860
+ const code = error instanceof Error && "code" in error && typeof error.code === "string" ? `${error.code}: ` : "";
1861
+ return `${code}${message}`;
1862
+ };
1863
+ var upgradeRows = (rows, upgrades, upgrade) => {
1864
+ if (upgrades.length === 0) return { rows, warnings: [] };
1865
+ const warnings = [];
1866
+ const upgraded = rows.flatMap((row, index) => {
1867
+ const next = { ...row };
1868
+ const said = [];
1869
+ for (const column of upgrades) {
1870
+ const value = row[column.key];
1871
+ if (value === null || value === void 0) continue;
1872
+ try {
1873
+ const result = upgrade(value, { kind: kindOf(column, row), stamp: stampOf(row[column.stampKeys[0]], column.path) });
1874
+ next[column.key] = result.document;
1875
+ for (const stampKey of column.stampKeys) next[stampKey] = result.stamp;
1876
+ } catch (error) {
1877
+ if (column.unreadable === "refuse") throw error;
1878
+ if (column.unreadable === "omit") {
1879
+ warnings.push(`The database's row ${index} (counting from 0) was left out: its ${column.path} does not upgrade (${reasonOf(error)}).`);
1880
+ return [];
1881
+ }
1882
+ next[column.key] = null;
1883
+ said.push(`The database's row ${index} (counting from 0) has ${column.path} set to null: it does not upgrade (${reasonOf(error)}).`);
1884
+ }
1885
+ }
1886
+ warnings.push(...said);
1887
+ return [next];
1888
+ });
1889
+ return { rows: upgraded, warnings };
1890
+ };
1745
1891
  var applySortContext = (dsl, context) => {
1746
1892
  const sortBy = context["sortBy"];
1747
1893
  if (typeof sortBy !== "string" || sortBy === "") return dsl;
@@ -1755,8 +1901,25 @@ var DEFAULT_MAX_LIMIT = 1e3;
1755
1901
  var DEFAULT_STATEMENT_TIMEOUT_MS = 1e4;
1756
1902
  var DEFAULT_UNSATISFIABLE_TTL_MS = 3e5;
1757
1903
  var DEFAULT_MAX_PRESENCE_VARIANTS = 32;
1904
+ var REMEMBERED_FINGERPRINTS = 1024;
1905
+ var forgetOldest = (noted) => {
1906
+ if (noted.size <= REMEMBERED_FINGERPRINTS) return;
1907
+ const oldest = noted.keys().next();
1908
+ if (oldest.done !== true) noted.delete(oldest.value);
1909
+ };
1758
1910
  var createQueryEngine = (engineConfig) => {
1759
- const { adapter, scope: scopePolicy, generateDsl, mapToShape, embed, behaviors } = engineConfig;
1911
+ const { adapter, scope: scopePolicy, generateDsl, mapToShape, embed, behaviors, upgrader } = engineConfig;
1912
+ const parsedColumns = UpgradedColumnsSchema.safeParse(engineConfig.upgradedColumns ?? {});
1913
+ if (!parsedColumns.success) throw new VexError("invalid_request", `The engine's upgradedColumns do not parse: ${parsedColumns.error.message}`);
1914
+ const upgradedColumns = parsedColumns.data;
1915
+ if (engineConfig.upgradedColumns !== void 0 && upgrader === void 0) {
1916
+ throw new VexError("invalid_request", "The engine was given `upgradedColumns` and no `upgrader`: hand it strata's `createUpgrader(grammars, { transform: evaluate })`.");
1917
+ }
1918
+ const unknown = upgrader === void 0 ? [] : unknownKinds(upgradedColumns, upgrader);
1919
+ if (unknown.length > 0) {
1920
+ throw new VexError("invalid_request", `The upgradedColumns name what the upgrader's grammars do not declare: ${unknown.join("; ")}. Fix the name, or give the upgrader that grammar.`);
1921
+ }
1922
+ const upgradeOf = (stored, upgrades) => upgrader === void 0 ? { rows: stored, warnings: [] } : upgradeRows(stored, upgrades, upgrader.upgrade);
1760
1923
  const emit = engineConfig.onEvent ?? (() => {
1761
1924
  });
1762
1925
  const maxNestingDepth = engineConfig.config?.maxNestingDepth ?? DEFAULT_MAX_NESTING_DEPTH;
@@ -1785,6 +1948,7 @@ var createQueryEngine = (engineConfig) => {
1785
1948
  if (seen === void 0) {
1786
1949
  seen = /* @__PURE__ */ new Set();
1787
1950
  variantsSeen.set(fingerprint, seen);
1951
+ forgetOldest(variantsSeen);
1788
1952
  }
1789
1953
  if (seen.has(signature)) return;
1790
1954
  seen.add(signature);
@@ -1808,6 +1972,10 @@ var createQueryEngine = (engineConfig) => {
1808
1972
  throw new VexError("execution_error", `The behaviors name columns the database does not have: ${missing.map((m) => `${m.entity}.${m.field}`).join(", ")}.`);
1809
1973
  }
1810
1974
  }
1975
+ const mistyped = mistypedColumns(upgradedColumns, schema);
1976
+ if (mistyped.length > 0) {
1977
+ throw new VexError("execution_error", `The upgradedColumns do not fit the database: ${mistyped.join("; ")}. Fix the name, or add the column in a migration.`);
1978
+ }
1811
1979
  cachedSchema = schema;
1812
1980
  cachedFingerprint = computeSchemaFingerprint(schema);
1813
1981
  return schema;
@@ -1846,15 +2014,30 @@ var createQueryEngine = (engineConfig) => {
1846
2014
  );
1847
2015
  }
1848
2016
  const compiled = adapter.compile(resolved);
1849
- return { compiled, warnings: analysis.warnings, ...engineLimit !== void 0 ? { engineLimit } : {} };
2017
+ return { compiled, warnings: analysis.warnings, upgrades: columnUpgrades(processedDsl, upgradedColumns), ...engineLimit !== void 0 ? { engineLimit } : {} };
1850
2018
  };
1851
2019
  const cutSaid = /* @__PURE__ */ new Set();
2020
+ const reachUnasked = /* @__PURE__ */ new Set();
2021
+ const policyAtReach2 = async (fingerprint, reach, current, options) => {
2022
+ if (options?.policyForReach === void 0) {
2023
+ if (!reachUnasked.has(fingerprint)) {
2024
+ reachUnasked.add(fingerprint);
2025
+ forgetOldest(reachUnasked);
2026
+ console.warn(`[vex] "${fingerprint}" declares reach "${reach}" and was replayed without policyForReach, so it ran under the caller's own policy. Pass policyForReach to serve it at its reach.`);
2027
+ }
2028
+ return current;
2029
+ }
2030
+ const narrowed = await options.policyForReach(reach);
2031
+ if (narrowed === void 0) throw new VexError("scope_denied", `Reach "${reach}" is not available to this principal.`);
2032
+ return narrowed;
2033
+ };
1852
2034
  const cutNote = (engineLimit, stated, rowCount, shape, fingerprint) => {
1853
2035
  if (engineLimit === void 0 || rowCount !== engineLimit) return void 0;
1854
2036
  if (shape !== void 0 && !Array.isArray(shape)) return void 0;
1855
2037
  const note = stated === void 0 ? `This list states no limit, so it ran with the engine's defaultLimit of ${engineLimit}, and exactly ${engineLimit} rows came back \u2014 it may have been cut. State a \`limit\`.` : `This query asks for ${stated} rows, the engine's maxLimit is ${engineLimit}, and exactly ${engineLimit} came back \u2014 the list may have been cut. Raise \`maxLimit\` to read more.`;
1856
2038
  if (fingerprint !== void 0 && !cutSaid.has(fingerprint)) {
1857
2039
  cutSaid.add(fingerprint);
2040
+ forgetOldest(cutSaid);
1858
2041
  console.warn(`[vex] "${fingerprint}": ${note}`);
1859
2042
  }
1860
2043
  return note;
@@ -1863,12 +2046,12 @@ var createQueryEngine = (engineConfig) => {
1863
2046
  const test = async (dsl, scopeValues) => {
1864
2047
  try {
1865
2048
  const testDsl = { ...pruneOptional(dsl, "all"), limit: 5 };
1866
- const { compiled, warnings } = runPipeline(testDsl);
2049
+ const { compiled, warnings, upgrades } = runPipeline(testDsl);
1867
2050
  const syntheticContext = buildValidationContext(compiled.contextContract);
1868
2051
  const scope = scopeValues ?? {};
1869
2052
  requireScope(compiled, scope);
1870
- const rows = await executeQuery(compiled, syntheticContext, scope, adapter, embed);
1871
- return { rows, warnings, errors: [] };
2053
+ const { rows, warnings: upgradeWarnings } = upgradeOf(await executeQuery(compiled, syntheticContext, scope, adapter, embed), upgrades);
2054
+ return { rows, warnings: [...warnings, ...upgradeWarnings], errors: [] };
1872
2055
  } catch (err) {
1873
2056
  const message = err instanceof Error ? err.message : String(err);
1874
2057
  return { rows: [], warnings: [], errors: [message] };
@@ -1881,7 +2064,7 @@ var createQueryEngine = (engineConfig) => {
1881
2064
  };
1882
2065
  const touch = (key, entry) => {
1883
2066
  const now = Date.now();
1884
- if (isTouchDue(entry, now)) fireAndForget(cache.set(key, { ...entry, lastUsedAt: now }));
2067
+ if (isTouchDue(entry, now)) fireAndForget(touchEntry(cache, key, entry, now));
1885
2068
  };
1886
2069
  const resolveFingerprint = async (validRequest, hasRequest, requestHash, scope) => {
1887
2070
  const fp = validRequest.fingerprint;
@@ -1905,6 +2088,7 @@ var createQueryEngine = (engineConfig) => {
1905
2088
  ...entry.intent !== void 0 ? { intent: entry.intent } : {},
1906
2089
  ...entry.shape !== void 0 ? { shape: entry.shape } : {},
1907
2090
  ...entry.refresh !== void 0 ? { refresh: entry.refresh } : {},
2091
+ ...entry.reach !== void 0 ? { reach: entry.reach } : {},
1908
2092
  seeded: entry.protected === true && entry.requestHash === void 0,
1909
2093
  hit: true,
1910
2094
  replaced: false
@@ -1926,13 +2110,15 @@ var createQueryEngine = (engineConfig) => {
1926
2110
  const callerOf = (policy, scope, tables) => ({
1927
2111
  bindings: scopeBindings(behaviors ?? {}, tables, scope),
1928
2112
  read: async (dsl) => {
1929
- const { compiled, warnings } = runPipeline(pruneOptional(dsl, "all"), policy);
2113
+ const pruned = pruneOptional(dsl, "all");
2114
+ const { compiled, warnings, upgrades } = runPipeline(pruned, policy);
1930
2115
  requireScope(compiled, scope);
1931
- if (compiled.paramSlots.some((slot) => slot.kind === "semantic")) {
2116
+ if (compiled.paramSlots.some((slot) => slot.kind === "semantic" || slot.embed === true)) {
1932
2117
  return { rows: [], sql: compiled.sql, warnings: [...warnings, "Semantic params present \u2014 execution skipped, SQL structure validated only"] };
1933
2118
  }
1934
2119
  const params = compiled.paramSlots.map((slot) => slot.kind === "scope" ? scope[slot.key] : null);
1935
- return { rows: await adapter.execute(compiled, params), sql: compiled.sql, warnings };
2120
+ const { rows, warnings: upgradeWarnings } = upgradeOf(await adapter.execute(compiled, params), upgrades);
2121
+ return { rows, sql: compiled.sql, warnings: [...warnings, ...upgradeWarnings] };
1936
2122
  }
1937
2123
  });
1938
2124
  const generateMissingDsl = async (validRequest, flightKey, negKey, entities, policy, scope) => {
@@ -1984,9 +2170,10 @@ var createQueryEngine = (engineConfig) => {
1984
2170
  };
1985
2171
  return prism.execute(ir, source);
1986
2172
  };
1987
- const executeAndMap = async (compiled, validRequest, cachedIr, context, scope) => {
2173
+ const executeAndMap = async (compiled, validRequest, cachedIr, context, scope, upgrades) => {
1988
2174
  const execStart = Date.now();
1989
- const rows = await executeQuery(compiled, context, scope, adapter, embed);
2175
+ const stored = await executeQuery(compiled, context, scope, adapter, embed);
2176
+ const { rows, warnings: upgradeWarnings } = upgradeOf(stored, upgrades);
1990
2177
  const executionMs = Date.now() - execStart;
1991
2178
  emit({ type: "query.rows", count: rows.length, executionMs });
1992
2179
  let result = rows;
@@ -2008,17 +2195,17 @@ var createQueryEngine = (engineConfig) => {
2008
2195
  }
2009
2196
  if (mappingMs !== void 0) emit({ type: "query.mapped", mappingMs });
2010
2197
  }
2011
- return { result, rowCount: rows.length, executionMs, mappingMs, mappedIr, ...mappedConfig !== void 0 ? { mappedConfig } : {} };
2198
+ return { result, storedRowCount: stored.length, upgradeWarnings, executionMs, mappingMs, mappedIr, ...mappedConfig !== void 0 ? { mappedConfig } : {} };
2012
2199
  };
2013
2200
  const execute = async (request, options) => {
2014
2201
  if (strata.exceedsDepth(request)) throw new VexError("invalid_request", `Invalid request: ${strata.depthRefusal()}`);
2015
- const parsed = QueryRequestSchema.safeParse(request);
2202
+ const parsed = QueryRequestSchema.safeParse(dropNullIntentAndFingerprint(request));
2016
2203
  if (!parsed.success) {
2017
2204
  throw new VexError("invalid_request", `Invalid request: ${parsed.error.message}`);
2018
2205
  }
2019
2206
  const validRequest = parsed.data;
2020
2207
  const scope = options?.scope ?? {};
2021
- const activePolicy = options?.scopePolicy ?? scopePolicy;
2208
+ let activePolicy = options?.scopePolicy ?? scopePolicy;
2022
2209
  const t0 = Date.now();
2023
2210
  const hasRequest = validRequest.shape !== void 0 && validRequest.shape !== null;
2024
2211
  if (validRequest.fingerprint === void 0 && !hasRequest) {
@@ -2036,6 +2223,7 @@ var createQueryEngine = (engineConfig) => {
2036
2223
  });
2037
2224
  const cached = await resolveFingerprint(validRequest, hasRequest, requestHash, scope);
2038
2225
  emit({ type: "query.cache", hit: cached.hit, fingerprint: cached.fingerprint, replaced: cached.replaced });
2226
+ if (cached.reach !== void 0) activePolicy = await policyAtReach2(cached.fingerprint, cached.reach, activePolicy, options);
2039
2227
  let dsl = cached.dsl;
2040
2228
  let agentMs;
2041
2229
  if (dsl === void 0) {
@@ -2057,7 +2245,7 @@ var createQueryEngine = (engineConfig) => {
2057
2245
  }
2058
2246
  const presence = presenceOf(validRequest.context);
2059
2247
  const shaped = pruneOptional(applySortContext(dsl, validRequest.context), presence);
2060
- const { compiled, warnings, engineLimit } = runPipeline(shaped, activePolicy, cached.seeded === true);
2248
+ const { compiled, warnings, upgrades, engineLimit } = runPipeline(shaped, activePolicy, cached.seeded === true);
2061
2249
  noteVariant(cached.fingerprint, presenceSignature(dsl, presence), warnings);
2062
2250
  emit({ type: "query.sql", sql: compiled.sql, warnings });
2063
2251
  requireScope(compiled, scope);
@@ -2083,7 +2271,11 @@ var createQueryEngine = (engineConfig) => {
2083
2271
  const reactiveIr = cached.cachedIr;
2084
2272
  if (cached.hit && cached.refresh === "reactive" && (effectiveRequest.shape === void 0 || reactiveIr !== void 0)) {
2085
2273
  const shape = effectiveRequest.shape;
2086
- const shapeRows = (rows2) => shape === void 0 || reactiveIr === void 0 ? rows2 : mapRows(rows2, shape, reactiveIr, context, scope);
2274
+ const shapeRows = (stored) => {
2275
+ const { rows: rows2, warnings: upgradeWarnings3 } = upgradeOf(stored, upgrades);
2276
+ const result3 = shape === void 0 || reactiveIr === void 0 ? rows2 : mapRows(rows2, shape, reactiveIr, context, scope);
2277
+ return { result: result3, upgradeWarnings: upgradeWarnings3 };
2278
+ };
2087
2279
  const params = await resolveParams(compiled.paramSlots, context, scope, embed);
2088
2280
  const key = canonicalHash([compiled.sql, params]);
2089
2281
  const source = { tables: [...discoverEntities(shaped)], fetch: () => adapter.execute(compiled, params) };
@@ -2091,10 +2283,10 @@ var createQueryEngine = (engineConfig) => {
2091
2283
  const rows = await live.read(key, source);
2092
2284
  const executionMs2 = Date.now() - execStart;
2093
2285
  emit({ type: "query.rows", count: rows.length, executionMs: executionMs2 });
2094
- const result2 = shapeRows(rows);
2095
- const metaOf = (rowCount2) => {
2096
- const cut2 = cutNote(engineLimit, shaped.limit, rowCount2, shape, validRequest.fingerprint);
2097
- const said2 = cut2 === void 0 ? warnings : [...warnings, cut2];
2286
+ const { result: result2, upgradeWarnings: upgradeWarnings2 } = shapeRows(rows);
2287
+ const metaOf = (rowCount, upgraded) => {
2288
+ const cut2 = cutNote(engineLimit, shaped.limit, rowCount, shape, validRequest.fingerprint);
2289
+ const said2 = [...warnings, ...upgraded, ...cut2 === void 0 ? [] : [cut2]];
2098
2290
  return {
2099
2291
  cache: {
2100
2292
  hit: cached.hit,
@@ -2107,29 +2299,30 @@ var createQueryEngine = (engineConfig) => {
2107
2299
  };
2108
2300
  const { signal, onChange } = options ?? {};
2109
2301
  if (signal !== void 0 && onChange !== void 0) {
2110
- let lastHash = canonicalHash(result2);
2302
+ let lastHash = canonicalHash([result2, upgradeWarnings2]);
2111
2303
  live.follow(key, source, rows, {
2112
2304
  deliver: (next) => {
2113
- const nextResult = shapeRows(next);
2114
- const nextHash = canonicalHash(nextResult);
2305
+ const { result: nextResult, upgradeWarnings: nextUpgradeWarnings } = shapeRows(next);
2306
+ const nextHash = canonicalHash([nextResult, nextUpgradeWarnings]);
2115
2307
  if (nextHash === lastHash) return;
2116
2308
  lastHash = nextHash;
2117
- onChange({ result: nextResult, meta: metaOf(next.length) });
2309
+ onChange({ result: nextResult, meta: metaOf(next.length, nextUpgradeWarnings) });
2118
2310
  }
2119
2311
  }, signal);
2120
2312
  }
2121
2313
  emit({ type: "query.done", totalMs: Date.now() - t0 });
2122
- return { result: result2, meta: { ...metaOf(rows.length), timing: { executionMs: executionMs2 } } };
2314
+ return { result: result2, meta: { ...metaOf(rows.length, upgradeWarnings2), timing: { executionMs: executionMs2 } } };
2123
2315
  }
2124
- const { result, rowCount, executionMs, mappingMs, mappedIr, mappedConfig } = await executeAndMap(
2316
+ const { result, storedRowCount, upgradeWarnings, executionMs, mappingMs, mappedIr, mappedConfig } = await executeAndMap(
2125
2317
  compiled,
2126
2318
  effectiveRequest,
2127
2319
  cached.cachedIr,
2128
2320
  context,
2129
- scope
2321
+ scope,
2322
+ upgrades
2130
2323
  );
2131
- const cut = cutNote(engineLimit, shaped.limit, rowCount, effectiveRequest.shape, validRequest.fingerprint);
2132
- const said = cut === void 0 ? warnings : [...warnings, cut];
2324
+ const cut = cutNote(engineLimit, shaped.limit, storedRowCount, effectiveRequest.shape, validRequest.fingerprint);
2325
+ const said = [...warnings, ...upgradeWarnings, ...cut === void 0 ? [] : [cut]];
2133
2326
  if (!cached.hit) {
2134
2327
  const now = Date.now();
2135
2328
  const entry = {
@@ -2176,6 +2369,7 @@ var createQueryEngine = (engineConfig) => {
2176
2369
  getDslSchema,
2177
2370
  getSchema,
2178
2371
  cache,
2372
+ ...scopePolicy !== void 0 ? { scopePolicy } : {},
2179
2373
  invalidate: live.invalidate,
2180
2374
  rows: { stats: live.stats, stop: live.stop }
2181
2375
  };
@@ -2223,6 +2417,8 @@ var COLUMNS_QUERY = `
2223
2417
  c.udt_name,
2224
2418
  c.is_nullable,
2225
2419
  c.column_default,
2420
+ c.is_identity,
2421
+ c.identity_generation,
2226
2422
  CASE
2227
2423
  WHEN c.data_type = 'USER-DEFINED' THEN c.udt_name
2228
2424
  WHEN c.data_type = 'ARRAY' THEN c.udt_name
@@ -2332,8 +2528,8 @@ var introspectPostgres = async (pool, options) => {
2332
2528
  const rowCountMap = /* @__PURE__ */ new Map();
2333
2529
  for (const row of rowCountsResult.rows) {
2334
2530
  const table = row["table_name"];
2335
- const count = Number(row["row_count"] ?? 0);
2336
- rowCountMap.set(table, count);
2531
+ const count2 = Number(row["row_count"] ?? 0);
2532
+ rowCountMap.set(table, count2);
2337
2533
  }
2338
2534
  const columnsByTable = /* @__PURE__ */ new Map();
2339
2535
  for (const row of columnsResult.rows) {
@@ -2342,7 +2538,7 @@ var introspectPostgres = async (pool, options) => {
2342
2538
  const dataType = row["effective_type"];
2343
2539
  const fullType = row["full_type"];
2344
2540
  const isNullable = row["is_nullable"];
2345
- const colDefault = row["column_default"];
2541
+ const colDefault = row["column_default"] ?? (row["is_identity"] === "YES" ? `GENERATED ${String(row["identity_generation"])} AS IDENTITY` : null);
2346
2542
  const colDescription = row["description"];
2347
2543
  const tablePks = pkMap.get(table);
2348
2544
  const isPk = tablePks !== void 0 && tablePks.has(colName);
@@ -2460,15 +2656,125 @@ var quoteLiteral = (s) => {
2460
2656
  return s.includes("\\") ? `E'${doubled.replace(/\\/g, "\\\\")}'` : `'${doubled}'`;
2461
2657
  };
2462
2658
  var quoteIdent = (name) => `"${name.replace(/"/g, '""')}"`;
2659
+ var RESERVED = /* @__PURE__ */ new Set([
2660
+ "all",
2661
+ "analyse",
2662
+ "analyze",
2663
+ "and",
2664
+ "any",
2665
+ "array",
2666
+ "as",
2667
+ "asc",
2668
+ "asymmetric",
2669
+ "authorization",
2670
+ "binary",
2671
+ "both",
2672
+ "case",
2673
+ "cast",
2674
+ "check",
2675
+ "collate",
2676
+ "collation",
2677
+ "column",
2678
+ "concurrently",
2679
+ "constraint",
2680
+ "create",
2681
+ "cross",
2682
+ "current_catalog",
2683
+ "current_date",
2684
+ "current_role",
2685
+ "current_schema",
2686
+ "current_time",
2687
+ "current_timestamp",
2688
+ "current_user",
2689
+ "default",
2690
+ "deferrable",
2691
+ "desc",
2692
+ "distinct",
2693
+ "do",
2694
+ "else",
2695
+ "end",
2696
+ "except",
2697
+ "false",
2698
+ "fetch",
2699
+ "for",
2700
+ "foreign",
2701
+ "freeze",
2702
+ "from",
2703
+ "full",
2704
+ "grant",
2705
+ "group",
2706
+ "having",
2707
+ "ilike",
2708
+ "in",
2709
+ "initially",
2710
+ "inner",
2711
+ "intersect",
2712
+ "into",
2713
+ "is",
2714
+ "isnull",
2715
+ "join",
2716
+ "lateral",
2717
+ "leading",
2718
+ "left",
2719
+ "like",
2720
+ "limit",
2721
+ "localtime",
2722
+ "localtimestamp",
2723
+ "natural",
2724
+ "not",
2725
+ "notnull",
2726
+ "null",
2727
+ "offset",
2728
+ "on",
2729
+ "only",
2730
+ "or",
2731
+ "order",
2732
+ "outer",
2733
+ "overlaps",
2734
+ "placing",
2735
+ "primary",
2736
+ "references",
2737
+ "returning",
2738
+ "right",
2739
+ "select",
2740
+ "session_user",
2741
+ "similar",
2742
+ "some",
2743
+ "symmetric",
2744
+ "system_user",
2745
+ "table",
2746
+ "tablesample",
2747
+ "then",
2748
+ "to",
2749
+ "trailing",
2750
+ "true",
2751
+ "union",
2752
+ "unique",
2753
+ "user",
2754
+ "using",
2755
+ "variadic",
2756
+ "verbose",
2757
+ "when",
2758
+ "where",
2759
+ "window",
2760
+ "with"
2761
+ ]);
2762
+ var LOWER_IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
2763
+ var sqlName = (name) => LOWER_IDENTIFIER.test(name) && !RESERVED.has(name) ? name : quoteIdent(name);
2764
+ var columnSql = (qualifier, column) => `${sqlName(qualifier)}.${sqlName(column)}`;
2765
+ var tableSql = (table, namespace) => namespace === void 0 ? sqlName(table) : `${quoteIdent(namespace)}.${sqlName(table)}`;
2463
2766
  var numberLiteral = (n) => {
2464
2767
  if (!Number.isFinite(n)) throw new VexError("invalid_dsl", `${String(n)} is not a number SQL can hold.`);
2465
2768
  return String(n);
2466
2769
  };
2467
2770
  var columnOf = (path, ctx) => {
2468
2771
  const mapped = ctx.aliasMap.get(path);
2469
- if (mapped !== void 0) return mapped;
2772
+ if (mapped !== void 0) {
2773
+ const dot = mapped.indexOf(".");
2774
+ return columnSql(mapped.slice(0, dot), mapped.slice(dot + 1));
2775
+ }
2470
2776
  const res = ctx.resolvedPaths.get(path);
2471
- if (res !== void 0) return `${res.alias}.${res.column}`;
2777
+ if (res !== void 0) return columnSql(res.alias, res.column);
2472
2778
  throw new VexError("invalid_dsl", `"${path}" is not a column this query reads.`);
2473
2779
  };
2474
2780
  var isFieldPath2 = isFieldPathShape;
@@ -2518,7 +2824,7 @@ var compileJoinPairs = (join) => join.fromColumns.map((column, i) => {
2518
2824
  `The join from "${join.fromAlias}" to "${join.toAlias}" pairs "${column}" with no column.`
2519
2825
  );
2520
2826
  }
2521
- return `${join.fromAlias}.${column} = ${join.toAlias}.${to}`;
2827
+ return `${columnSql(join.fromAlias, column)} = ${columnSql(join.toAlias, to)}`;
2522
2828
  });
2523
2829
  var compileComparisonFilter = (op, pair, ctx) => {
2524
2830
  const left = compileFieldOrValue(pair[0], ctx);
@@ -2537,7 +2843,7 @@ var compileFilter = (filter, ctx) => {
2537
2843
  };
2538
2844
  const parts = ["SELECT 1"];
2539
2845
  const first = resolved.sources[0];
2540
- if (first?.table !== void 0) parts.push(`FROM ${first.table} AS ${first.alias}`);
2846
+ if (first?.table !== void 0) parts.push(`FROM ${tableSql(first.table, ctx.namespace)} AS ${sqlName(first.alias)}`);
2541
2847
  for (const join of resolved.joins) {
2542
2848
  const source = resolved.sources.find((s) => s.alias === join.toAlias);
2543
2849
  if (source?.table === void 0) continue;
@@ -2546,7 +2852,7 @@ var compileFilter = (filter, ctx) => {
2546
2852
  ...compileJoinPairs(join),
2547
2853
  ...(join.on ?? []).map((extra) => compileFilter(extra.original, inner))
2548
2854
  ];
2549
- parts.push(`${keyword} ${source.table} AS ${join.toAlias} ON ${conditions.join(" AND ")}`);
2855
+ parts.push(`${keyword} ${tableSql(source.table, ctx.namespace)} AS ${sqlName(join.toAlias)} ON ${conditions.join(" AND ")}`);
2550
2856
  }
2551
2857
  if (resolved.filter !== void 0) parts.push(`WHERE ${compileFilter(resolved.filter.original, inner)}`);
2552
2858
  return `EXISTS (${parts.join(" ")})`;
@@ -2629,17 +2935,13 @@ var compileFilter = (filter, ctx) => {
2629
2935
  const fieldPath2 = filter.semantic.field;
2630
2936
  const col = columnOf(fieldPath2, ctx);
2631
2937
  const queryRef = filter.semantic.query;
2632
- const key = "$context" in queryRef ? queryRef.$context : queryRef.$scope;
2633
2938
  if ("$context" in queryRef) assertNotReserved(queryRef.$context);
2634
2939
  const res = ctx.resolvedPaths.get(fieldPath2);
2635
2940
  const dimensions = res?.schema.vectorDimensions;
2636
2941
  ctx.paramCounter.value += 1;
2637
- ctx.paramSlots.push({
2638
- key,
2639
- kind: "semantic",
2640
- type: "string",
2641
- dimensions
2642
- });
2942
+ ctx.paramSlots.push(
2943
+ "$context" in queryRef ? { key: queryRef.$context, kind: "semantic", type: "string", dimensions } : { key: queryRef.$scope, kind: "scope", type: "string", dimensions, embed: true }
2944
+ );
2643
2945
  const paramRef = `$${ctx.paramCounter.value}`;
2644
2946
  const minScore = numberLiteral(filter.semantic.minScore ?? 0);
2645
2947
  return `1 - (${col} <=> ${paramRef}) >= ${minScore}`;
@@ -2717,22 +3019,23 @@ var compileAggregate = (expr, ctx) => {
2717
3019
  };
2718
3020
 
2719
3021
  // src/adapters/postgres/compile.ts
2720
- var compileQuery = (resolved) => {
3022
+ var compileQuery = (resolved, namespace) => {
2721
3023
  const paramSlots = [];
2722
- const sql = compileLevel(resolved, paramSlots, { value: 0 });
3024
+ const sql = compileLevel(resolved, paramSlots, { value: 0 }, namespace);
2723
3025
  const contextContract = {};
2724
3026
  for (const slot of paramSlots) {
2725
3027
  contextContract[slot.key] = { type: slot.type, kind: slot.kind };
2726
3028
  }
2727
3029
  return { sql, paramSlots, contextContract };
2728
3030
  };
2729
- var compileLevel = (resolved, paramSlots, paramCounter) => {
3031
+ var compileLevel = (resolved, paramSlots, paramCounter, namespace) => {
2730
3032
  const ctx = {
2731
3033
  resolvedPaths: resolved.filter?.resolvedPaths ?? /* @__PURE__ */ new Map(),
2732
3034
  aliasMap: resolved.aliasMap,
2733
3035
  paramSlots,
2734
3036
  paramCounter,
2735
- ...resolved.existsMap !== void 0 ? { existsMap: resolved.existsMap } : {}
3037
+ ...resolved.existsMap !== void 0 ? { existsMap: resolved.existsMap } : {},
3038
+ ...namespace !== void 0 ? { namespace } : {}
2736
3039
  };
2737
3040
  const sqlParts = [];
2738
3041
  const selectParts = [];
@@ -2740,7 +3043,7 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2740
3043
  selectParts.push("DISTINCT");
2741
3044
  }
2742
3045
  const fieldColumns = resolved.fields.map(
2743
- (f) => `${f.alias}.${f.column} AS ${quoteIdent(f.outputName)}`
3046
+ (f) => `${columnSql(f.alias, f.column)} AS ${quoteIdent(f.outputName)}`
2744
3047
  );
2745
3048
  const computeColumns = resolved.computes.map((c) => {
2746
3049
  const expr = compileCompute(c.expression, ctx);
@@ -2759,9 +3062,9 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2759
3062
  const firstSource = resolved.sources[0];
2760
3063
  if (firstSource !== void 0) {
2761
3064
  if (firstSource.subquery !== void 0) {
2762
- sqlParts.push(`FROM (${compileLevel(firstSource.subquery, paramSlots, paramCounter)}) AS ${firstSource.alias}`);
3065
+ sqlParts.push(`FROM (${compileLevel(firstSource.subquery, paramSlots, paramCounter, namespace)}) AS ${sqlName(firstSource.alias)}`);
2763
3066
  } else if (firstSource.table !== void 0) {
2764
- sqlParts.push(`FROM ${firstSource.table} AS ${firstSource.alias}`);
3067
+ sqlParts.push(`FROM ${tableSql(firstSource.table, namespace)} AS ${sqlName(firstSource.alias)}`);
2765
3068
  }
2766
3069
  }
2767
3070
  for (const join of resolved.joins) {
@@ -2774,9 +3077,9 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2774
3077
  ];
2775
3078
  const on = conditions.join(" AND ");
2776
3079
  if (joinSource.subquery !== void 0) {
2777
- sqlParts.push(`${keyword} (${compileLevel(joinSource.subquery, paramSlots, paramCounter)}) AS ${join.toAlias} ON ${on}`);
3080
+ sqlParts.push(`${keyword} (${compileLevel(joinSource.subquery, paramSlots, paramCounter, namespace)}) AS ${sqlName(join.toAlias)} ON ${on}`);
2778
3081
  } else {
2779
- sqlParts.push(`${keyword} ${join.toTable} AS ${join.toAlias} ON ${on}`);
3082
+ sqlParts.push(`${keyword} ${tableSql(join.toTable, namespace)} AS ${sqlName(join.toAlias)} ON ${on}`);
2780
3083
  }
2781
3084
  }
2782
3085
  }
@@ -2784,9 +3087,9 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2784
3087
  for (const source of resolved.sources) {
2785
3088
  if (source.alias === firstSource?.alias || joinedAliases.has(source.alias)) continue;
2786
3089
  if (source.subquery !== void 0) {
2787
- sqlParts.push(`CROSS JOIN (${compileLevel(source.subquery, paramSlots, paramCounter)}) AS ${source.alias}`);
3090
+ sqlParts.push(`CROSS JOIN (${compileLevel(source.subquery, paramSlots, paramCounter, namespace)}) AS ${sqlName(source.alias)}`);
2788
3091
  } else if (source.table !== void 0) {
2789
- sqlParts.push(`CROSS JOIN ${source.table} AS ${source.alias}`);
3092
+ sqlParts.push(`CROSS JOIN ${tableSql(source.table, namespace)} AS ${sqlName(source.alias)}`);
2790
3093
  }
2791
3094
  }
2792
3095
  if (resolved.filter !== void 0) {
@@ -2794,7 +3097,7 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2794
3097
  sqlParts.push(`WHERE ${whereClause}`);
2795
3098
  }
2796
3099
  if (resolved.groupBy.length > 0) {
2797
- const groupByParts = resolved.groupBy.map((f) => `${f.alias}.${f.column}`);
3100
+ const groupByParts = resolved.groupBy.map((f) => columnSql(f.alias, f.column));
2798
3101
  sqlParts.push(`GROUP BY ${groupByParts.join(", ")}`);
2799
3102
  }
2800
3103
  if (resolved.sort.length > 0) {
@@ -2802,13 +3105,13 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2802
3105
  if (typeof s.field === "string") {
2803
3106
  return `${quoteIdent(s.field)} ${s.dir === "desc" ? "DESC" : "ASC"}`;
2804
3107
  }
2805
- return `${s.field.alias}.${s.field.column} ${s.dir === "desc" ? "DESC" : "ASC"}`;
3108
+ return `${columnSql(s.field.alias, s.field.column)} ${s.dir === "desc" ? "DESC" : "ASC"}`;
2806
3109
  });
2807
3110
  sqlParts.push(`ORDER BY ${orderByParts.join(", ")}`);
2808
3111
  } else if (resolved.semantic !== void 0) {
2809
3112
  const { field, contextPath } = resolved.semantic;
2810
- const position = paramSlots.findIndex((slot) => slot.kind === "semantic" && slot.key === contextPath) + 1;
2811
- if (position > 0) sqlParts.push(`ORDER BY ${field.alias}.${field.column} <=> $${position} ASC`);
3113
+ const position = paramSlots.findIndex((slot) => (slot.kind === "semantic" || slot.embed === true) && slot.key === contextPath) + 1;
3114
+ if (position > 0) sqlParts.push(`ORDER BY ${columnSql(field.alias, field.column)} <=> $${position} ASC`);
2812
3115
  }
2813
3116
  if (resolved.limit !== void 0) {
2814
3117
  if (!Number.isInteger(resolved.limit) || resolved.limit < 1) {
@@ -2863,6 +3166,7 @@ var coerceNumericColumns = (rows, fields) => {
2863
3166
  };
2864
3167
  var createPostgresAdapter = (config) => {
2865
3168
  const { pool, schema = "public", exclude } = config;
3169
+ const namespace = config.qualifyTables === true ? schema : void 0;
2866
3170
  const capabilities = {
2867
3171
  vectorSearch: true,
2868
3172
  fuzzyMatch: false,
@@ -2874,12 +3178,15 @@ var createPostgresAdapter = (config) => {
2874
3178
  windowFunctions: true,
2875
3179
  statementTimeout: true
2876
3180
  };
2877
- const introspect = async (options) => introspectPostgres(pool, {
2878
- ...options,
2879
- schema: options?.schema ?? schema,
2880
- exclude: options?.exclude ?? exclude
2881
- });
2882
- const compile2 = (resolved) => compileQuery(resolved);
3181
+ const introspect = async (options) => {
3182
+ const introspected = await introspectPostgres(pool, {
3183
+ ...options,
3184
+ schema: options?.schema ?? schema,
3185
+ exclude: options?.exclude ?? exclude
3186
+ });
3187
+ return namespace === void 0 ? introspected : { ...introspected, namespace };
3188
+ };
3189
+ const compile2 = (resolved) => compileQuery(resolved, namespace);
2883
3190
  let perStatementMs;
2884
3191
  const limitReads = async (ms) => {
2885
3192
  perStatementMs = void 0;
@@ -2922,7 +3229,7 @@ var vexGuide = () => [
2922
3229
  ' - A value the query filters with ILIKE is a pattern: "%text%" matches contains.',
2923
3230
  ' - OPTIONAL keys: meta.context marks some keys `optional: true`. Those switch a condition ON \u2014 send the key and it applies, omit it and the condition is not in the query at all (it does not match everything by accident, and omitting it is never an error). A key marked `absent: true` is one you did not send on this run. This is how one fingerprint answers "everyone", "everyone matching a search", and "one by id".',
2924
3231
  "",
2925
- "result \u2014 exactly the requested shape (array, object, or scalar). meta.cache = { hit, fingerprint, replaced? }; meta.missingContext lists REQUIRED context keys you did not send \u2014 the query ran without them, so the result is WRONG. Supply the keys and re-run before trusting it. Optional keys never appear there; leaving one out is a choice, not a mistake.",
3232
+ "result \u2014 exactly the requested shape (array, object, or scalar). meta.cache = { hit, fingerprint, replaced? }; meta.missingContext lists REQUIRED context keys you did not send \u2014 the query did NOT run, and the result is an empty list whatever the shape. Supply the keys and send the request again. Optional keys never appear there; leaving one out is a choice, not a mistake.",
2926
3233
  "",
2927
3234
  "GET on the same URL returns the endpoint's self-description: its entities, the query body contract, and every existing named fingerprint with its intent \u2014 check it before generating a query that may already exist."
2928
3235
  ].join("\n");
@@ -3211,7 +3518,10 @@ var createPostgresCache = (config) => {
3211
3518
  }
3212
3519
  return out;
3213
3520
  };
3214
- return { init, sequence, get, set, delete: del, clear, keys, entries };
3521
+ const touch = async (key, lastUsedAt) => {
3522
+ await pool.query(`UPDATE ${qualified} SET last_used_at = $2 WHERE key = $1`, [key, new Date(lastUsedAt)]);
3523
+ };
3524
+ return { init, sequence, get, set, delete: del, clear, keys, entries, touch };
3215
3525
  };
3216
3526
 
3217
3527
  // src/cache/tiered.ts
@@ -3273,7 +3583,22 @@ var createTieredCache = (config) => {
3273
3583
  fireAndForget(l2.clear(), onError);
3274
3584
  };
3275
3585
  const keys = async () => l1.keys();
3276
- return { init, get, set, delete: del, clear, keys, ...l2.sequence !== void 0 ? { sequence: l2.sequence } : {} };
3586
+ const { touch: touchL1 } = l1;
3587
+ const { touch: touchL2 } = l2;
3588
+ const touch = touchL1 === void 0 || touchL2 === void 0 ? void 0 : async (key, lastUsedAt) => {
3589
+ await touchL1(key, lastUsedAt);
3590
+ fireAndForget(touchL2(key, lastUsedAt), onError);
3591
+ };
3592
+ return {
3593
+ init,
3594
+ get,
3595
+ set,
3596
+ delete: del,
3597
+ clear,
3598
+ keys,
3599
+ ...touch !== void 0 ? { touch } : {},
3600
+ ...l2.sequence !== void 0 ? { sequence: l2.sequence } : {}
3601
+ };
3277
3602
  };
3278
3603
 
3279
3604
  // src/mutations/signature.ts
@@ -3616,18 +3941,11 @@ var assertReturnedColumns = (refs, schema) => {
3616
3941
  }
3617
3942
  };
3618
3943
  var readMatchesFor = (table, policy) => {
3619
- const rule = policy.entities[table];
3620
- if (rule === void 0) {
3621
- if (policy.default === "deny") throw new VexScopeError(table, `A $lookup reads "${table}", which is not allowed by scope policy (default: deny).`);
3622
- return [];
3623
- }
3624
- if ("public" in rule) return [];
3625
- if ("deny" in rule) throw new VexScopeError(table, `A $lookup reads "${table}", which is denied by scope policy.`);
3626
- if (rule.read === void 0) {
3627
- if (policy.default === "deny") throw new VexScopeError(table, `A $lookup reads "${table}", which this principal has no read grant for.`);
3628
- return [];
3629
- }
3630
- return rule.read;
3944
+ const rules = readRulesOf(policy, table);
3945
+ if (rules === "unlisted") throw new VexScopeError(table, `A $lookup reads "${table}", which is not allowed by scope policy (default: deny).`);
3946
+ if (rules === "denied") throw new VexScopeError(table, `A $lookup reads "${table}", which is denied by scope policy.`);
3947
+ if (rules === "ungranted") throw new VexScopeError(table, `A $lookup reads "${table}", which this principal has no read grant for.`);
3948
+ return rules;
3631
3949
  };
3632
3950
  var boundaryOf = (table, r) => isSetMatch(r) ? { in: [`${table}.${r.match}`, { $scope: r.in }] } : { eq: [`${table}.${r.match}`, { $scope: r.to }] };
3633
3951
  var scopeLookups = (cols, policy) => {
@@ -3645,21 +3963,22 @@ var scopeLookups = (cols, policy) => {
3645
3963
  }
3646
3964
  return out;
3647
3965
  };
3648
- var writeGate = (table, op, policy) => {
3966
+ var writeGateOf = (table, op, policy) => {
3649
3967
  const rule = policy.entities[table];
3650
- if (rule === void 0) {
3651
- if (policy.default === "deny") throw new VexScopeError(table, `Writes to "${table}" are not allowed by scope policy (default: deny).`);
3652
- return void 0;
3653
- }
3968
+ if (rule === void 0) return policy.default === "deny" ? "unlisted" : void 0;
3654
3969
  if ("public" in rule) return void 0;
3655
- if ("deny" in rule) throw new VexScopeError(table, `Writes to "${table}" are denied by scope policy.`);
3970
+ if ("deny" in rule) return "denied";
3656
3971
  const specific = op === "insert" ? rule.insert : op === "update" ? rule.update : rule.delete;
3657
- if (rule.write === void 0 && specific === void 0) {
3658
- if (policy.default === "deny") throw new VexScopeError(table, `"${op}" on "${table}" is not allowed by scope policy (default: deny).`);
3659
- return void 0;
3660
- }
3972
+ if (rule.write === void 0 && specific === void 0) return policy.default === "deny" ? "ungranted" : void 0;
3661
3973
  return { rule, rules: [...rule.write ?? [], ...specific ?? []] };
3662
3974
  };
3975
+ var writeGate = (table, op, policy) => {
3976
+ const gate = writeGateOf(table, op, policy);
3977
+ if (gate === "unlisted") throw new VexScopeError(table, `Writes to "${table}" are not allowed by scope policy (default: deny).`);
3978
+ if (gate === "denied") throw new VexScopeError(table, `Writes to "${table}" are denied by scope policy.`);
3979
+ if (gate === "ungranted") throw new VexScopeError(table, `"${op}" on "${table}" is not allowed by scope policy (default: deny).`);
3980
+ return gate;
3981
+ };
3663
3982
  var scopeInsertParts = (table, rawValues, rawConflict, policy) => {
3664
3983
  let values = scopeLookups(rawValues, policy);
3665
3984
  let conflict = rawConflict === void 0 || rawConflict.set === void 0 ? rawConflict : { ...rawConflict, set: scopeLookups(rawConflict.set, policy) };
@@ -3723,12 +4042,13 @@ var itemRow = (element, itemKeys) => {
3723
4042
  const fields = element !== null && typeof element === "object" && !Array.isArray(element) ? element : {};
3724
4043
  return Object.fromEntries(Object.entries(itemKeys).map(([column, key]) => [column, fields[key]]));
3725
4044
  };
3726
- var newCtx = () => ({
4045
+ var newCtx = (namespace) => ({
3727
4046
  resolvedPaths: /* @__PURE__ */ new Map(),
3728
4047
  aliasMap: /* @__PURE__ */ new Map(),
3729
4048
  paramSlots: [],
3730
4049
  paramCounter: { value: 0 },
3731
- returned: /* @__PURE__ */ new Map()
4050
+ returned: /* @__PURE__ */ new Map(),
4051
+ ...namespace !== void 0 ? { namespace } : {}
3732
4052
  });
3733
4053
  var indexFilterFields = (filter, aliasMap) => {
3734
4054
  for (const path of filterColumns(filter)) aliasMap.set(path, path);
@@ -3737,7 +4057,7 @@ var compileValue = (v, ctx) => {
3737
4057
  if (isLookup(v)) {
3738
4058
  indexFilterFields(v.$lookup.where, ctx.aliasMap);
3739
4059
  const where = compileFilter(v.$lookup.where, ctx);
3740
- return `(SELECT ${v.$lookup.field} FROM ${v.$lookup.from} WHERE ${where})`;
4060
+ return `(SELECT ${sqlName(v.$lookup.field)} FROM ${tableSql(v.$lookup.from, ctx.namespace)} WHERE ${where})`;
3741
4061
  }
3742
4062
  if (isReturned(v)) {
3743
4063
  ctx.paramCounter.value += 1;
@@ -3757,37 +4077,84 @@ var compileColumnValue = (table, column, v, ctx, schema) => {
3757
4077
  }
3758
4078
  return sql;
3759
4079
  };
3760
- var compileConflict = (m, ctx, schema) => {
4080
+ var scopeSlot = (r, ctx) => {
4081
+ ctx.paramCounter.value += 1;
4082
+ ctx.paramSlots.push(isSetMatch(r) ? { key: r.in, kind: "scope", type: "string[]" } : { key: r.to, kind: "scope", type: "string" });
4083
+ return isSetMatch(r) ? `= ANY($${ctx.paramCounter.value})` : `= $${ctx.paramCounter.value}`;
4084
+ };
4085
+ var keptChecks = (table, written, pinned, ctx, schema) => pinned.flatMap((rule) => {
4086
+ const value = written.get(rule.match);
4087
+ const type = findEntity2(table, schema)?.fields.find((f) => f.name === rule.match)?.type;
4088
+ if (value === void 0 || type === void 0) return [];
4089
+ return [{ rule, sql: `(${value})::${type} ${scopeSlot(rule, ctx)}` }];
4090
+ });
4091
+ var compileConflict = (m, ctx, schema, pinned) => {
3761
4092
  const c = m.onConflict;
3762
4093
  if (c === void 0) return "";
3763
- if (c.set === void 0) return ` ON CONFLICT (${c.target.join(", ")}) DO NOTHING`;
3764
- const sets = Object.entries(c.set).map(([col, v]) => `${col} = ${compileColumnValue(m.table, col, v, ctx, schema)}`);
3765
- let where = "";
4094
+ const target = c.target.map(sqlName).join(", ");
4095
+ if (c.set === void 0) return ` ON CONFLICT (${target}) DO NOTHING`;
4096
+ const written = new Map(Object.entries(c.set).map(([col, v]) => [col, compileColumnValue(m.table, col, v, ctx, schema)]));
4097
+ const sets = [...written].map(([col, sql]) => `${sqlName(col)} = ${sql}`);
4098
+ const conditions = [];
3766
4099
  if (c.where !== void 0) {
3767
4100
  indexFilterFields(c.where, ctx.aliasMap);
3768
- where = ` WHERE ${compileFilter(c.where, ctx)}`;
4101
+ conditions.push(compileFilter(c.where, ctx));
3769
4102
  }
3770
- return ` ON CONFLICT (${c.target.join(", ")}) DO UPDATE SET ${sets.join(", ")}${where}`;
4103
+ conditions.push(...keptChecks(m.table, written, pinned, ctx, schema).map((k) => k.sql));
4104
+ const where = conditions.length === 0 ? "" : ` WHERE ${conditions.join(" AND ")}`;
4105
+ return ` ON CONFLICT (${target}) DO UPDATE SET ${sets.join(", ")}${where}`;
3771
4106
  };
3772
- var compileMutation = (m, schema) => {
3773
- const ctx = newCtx();
4107
+ var compileMovedCheck = (m, schema, pinned) => {
4108
+ const ctx = newCtx(schema.namespace);
4109
+ const written = new Map(
4110
+ Object.entries(m.set).filter(([c]) => pinned.some((r) => r.match === c)).map(([c, v]) => [c, compileColumnValue(m.table, c, v, ctx, schema)])
4111
+ );
4112
+ const checks = keptChecks(m.table, written, pinned, ctx, schema);
4113
+ if (checks.length === 0) return void 0;
4114
+ indexFilterFields(m.where, ctx.aliasMap);
4115
+ const where = compileFilter(m.where, ctx);
4116
+ const each = checks.map((k, i) => `(${k.sql}) IS TRUE AS "${i}"`).join(", ");
4117
+ const all = checks.map((k) => k.sql).join(" AND ");
4118
+ return {
4119
+ sql: `SELECT ${each} FROM ${tableSql(m.table, schema.namespace)} WHERE ${where} AND (${all}) IS NOT TRUE LIMIT 1`,
4120
+ slots: ctx.paramSlots,
4121
+ returned: ctx.returned,
4122
+ rules: checks.map((k) => k.rule)
4123
+ };
4124
+ };
4125
+ var movedRefusal = (table, rule) => new VexScopeError(
4126
+ table,
4127
+ `This update would move a row of "${table}" out of the caller's update rule { match: "${rule.match}", ${isSetMatch(rule) ? `in: "${rule.in}"` : `to: "${rule.to}"`} }: the new "${table}.${rule.match}" ${isSetMatch(rule) ? `is not one of the scope's "${rule.in}"` : `is not the scope's "${rule.to}"`}. Nothing was written.`
4128
+ );
4129
+ var READABLE = "vex:readable";
4130
+ var returning = (readable, ctx) => {
4131
+ if (readable === "all") return " RETURNING *";
4132
+ if (readable === "none") return ` RETURNING *, FALSE AS "${READABLE}"`;
4133
+ return ` RETURNING *, (${readable.map((r) => `${sqlName(r.match)} ${scopeSlot(r, ctx)}`).join(" AND ")}) AS "${READABLE}"`;
4134
+ };
4135
+ var compileMutation = (m, schema, pinned, readable) => {
4136
+ const ctx = newCtx(schema.namespace);
4137
+ const finish = (head) => {
4138
+ const ownSlots = ctx.paramSlots.length;
4139
+ return { sql: `${head}${returning(readable, ctx)}`, slots: ctx.paramSlots, returned: ctx.returned, ownSlots, marked: readable !== "all" };
4140
+ };
3774
4141
  if (m.op === "insert") {
3775
4142
  const entries = Object.entries(m.values);
3776
- const cols = entries.map(([c]) => c);
4143
+ const cols = entries.map(([c]) => sqlName(c));
3777
4144
  const vals = entries.map(([c, v]) => compileColumnValue(m.table, c, v, ctx, schema));
3778
- return { sql: `INSERT INTO ${m.table} (${cols.join(", ")}) VALUES (${vals.join(", ")})${compileConflict(m, ctx, schema)} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
4145
+ return finish(`INSERT INTO ${tableSql(m.table, schema.namespace)} (${cols.join(", ")}) VALUES (${vals.join(", ")})${compileConflict(m, ctx, schema, pinned)}`);
3779
4146
  }
3780
4147
  if (m.op === "insertEach") {
3781
4148
  const types = new Map(findEntity2(m.table, schema)?.fields.map((f) => [f.name, f.type]));
3782
4149
  const entries = Object.entries(m.values);
3783
- const cols = entries.map(([c]) => c);
4150
+ const cols = entries.map(([c]) => sqlName(c));
3784
4151
  const itemKeys = {};
3785
4152
  const itemColumns = [];
3786
4153
  const exprs = entries.map(([col, v]) => {
3787
4154
  if (isItemRef(v)) {
3788
4155
  itemKeys[col] = v.$item;
3789
- itemColumns.push(`${col} ${String(types.get(col))}`);
3790
- return `item.${col}`;
4156
+ itemColumns.push(`${sqlName(col)} ${String(types.get(col))}`);
4157
+ return `item.${sqlName(col)}`;
3791
4158
  }
3792
4159
  return isReturned(v) ? compileColumnValue(m.table, col, v, ctx, schema) : compileValue(v, ctx);
3793
4160
  });
@@ -3795,32 +4162,31 @@ var compileMutation = (m, schema) => {
3795
4162
  ctx.paramSlots.push({ key: m.items.$context, kind: "context", type: "json" });
3796
4163
  const items = `$${ctx.paramCounter.value}::jsonb`;
3797
4164
  const source = itemColumns.length === 0 ? `jsonb_array_elements(${items}) AS item` : `jsonb_to_recordset(${items}) AS item(${itemColumns.join(", ")})`;
3798
- return {
3799
- sql: `INSERT INTO ${m.table} (${cols.join(", ")}) SELECT ${exprs.join(", ")} FROM ${source}${compileConflict(m, ctx, schema)} RETURNING *`,
3800
- slots: ctx.paramSlots,
3801
- returned: ctx.returned,
3802
- itemKeys
3803
- };
4165
+ return { ...finish(`INSERT INTO ${tableSql(m.table, schema.namespace)} (${cols.join(", ")}) SELECT ${exprs.join(", ")} FROM ${source}${compileConflict(m, ctx, schema, pinned)}`), itemKeys };
3804
4166
  }
3805
4167
  if (m.op === "update") {
3806
- const sets = Object.entries(m.set).map(([c, v]) => `${c} = ${compileColumnValue(m.table, c, v, ctx, schema)}`);
4168
+ const written = new Map(Object.entries(m.set).map(([c, v]) => [c, compileColumnValue(m.table, c, v, ctx, schema)]));
4169
+ const sets = [...written].map(([c, sql]) => `${sqlName(c)} = ${sql}`);
3807
4170
  indexFilterFields(m.where, ctx.aliasMap);
3808
- const where2 = compileFilter(m.where, ctx);
3809
- return { sql: `UPDATE ${m.table} SET ${sets.join(", ")} WHERE ${where2} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
4171
+ const where2 = [compileFilter(m.where, ctx), ...keptChecks(m.table, written, pinned, ctx, schema).map((k) => k.sql)].join(" AND ");
4172
+ return finish(`UPDATE ${tableSql(m.table, schema.namespace)} SET ${sets.join(", ")} WHERE ${where2}`);
3810
4173
  }
3811
4174
  indexFilterFields(m.where, ctx.aliasMap);
3812
4175
  const where = compileFilter(m.where, ctx);
3813
- return { sql: `DELETE FROM ${m.table} WHERE ${where} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
4176
+ return finish(`DELETE FROM ${tableSql(m.table, schema.namespace)} WHERE ${where}`);
3814
4177
  };
4178
+ var keyMadeByDatabase = (m, schema) => !(m.key in m.columns) && !(m.key in (m.insert ?? {})) && findEntity2(m.table, schema)?.fields.find((f) => f.name === m.key)?.defaultValue !== void 0;
3815
4179
  var SUGAR = {
3816
- upsert: (m, context) => {
3817
- const keyed = context[m.key] !== void 0 && context[m.key] !== "";
4180
+ // Where the database does not make the key, inserting on a null one would break its NOT NULL.
4181
+ upsert: (m, context, schema) => {
4182
+ const value = context[m.key];
4183
+ const keyed = value !== void 0 && value !== "" && (value !== null || !keyMadeByDatabase(m, schema));
3818
4184
  return keyed ? { op: "update", table: m.table, set: m.columns, where: { eq: [`${m.table}.${m.key}`, { $context: m.key }] } } : { op: "insert", table: m.table, values: { ...m.columns, ...m.insert } };
3819
4185
  }
3820
4186
  };
3821
- var desugarMutation = (m, context) => {
4187
+ var desugarMutation = (m, context, schema) => {
3822
4188
  const rewrite = SUGAR[m.op];
3823
- return rewrite === void 0 ? m : rewrite(m, context);
4189
+ return rewrite === void 0 ? m : rewrite(m, context, schema);
3824
4190
  };
3825
4191
  var mutationMisfits = (def, schema) => {
3826
4192
  const reasons = [];
@@ -3828,7 +4194,7 @@ var mutationMisfits = (def, schema) => {
3828
4194
  for (const [at, entry] of list.entries()) {
3829
4195
  const asked = [
3830
4196
  // keyed, an upsert is an update; unkeyed, an insert
3831
- ...(entry.op === "upsert" ? [{ [entry.key]: 0 }, {}] : [{}]).map((context) => () => assertWritableColumns(desugarMutation(entry, context), schema)),
4197
+ ...(entry.op === "upsert" ? [{ [entry.key]: 0 }, {}] : [{}]).map((context) => () => assertWritableColumns(desugarMutation(entry, context, schema), schema)),
3832
4198
  () => assertReturnedColumns(returnedIn(list, at).refs, schema)
3833
4199
  ];
3834
4200
  for (const ask of asked) {
@@ -3841,10 +4207,22 @@ var mutationMisfits = (def, schema) => {
3841
4207
  }
3842
4208
  return reasons;
3843
4209
  };
4210
+ var pinnedRules = (m, policy) => {
4211
+ const updates = m.op === "update" || m.op !== "delete" && m.onConflict?.set !== void 0;
4212
+ const gate = updates ? writeGateOf(m.table, "update", policy) : void 0;
4213
+ if (gate === void 0 || typeof gate === "string") return [];
4214
+ const stamped = new Set(gate.rules.flatMap((r) => "set" in r ? [r.set] : []));
4215
+ return gate.rules.flatMap((r) => "match" in r && !stamped.has(r.match) ? [r] : []);
4216
+ };
4217
+ var readableRules = (m, policy) => {
4218
+ if ((m.op === "insert" || m.op === "insertEach") && m.onConflict?.set === void 0) return "all";
4219
+ const rules = readRulesOf(policy, m.table);
4220
+ return typeof rules === "string" ? "none" : rules.length === 0 ? "all" : rules;
4221
+ };
3844
4222
  var executeWrites = async (client, def, mctx) => {
3845
4223
  const parsed = MutationDefinitionSchema.parse(def);
3846
4224
  const entries = Array.isArray(parsed) ? parsed : [parsed];
3847
- const cores = entries.map((entry) => desugarMutation(entry, mctx.context));
4225
+ const cores = entries.map((entry) => desugarMutation(entry, mctx.context, mctx.schema));
3848
4226
  const compiled = cores.map((core, at) => {
3849
4227
  const missing = requiredContextKeys(core).filter((k) => mctx.context[k] === void 0);
3850
4228
  if (missing.length > 0) {
@@ -3857,45 +4235,70 @@ var executeWrites = async (client, def, mctx) => {
3857
4235
  const m = scopeMutation(core, mctx.policy);
3858
4236
  assertWritableColumns(m, mctx.schema);
3859
4237
  assertReturnedColumns(returned.refs, mctx.schema);
3860
- const statement = compileMutation(m, mctx.schema);
3861
- requireScope({ paramSlots: statement.slots }, mctx.scope);
3862
- const reads = [...statement.returned].map(([slot, ref]) => {
4238
+ const pinned = mctx.checkMovedRows === false ? [] : pinnedRules(m, mctx.policy);
4239
+ const statement = compileMutation(m, mctx.schema, pinned, mctx.answerReadableRows === true ? readableRules(m, mctx.policy) : "all");
4240
+ requireScope({ paramSlots: statement.slots.slice(0, statement.ownSlots) }, mctx.scope);
4241
+ const readsOf = (of) => [...of.returned].map(([slot, ref]) => {
3863
4242
  const source = returned.refs.get(ref);
3864
4243
  if (source === void 0) throw new VexError("invalid_dsl", `"${ref}" names no earlier statement of the batch.`);
3865
4244
  return { slot, ref, source };
3866
4245
  });
3867
- return { ...statement, reads, table: m.table, op: m.op === "insertEach" ? "insert" : m.op };
4246
+ const moved = m.op === "update" ? compileMovedCheck(m, mctx.schema, pinned) : void 0;
4247
+ return {
4248
+ ...statement,
4249
+ reads: readsOf(statement),
4250
+ ...moved === void 0 ? {} : { moved: { ...moved, reads: readsOf(moved) } },
4251
+ table: m.table,
4252
+ op: m.op === "insertEach" ? "insert" : m.op
4253
+ };
3868
4254
  });
4255
+ const bindParams = async (c, results) => {
4256
+ const params = await resolveParams(c.slots, mctx.context, mctx.scope);
4257
+ for (const read of c.reads) {
4258
+ const rows = results[read.source.statement]?.rows ?? [];
4259
+ const row = rows[0];
4260
+ if (rows.length !== 1 || row === void 0) {
4261
+ throw new VexError(
4262
+ "execution_error",
4263
+ `"${read.ref}" needs exactly one row from statement ${read.source.statement + 1} of the batch, which wrote ${rows.length}. Nothing was written.`,
4264
+ { returned: read.ref, rows: rows.length }
4265
+ );
4266
+ }
4267
+ if (!(read.source.column in row)) {
4268
+ throw new VexError("execution_error", `"${read.ref}": the row statement ${read.source.statement + 1} returned has no "${read.source.column}" key. Nothing was written.`, { returned: read.ref });
4269
+ }
4270
+ params[read.slot] = row[read.source.column];
4271
+ }
4272
+ return params.map((value, i) => {
4273
+ if (c.slots[i]?.encode === "json") return value !== null && typeof value === "object" ? JSON.stringify(value) : value;
4274
+ if (c.slots[i]?.type !== "json") return value;
4275
+ if (!Array.isArray(value)) {
4276
+ throw new VexError("invalid_request", `"${c.slots[i]?.key ?? ""}" must be an array of objects (one inserted row per element).`);
4277
+ }
4278
+ const { itemKeys } = c;
4279
+ return JSON.stringify(itemKeys === void 0 ? value : value.map((element) => itemRow(element, itemKeys)));
4280
+ });
4281
+ };
3869
4282
  const runAll = async (q) => {
3870
4283
  const results = [];
3871
4284
  for (const c of compiled) {
3872
- const params = await resolveParams(c.slots, mctx.context, mctx.scope);
3873
- for (const read of c.reads) {
3874
- const rows = results[read.source.statement]?.rows ?? [];
3875
- const row = rows[0];
3876
- if (rows.length !== 1 || row === void 0) {
3877
- throw new VexError(
3878
- "execution_error",
3879
- `"${read.ref}" needs exactly one row from statement ${read.source.statement + 1} of the batch, which wrote ${rows.length}. Nothing was written.`,
3880
- { returned: read.ref, rows: rows.length }
3881
- );
3882
- }
3883
- if (!(read.source.column in row)) {
3884
- throw new VexError("execution_error", `"${read.ref}": the row statement ${read.source.statement + 1} returned has no "${read.source.column}" key. Nothing was written.`, { returned: read.ref });
3885
- }
3886
- params[read.slot] = row[read.source.column];
4285
+ if (c.moved !== void 0) {
4286
+ const [row] = (await q.query(c.moved.sql, await bindParams(c.moved, results))).rows;
4287
+ const broken = row === void 0 ? void 0 : c.moved.rules.find((_, i) => row[String(i)] !== true);
4288
+ if (broken !== void 0) throw movedRefusal(c.table, broken);
3887
4289
  }
3888
- const bound = params.map((value, i) => {
3889
- if (c.slots[i]?.encode === "json") return value !== null && typeof value === "object" ? JSON.stringify(value) : value;
3890
- if (c.slots[i]?.type !== "json") return value;
3891
- if (!Array.isArray(value)) {
3892
- throw new VexError("invalid_request", `"${c.slots[i]?.key ?? ""}" must be an array of objects (one inserted row per element).`);
3893
- }
3894
- const { itemKeys } = c;
3895
- return JSON.stringify(itemKeys === void 0 ? value : value.map((element) => itemRow(element, itemKeys)));
3896
- });
3897
- const res = await q.query(c.sql, bound);
3898
- results.push({ table: c.table, op: c.op, rows: res.rows });
4290
+ const res = await q.query(c.sql, await bindParams(c, results));
4291
+ if (!c.marked) {
4292
+ results.push({ table: c.table, op: c.op, rows: res.rows });
4293
+ continue;
4294
+ }
4295
+ const rows = [];
4296
+ const readable = [];
4297
+ for (const { [READABLE]: seen, ...row } of res.rows) {
4298
+ rows.push(row);
4299
+ if (seen === true) readable.push(row);
4300
+ }
4301
+ results.push({ table: c.table, op: c.op, rows, readable });
3899
4302
  }
3900
4303
  return results;
3901
4304
  };
@@ -3929,40 +4332,39 @@ var filterSchema = (schema, entities) => {
3929
4332
  if (entities === void 0 || entities.length === 0) return schema.entities;
3930
4333
  return schema.entities.filter((e) => entities.includes(e.name));
3931
4334
  };
3932
- var canWriteTable = (policy, table, op) => {
3933
- const rule = policy.entities[table];
3934
- if (rule === void 0) return policy.default === "allow";
3935
- if ("public" in rule) return true;
3936
- if ("deny" in rule) return false;
3937
- if (rule.write !== void 0 || policy.default === "allow") return true;
3938
- if (op === "insert" || op === "insertEach") return rule.insert !== void 0;
3939
- if (op === "update") return rule.update !== void 0;
3940
- if (op === "delete") return rule.delete !== void 0;
3941
- if (op === "upsert") return rule.insert !== void 0 || rule.update !== void 0;
3942
- return false;
4335
+ var WRITES_OF = {
4336
+ insert: ["insert"],
4337
+ insertEach: ["insert"],
4338
+ update: ["update"],
4339
+ delete: ["delete"],
4340
+ upsert: ["insert", "update"]
3943
4341
  };
3944
- var collectTables = (dsl) => {
3945
- const out = [];
3946
- const walk = (q) => {
3947
- for (const src of q.from) {
3948
- if (typeof src === "string") out.push(src);
3949
- else walk(src.query);
3950
- }
3951
- };
3952
- walk(dsl);
3953
- return out;
4342
+ var canWriteTable = (policy, table, op) => WRITES_OF[op].some((write) => typeof writeGateOf(table, write, policy) !== "string");
4343
+ var tablesRead = (dsl) => {
4344
+ try {
4345
+ return [...discoverEntities(pruneOptional(dsl, "all"))];
4346
+ } catch (err) {
4347
+ if (isVexError(err)) return void 0;
4348
+ throw err;
4349
+ }
3954
4350
  };
3955
- var entryVisible = (policy, entry) => {
3956
- if (entry.kind === "ok") return collectTables(entry.dsl).every((t) => canReadTable(policy, t));
3957
- if (entry.kind === "mutation") return mutationEffect(entry.mutation).every((e) => canWriteTable(policy, e.table, e.op));
4351
+ var entryVisible = (policies, entry) => {
4352
+ if (entry.kind === "ok") {
4353
+ const { read } = policies;
4354
+ return read === void 0 || (tablesRead(entry.dsl)?.every((t) => canReadTable(read, t)) ?? false);
4355
+ }
4356
+ if (entry.kind === "mutation") {
4357
+ const { write } = policies;
4358
+ return write === void 0 || mutationEffect(entry.mutation).every((e) => canWriteTable(write, e.table, e.op));
4359
+ }
3958
4360
  return false;
3959
4361
  };
3960
- var listFingerprints = async (engine, policy) => {
4362
+ var listFingerprints = async (engine, policies) => {
3961
4363
  if (engine.cache.entries === void 0) return [];
3962
4364
  const schema = engine.getSchema();
3963
4365
  const current = schema !== void 0 ? computeSchemaFingerprint(schema) : void 0;
3964
4366
  const rows = await engine.cache.entries();
3965
- return rows.filter(({ key, entry }) => (entry.kind === "ok" || entry.kind === "mutation") && !key.startsWith("neg:")).filter(({ entry }) => policy === void 0 || entryVisible(policy, entry)).map(({ key, entry }) => ({
4367
+ return rows.filter(({ key, entry }) => (entry.kind === "ok" || entry.kind === "mutation") && !key.startsWith("neg:")).filter(({ entry }) => entryVisible(policies, entry)).map(({ key, entry }) => ({
3966
4368
  fingerprint: key,
3967
4369
  kind: entry.kind === "mutation" ? "mutation" : "query",
3968
4370
  protected: entry.protected === true,
@@ -3980,11 +4382,12 @@ var listFingerprints = async (engine, policy) => {
3980
4382
  }));
3981
4383
  };
3982
4384
  var handleDiscovery = async (config) => {
3983
- const { engine, entities: entityFilter, scopePolicy } = config;
4385
+ const { engine, entities: entityFilter } = config;
4386
+ const scopePolicy = config.scopePolicy ?? engine.scopePolicy;
3984
4387
  const filtered = filterSchema(engine.getSchema(), entityFilter).filter(
3985
4388
  (e) => scopePolicy === void 0 || canReadTable(scopePolicy, e.name)
3986
4389
  );
3987
- const fingerprints = await listFingerprints(engine, scopePolicy);
4390
+ const fingerprints = await listFingerprints(engine, { read: scopePolicy, write: config.mutations?.policy ?? scopePolicy });
3988
4391
  const protectedCount = fingerprints.filter((f) => f.protected).length;
3989
4392
  return {
3990
4393
  protection: protectedCount === 0 ? "none" : protectedCount === fingerprints.length ? "all" : "some",
@@ -4062,10 +4465,29 @@ var handleQuery = async (config, body, scope, live) => {
4062
4465
  return result;
4063
4466
  };
4064
4467
  var elapsedClock = () => typeof performance !== "undefined" ? performance.now() : Date.now();
4468
+ var policyAtReach = async (config, fingerprint, reach) => {
4469
+ if (config.policyForReach === void 0) {
4470
+ return {
4471
+ status: 500,
4472
+ body: {
4473
+ error: "execution_error",
4474
+ message: `Entry "${fingerprint}" requires reach "${reach}" and this handler has no policyForReach.`
4475
+ }
4476
+ };
4477
+ }
4478
+ const narrowed = await config.policyForReach(reach);
4479
+ if (narrowed === void 0) {
4480
+ return {
4481
+ status: 403,
4482
+ body: { error: "scope_denied", message: `Reach "${reach}" is not available to this principal.` }
4483
+ };
4484
+ }
4485
+ return narrowed;
4486
+ };
4065
4487
  var runQuery = async (config, body, scope, probe, live) => {
4066
4488
  const { engine } = config;
4067
4489
  if (strata.exceedsDepth(body)) return { status: 400, body: { error: "invalid_request", message: strata.depthRefusal() } };
4068
- const parsed = QueryRequestSchema.safeParse(body);
4490
+ const parsed = QueryRequestSchema.safeParse(dropNullIntentAndFingerprint(body));
4069
4491
  if (!parsed.success) {
4070
4492
  return {
4071
4493
  status: 400,
@@ -4109,31 +4531,19 @@ var runQuery = async (config, body, scope, probe, live) => {
4109
4531
  }
4110
4532
  let writePolicy = config.mutations.policy;
4111
4533
  if (entry.reach !== void 0) {
4112
- if (config.policyForReach === void 0) {
4113
- return {
4114
- status: 500,
4115
- body: {
4116
- error: "execution_error",
4117
- message: `Entry "${parsed.data.fingerprint ?? ""}" requires reach "${entry.reach}" and this handler has no policyForReach.`
4118
- }
4119
- };
4120
- }
4121
- const narrowed = await config.policyForReach(entry.reach);
4122
- if (narrowed === void 0) {
4123
- return {
4124
- status: 403,
4125
- body: { error: "scope_denied", message: `Reach "${entry.reach}" is not available to this principal.` }
4126
- };
4127
- }
4128
- writePolicy = narrowed;
4534
+ const reached = await policyAtReach(config, parsed.data.fingerprint, entry.reach);
4535
+ if ("status" in reached) return reached;
4536
+ writePolicy = reached;
4129
4537
  }
4130
4538
  const writes = await executeWrites(config.mutations.client, entry.mutation, {
4131
4539
  context: parsed.data.context,
4132
4540
  scope,
4133
4541
  policy: writePolicy,
4134
- schema
4542
+ schema,
4543
+ ...config.mutations.checkMovedRows !== void 0 ? { checkMovedRows: config.mutations.checkMovedRows } : {},
4544
+ ...config.mutations.answerReadableRows === true ? { answerReadableRows: true } : {}
4135
4545
  });
4136
- const rows = writes.flatMap((w) => w.rows);
4546
+ const rows = writes.flatMap((w) => w.readable ?? w.rows);
4137
4547
  engine.invalidate(tablesChangedBy(writes, schema));
4138
4548
  if (config.mutations.onWrite !== void 0) {
4139
4549
  try {
@@ -4143,35 +4553,23 @@ var runQuery = async (config, body, scope, probe, live) => {
4143
4553
  }
4144
4554
  }
4145
4555
  const now = Date.now();
4146
- if (isTouchDue(entry, now)) fireAndForget(engine.cache.set(parsed.data.fingerprint, { ...entry, lastUsedAt: now }));
4556
+ if (isTouchDue(entry, now)) fireAndForget(touchEntry(engine.cache, parsed.data.fingerprint, entry, now));
4147
4557
  if (probe !== void 0) probe.rows = rows.length;
4148
4558
  return { status: 200, body: { result: rows.length === 1 ? rows[0] : rows } };
4149
4559
  }
4150
4560
  }
4151
4561
  let readPolicy = config.scopePolicy;
4152
4562
  if (entryReach !== void 0) {
4153
- if (config.policyForReach === void 0) {
4154
- return {
4155
- status: 500,
4156
- body: {
4157
- error: "execution_error",
4158
- message: `Entry "${parsed.data.fingerprint ?? ""}" requires reach "${entryReach}" and this handler has no policyForReach.`
4159
- }
4160
- };
4161
- }
4162
- readPolicy = await config.policyForReach(entryReach);
4163
- if (readPolicy === void 0) {
4164
- return {
4165
- status: 403,
4166
- body: { error: "scope_denied", message: `Reach "${entryReach}" is not available to this principal.` }
4167
- };
4168
- }
4563
+ const reached = await policyAtReach(config, parsed.data.fingerprint ?? "", entryReach);
4564
+ if ("status" in reached) return reached;
4565
+ readPolicy = reached;
4169
4566
  }
4170
4567
  const response = await engine.execute(parsed.data, {
4171
4568
  scope,
4172
4569
  entities: config.entities,
4173
4570
  ...config.locked === true ? { locked: true } : {},
4174
4571
  ...readPolicy !== void 0 ? { scopePolicy: readPolicy } : {},
4572
+ ...entryReach !== void 0 ? { policyForReach: () => readPolicy } : {},
4175
4573
  ...live !== void 0 ? { signal: live.signal, onChange: live.onChange } : {}
4176
4574
  });
4177
4575
  if (probe !== void 0) {
@@ -4196,20 +4594,29 @@ var runQuery = async (config, body, scope, probe, live) => {
4196
4594
  }
4197
4595
  };
4198
4596
  }
4199
- console.error("[vex] unhandled error:", err);
4200
4597
  const errObj = err;
4201
4598
  const message = err instanceof Error ? err.message : typeof errObj?.message === "string" ? errObj.message : "Unknown error";
4202
4599
  const code = typeof errObj?.code === "string" ? errObj.code : "execution_error";
4600
+ const sql = typeof errObj?.query === "string" ? ` in: ${errObj.query}` : "";
4601
+ console.error(`[vex] unhandled error ${code}${sql}`, err instanceof Error && err.stack !== void 0 ? err.stack : message);
4203
4602
  return {
4204
4603
  status: 500,
4205
4604
  body: { error: code, message }
4206
4605
  };
4207
4606
  }
4208
4607
  };
4209
- var handleFingerprintPatch = async (config, fingerprint, patch) => {
4608
+ var managementRefusal = (config) => {
4210
4609
  if (config.locked === true) {
4211
4610
  return { status: 403, body: { error: "locked", message: "This endpoint is locked \u2014 fingerprints cannot be managed here." } };
4212
4611
  }
4612
+ if (config.manageFingerprints === false) {
4613
+ return { status: 403, body: { error: "locked", message: "Fingerprint management is off on this endpoint." } };
4614
+ }
4615
+ return void 0;
4616
+ };
4617
+ var handleFingerprintPatch = async (config, fingerprint, patch) => {
4618
+ const refused = managementRefusal(config);
4619
+ if (refused !== void 0) return refused;
4213
4620
  const entry = await config.engine.cache.get(fingerprint);
4214
4621
  if (entry === void 0 || entry.kind !== "ok" && entry.kind !== "mutation") {
4215
4622
  return { status: 404, body: { error: "cache_miss", message: `Unknown fingerprint "${fingerprint}"` } };
@@ -4221,9 +4628,8 @@ var handleFingerprintPatch = async (config, fingerprint, patch) => {
4221
4628
  return { status: 200, body: { fingerprint, protected: patch.protected } };
4222
4629
  };
4223
4630
  var handleFingerprintDelete = async (config, fingerprint) => {
4224
- if (config.locked === true) {
4225
- return { status: 403, body: { error: "locked", message: "This endpoint is locked \u2014 fingerprints cannot be managed here." } };
4226
- }
4631
+ const refused = managementRefusal(config);
4632
+ if (refused !== void 0) return refused;
4227
4633
  const entry = await config.engine.cache.get(fingerprint);
4228
4634
  if (entry === void 0) {
4229
4635
  return { status: 404, body: { error: "cache_miss", message: `Unknown fingerprint "${fingerprint}"` } };
@@ -4244,6 +4650,8 @@ exports.QueryRequestSchema = QueryRequestSchema;
4244
4650
  exports.QuerySchema = QuerySchema;
4245
4651
  exports.REFRESH_MODES = REFRESH_MODES;
4246
4652
  exports.SCOPE_VERBS = SCOPE_VERBS;
4653
+ exports.UNREADABLE_MODES = UNREADABLE_MODES;
4654
+ exports.UpgradedColumnsSchema = UpgradedColumnsSchema;
4247
4655
  exports.VexError = VexError;
4248
4656
  exports.VexScopeError = VexScopeError;
4249
4657
  exports.analyze = analyze;