@niscorp/vex 0.4.5 → 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 +78 -0
  2. package/DESIGN.md +72 -45
  3. package/DOCS.md +130 -21
  4. package/README.md +17 -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-O6XslV-S.d.ts → handler-DdfaWN_J.d.ts} +7 -1
  28. package/dist/{handler-CB0BqKsY.d.cts → handler-kvZkxwaN.d.cts} +7 -1
  29. package/dist/index.cjs +493 -232
  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 +118 -221
  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-BmHuPfPS.d.cts → types-BxkRxTTx.d.cts} +5 -0
  38. package/dist/{types-D5CCaqcd.d.ts → types-DgUZNKii.d.ts} +5 -0
  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;
@@ -1877,6 +1901,12 @@ var DEFAULT_MAX_LIMIT = 1e3;
1877
1901
  var DEFAULT_STATEMENT_TIMEOUT_MS = 1e4;
1878
1902
  var DEFAULT_UNSATISFIABLE_TTL_MS = 3e5;
1879
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
+ };
1880
1910
  var createQueryEngine = (engineConfig) => {
1881
1911
  const { adapter, scope: scopePolicy, generateDsl, mapToShape, embed, behaviors, upgrader } = engineConfig;
1882
1912
  const parsedColumns = UpgradedColumnsSchema.safeParse(engineConfig.upgradedColumns ?? {});
@@ -1918,6 +1948,7 @@ var createQueryEngine = (engineConfig) => {
1918
1948
  if (seen === void 0) {
1919
1949
  seen = /* @__PURE__ */ new Set();
1920
1950
  variantsSeen.set(fingerprint, seen);
1951
+ forgetOldest(variantsSeen);
1921
1952
  }
1922
1953
  if (seen.has(signature)) return;
1923
1954
  seen.add(signature);
@@ -1986,12 +2017,27 @@ var createQueryEngine = (engineConfig) => {
1986
2017
  return { compiled, warnings: analysis.warnings, upgrades: columnUpgrades(processedDsl, upgradedColumns), ...engineLimit !== void 0 ? { engineLimit } : {} };
1987
2018
  };
1988
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
+ };
1989
2034
  const cutNote = (engineLimit, stated, rowCount, shape, fingerprint) => {
1990
2035
  if (engineLimit === void 0 || rowCount !== engineLimit) return void 0;
1991
2036
  if (shape !== void 0 && !Array.isArray(shape)) return void 0;
1992
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.`;
1993
2038
  if (fingerprint !== void 0 && !cutSaid.has(fingerprint)) {
1994
2039
  cutSaid.add(fingerprint);
2040
+ forgetOldest(cutSaid);
1995
2041
  console.warn(`[vex] "${fingerprint}": ${note}`);
1996
2042
  }
1997
2043
  return note;
@@ -2018,7 +2064,7 @@ var createQueryEngine = (engineConfig) => {
2018
2064
  };
2019
2065
  const touch = (key, entry) => {
2020
2066
  const now = Date.now();
2021
- if (isTouchDue(entry, now)) fireAndForget(cache.set(key, { ...entry, lastUsedAt: now }));
2067
+ if (isTouchDue(entry, now)) fireAndForget(touchEntry(cache, key, entry, now));
2022
2068
  };
2023
2069
  const resolveFingerprint = async (validRequest, hasRequest, requestHash, scope) => {
2024
2070
  const fp = validRequest.fingerprint;
@@ -2042,6 +2088,7 @@ var createQueryEngine = (engineConfig) => {
2042
2088
  ...entry.intent !== void 0 ? { intent: entry.intent } : {},
2043
2089
  ...entry.shape !== void 0 ? { shape: entry.shape } : {},
2044
2090
  ...entry.refresh !== void 0 ? { refresh: entry.refresh } : {},
2091
+ ...entry.reach !== void 0 ? { reach: entry.reach } : {},
2045
2092
  seeded: entry.protected === true && entry.requestHash === void 0,
2046
2093
  hit: true,
2047
2094
  replaced: false
@@ -2066,7 +2113,7 @@ var createQueryEngine = (engineConfig) => {
2066
2113
  const pruned = pruneOptional(dsl, "all");
2067
2114
  const { compiled, warnings, upgrades } = runPipeline(pruned, policy);
2068
2115
  requireScope(compiled, scope);
2069
- if (compiled.paramSlots.some((slot) => slot.kind === "semantic")) {
2116
+ if (compiled.paramSlots.some((slot) => slot.kind === "semantic" || slot.embed === true)) {
2070
2117
  return { rows: [], sql: compiled.sql, warnings: [...warnings, "Semantic params present \u2014 execution skipped, SQL structure validated only"] };
2071
2118
  }
2072
2119
  const params = compiled.paramSlots.map((slot) => slot.kind === "scope" ? scope[slot.key] : null);
@@ -2152,13 +2199,13 @@ var createQueryEngine = (engineConfig) => {
2152
2199
  };
2153
2200
  const execute = async (request, options) => {
2154
2201
  if (strata.exceedsDepth(request)) throw new VexError("invalid_request", `Invalid request: ${strata.depthRefusal()}`);
2155
- const parsed = QueryRequestSchema.safeParse(request);
2202
+ const parsed = QueryRequestSchema.safeParse(dropNullIntentAndFingerprint(request));
2156
2203
  if (!parsed.success) {
2157
2204
  throw new VexError("invalid_request", `Invalid request: ${parsed.error.message}`);
2158
2205
  }
2159
2206
  const validRequest = parsed.data;
2160
2207
  const scope = options?.scope ?? {};
2161
- const activePolicy = options?.scopePolicy ?? scopePolicy;
2208
+ let activePolicy = options?.scopePolicy ?? scopePolicy;
2162
2209
  const t0 = Date.now();
2163
2210
  const hasRequest = validRequest.shape !== void 0 && validRequest.shape !== null;
2164
2211
  if (validRequest.fingerprint === void 0 && !hasRequest) {
@@ -2176,6 +2223,7 @@ var createQueryEngine = (engineConfig) => {
2176
2223
  });
2177
2224
  const cached = await resolveFingerprint(validRequest, hasRequest, requestHash, scope);
2178
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);
2179
2227
  let dsl = cached.dsl;
2180
2228
  let agentMs;
2181
2229
  if (dsl === void 0) {
@@ -2321,6 +2369,7 @@ var createQueryEngine = (engineConfig) => {
2321
2369
  getDslSchema,
2322
2370
  getSchema,
2323
2371
  cache,
2372
+ ...scopePolicy !== void 0 ? { scopePolicy } : {},
2324
2373
  invalidate: live.invalidate,
2325
2374
  rows: { stats: live.stats, stop: live.stop }
2326
2375
  };
@@ -2368,6 +2417,8 @@ var COLUMNS_QUERY = `
2368
2417
  c.udt_name,
2369
2418
  c.is_nullable,
2370
2419
  c.column_default,
2420
+ c.is_identity,
2421
+ c.identity_generation,
2371
2422
  CASE
2372
2423
  WHEN c.data_type = 'USER-DEFINED' THEN c.udt_name
2373
2424
  WHEN c.data_type = 'ARRAY' THEN c.udt_name
@@ -2487,7 +2538,7 @@ var introspectPostgres = async (pool, options) => {
2487
2538
  const dataType = row["effective_type"];
2488
2539
  const fullType = row["full_type"];
2489
2540
  const isNullable = row["is_nullable"];
2490
- const colDefault = row["column_default"];
2541
+ const colDefault = row["column_default"] ?? (row["is_identity"] === "YES" ? `GENERATED ${String(row["identity_generation"])} AS IDENTITY` : null);
2491
2542
  const colDescription = row["description"];
2492
2543
  const tablePks = pkMap.get(table);
2493
2544
  const isPk = tablePks !== void 0 && tablePks.has(colName);
@@ -2605,15 +2656,125 @@ var quoteLiteral = (s) => {
2605
2656
  return s.includes("\\") ? `E'${doubled.replace(/\\/g, "\\\\")}'` : `'${doubled}'`;
2606
2657
  };
2607
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)}`;
2608
2766
  var numberLiteral = (n) => {
2609
2767
  if (!Number.isFinite(n)) throw new VexError("invalid_dsl", `${String(n)} is not a number SQL can hold.`);
2610
2768
  return String(n);
2611
2769
  };
2612
2770
  var columnOf = (path, ctx) => {
2613
2771
  const mapped = ctx.aliasMap.get(path);
2614
- 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
+ }
2615
2776
  const res = ctx.resolvedPaths.get(path);
2616
- if (res !== void 0) return `${res.alias}.${res.column}`;
2777
+ if (res !== void 0) return columnSql(res.alias, res.column);
2617
2778
  throw new VexError("invalid_dsl", `"${path}" is not a column this query reads.`);
2618
2779
  };
2619
2780
  var isFieldPath2 = isFieldPathShape;
@@ -2663,7 +2824,7 @@ var compileJoinPairs = (join) => join.fromColumns.map((column, i) => {
2663
2824
  `The join from "${join.fromAlias}" to "${join.toAlias}" pairs "${column}" with no column.`
2664
2825
  );
2665
2826
  }
2666
- return `${join.fromAlias}.${column} = ${join.toAlias}.${to}`;
2827
+ return `${columnSql(join.fromAlias, column)} = ${columnSql(join.toAlias, to)}`;
2667
2828
  });
2668
2829
  var compileComparisonFilter = (op, pair, ctx) => {
2669
2830
  const left = compileFieldOrValue(pair[0], ctx);
@@ -2682,7 +2843,7 @@ var compileFilter = (filter, ctx) => {
2682
2843
  };
2683
2844
  const parts = ["SELECT 1"];
2684
2845
  const first = resolved.sources[0];
2685
- 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)}`);
2686
2847
  for (const join of resolved.joins) {
2687
2848
  const source = resolved.sources.find((s) => s.alias === join.toAlias);
2688
2849
  if (source?.table === void 0) continue;
@@ -2691,7 +2852,7 @@ var compileFilter = (filter, ctx) => {
2691
2852
  ...compileJoinPairs(join),
2692
2853
  ...(join.on ?? []).map((extra) => compileFilter(extra.original, inner))
2693
2854
  ];
2694
- 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 ")}`);
2695
2856
  }
2696
2857
  if (resolved.filter !== void 0) parts.push(`WHERE ${compileFilter(resolved.filter.original, inner)}`);
2697
2858
  return `EXISTS (${parts.join(" ")})`;
@@ -2774,17 +2935,13 @@ var compileFilter = (filter, ctx) => {
2774
2935
  const fieldPath2 = filter.semantic.field;
2775
2936
  const col = columnOf(fieldPath2, ctx);
2776
2937
  const queryRef = filter.semantic.query;
2777
- const key = "$context" in queryRef ? queryRef.$context : queryRef.$scope;
2778
2938
  if ("$context" in queryRef) assertNotReserved(queryRef.$context);
2779
2939
  const res = ctx.resolvedPaths.get(fieldPath2);
2780
2940
  const dimensions = res?.schema.vectorDimensions;
2781
2941
  ctx.paramCounter.value += 1;
2782
- ctx.paramSlots.push({
2783
- key,
2784
- kind: "semantic",
2785
- type: "string",
2786
- dimensions
2787
- });
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
+ );
2788
2945
  const paramRef = `$${ctx.paramCounter.value}`;
2789
2946
  const minScore = numberLiteral(filter.semantic.minScore ?? 0);
2790
2947
  return `1 - (${col} <=> ${paramRef}) >= ${minScore}`;
@@ -2862,22 +3019,23 @@ var compileAggregate = (expr, ctx) => {
2862
3019
  };
2863
3020
 
2864
3021
  // src/adapters/postgres/compile.ts
2865
- var compileQuery = (resolved) => {
3022
+ var compileQuery = (resolved, namespace) => {
2866
3023
  const paramSlots = [];
2867
- const sql = compileLevel(resolved, paramSlots, { value: 0 });
3024
+ const sql = compileLevel(resolved, paramSlots, { value: 0 }, namespace);
2868
3025
  const contextContract = {};
2869
3026
  for (const slot of paramSlots) {
2870
3027
  contextContract[slot.key] = { type: slot.type, kind: slot.kind };
2871
3028
  }
2872
3029
  return { sql, paramSlots, contextContract };
2873
3030
  };
2874
- var compileLevel = (resolved, paramSlots, paramCounter) => {
3031
+ var compileLevel = (resolved, paramSlots, paramCounter, namespace) => {
2875
3032
  const ctx = {
2876
3033
  resolvedPaths: resolved.filter?.resolvedPaths ?? /* @__PURE__ */ new Map(),
2877
3034
  aliasMap: resolved.aliasMap,
2878
3035
  paramSlots,
2879
3036
  paramCounter,
2880
- ...resolved.existsMap !== void 0 ? { existsMap: resolved.existsMap } : {}
3037
+ ...resolved.existsMap !== void 0 ? { existsMap: resolved.existsMap } : {},
3038
+ ...namespace !== void 0 ? { namespace } : {}
2881
3039
  };
2882
3040
  const sqlParts = [];
2883
3041
  const selectParts = [];
@@ -2885,7 +3043,7 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2885
3043
  selectParts.push("DISTINCT");
2886
3044
  }
2887
3045
  const fieldColumns = resolved.fields.map(
2888
- (f) => `${f.alias}.${f.column} AS ${quoteIdent(f.outputName)}`
3046
+ (f) => `${columnSql(f.alias, f.column)} AS ${quoteIdent(f.outputName)}`
2889
3047
  );
2890
3048
  const computeColumns = resolved.computes.map((c) => {
2891
3049
  const expr = compileCompute(c.expression, ctx);
@@ -2904,9 +3062,9 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2904
3062
  const firstSource = resolved.sources[0];
2905
3063
  if (firstSource !== void 0) {
2906
3064
  if (firstSource.subquery !== void 0) {
2907
- 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)}`);
2908
3066
  } else if (firstSource.table !== void 0) {
2909
- sqlParts.push(`FROM ${firstSource.table} AS ${firstSource.alias}`);
3067
+ sqlParts.push(`FROM ${tableSql(firstSource.table, namespace)} AS ${sqlName(firstSource.alias)}`);
2910
3068
  }
2911
3069
  }
2912
3070
  for (const join of resolved.joins) {
@@ -2919,9 +3077,9 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2919
3077
  ];
2920
3078
  const on = conditions.join(" AND ");
2921
3079
  if (joinSource.subquery !== void 0) {
2922
- 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}`);
2923
3081
  } else {
2924
- sqlParts.push(`${keyword} ${join.toTable} AS ${join.toAlias} ON ${on}`);
3082
+ sqlParts.push(`${keyword} ${tableSql(join.toTable, namespace)} AS ${sqlName(join.toAlias)} ON ${on}`);
2925
3083
  }
2926
3084
  }
2927
3085
  }
@@ -2929,9 +3087,9 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2929
3087
  for (const source of resolved.sources) {
2930
3088
  if (source.alias === firstSource?.alias || joinedAliases.has(source.alias)) continue;
2931
3089
  if (source.subquery !== void 0) {
2932
- 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)}`);
2933
3091
  } else if (source.table !== void 0) {
2934
- sqlParts.push(`CROSS JOIN ${source.table} AS ${source.alias}`);
3092
+ sqlParts.push(`CROSS JOIN ${tableSql(source.table, namespace)} AS ${sqlName(source.alias)}`);
2935
3093
  }
2936
3094
  }
2937
3095
  if (resolved.filter !== void 0) {
@@ -2939,7 +3097,7 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2939
3097
  sqlParts.push(`WHERE ${whereClause}`);
2940
3098
  }
2941
3099
  if (resolved.groupBy.length > 0) {
2942
- const groupByParts = resolved.groupBy.map((f) => `${f.alias}.${f.column}`);
3100
+ const groupByParts = resolved.groupBy.map((f) => columnSql(f.alias, f.column));
2943
3101
  sqlParts.push(`GROUP BY ${groupByParts.join(", ")}`);
2944
3102
  }
2945
3103
  if (resolved.sort.length > 0) {
@@ -2947,13 +3105,13 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
2947
3105
  if (typeof s.field === "string") {
2948
3106
  return `${quoteIdent(s.field)} ${s.dir === "desc" ? "DESC" : "ASC"}`;
2949
3107
  }
2950
- 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"}`;
2951
3109
  });
2952
3110
  sqlParts.push(`ORDER BY ${orderByParts.join(", ")}`);
2953
3111
  } else if (resolved.semantic !== void 0) {
2954
3112
  const { field, contextPath } = resolved.semantic;
2955
- const position = paramSlots.findIndex((slot) => slot.kind === "semantic" && slot.key === contextPath) + 1;
2956
- 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`);
2957
3115
  }
2958
3116
  if (resolved.limit !== void 0) {
2959
3117
  if (!Number.isInteger(resolved.limit) || resolved.limit < 1) {
@@ -3008,6 +3166,7 @@ var coerceNumericColumns = (rows, fields) => {
3008
3166
  };
3009
3167
  var createPostgresAdapter = (config) => {
3010
3168
  const { pool, schema = "public", exclude } = config;
3169
+ const namespace = config.qualifyTables === true ? schema : void 0;
3011
3170
  const capabilities = {
3012
3171
  vectorSearch: true,
3013
3172
  fuzzyMatch: false,
@@ -3019,12 +3178,15 @@ var createPostgresAdapter = (config) => {
3019
3178
  windowFunctions: true,
3020
3179
  statementTimeout: true
3021
3180
  };
3022
- const introspect = async (options) => introspectPostgres(pool, {
3023
- ...options,
3024
- schema: options?.schema ?? schema,
3025
- exclude: options?.exclude ?? exclude
3026
- });
3027
- 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);
3028
3190
  let perStatementMs;
3029
3191
  const limitReads = async (ms) => {
3030
3192
  perStatementMs = void 0;
@@ -3067,7 +3229,7 @@ var vexGuide = () => [
3067
3229
  ' - A value the query filters with ILIKE is a pattern: "%text%" matches contains.',
3068
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".',
3069
3231
  "",
3070
- "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.",
3071
3233
  "",
3072
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."
3073
3235
  ].join("\n");
@@ -3356,7 +3518,10 @@ var createPostgresCache = (config) => {
3356
3518
  }
3357
3519
  return out;
3358
3520
  };
3359
- 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 };
3360
3525
  };
3361
3526
 
3362
3527
  // src/cache/tiered.ts
@@ -3418,7 +3583,22 @@ var createTieredCache = (config) => {
3418
3583
  fireAndForget(l2.clear(), onError);
3419
3584
  };
3420
3585
  const keys = async () => l1.keys();
3421
- 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
+ };
3422
3602
  };
3423
3603
 
3424
3604
  // src/mutations/signature.ts
@@ -3761,18 +3941,11 @@ var assertReturnedColumns = (refs, schema) => {
3761
3941
  }
3762
3942
  };
3763
3943
  var readMatchesFor = (table, policy) => {
3764
- const rule = policy.entities[table];
3765
- if (rule === void 0) {
3766
- if (policy.default === "deny") throw new VexScopeError(table, `A $lookup reads "${table}", which is not allowed by scope policy (default: deny).`);
3767
- return [];
3768
- }
3769
- if ("public" in rule) return [];
3770
- if ("deny" in rule) throw new VexScopeError(table, `A $lookup reads "${table}", which is denied by scope policy.`);
3771
- if (rule.read === void 0) {
3772
- if (policy.default === "deny") throw new VexScopeError(table, `A $lookup reads "${table}", which this principal has no read grant for.`);
3773
- return [];
3774
- }
3775
- 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;
3776
3949
  };
3777
3950
  var boundaryOf = (table, r) => isSetMatch(r) ? { in: [`${table}.${r.match}`, { $scope: r.in }] } : { eq: [`${table}.${r.match}`, { $scope: r.to }] };
3778
3951
  var scopeLookups = (cols, policy) => {
@@ -3790,21 +3963,22 @@ var scopeLookups = (cols, policy) => {
3790
3963
  }
3791
3964
  return out;
3792
3965
  };
3793
- var writeGate = (table, op, policy) => {
3966
+ var writeGateOf = (table, op, policy) => {
3794
3967
  const rule = policy.entities[table];
3795
- if (rule === void 0) {
3796
- if (policy.default === "deny") throw new VexScopeError(table, `Writes to "${table}" are not allowed by scope policy (default: deny).`);
3797
- return void 0;
3798
- }
3968
+ if (rule === void 0) return policy.default === "deny" ? "unlisted" : void 0;
3799
3969
  if ("public" in rule) return void 0;
3800
- if ("deny" in rule) throw new VexScopeError(table, `Writes to "${table}" are denied by scope policy.`);
3970
+ if ("deny" in rule) return "denied";
3801
3971
  const specific = op === "insert" ? rule.insert : op === "update" ? rule.update : rule.delete;
3802
- if (rule.write === void 0 && specific === void 0) {
3803
- if (policy.default === "deny") throw new VexScopeError(table, `"${op}" on "${table}" is not allowed by scope policy (default: deny).`);
3804
- return void 0;
3805
- }
3972
+ if (rule.write === void 0 && specific === void 0) return policy.default === "deny" ? "ungranted" : void 0;
3806
3973
  return { rule, rules: [...rule.write ?? [], ...specific ?? []] };
3807
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
+ };
3808
3982
  var scopeInsertParts = (table, rawValues, rawConflict, policy) => {
3809
3983
  let values = scopeLookups(rawValues, policy);
3810
3984
  let conflict = rawConflict === void 0 || rawConflict.set === void 0 ? rawConflict : { ...rawConflict, set: scopeLookups(rawConflict.set, policy) };
@@ -3868,12 +4042,13 @@ var itemRow = (element, itemKeys) => {
3868
4042
  const fields = element !== null && typeof element === "object" && !Array.isArray(element) ? element : {};
3869
4043
  return Object.fromEntries(Object.entries(itemKeys).map(([column, key]) => [column, fields[key]]));
3870
4044
  };
3871
- var newCtx = () => ({
4045
+ var newCtx = (namespace) => ({
3872
4046
  resolvedPaths: /* @__PURE__ */ new Map(),
3873
4047
  aliasMap: /* @__PURE__ */ new Map(),
3874
4048
  paramSlots: [],
3875
4049
  paramCounter: { value: 0 },
3876
- returned: /* @__PURE__ */ new Map()
4050
+ returned: /* @__PURE__ */ new Map(),
4051
+ ...namespace !== void 0 ? { namespace } : {}
3877
4052
  });
3878
4053
  var indexFilterFields = (filter, aliasMap) => {
3879
4054
  for (const path of filterColumns(filter)) aliasMap.set(path, path);
@@ -3882,7 +4057,7 @@ var compileValue = (v, ctx) => {
3882
4057
  if (isLookup(v)) {
3883
4058
  indexFilterFields(v.$lookup.where, ctx.aliasMap);
3884
4059
  const where = compileFilter(v.$lookup.where, ctx);
3885
- 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})`;
3886
4061
  }
3887
4062
  if (isReturned(v)) {
3888
4063
  ctx.paramCounter.value += 1;
@@ -3902,37 +4077,84 @@ var compileColumnValue = (table, column, v, ctx, schema) => {
3902
4077
  }
3903
4078
  return sql;
3904
4079
  };
3905
- 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) => {
3906
4092
  const c = m.onConflict;
3907
4093
  if (c === void 0) return "";
3908
- if (c.set === void 0) return ` ON CONFLICT (${c.target.join(", ")}) DO NOTHING`;
3909
- const sets = Object.entries(c.set).map(([col, v]) => `${col} = ${compileColumnValue(m.table, col, v, ctx, schema)}`);
3910
- 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 = [];
3911
4099
  if (c.where !== void 0) {
3912
4100
  indexFilterFields(c.where, ctx.aliasMap);
3913
- where = ` WHERE ${compileFilter(c.where, ctx)}`;
4101
+ conditions.push(compileFilter(c.where, ctx));
3914
4102
  }
3915
- 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}`;
4106
+ };
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
+ };
3916
4124
  };
3917
- var compileMutation = (m, schema) => {
3918
- const ctx = newCtx();
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
+ };
3919
4141
  if (m.op === "insert") {
3920
4142
  const entries = Object.entries(m.values);
3921
- const cols = entries.map(([c]) => c);
4143
+ const cols = entries.map(([c]) => sqlName(c));
3922
4144
  const vals = entries.map(([c, v]) => compileColumnValue(m.table, c, v, ctx, schema));
3923
- 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)}`);
3924
4146
  }
3925
4147
  if (m.op === "insertEach") {
3926
4148
  const types = new Map(findEntity2(m.table, schema)?.fields.map((f) => [f.name, f.type]));
3927
4149
  const entries = Object.entries(m.values);
3928
- const cols = entries.map(([c]) => c);
4150
+ const cols = entries.map(([c]) => sqlName(c));
3929
4151
  const itemKeys = {};
3930
4152
  const itemColumns = [];
3931
4153
  const exprs = entries.map(([col, v]) => {
3932
4154
  if (isItemRef(v)) {
3933
4155
  itemKeys[col] = v.$item;
3934
- itemColumns.push(`${col} ${String(types.get(col))}`);
3935
- return `item.${col}`;
4156
+ itemColumns.push(`${sqlName(col)} ${String(types.get(col))}`);
4157
+ return `item.${sqlName(col)}`;
3936
4158
  }
3937
4159
  return isReturned(v) ? compileColumnValue(m.table, col, v, ctx, schema) : compileValue(v, ctx);
3938
4160
  });
@@ -3940,32 +4162,31 @@ var compileMutation = (m, schema) => {
3940
4162
  ctx.paramSlots.push({ key: m.items.$context, kind: "context", type: "json" });
3941
4163
  const items = `$${ctx.paramCounter.value}::jsonb`;
3942
4164
  const source = itemColumns.length === 0 ? `jsonb_array_elements(${items}) AS item` : `jsonb_to_recordset(${items}) AS item(${itemColumns.join(", ")})`;
3943
- return {
3944
- sql: `INSERT INTO ${m.table} (${cols.join(", ")}) SELECT ${exprs.join(", ")} FROM ${source}${compileConflict(m, ctx, schema)} RETURNING *`,
3945
- slots: ctx.paramSlots,
3946
- returned: ctx.returned,
3947
- itemKeys
3948
- };
4165
+ return { ...finish(`INSERT INTO ${tableSql(m.table, schema.namespace)} (${cols.join(", ")}) SELECT ${exprs.join(", ")} FROM ${source}${compileConflict(m, ctx, schema, pinned)}`), itemKeys };
3949
4166
  }
3950
4167
  if (m.op === "update") {
3951
- 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}`);
3952
4170
  indexFilterFields(m.where, ctx.aliasMap);
3953
- const where2 = compileFilter(m.where, ctx);
3954
- 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}`);
3955
4173
  }
3956
4174
  indexFilterFields(m.where, ctx.aliasMap);
3957
4175
  const where = compileFilter(m.where, ctx);
3958
- 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}`);
3959
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;
3960
4179
  var SUGAR = {
3961
- upsert: (m, context) => {
3962
- 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));
3963
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 } };
3964
4185
  }
3965
4186
  };
3966
- var desugarMutation = (m, context) => {
4187
+ var desugarMutation = (m, context, schema) => {
3967
4188
  const rewrite = SUGAR[m.op];
3968
- return rewrite === void 0 ? m : rewrite(m, context);
4189
+ return rewrite === void 0 ? m : rewrite(m, context, schema);
3969
4190
  };
3970
4191
  var mutationMisfits = (def, schema) => {
3971
4192
  const reasons = [];
@@ -3973,7 +4194,7 @@ var mutationMisfits = (def, schema) => {
3973
4194
  for (const [at, entry] of list.entries()) {
3974
4195
  const asked = [
3975
4196
  // keyed, an upsert is an update; unkeyed, an insert
3976
- ...(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)),
3977
4198
  () => assertReturnedColumns(returnedIn(list, at).refs, schema)
3978
4199
  ];
3979
4200
  for (const ask of asked) {
@@ -3986,10 +4207,22 @@ var mutationMisfits = (def, schema) => {
3986
4207
  }
3987
4208
  return reasons;
3988
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
+ };
3989
4222
  var executeWrites = async (client, def, mctx) => {
3990
4223
  const parsed = MutationDefinitionSchema.parse(def);
3991
4224
  const entries = Array.isArray(parsed) ? parsed : [parsed];
3992
- const cores = entries.map((entry) => desugarMutation(entry, mctx.context));
4225
+ const cores = entries.map((entry) => desugarMutation(entry, mctx.context, mctx.schema));
3993
4226
  const compiled = cores.map((core, at) => {
3994
4227
  const missing = requiredContextKeys(core).filter((k) => mctx.context[k] === void 0);
3995
4228
  if (missing.length > 0) {
@@ -4002,45 +4235,70 @@ var executeWrites = async (client, def, mctx) => {
4002
4235
  const m = scopeMutation(core, mctx.policy);
4003
4236
  assertWritableColumns(m, mctx.schema);
4004
4237
  assertReturnedColumns(returned.refs, mctx.schema);
4005
- const statement = compileMutation(m, mctx.schema);
4006
- requireScope({ paramSlots: statement.slots }, mctx.scope);
4007
- 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]) => {
4008
4242
  const source = returned.refs.get(ref);
4009
4243
  if (source === void 0) throw new VexError("invalid_dsl", `"${ref}" names no earlier statement of the batch.`);
4010
4244
  return { slot, ref, source };
4011
4245
  });
4012
- 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
+ };
4013
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
+ };
4014
4282
  const runAll = async (q) => {
4015
4283
  const results = [];
4016
4284
  for (const c of compiled) {
4017
- const params = await resolveParams(c.slots, mctx.context, mctx.scope);
4018
- for (const read of c.reads) {
4019
- const rows = results[read.source.statement]?.rows ?? [];
4020
- const row = rows[0];
4021
- if (rows.length !== 1 || row === void 0) {
4022
- throw new VexError(
4023
- "execution_error",
4024
- `"${read.ref}" needs exactly one row from statement ${read.source.statement + 1} of the batch, which wrote ${rows.length}. Nothing was written.`,
4025
- { returned: read.ref, rows: rows.length }
4026
- );
4027
- }
4028
- if (!(read.source.column in row)) {
4029
- 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 });
4030
- }
4031
- 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);
4032
4289
  }
4033
- const bound = params.map((value, i) => {
4034
- if (c.slots[i]?.encode === "json") return value !== null && typeof value === "object" ? JSON.stringify(value) : value;
4035
- if (c.slots[i]?.type !== "json") return value;
4036
- if (!Array.isArray(value)) {
4037
- throw new VexError("invalid_request", `"${c.slots[i]?.key ?? ""}" must be an array of objects (one inserted row per element).`);
4038
- }
4039
- const { itemKeys } = c;
4040
- return JSON.stringify(itemKeys === void 0 ? value : value.map((element) => itemRow(element, itemKeys)));
4041
- });
4042
- const res = await q.query(c.sql, bound);
4043
- 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 });
4044
4302
  }
4045
4303
  return results;
4046
4304
  };
@@ -4074,40 +4332,39 @@ var filterSchema = (schema, entities) => {
4074
4332
  if (entities === void 0 || entities.length === 0) return schema.entities;
4075
4333
  return schema.entities.filter((e) => entities.includes(e.name));
4076
4334
  };
4077
- var canWriteTable = (policy, table, op) => {
4078
- const rule = policy.entities[table];
4079
- if (rule === void 0) return policy.default === "allow";
4080
- if ("public" in rule) return true;
4081
- if ("deny" in rule) return false;
4082
- if (rule.write !== void 0 || policy.default === "allow") return true;
4083
- if (op === "insert" || op === "insertEach") return rule.insert !== void 0;
4084
- if (op === "update") return rule.update !== void 0;
4085
- if (op === "delete") return rule.delete !== void 0;
4086
- if (op === "upsert") return rule.insert !== void 0 || rule.update !== void 0;
4087
- return false;
4335
+ var WRITES_OF = {
4336
+ insert: ["insert"],
4337
+ insertEach: ["insert"],
4338
+ update: ["update"],
4339
+ delete: ["delete"],
4340
+ upsert: ["insert", "update"]
4088
4341
  };
4089
- var collectTables = (dsl) => {
4090
- const out = [];
4091
- const walk = (q) => {
4092
- for (const src of q.from) {
4093
- if (typeof src === "string") out.push(src);
4094
- else walk(src.query);
4095
- }
4096
- };
4097
- walk(dsl);
4098
- 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
+ }
4099
4350
  };
4100
- var entryVisible = (policy, entry) => {
4101
- if (entry.kind === "ok") return collectTables(entry.dsl).every((t) => canReadTable(policy, t));
4102
- 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
+ }
4103
4360
  return false;
4104
4361
  };
4105
- var listFingerprints = async (engine, policy) => {
4362
+ var listFingerprints = async (engine, policies) => {
4106
4363
  if (engine.cache.entries === void 0) return [];
4107
4364
  const schema = engine.getSchema();
4108
4365
  const current = schema !== void 0 ? computeSchemaFingerprint(schema) : void 0;
4109
4366
  const rows = await engine.cache.entries();
4110
- 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 }) => ({
4111
4368
  fingerprint: key,
4112
4369
  kind: entry.kind === "mutation" ? "mutation" : "query",
4113
4370
  protected: entry.protected === true,
@@ -4125,11 +4382,12 @@ var listFingerprints = async (engine, policy) => {
4125
4382
  }));
4126
4383
  };
4127
4384
  var handleDiscovery = async (config) => {
4128
- const { engine, entities: entityFilter, scopePolicy } = config;
4385
+ const { engine, entities: entityFilter } = config;
4386
+ const scopePolicy = config.scopePolicy ?? engine.scopePolicy;
4129
4387
  const filtered = filterSchema(engine.getSchema(), entityFilter).filter(
4130
4388
  (e) => scopePolicy === void 0 || canReadTable(scopePolicy, e.name)
4131
4389
  );
4132
- const fingerprints = await listFingerprints(engine, scopePolicy);
4390
+ const fingerprints = await listFingerprints(engine, { read: scopePolicy, write: config.mutations?.policy ?? scopePolicy });
4133
4391
  const protectedCount = fingerprints.filter((f) => f.protected).length;
4134
4392
  return {
4135
4393
  protection: protectedCount === 0 ? "none" : protectedCount === fingerprints.length ? "all" : "some",
@@ -4207,10 +4465,29 @@ var handleQuery = async (config, body, scope, live) => {
4207
4465
  return result;
4208
4466
  };
4209
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
+ };
4210
4487
  var runQuery = async (config, body, scope, probe, live) => {
4211
4488
  const { engine } = config;
4212
4489
  if (strata.exceedsDepth(body)) return { status: 400, body: { error: "invalid_request", message: strata.depthRefusal() } };
4213
- const parsed = QueryRequestSchema.safeParse(body);
4490
+ const parsed = QueryRequestSchema.safeParse(dropNullIntentAndFingerprint(body));
4214
4491
  if (!parsed.success) {
4215
4492
  return {
4216
4493
  status: 400,
@@ -4254,31 +4531,19 @@ var runQuery = async (config, body, scope, probe, live) => {
4254
4531
  }
4255
4532
  let writePolicy = config.mutations.policy;
4256
4533
  if (entry.reach !== void 0) {
4257
- if (config.policyForReach === void 0) {
4258
- return {
4259
- status: 500,
4260
- body: {
4261
- error: "execution_error",
4262
- message: `Entry "${parsed.data.fingerprint ?? ""}" requires reach "${entry.reach}" and this handler has no policyForReach.`
4263
- }
4264
- };
4265
- }
4266
- const narrowed = await config.policyForReach(entry.reach);
4267
- if (narrowed === void 0) {
4268
- return {
4269
- status: 403,
4270
- body: { error: "scope_denied", message: `Reach "${entry.reach}" is not available to this principal.` }
4271
- };
4272
- }
4273
- writePolicy = narrowed;
4534
+ const reached = await policyAtReach(config, parsed.data.fingerprint, entry.reach);
4535
+ if ("status" in reached) return reached;
4536
+ writePolicy = reached;
4274
4537
  }
4275
4538
  const writes = await executeWrites(config.mutations.client, entry.mutation, {
4276
4539
  context: parsed.data.context,
4277
4540
  scope,
4278
4541
  policy: writePolicy,
4279
- schema
4542
+ schema,
4543
+ ...config.mutations.checkMovedRows !== void 0 ? { checkMovedRows: config.mutations.checkMovedRows } : {},
4544
+ ...config.mutations.answerReadableRows === true ? { answerReadableRows: true } : {}
4280
4545
  });
4281
- const rows = writes.flatMap((w) => w.rows);
4546
+ const rows = writes.flatMap((w) => w.readable ?? w.rows);
4282
4547
  engine.invalidate(tablesChangedBy(writes, schema));
4283
4548
  if (config.mutations.onWrite !== void 0) {
4284
4549
  try {
@@ -4288,35 +4553,23 @@ var runQuery = async (config, body, scope, probe, live) => {
4288
4553
  }
4289
4554
  }
4290
4555
  const now = Date.now();
4291
- 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));
4292
4557
  if (probe !== void 0) probe.rows = rows.length;
4293
4558
  return { status: 200, body: { result: rows.length === 1 ? rows[0] : rows } };
4294
4559
  }
4295
4560
  }
4296
4561
  let readPolicy = config.scopePolicy;
4297
4562
  if (entryReach !== void 0) {
4298
- if (config.policyForReach === void 0) {
4299
- return {
4300
- status: 500,
4301
- body: {
4302
- error: "execution_error",
4303
- message: `Entry "${parsed.data.fingerprint ?? ""}" requires reach "${entryReach}" and this handler has no policyForReach.`
4304
- }
4305
- };
4306
- }
4307
- readPolicy = await config.policyForReach(entryReach);
4308
- if (readPolicy === void 0) {
4309
- return {
4310
- status: 403,
4311
- body: { error: "scope_denied", message: `Reach "${entryReach}" is not available to this principal.` }
4312
- };
4313
- }
4563
+ const reached = await policyAtReach(config, parsed.data.fingerprint ?? "", entryReach);
4564
+ if ("status" in reached) return reached;
4565
+ readPolicy = reached;
4314
4566
  }
4315
4567
  const response = await engine.execute(parsed.data, {
4316
4568
  scope,
4317
4569
  entities: config.entities,
4318
4570
  ...config.locked === true ? { locked: true } : {},
4319
4571
  ...readPolicy !== void 0 ? { scopePolicy: readPolicy } : {},
4572
+ ...entryReach !== void 0 ? { policyForReach: () => readPolicy } : {},
4320
4573
  ...live !== void 0 ? { signal: live.signal, onChange: live.onChange } : {}
4321
4574
  });
4322
4575
  if (probe !== void 0) {
@@ -4341,20 +4594,29 @@ var runQuery = async (config, body, scope, probe, live) => {
4341
4594
  }
4342
4595
  };
4343
4596
  }
4344
- console.error("[vex] unhandled error:", err);
4345
4597
  const errObj = err;
4346
4598
  const message = err instanceof Error ? err.message : typeof errObj?.message === "string" ? errObj.message : "Unknown error";
4347
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);
4348
4602
  return {
4349
4603
  status: 500,
4350
4604
  body: { error: code, message }
4351
4605
  };
4352
4606
  }
4353
4607
  };
4354
- var handleFingerprintPatch = async (config, fingerprint, patch) => {
4608
+ var managementRefusal = (config) => {
4355
4609
  if (config.locked === true) {
4356
4610
  return { status: 403, body: { error: "locked", message: "This endpoint is locked \u2014 fingerprints cannot be managed here." } };
4357
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;
4358
4620
  const entry = await config.engine.cache.get(fingerprint);
4359
4621
  if (entry === void 0 || entry.kind !== "ok" && entry.kind !== "mutation") {
4360
4622
  return { status: 404, body: { error: "cache_miss", message: `Unknown fingerprint "${fingerprint}"` } };
@@ -4366,9 +4628,8 @@ var handleFingerprintPatch = async (config, fingerprint, patch) => {
4366
4628
  return { status: 200, body: { fingerprint, protected: patch.protected } };
4367
4629
  };
4368
4630
  var handleFingerprintDelete = async (config, fingerprint) => {
4369
- if (config.locked === true) {
4370
- return { status: 403, body: { error: "locked", message: "This endpoint is locked \u2014 fingerprints cannot be managed here." } };
4371
- }
4631
+ const refused = managementRefusal(config);
4632
+ if (refused !== void 0) return refused;
4372
4633
  const entry = await config.engine.cache.get(fingerprint);
4373
4634
  if (entry === void 0) {
4374
4635
  return { status: 404, body: { error: "cache_miss", message: `Unknown fingerprint "${fingerprint}"` } };