@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.js CHANGED
@@ -1,7 +1,7 @@
1
- import { isRefresh } from './chunk-F7RDSWYF.js';
2
- export { REFRESH_MODES, isRefresh } from './chunk-F7RDSWYF.js';
3
- import { MutationDefinitionSchema, lintMutation, computeSchemaFingerprint, pruneOptional, buildValidationContext, requireScope, executeQuery, QueryRequestSchema, computeRequestHash, computePolicyKey, presenceOf, presenceSignature, findMissingContext, buildContextContract, optionalKeysOf, resolveParams, canonicalHash, fireAndForget, isSetMatch, refuseOptional, canonicalText, checkScope, scopeResolved, mintFingerprint, isEntryFresh, canReadTable, hashText, quoteIdent, compileCompute, compileAggregate, compileJoinPairs, compileFilter, isTouchDue } from './chunk-W5MYFJKT.js';
4
- export { MutationDefinitionSchema, MutationSchema, QueryRequestSchema, VexScopeError, applyScope, buildContextContract, buildValidationContext, checkScope, collectMutationContext, collectQueryContext, compileFieldOrValue, compileFilter, computeRequestHash, computeSchemaFingerprint, executeMutation, executeQuery, executeWrites, findMissingContext, handleDiscovery, handleFingerprintDelete, handleFingerprintPatch, handleQuery, lintMutation, mintFingerprint, mutationEffect, mutationMisfits, normalizeShape, optionalKeysOf, presenceOf, pruneOptional, requiredContextKeys, resolveParams, scopeResolved, sweepCache, tablesChangedBy } from './chunk-W5MYFJKT.js';
1
+ import { isRefresh } from './chunk-VHNCSQPO.js';
2
+ export { REFRESH_MODES, isRefresh } from './chunk-VHNCSQPO.js';
3
+ import { MutationDefinitionSchema, lintMutation, computeSchemaFingerprint, pruneOptional, buildValidationContext, requireScope, executeQuery, QueryRequestSchema, dropNullIntentAndFingerprint, computeRequestHash, computePolicyKey, presenceOf, presenceSignature, findMissingContext, buildContextContract, optionalKeysOf, resolveParams, canonicalHash, discoverEntities, fireAndForget, isSetMatch, refuseOptional, canonicalText, checkScope, scopeResolved, mintFingerprint, isEntryFresh, canReadTable, hashText, columnSql, quoteIdent, compileCompute, compileAggregate, sqlName, tableSql, compileJoinPairs, compileFilter, isTouchDue, touchEntry } from './chunk-F7OXXJIH.js';
4
+ export { MutationDefinitionSchema, MutationSchema, QueryRequestSchema, VexScopeError, applyScope, buildContextContract, buildValidationContext, checkScope, collectMutationContext, collectQueryContext, compileFieldOrValue, compileFilter, computeRequestHash, computeSchemaFingerprint, discoverEntities, executeMutation, executeQuery, executeWrites, findMissingContext, handleDiscovery, handleFingerprintDelete, handleFingerprintPatch, handleQuery, lintMutation, mintFingerprint, mutationEffect, mutationMisfits, normalizeShape, optionalKeysOf, presenceOf, pruneOptional, requiredContextKeys, resolveParams, scopeResolved, sweepCache, tablesChangedBy } from './chunk-F7OXXJIH.js';
5
5
  import { VexError, isVexError } from './chunk-XTOK7YOR.js';
6
6
  export { VexError } from './chunk-XTOK7YOR.js';
7
7
  import { QuerySchema, isIdentifier, isFieldPathShape } from './chunk-UPQMKAAX.js';
@@ -11,179 +11,6 @@ import { exceedsDepth, depthRefusal } from '@niscorp/strata';
11
11
  import { compile, execute } from '@niscorp/prism';
12
12
  import { migrate } from '@niscorp/strata/postgres';
13
13
 
14
- // src/scope/discover.ts
15
- var extractEntityFromPath = (path) => {
16
- const parts = path.split(".");
17
- return parts.length === 2 ? parts[0] : void 0;
18
- };
19
- var collectFromFieldOrValue = (fov, out) => {
20
- if (isFieldPathShape(fov)) {
21
- const entity = extractEntityFromPath(fov);
22
- if (entity !== void 0) out.add(entity);
23
- }
24
- };
25
- var collectFromFilter = (filter, out) => {
26
- if ("exists" in filter) {
27
- for (const entity of filter.exists.from) out.add(entity);
28
- if (filter.exists.filter !== void 0) collectFromFilter(filter.exists.filter, out);
29
- return;
30
- }
31
- if ("eq" in filter || "neq" in filter || "gt" in filter || "gte" in filter || "lt" in filter || "lte" in filter) {
32
- const pair = "eq" in filter ? filter.eq : "neq" in filter ? filter.neq : "gt" in filter ? filter.gt : "gte" in filter ? filter.gte : "lt" in filter ? filter.lt : filter.lte;
33
- collectFromFieldOrValue(pair[0], out);
34
- collectFromFieldOrValue(pair[1], out);
35
- return;
36
- }
37
- if ("in" in filter || "notIn" in filter) {
38
- const tuple = "in" in filter ? filter.in : filter.notIn;
39
- const entity = extractEntityFromPath(tuple[0]);
40
- if (entity !== void 0) out.add(entity);
41
- const target = tuple[1];
42
- if (Array.isArray(target)) {
43
- for (const v of target) {
44
- collectFromFieldOrValue(v, out);
45
- }
46
- }
47
- return;
48
- }
49
- if ("like" in filter || "ilike" in filter) {
50
- const tuple = "like" in filter ? filter.like : filter.ilike;
51
- const entity = extractEntityFromPath(tuple[0]);
52
- if (entity !== void 0) out.add(entity);
53
- collectFromFieldOrValue(tuple[1], out);
54
- return;
55
- }
56
- if ("isNull" in filter) {
57
- const entity = extractEntityFromPath(filter.isNull);
58
- if (entity !== void 0) out.add(entity);
59
- return;
60
- }
61
- if ("isNotNull" in filter) {
62
- const entity = extractEntityFromPath(filter.isNotNull);
63
- if (entity !== void 0) out.add(entity);
64
- return;
65
- }
66
- if ("and" in filter) {
67
- for (const sub of filter.and) {
68
- collectFromFilter(sub, out);
69
- }
70
- return;
71
- }
72
- if ("or" in filter) {
73
- for (const sub of filter.or) {
74
- collectFromFilter(sub, out);
75
- }
76
- return;
77
- }
78
- if ("not" in filter) {
79
- collectFromFilter(filter.not, out);
80
- return;
81
- }
82
- if ("semantic" in filter) {
83
- const entity = extractEntityFromPath(filter.semantic.field);
84
- if (entity !== void 0) out.add(entity);
85
- return;
86
- }
87
- if ("fuzzy" in filter) {
88
- const entity = extractEntityFromPath(filter.fuzzy.field);
89
- if (entity !== void 0) out.add(entity);
90
- return;
91
- }
92
- if ("optional" in filter) refuseOptional("scope discovery");
93
- };
94
- var collectFromCompute = (expr, out) => {
95
- if ("add" in expr || "subtract" in expr || "multiply" in expr || "divide" in expr) {
96
- const pair = "add" in expr ? expr.add : "subtract" in expr ? expr.subtract : "multiply" in expr ? expr.multiply : expr.divide;
97
- collectFromFieldOrValue(pair[0], out);
98
- collectFromFieldOrValue(pair[1], out);
99
- return;
100
- }
101
- if ("concat" in expr) {
102
- for (const v of expr.concat) {
103
- collectFromFieldOrValue(v, out);
104
- }
105
- return;
106
- }
107
- if ("coalesce" in expr) {
108
- for (const v of expr.coalesce) {
109
- collectFromFieldOrValue(v, out);
110
- }
111
- return;
112
- }
113
- if ("case" in expr) {
114
- for (const when of expr.case.when) {
115
- collectFromFilter(when.condition, out);
116
- collectFromFieldOrValue(when.then, out);
117
- }
118
- collectFromFieldOrValue(expr.case.else, out);
119
- return;
120
- }
121
- };
122
- var collectFromAggregate = (expr, out) => {
123
- 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;
124
- if (typeof arg !== "string") {
125
- collectFromCompute(arg, out);
126
- return;
127
- }
128
- const entity = extractEntityFromPath(arg);
129
- if (entity !== void 0) out.add(entity);
130
- };
131
- var collectFromQuery = (dsl, out) => {
132
- const aliases = /* @__PURE__ */ new Set();
133
- const local = /* @__PURE__ */ new Set();
134
- for (const source of dsl.from) {
135
- if (typeof source === "string") {
136
- out.add(source);
137
- } else {
138
- aliases.add(source.as);
139
- collectFromQuery(source.query, out);
140
- }
141
- }
142
- for (const ref of dsl.fields ?? []) {
143
- const entity = extractEntityFromPath(typeof ref === "string" ? ref : ref.field);
144
- if (entity !== void 0) local.add(entity);
145
- }
146
- if (dsl.filter !== void 0) {
147
- collectFromFilter(dsl.filter, local);
148
- }
149
- if (dsl.compute !== void 0) {
150
- for (const key of Object.keys(dsl.compute)) {
151
- const expr = dsl.compute[key];
152
- if (expr !== void 0) {
153
- collectFromCompute(expr, local);
154
- }
155
- }
156
- }
157
- if (dsl.aggregate !== void 0) {
158
- for (const key of Object.keys(dsl.aggregate)) {
159
- const expr = dsl.aggregate[key];
160
- if (expr !== void 0) {
161
- collectFromAggregate(expr, local);
162
- }
163
- }
164
- }
165
- if (dsl.groupBy !== void 0) {
166
- for (const path of dsl.groupBy) {
167
- const entity = extractEntityFromPath(path);
168
- if (entity !== void 0) local.add(entity);
169
- }
170
- }
171
- if (dsl.sort !== void 0) {
172
- for (const entry of dsl.sort) {
173
- const entity = extractEntityFromPath(entry.field);
174
- if (entity !== void 0) local.add(entity);
175
- }
176
- }
177
- for (const entity of local) {
178
- if (!aliases.has(entity)) out.add(entity);
179
- }
180
- };
181
- var discoverEntities = (dsl) => {
182
- const entities = /* @__PURE__ */ new Set();
183
- collectFromQuery(dsl, entities);
184
- return entities;
185
- };
186
-
187
14
  // src/scope/grants.ts
188
15
  var SCOPE_VERBS = ["read", "write.insert", "write.update", "write.delete"];
189
16
  var scopeGrants = (tables) => tables.flatMap((t) => SCOPE_VERBS.map((v) => `${t}.${v}`));
@@ -245,11 +72,24 @@ var createScopePolicy = (grants, behaviors = {}, scoping) => {
245
72
  return { default: "deny", entities };
246
73
  };
247
74
  var matchCount = (rules) => (rules ?? []).filter((r) => "match" in r).length;
75
+ var phasesOf = (rule) => {
76
+ if (rule === void 0 || "deny" in rule) return {};
77
+ if ("public" in rule) return { read: [], insert: [], update: [], delete: [] };
78
+ const { read, write, insert, update, delete: del } = rule;
79
+ const withWrite = (common, own) => [...common ?? [], ...own ?? []];
80
+ return {
81
+ ...read !== void 0 ? { read } : {},
82
+ ...write !== void 0 || insert !== void 0 ? { insert: withWrite(write, insert) } : {},
83
+ ...write !== void 0 || update !== void 0 ? { update: withWrite(write, update) } : {},
84
+ ...write !== void 0 || del !== void 0 ? { delete: withWrite(write && onlyMatches(write), del) } : {}
85
+ };
86
+ };
248
87
  var mergeScopePolicies = (policies) => {
249
88
  const entities = {};
250
89
  for (const policy of policies) {
251
- for (const [table, rule] of Object.entries(policy.entities)) {
252
- if (rule === void 0 || "public" in rule || "deny" in rule) continue;
90
+ for (const [table, listed] of Object.entries(policy.entities)) {
91
+ const rule = phasesOf(listed);
92
+ if (Object.keys(rule).length === 0) continue;
253
93
  const into = entities[table] ??= {};
254
94
  for (const phase of ["read", "insert", "update", "delete"]) {
255
95
  const incoming = rule[phase];
@@ -302,9 +142,9 @@ var findClosest = (target, candidates) => {
302
142
  };
303
143
  var generateAlias = (name, counter) => {
304
144
  const prefix = name.charAt(0).toLowerCase();
305
- const current = counter.get(prefix) ?? 0;
306
- const next = current + 1;
307
- counter.set(prefix, next);
145
+ let next = (counter.counts.get(prefix) ?? 0) + 1;
146
+ while (counter.taken.has(`${prefix}${next}`)) next += 1;
147
+ counter.counts.set(prefix, next);
308
148
  return `${prefix}${next}`;
309
149
  };
310
150
  var findEntity = (name, schema) => {
@@ -553,7 +393,10 @@ var extractSemantic = (filter, entityLookup, schema) => {
553
393
  return void 0;
554
394
  };
555
395
  var resolve = (dsl, schema) => {
556
- const aliasCounter = /* @__PURE__ */ new Map();
396
+ const aliasCounter = {
397
+ counts: /* @__PURE__ */ new Map(),
398
+ taken: /* @__PURE__ */ new Set([...schema.entities.map((e) => e.name), ...dsl.from.flatMap((source) => typeof source === "string" ? [] : [source.as])])
399
+ };
557
400
  const entityLookup = /* @__PURE__ */ new Map();
558
401
  const aliasMap = /* @__PURE__ */ new Map();
559
402
  const sources = [];
@@ -650,7 +493,7 @@ var resolve = (dsl, schema) => {
650
493
  for (const [name, expr] of Object.entries(dsl.aggregate)) {
651
494
  if (expr !== void 0) {
652
495
  assertName(name, "aggregate name");
653
- resolveAggregatePaths(expr, entityLookup, schema, aliasMap);
496
+ resolveAggregatePaths(expr, entityLookup, schema, aliasMap, existsMap, aliasCounter);
654
497
  aggregates.push({ name, expression: expr });
655
498
  }
656
499
  }
@@ -729,11 +572,11 @@ var resolveComputePaths = (expr, entityLookup, schema, aliasMap, existsOut, alia
729
572
  resolveFieldOrValue(expr.case.else);
730
573
  }
731
574
  };
732
- var resolveAggregatePaths = (expr, entityLookup, schema, aliasMap) => {
575
+ var resolveAggregatePaths = (expr, entityLookup, schema, aliasMap, existsOut, aliasCounter) => {
733
576
  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;
734
577
  if (arg === "*") return;
735
578
  if (typeof arg !== "string") {
736
- resolveComputePaths(arg, entityLookup, schema, aliasMap);
579
+ resolveComputePaths(arg, entityLookup, schema, aliasMap, existsOut, aliasCounter);
737
580
  return;
738
581
  }
739
582
  if (!aliasMap.has(arg)) {
@@ -781,8 +624,8 @@ var hasCartesianProduct = (resolved) => {
781
624
  };
782
625
  var findUnindexedFilterColumns = (resolved) => {
783
626
  if (resolved.filter === void 0) return [];
784
- const unindexed = [];
785
- for (const [path, res] of resolved.filter.resolvedPaths) {
627
+ const unindexed = /* @__PURE__ */ new Set();
628
+ for (const res of resolved.filter.resolvedPaths.values()) {
786
629
  const source = resolved.sources.find((s) => s.alias === res.alias);
787
630
  if (source === void 0 || source.entity === void 0) continue;
788
631
  const isIndexed = source.entity.indexes.some(
@@ -792,10 +635,10 @@ var findUnindexedFilterColumns = (resolved) => {
792
635
  (f) => f.name === res.column && f.primaryKey
793
636
  );
794
637
  if (!isIndexed && !isPrimaryKey) {
795
- unindexed.push(path);
638
+ unindexed.add(`${source.entity.name}.${res.column}`);
796
639
  }
797
640
  }
798
- return unindexed;
641
+ return [...unindexed];
799
642
  };
800
643
  var hasAggregatesWithoutGroupBy = (resolved) => resolved.aggregates.length > 0 && resolved.groupBy.length === 0;
801
644
  var analyze = (resolved, config) => {
@@ -866,7 +709,11 @@ var createMemoryCache = () => {
866
709
  const entries = async () => {
867
710
  return [...store.entries()].map(([key, entry]) => ({ key, entry }));
868
711
  };
869
- return { get, set, delete: del, clear, keys, entries };
712
+ const touch = async (key, lastUsedAt) => {
713
+ const entry = store.get(key);
714
+ if (entry !== void 0) store.set(key, { ...entry, lastUsedAt });
715
+ };
716
+ return { get, set, delete: del, clear, keys, entries, touch };
870
717
  };
871
718
 
872
719
  // src/engine/live.ts
@@ -1065,6 +912,128 @@ var createLiveRows = (config = {}, emit = () => {
1065
912
  };
1066
913
  return { read, follow, invalidate, stats, stop };
1067
914
  };
915
+ var UNREADABLE_MODES = ["refuse", "omit", "null"];
916
+ var UpgradedColumnSchema = z.object({
917
+ stamp: z.string(),
918
+ kind: z.union([z.string(), z.object({ grammar: z.string(), column: z.string() }).strict()]),
919
+ unreadable: z.enum(UNREADABLE_MODES).optional()
920
+ }).strict();
921
+ var UpgradedColumnsSchema = z.record(z.string(), z.record(z.string(), UpgradedColumnSchema));
922
+ var outputOf = (ref) => typeof ref === "string" ? { path: ref, key: ref.slice(ref.indexOf(".") + 1) } : { path: ref.field, key: ref.as };
923
+ var outputsOf = (dsl, path) => (dsl.fields ?? []).map(outputOf).flatMap((out) => out.path === path ? [out.key] : []);
924
+ var count = (value, path) => {
925
+ if (value === path) return 1;
926
+ if (Array.isArray(value)) return value.reduce((sum, item) => sum + count(item, path), 0);
927
+ if (typeof value === "object" && value !== null) return Object.values(value).reduce((sum, item) => sum + count(item, path), 0);
928
+ return 0;
929
+ };
930
+ var usesOutsideFields = (dsl, path, outer) => Object.entries(dsl).reduce((sum, [part, value]) => {
931
+ if (part === "filter" || part === "sort" || outer && part === "fields") return sum;
932
+ if (part !== "from") return sum + count(value, path);
933
+ return sum + dsl.from.reduce((inner, source) => inner + (typeof source === "string" ? 0 : usesOutsideFields(source.query, path, false)), 0);
934
+ }, 0);
935
+ var selected = (dsl, path, upgraded) => {
936
+ const [first, ...rest] = outputsOf(dsl, path);
937
+ 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.`);
938
+ return [first, ...rest];
939
+ };
940
+ var refuseSharedKeys = (dsl, upgrades) => {
941
+ const sourcesByKey = /* @__PURE__ */ new Map();
942
+ const note = (key, source) => {
943
+ sourcesByKey.set(key, (sourcesByKey.get(key) ?? /* @__PURE__ */ new Set()).add(source));
944
+ };
945
+ for (const { path, key } of (dsl.fields ?? []).map(outputOf)) note(key, path);
946
+ for (const key of [...Object.keys(dsl.compute ?? {}), ...Object.keys(dsl.aggregate ?? {})]) note(key, `the computed ${key}`);
947
+ const used = upgrades.flatMap((upgrade) => [upgrade.key, ...upgrade.stampKeys, ...typeof upgrade.kind === "string" ? [] : [upgrade.kind.key]]);
948
+ const shared = [...new Set(used)].filter((key) => (sourcesByKey.get(key)?.size ?? 0) > 1);
949
+ if (shared.length > 0) {
950
+ 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\`.`);
951
+ }
952
+ };
953
+ var declared = (columns) => Object.entries(columns).flatMap(([table, byColumn]) => Object.entries(byColumn).map(([column, upgraded]) => ({ table, column, upgraded })));
954
+ var columnUpgrades = (dsl, columns) => {
955
+ const upgrades = declared(columns).flatMap(({ table, column, upgraded }) => {
956
+ const path = `${table}.${column}`;
957
+ if (usesOutsideFields(dsl, path, true) > 0) {
958
+ throw new VexError(
959
+ "invalid_dsl",
960
+ `${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.`
961
+ );
962
+ }
963
+ const keys = outputsOf(dsl, path);
964
+ if (keys.length === 0) return [];
965
+ const stampKeys = selected(dsl, `${table}.${upgraded.stamp}`, path);
966
+ const kind = typeof upgraded.kind === "string" ? upgraded.kind : { grammar: upgraded.kind.grammar, key: selected(dsl, `${table}.${upgraded.kind.column}`, path)[0] };
967
+ return keys.map((key) => ({ path, key, stampKeys, kind, unreadable: upgraded.unreadable ?? "refuse" }));
968
+ });
969
+ refuseSharedKeys(dsl, upgrades);
970
+ return upgrades;
971
+ };
972
+ var unknownKinds = (columns, upgrader) => declared(columns).flatMap(({ table, column, upgraded: { kind } }) => {
973
+ if (typeof kind !== "string") return kind.grammar in upgrader.stamp ? [] : [`${table}.${column} names the grammar "${kind.grammar}"`];
974
+ try {
975
+ upgrader.locate({}, kind);
976
+ return [];
977
+ } catch {
978
+ return [`${table}.${column} names the kind "${kind}"`];
979
+ }
980
+ });
981
+ var mistypedColumns = (columns, schema) => declared(columns).flatMap(({ table, column, upgraded }) => {
982
+ const fields = schema.entities.find((e) => e.name === table)?.fields ?? [];
983
+ const json = (name) => {
984
+ const field = fields.find((f) => f.name === name);
985
+ if (field === void 0) return [`${table}.${name} is not in the database`];
986
+ return ["json", "jsonb"].includes(field.type.toLowerCase()) ? [] : [`${table}.${name} is ${field.type}, not json`];
987
+ };
988
+ const { kind } = upgraded;
989
+ const kindColumn = typeof kind === "string" || fields.some((f) => f.name === kind.column) ? [] : [`${table}.${kind.column} is not in the database`];
990
+ return [...json(column), ...json(upgraded.stamp), ...kindColumn];
991
+ });
992
+ var StampSchema = z.union([z.null(), z.undefined(), z.record(z.string(), z.number().int().nonnegative())]);
993
+ var stampOf = (value, path) => {
994
+ const parsed = StampSchema.safeParse(value);
995
+ 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.`);
996
+ return parsed.data ?? {};
997
+ };
998
+ var kindOf = (upgrade, row) => {
999
+ if (typeof upgrade.kind === "string") return upgrade.kind;
1000
+ const name = row[upgrade.kind.key];
1001
+ 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}.`);
1002
+ return `${upgrade.kind.grammar}/${name}`;
1003
+ };
1004
+ var reasonOf = (error) => {
1005
+ const message = error instanceof Error ? error.message.split("\n")[0] ?? "" : String(error);
1006
+ const code = error instanceof Error && "code" in error && typeof error.code === "string" ? `${error.code}: ` : "";
1007
+ return `${code}${message}`;
1008
+ };
1009
+ var upgradeRows = (rows, upgrades, upgrade) => {
1010
+ if (upgrades.length === 0) return { rows, warnings: [] };
1011
+ const warnings = [];
1012
+ const upgraded = rows.flatMap((row, index) => {
1013
+ const next = { ...row };
1014
+ const said = [];
1015
+ for (const column of upgrades) {
1016
+ const value = row[column.key];
1017
+ if (value === null || value === void 0) continue;
1018
+ try {
1019
+ const result = upgrade(value, { kind: kindOf(column, row), stamp: stampOf(row[column.stampKeys[0]], column.path) });
1020
+ next[column.key] = result.document;
1021
+ for (const stampKey of column.stampKeys) next[stampKey] = result.stamp;
1022
+ } catch (error) {
1023
+ if (column.unreadable === "refuse") throw error;
1024
+ if (column.unreadable === "omit") {
1025
+ warnings.push(`The database's row ${index} (counting from 0) was left out: its ${column.path} does not upgrade (${reasonOf(error)}).`);
1026
+ return [];
1027
+ }
1028
+ next[column.key] = null;
1029
+ said.push(`The database's row ${index} (counting from 0) has ${column.path} set to null: it does not upgrade (${reasonOf(error)}).`);
1030
+ }
1031
+ }
1032
+ warnings.push(...said);
1033
+ return [next];
1034
+ });
1035
+ return { rows: upgraded, warnings };
1036
+ };
1068
1037
  var applySortContext = (dsl, context) => {
1069
1038
  const sortBy = context["sortBy"];
1070
1039
  if (typeof sortBy !== "string" || sortBy === "") return dsl;
@@ -1078,8 +1047,25 @@ var DEFAULT_MAX_LIMIT = 1e3;
1078
1047
  var DEFAULT_STATEMENT_TIMEOUT_MS = 1e4;
1079
1048
  var DEFAULT_UNSATISFIABLE_TTL_MS = 3e5;
1080
1049
  var DEFAULT_MAX_PRESENCE_VARIANTS = 32;
1050
+ var REMEMBERED_FINGERPRINTS = 1024;
1051
+ var forgetOldest = (noted) => {
1052
+ if (noted.size <= REMEMBERED_FINGERPRINTS) return;
1053
+ const oldest = noted.keys().next();
1054
+ if (oldest.done !== true) noted.delete(oldest.value);
1055
+ };
1081
1056
  var createQueryEngine = (engineConfig) => {
1082
- const { adapter, scope: scopePolicy, generateDsl, mapToShape, embed, behaviors } = engineConfig;
1057
+ const { adapter, scope: scopePolicy, generateDsl, mapToShape, embed, behaviors, upgrader } = engineConfig;
1058
+ const parsedColumns = UpgradedColumnsSchema.safeParse(engineConfig.upgradedColumns ?? {});
1059
+ if (!parsedColumns.success) throw new VexError("invalid_request", `The engine's upgradedColumns do not parse: ${parsedColumns.error.message}`);
1060
+ const upgradedColumns = parsedColumns.data;
1061
+ if (engineConfig.upgradedColumns !== void 0 && upgrader === void 0) {
1062
+ throw new VexError("invalid_request", "The engine was given `upgradedColumns` and no `upgrader`: hand it strata's `createUpgrader(grammars, { transform: evaluate })`.");
1063
+ }
1064
+ const unknown = upgrader === void 0 ? [] : unknownKinds(upgradedColumns, upgrader);
1065
+ if (unknown.length > 0) {
1066
+ 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.`);
1067
+ }
1068
+ const upgradeOf = (stored, upgrades) => upgrader === void 0 ? { rows: stored, warnings: [] } : upgradeRows(stored, upgrades, upgrader.upgrade);
1083
1069
  const emit = engineConfig.onEvent ?? (() => {
1084
1070
  });
1085
1071
  const maxNestingDepth = engineConfig.config?.maxNestingDepth ?? DEFAULT_MAX_NESTING_DEPTH;
@@ -1108,6 +1094,7 @@ var createQueryEngine = (engineConfig) => {
1108
1094
  if (seen === void 0) {
1109
1095
  seen = /* @__PURE__ */ new Set();
1110
1096
  variantsSeen.set(fingerprint, seen);
1097
+ forgetOldest(variantsSeen);
1111
1098
  }
1112
1099
  if (seen.has(signature)) return;
1113
1100
  seen.add(signature);
@@ -1131,6 +1118,10 @@ var createQueryEngine = (engineConfig) => {
1131
1118
  throw new VexError("execution_error", `The behaviors name columns the database does not have: ${missing.map((m) => `${m.entity}.${m.field}`).join(", ")}.`);
1132
1119
  }
1133
1120
  }
1121
+ const mistyped = mistypedColumns(upgradedColumns, schema);
1122
+ if (mistyped.length > 0) {
1123
+ throw new VexError("execution_error", `The upgradedColumns do not fit the database: ${mistyped.join("; ")}. Fix the name, or add the column in a migration.`);
1124
+ }
1134
1125
  cachedSchema = schema;
1135
1126
  cachedFingerprint = computeSchemaFingerprint(schema);
1136
1127
  return schema;
@@ -1169,15 +1160,30 @@ var createQueryEngine = (engineConfig) => {
1169
1160
  );
1170
1161
  }
1171
1162
  const compiled = adapter.compile(resolved);
1172
- return { compiled, warnings: analysis.warnings, ...engineLimit !== void 0 ? { engineLimit } : {} };
1163
+ return { compiled, warnings: analysis.warnings, upgrades: columnUpgrades(processedDsl, upgradedColumns), ...engineLimit !== void 0 ? { engineLimit } : {} };
1173
1164
  };
1174
1165
  const cutSaid = /* @__PURE__ */ new Set();
1166
+ const reachUnasked = /* @__PURE__ */ new Set();
1167
+ const policyAtReach = async (fingerprint, reach, current, options) => {
1168
+ if (options?.policyForReach === void 0) {
1169
+ if (!reachUnasked.has(fingerprint)) {
1170
+ reachUnasked.add(fingerprint);
1171
+ forgetOldest(reachUnasked);
1172
+ 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.`);
1173
+ }
1174
+ return current;
1175
+ }
1176
+ const narrowed = await options.policyForReach(reach);
1177
+ if (narrowed === void 0) throw new VexError("scope_denied", `Reach "${reach}" is not available to this principal.`);
1178
+ return narrowed;
1179
+ };
1175
1180
  const cutNote = (engineLimit, stated, rowCount, shape, fingerprint) => {
1176
1181
  if (engineLimit === void 0 || rowCount !== engineLimit) return void 0;
1177
1182
  if (shape !== void 0 && !Array.isArray(shape)) return void 0;
1178
1183
  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.`;
1179
1184
  if (fingerprint !== void 0 && !cutSaid.has(fingerprint)) {
1180
1185
  cutSaid.add(fingerprint);
1186
+ forgetOldest(cutSaid);
1181
1187
  console.warn(`[vex] "${fingerprint}": ${note}`);
1182
1188
  }
1183
1189
  return note;
@@ -1186,12 +1192,12 @@ var createQueryEngine = (engineConfig) => {
1186
1192
  const test = async (dsl, scopeValues) => {
1187
1193
  try {
1188
1194
  const testDsl = { ...pruneOptional(dsl, "all"), limit: 5 };
1189
- const { compiled, warnings } = runPipeline(testDsl);
1195
+ const { compiled, warnings, upgrades } = runPipeline(testDsl);
1190
1196
  const syntheticContext = buildValidationContext(compiled.contextContract);
1191
1197
  const scope = scopeValues ?? {};
1192
1198
  requireScope(compiled, scope);
1193
- const rows = await executeQuery(compiled, syntheticContext, scope, adapter, embed);
1194
- return { rows, warnings, errors: [] };
1199
+ const { rows, warnings: upgradeWarnings } = upgradeOf(await executeQuery(compiled, syntheticContext, scope, adapter, embed), upgrades);
1200
+ return { rows, warnings: [...warnings, ...upgradeWarnings], errors: [] };
1195
1201
  } catch (err) {
1196
1202
  const message = err instanceof Error ? err.message : String(err);
1197
1203
  return { rows: [], warnings: [], errors: [message] };
@@ -1204,7 +1210,7 @@ var createQueryEngine = (engineConfig) => {
1204
1210
  };
1205
1211
  const touch = (key, entry) => {
1206
1212
  const now = Date.now();
1207
- if (isTouchDue(entry, now)) fireAndForget(cache.set(key, { ...entry, lastUsedAt: now }));
1213
+ if (isTouchDue(entry, now)) fireAndForget(touchEntry(cache, key, entry, now));
1208
1214
  };
1209
1215
  const resolveFingerprint = async (validRequest, hasRequest, requestHash, scope) => {
1210
1216
  const fp = validRequest.fingerprint;
@@ -1228,6 +1234,7 @@ var createQueryEngine = (engineConfig) => {
1228
1234
  ...entry.intent !== void 0 ? { intent: entry.intent } : {},
1229
1235
  ...entry.shape !== void 0 ? { shape: entry.shape } : {},
1230
1236
  ...entry.refresh !== void 0 ? { refresh: entry.refresh } : {},
1237
+ ...entry.reach !== void 0 ? { reach: entry.reach } : {},
1231
1238
  seeded: entry.protected === true && entry.requestHash === void 0,
1232
1239
  hit: true,
1233
1240
  replaced: false
@@ -1249,13 +1256,15 @@ var createQueryEngine = (engineConfig) => {
1249
1256
  const callerOf = (policy, scope, tables) => ({
1250
1257
  bindings: scopeBindings(behaviors ?? {}, tables, scope),
1251
1258
  read: async (dsl) => {
1252
- const { compiled, warnings } = runPipeline(pruneOptional(dsl, "all"), policy);
1259
+ const pruned = pruneOptional(dsl, "all");
1260
+ const { compiled, warnings, upgrades } = runPipeline(pruned, policy);
1253
1261
  requireScope(compiled, scope);
1254
- if (compiled.paramSlots.some((slot) => slot.kind === "semantic")) {
1262
+ if (compiled.paramSlots.some((slot) => slot.kind === "semantic" || slot.embed === true)) {
1255
1263
  return { rows: [], sql: compiled.sql, warnings: [...warnings, "Semantic params present \u2014 execution skipped, SQL structure validated only"] };
1256
1264
  }
1257
1265
  const params = compiled.paramSlots.map((slot) => slot.kind === "scope" ? scope[slot.key] : null);
1258
- return { rows: await adapter.execute(compiled, params), sql: compiled.sql, warnings };
1266
+ const { rows, warnings: upgradeWarnings } = upgradeOf(await adapter.execute(compiled, params), upgrades);
1267
+ return { rows, sql: compiled.sql, warnings: [...warnings, ...upgradeWarnings] };
1259
1268
  }
1260
1269
  });
1261
1270
  const generateMissingDsl = async (validRequest, flightKey, negKey, entities, policy, scope) => {
@@ -1307,9 +1316,10 @@ var createQueryEngine = (engineConfig) => {
1307
1316
  };
1308
1317
  return execute(ir, source);
1309
1318
  };
1310
- const executeAndMap = async (compiled, validRequest, cachedIr, context, scope) => {
1319
+ const executeAndMap = async (compiled, validRequest, cachedIr, context, scope, upgrades) => {
1311
1320
  const execStart = Date.now();
1312
- const rows = await executeQuery(compiled, context, scope, adapter, embed);
1321
+ const stored = await executeQuery(compiled, context, scope, adapter, embed);
1322
+ const { rows, warnings: upgradeWarnings } = upgradeOf(stored, upgrades);
1313
1323
  const executionMs = Date.now() - execStart;
1314
1324
  emit({ type: "query.rows", count: rows.length, executionMs });
1315
1325
  let result = rows;
@@ -1331,17 +1341,17 @@ var createQueryEngine = (engineConfig) => {
1331
1341
  }
1332
1342
  if (mappingMs !== void 0) emit({ type: "query.mapped", mappingMs });
1333
1343
  }
1334
- return { result, rowCount: rows.length, executionMs, mappingMs, mappedIr, ...mappedConfig !== void 0 ? { mappedConfig } : {} };
1344
+ return { result, storedRowCount: stored.length, upgradeWarnings, executionMs, mappingMs, mappedIr, ...mappedConfig !== void 0 ? { mappedConfig } : {} };
1335
1345
  };
1336
1346
  const execute$1 = async (request, options) => {
1337
1347
  if (exceedsDepth(request)) throw new VexError("invalid_request", `Invalid request: ${depthRefusal()}`);
1338
- const parsed = QueryRequestSchema.safeParse(request);
1348
+ const parsed = QueryRequestSchema.safeParse(dropNullIntentAndFingerprint(request));
1339
1349
  if (!parsed.success) {
1340
1350
  throw new VexError("invalid_request", `Invalid request: ${parsed.error.message}`);
1341
1351
  }
1342
1352
  const validRequest = parsed.data;
1343
1353
  const scope = options?.scope ?? {};
1344
- const activePolicy = options?.scopePolicy ?? scopePolicy;
1354
+ let activePolicy = options?.scopePolicy ?? scopePolicy;
1345
1355
  const t0 = Date.now();
1346
1356
  const hasRequest = validRequest.shape !== void 0 && validRequest.shape !== null;
1347
1357
  if (validRequest.fingerprint === void 0 && !hasRequest) {
@@ -1359,6 +1369,7 @@ var createQueryEngine = (engineConfig) => {
1359
1369
  });
1360
1370
  const cached = await resolveFingerprint(validRequest, hasRequest, requestHash, scope);
1361
1371
  emit({ type: "query.cache", hit: cached.hit, fingerprint: cached.fingerprint, replaced: cached.replaced });
1372
+ if (cached.reach !== void 0) activePolicy = await policyAtReach(cached.fingerprint, cached.reach, activePolicy, options);
1362
1373
  let dsl = cached.dsl;
1363
1374
  let agentMs;
1364
1375
  if (dsl === void 0) {
@@ -1380,7 +1391,7 @@ var createQueryEngine = (engineConfig) => {
1380
1391
  }
1381
1392
  const presence = presenceOf(validRequest.context);
1382
1393
  const shaped = pruneOptional(applySortContext(dsl, validRequest.context), presence);
1383
- const { compiled, warnings, engineLimit } = runPipeline(shaped, activePolicy, cached.seeded === true);
1394
+ const { compiled, warnings, upgrades, engineLimit } = runPipeline(shaped, activePolicy, cached.seeded === true);
1384
1395
  noteVariant(cached.fingerprint, presenceSignature(dsl, presence), warnings);
1385
1396
  emit({ type: "query.sql", sql: compiled.sql, warnings });
1386
1397
  requireScope(compiled, scope);
@@ -1406,7 +1417,11 @@ var createQueryEngine = (engineConfig) => {
1406
1417
  const reactiveIr = cached.cachedIr;
1407
1418
  if (cached.hit && cached.refresh === "reactive" && (effectiveRequest.shape === void 0 || reactiveIr !== void 0)) {
1408
1419
  const shape = effectiveRequest.shape;
1409
- const shapeRows = (rows2) => shape === void 0 || reactiveIr === void 0 ? rows2 : mapRows(rows2, shape, reactiveIr, context, scope);
1420
+ const shapeRows = (stored) => {
1421
+ const { rows: rows2, warnings: upgradeWarnings3 } = upgradeOf(stored, upgrades);
1422
+ const result3 = shape === void 0 || reactiveIr === void 0 ? rows2 : mapRows(rows2, shape, reactiveIr, context, scope);
1423
+ return { result: result3, upgradeWarnings: upgradeWarnings3 };
1424
+ };
1410
1425
  const params = await resolveParams(compiled.paramSlots, context, scope, embed);
1411
1426
  const key = canonicalHash([compiled.sql, params]);
1412
1427
  const source = { tables: [...discoverEntities(shaped)], fetch: () => adapter.execute(compiled, params) };
@@ -1414,10 +1429,10 @@ var createQueryEngine = (engineConfig) => {
1414
1429
  const rows = await live.read(key, source);
1415
1430
  const executionMs2 = Date.now() - execStart;
1416
1431
  emit({ type: "query.rows", count: rows.length, executionMs: executionMs2 });
1417
- const result2 = shapeRows(rows);
1418
- const metaOf = (rowCount2) => {
1419
- const cut2 = cutNote(engineLimit, shaped.limit, rowCount2, shape, validRequest.fingerprint);
1420
- const said2 = cut2 === void 0 ? warnings : [...warnings, cut2];
1432
+ const { result: result2, upgradeWarnings: upgradeWarnings2 } = shapeRows(rows);
1433
+ const metaOf = (rowCount, upgraded) => {
1434
+ const cut2 = cutNote(engineLimit, shaped.limit, rowCount, shape, validRequest.fingerprint);
1435
+ const said2 = [...warnings, ...upgraded, ...cut2 === void 0 ? [] : [cut2]];
1421
1436
  return {
1422
1437
  cache: {
1423
1438
  hit: cached.hit,
@@ -1430,29 +1445,30 @@ var createQueryEngine = (engineConfig) => {
1430
1445
  };
1431
1446
  const { signal, onChange } = options ?? {};
1432
1447
  if (signal !== void 0 && onChange !== void 0) {
1433
- let lastHash = canonicalHash(result2);
1448
+ let lastHash = canonicalHash([result2, upgradeWarnings2]);
1434
1449
  live.follow(key, source, rows, {
1435
1450
  deliver: (next) => {
1436
- const nextResult = shapeRows(next);
1437
- const nextHash = canonicalHash(nextResult);
1451
+ const { result: nextResult, upgradeWarnings: nextUpgradeWarnings } = shapeRows(next);
1452
+ const nextHash = canonicalHash([nextResult, nextUpgradeWarnings]);
1438
1453
  if (nextHash === lastHash) return;
1439
1454
  lastHash = nextHash;
1440
- onChange({ result: nextResult, meta: metaOf(next.length) });
1455
+ onChange({ result: nextResult, meta: metaOf(next.length, nextUpgradeWarnings) });
1441
1456
  }
1442
1457
  }, signal);
1443
1458
  }
1444
1459
  emit({ type: "query.done", totalMs: Date.now() - t0 });
1445
- return { result: result2, meta: { ...metaOf(rows.length), timing: { executionMs: executionMs2 } } };
1460
+ return { result: result2, meta: { ...metaOf(rows.length, upgradeWarnings2), timing: { executionMs: executionMs2 } } };
1446
1461
  }
1447
- const { result, rowCount, executionMs, mappingMs, mappedIr, mappedConfig } = await executeAndMap(
1462
+ const { result, storedRowCount, upgradeWarnings, executionMs, mappingMs, mappedIr, mappedConfig } = await executeAndMap(
1448
1463
  compiled,
1449
1464
  effectiveRequest,
1450
1465
  cached.cachedIr,
1451
1466
  context,
1452
- scope
1467
+ scope,
1468
+ upgrades
1453
1469
  );
1454
- const cut = cutNote(engineLimit, shaped.limit, rowCount, effectiveRequest.shape, validRequest.fingerprint);
1455
- const said = cut === void 0 ? warnings : [...warnings, cut];
1470
+ const cut = cutNote(engineLimit, shaped.limit, storedRowCount, effectiveRequest.shape, validRequest.fingerprint);
1471
+ const said = [...warnings, ...upgradeWarnings, ...cut === void 0 ? [] : [cut]];
1456
1472
  if (!cached.hit) {
1457
1473
  const now = Date.now();
1458
1474
  const entry = {
@@ -1499,6 +1515,7 @@ var createQueryEngine = (engineConfig) => {
1499
1515
  getDslSchema,
1500
1516
  getSchema,
1501
1517
  cache,
1518
+ ...scopePolicy !== void 0 ? { scopePolicy } : {},
1502
1519
  invalidate: live.invalidate,
1503
1520
  rows: { stats: live.stats, stop: live.stop }
1504
1521
  };
@@ -1546,6 +1563,8 @@ var COLUMNS_QUERY = `
1546
1563
  c.udt_name,
1547
1564
  c.is_nullable,
1548
1565
  c.column_default,
1566
+ c.is_identity,
1567
+ c.identity_generation,
1549
1568
  CASE
1550
1569
  WHEN c.data_type = 'USER-DEFINED' THEN c.udt_name
1551
1570
  WHEN c.data_type = 'ARRAY' THEN c.udt_name
@@ -1655,8 +1674,8 @@ var introspectPostgres = async (pool, options) => {
1655
1674
  const rowCountMap = /* @__PURE__ */ new Map();
1656
1675
  for (const row of rowCountsResult.rows) {
1657
1676
  const table = row["table_name"];
1658
- const count = Number(row["row_count"] ?? 0);
1659
- rowCountMap.set(table, count);
1677
+ const count2 = Number(row["row_count"] ?? 0);
1678
+ rowCountMap.set(table, count2);
1660
1679
  }
1661
1680
  const columnsByTable = /* @__PURE__ */ new Map();
1662
1681
  for (const row of columnsResult.rows) {
@@ -1665,7 +1684,7 @@ var introspectPostgres = async (pool, options) => {
1665
1684
  const dataType = row["effective_type"];
1666
1685
  const fullType = row["full_type"];
1667
1686
  const isNullable = row["is_nullable"];
1668
- const colDefault = row["column_default"];
1687
+ const colDefault = row["column_default"] ?? (row["is_identity"] === "YES" ? `GENERATED ${String(row["identity_generation"])} AS IDENTITY` : null);
1669
1688
  const colDescription = row["description"];
1670
1689
  const tablePks = pkMap.get(table);
1671
1690
  const isPk = tablePks !== void 0 && tablePks.has(colName);
@@ -1771,22 +1790,23 @@ var mapIndexType = (pgType) => {
1771
1790
  };
1772
1791
 
1773
1792
  // src/adapters/postgres/compile.ts
1774
- var compileQuery = (resolved) => {
1793
+ var compileQuery = (resolved, namespace) => {
1775
1794
  const paramSlots = [];
1776
- const sql = compileLevel(resolved, paramSlots, { value: 0 });
1795
+ const sql = compileLevel(resolved, paramSlots, { value: 0 }, namespace);
1777
1796
  const contextContract = {};
1778
1797
  for (const slot of paramSlots) {
1779
1798
  contextContract[slot.key] = { type: slot.type, kind: slot.kind };
1780
1799
  }
1781
1800
  return { sql, paramSlots, contextContract };
1782
1801
  };
1783
- var compileLevel = (resolved, paramSlots, paramCounter) => {
1802
+ var compileLevel = (resolved, paramSlots, paramCounter, namespace) => {
1784
1803
  const ctx = {
1785
1804
  resolvedPaths: resolved.filter?.resolvedPaths ?? /* @__PURE__ */ new Map(),
1786
1805
  aliasMap: resolved.aliasMap,
1787
1806
  paramSlots,
1788
1807
  paramCounter,
1789
- ...resolved.existsMap !== void 0 ? { existsMap: resolved.existsMap } : {}
1808
+ ...resolved.existsMap !== void 0 ? { existsMap: resolved.existsMap } : {},
1809
+ ...namespace !== void 0 ? { namespace } : {}
1790
1810
  };
1791
1811
  const sqlParts = [];
1792
1812
  const selectParts = [];
@@ -1794,7 +1814,7 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
1794
1814
  selectParts.push("DISTINCT");
1795
1815
  }
1796
1816
  const fieldColumns = resolved.fields.map(
1797
- (f) => `${f.alias}.${f.column} AS ${quoteIdent(f.outputName)}`
1817
+ (f) => `${columnSql(f.alias, f.column)} AS ${quoteIdent(f.outputName)}`
1798
1818
  );
1799
1819
  const computeColumns = resolved.computes.map((c) => {
1800
1820
  const expr = compileCompute(c.expression, ctx);
@@ -1813,9 +1833,9 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
1813
1833
  const firstSource = resolved.sources[0];
1814
1834
  if (firstSource !== void 0) {
1815
1835
  if (firstSource.subquery !== void 0) {
1816
- sqlParts.push(`FROM (${compileLevel(firstSource.subquery, paramSlots, paramCounter)}) AS ${firstSource.alias}`);
1836
+ sqlParts.push(`FROM (${compileLevel(firstSource.subquery, paramSlots, paramCounter, namespace)}) AS ${sqlName(firstSource.alias)}`);
1817
1837
  } else if (firstSource.table !== void 0) {
1818
- sqlParts.push(`FROM ${firstSource.table} AS ${firstSource.alias}`);
1838
+ sqlParts.push(`FROM ${tableSql(firstSource.table, namespace)} AS ${sqlName(firstSource.alias)}`);
1819
1839
  }
1820
1840
  }
1821
1841
  for (const join of resolved.joins) {
@@ -1828,9 +1848,9 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
1828
1848
  ];
1829
1849
  const on = conditions.join(" AND ");
1830
1850
  if (joinSource.subquery !== void 0) {
1831
- sqlParts.push(`${keyword} (${compileLevel(joinSource.subquery, paramSlots, paramCounter)}) AS ${join.toAlias} ON ${on}`);
1851
+ sqlParts.push(`${keyword} (${compileLevel(joinSource.subquery, paramSlots, paramCounter, namespace)}) AS ${sqlName(join.toAlias)} ON ${on}`);
1832
1852
  } else {
1833
- sqlParts.push(`${keyword} ${join.toTable} AS ${join.toAlias} ON ${on}`);
1853
+ sqlParts.push(`${keyword} ${tableSql(join.toTable, namespace)} AS ${sqlName(join.toAlias)} ON ${on}`);
1834
1854
  }
1835
1855
  }
1836
1856
  }
@@ -1838,9 +1858,9 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
1838
1858
  for (const source of resolved.sources) {
1839
1859
  if (source.alias === firstSource?.alias || joinedAliases.has(source.alias)) continue;
1840
1860
  if (source.subquery !== void 0) {
1841
- sqlParts.push(`CROSS JOIN (${compileLevel(source.subquery, paramSlots, paramCounter)}) AS ${source.alias}`);
1861
+ sqlParts.push(`CROSS JOIN (${compileLevel(source.subquery, paramSlots, paramCounter, namespace)}) AS ${sqlName(source.alias)}`);
1842
1862
  } else if (source.table !== void 0) {
1843
- sqlParts.push(`CROSS JOIN ${source.table} AS ${source.alias}`);
1863
+ sqlParts.push(`CROSS JOIN ${tableSql(source.table, namespace)} AS ${sqlName(source.alias)}`);
1844
1864
  }
1845
1865
  }
1846
1866
  if (resolved.filter !== void 0) {
@@ -1848,7 +1868,7 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
1848
1868
  sqlParts.push(`WHERE ${whereClause}`);
1849
1869
  }
1850
1870
  if (resolved.groupBy.length > 0) {
1851
- const groupByParts = resolved.groupBy.map((f) => `${f.alias}.${f.column}`);
1871
+ const groupByParts = resolved.groupBy.map((f) => columnSql(f.alias, f.column));
1852
1872
  sqlParts.push(`GROUP BY ${groupByParts.join(", ")}`);
1853
1873
  }
1854
1874
  if (resolved.sort.length > 0) {
@@ -1856,13 +1876,13 @@ var compileLevel = (resolved, paramSlots, paramCounter) => {
1856
1876
  if (typeof s.field === "string") {
1857
1877
  return `${quoteIdent(s.field)} ${s.dir === "desc" ? "DESC" : "ASC"}`;
1858
1878
  }
1859
- return `${s.field.alias}.${s.field.column} ${s.dir === "desc" ? "DESC" : "ASC"}`;
1879
+ return `${columnSql(s.field.alias, s.field.column)} ${s.dir === "desc" ? "DESC" : "ASC"}`;
1860
1880
  });
1861
1881
  sqlParts.push(`ORDER BY ${orderByParts.join(", ")}`);
1862
1882
  } else if (resolved.semantic !== void 0) {
1863
1883
  const { field, contextPath } = resolved.semantic;
1864
- const position = paramSlots.findIndex((slot) => slot.kind === "semantic" && slot.key === contextPath) + 1;
1865
- if (position > 0) sqlParts.push(`ORDER BY ${field.alias}.${field.column} <=> $${position} ASC`);
1884
+ const position = paramSlots.findIndex((slot) => (slot.kind === "semantic" || slot.embed === true) && slot.key === contextPath) + 1;
1885
+ if (position > 0) sqlParts.push(`ORDER BY ${columnSql(field.alias, field.column)} <=> $${position} ASC`);
1866
1886
  }
1867
1887
  if (resolved.limit !== void 0) {
1868
1888
  if (!Number.isInteger(resolved.limit) || resolved.limit < 1) {
@@ -1917,6 +1937,7 @@ var coerceNumericColumns = (rows, fields) => {
1917
1937
  };
1918
1938
  var createPostgresAdapter = (config) => {
1919
1939
  const { pool, schema = "public", exclude } = config;
1940
+ const namespace = config.qualifyTables === true ? schema : void 0;
1920
1941
  const capabilities = {
1921
1942
  vectorSearch: true,
1922
1943
  fuzzyMatch: false,
@@ -1928,12 +1949,15 @@ var createPostgresAdapter = (config) => {
1928
1949
  windowFunctions: true,
1929
1950
  statementTimeout: true
1930
1951
  };
1931
- const introspect = async (options) => introspectPostgres(pool, {
1932
- ...options,
1933
- schema: options?.schema ?? schema,
1934
- exclude: options?.exclude ?? exclude
1935
- });
1936
- const compile2 = (resolved) => compileQuery(resolved);
1952
+ const introspect = async (options) => {
1953
+ const introspected = await introspectPostgres(pool, {
1954
+ ...options,
1955
+ schema: options?.schema ?? schema,
1956
+ exclude: options?.exclude ?? exclude
1957
+ });
1958
+ return namespace === void 0 ? introspected : { ...introspected, namespace };
1959
+ };
1960
+ const compile2 = (resolved) => compileQuery(resolved, namespace);
1937
1961
  let perStatementMs;
1938
1962
  const limitReads = async (ms) => {
1939
1963
  perStatementMs = void 0;
@@ -1976,7 +2000,7 @@ var vexGuide = () => [
1976
2000
  ' - A value the query filters with ILIKE is a pattern: "%text%" matches contains.',
1977
2001
  ' - 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".',
1978
2002
  "",
1979
- "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.",
2003
+ "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.",
1980
2004
  "",
1981
2005
  "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."
1982
2006
  ].join("\n");
@@ -2212,7 +2236,10 @@ var createPostgresCache = (config) => {
2212
2236
  }
2213
2237
  return out;
2214
2238
  };
2215
- return { init, sequence, get, set, delete: del, clear, keys, entries };
2239
+ const touch = async (key, lastUsedAt) => {
2240
+ await pool.query(`UPDATE ${qualified} SET last_used_at = $2 WHERE key = $1`, [key, new Date(lastUsedAt)]);
2241
+ };
2242
+ return { init, sequence, get, set, delete: del, clear, keys, entries, touch };
2216
2243
  };
2217
2244
 
2218
2245
  // src/cache/tiered.ts
@@ -2274,7 +2301,22 @@ var createTieredCache = (config) => {
2274
2301
  fireAndForget(l2.clear(), onError);
2275
2302
  };
2276
2303
  const keys = async () => l1.keys();
2277
- return { init, get, set, delete: del, clear, keys, ...l2.sequence !== void 0 ? { sequence: l2.sequence } : {} };
2304
+ const { touch: touchL1 } = l1;
2305
+ const { touch: touchL2 } = l2;
2306
+ const touch = touchL1 === void 0 || touchL2 === void 0 ? void 0 : async (key, lastUsedAt) => {
2307
+ await touchL1(key, lastUsedAt);
2308
+ fireAndForget(touchL2(key, lastUsedAt), onError);
2309
+ };
2310
+ return {
2311
+ init,
2312
+ get,
2313
+ set,
2314
+ delete: del,
2315
+ clear,
2316
+ keys,
2317
+ ...touch !== void 0 ? { touch } : {},
2318
+ ...l2.sequence !== void 0 ? { sequence: l2.sequence } : {}
2319
+ };
2278
2320
  };
2279
2321
  var same = (a, b) => a === void 0 || b === void 0 ? a === b : canonicalText(a) === canonicalText(b);
2280
2322
  var seedCache = async (cache, entries) => {
@@ -2315,6 +2357,6 @@ var seedCache = async (cache, entries) => {
2315
2357
  }
2316
2358
  };
2317
2359
 
2318
- export { SCOPE_VERBS, analyze, createMemoryCache, createPostgresAdapter, createPostgresCache, createQueryEngine, createScopePolicy, createTieredCache, discoverEntities, mergeScopePolicies, resolve, scopeBindings, scopeGrants, scopeProfiles, seedCache, validateEntry, vexGuide };
2360
+ export { SCOPE_VERBS, UNREADABLE_MODES, UpgradedColumnsSchema, analyze, createMemoryCache, createPostgresAdapter, createPostgresCache, createQueryEngine, createScopePolicy, createTieredCache, mergeScopePolicies, resolve, scopeBindings, scopeGrants, scopeProfiles, seedCache, validateEntry, vexGuide };
2319
2361
  //# sourceMappingURL=index.js.map
2320
2362
  //# sourceMappingURL=index.js.map