@niscorp/vex 0.3.0 → 0.4.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.
- package/CHANGELOG.md +40 -0
- package/DESIGN.md +30 -14
- package/DOCS.md +65 -13
- package/dist/adapters/express/index.cjs +7 -25
- package/dist/adapters/express/index.cjs.map +1 -1
- package/dist/adapters/express/index.d.cts +3 -2
- package/dist/adapters/express/index.d.ts +3 -2
- package/dist/adapters/express/index.js +3 -2
- package/dist/adapters/express/index.js.map +1 -1
- package/dist/adapters/hono/index.cjs +7 -25
- package/dist/adapters/hono/index.cjs.map +1 -1
- package/dist/adapters/hono/index.d.cts +3 -2
- package/dist/adapters/hono/index.d.ts +3 -2
- package/dist/adapters/hono/index.js +3 -2
- package/dist/adapters/hono/index.js.map +1 -1
- package/dist/adapters/pglite/index.cjs.map +1 -1
- package/dist/adapters/pglite/index.js.map +1 -1
- package/dist/agent/index.cjs +9 -14
- package/dist/agent/index.cjs.map +1 -1
- package/dist/agent/index.d.cts +3 -2
- package/dist/agent/index.d.ts +3 -2
- package/dist/agent/index.js +8 -9
- package/dist/agent/index.js.map +1 -1
- package/dist/{chunk-IQM4SQE2.js → chunk-7F2OH4IP.js} +8 -22
- package/dist/chunk-7F2OH4IP.js.map +1 -0
- package/dist/chunk-F7RDSWYF.js +7 -0
- package/dist/chunk-F7RDSWYF.js.map +1 -0
- package/dist/{chunk-H4BHW76Q.js → chunk-UPQMKAAX.js} +6 -24
- package/dist/chunk-UPQMKAAX.js.map +1 -0
- package/dist/chunk-XTOK7YOR.js +18 -0
- package/dist/chunk-XTOK7YOR.js.map +1 -0
- package/dist/{handler-BGCL6_Si.d.ts → handler-Bw7xVmBM.d.ts} +2 -1
- package/dist/{handler-CMrjTXNx.d.cts → handler-Cy0gNM6K.d.cts} +2 -1
- package/dist/index.cjs +44 -90
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +17 -63
- package/dist/index.d.ts +17 -63
- package/dist/index.js +46 -74
- package/dist/index.js.map +1 -1
- package/dist/migrations/index.cjs +173 -0
- package/dist/migrations/index.cjs.map +1 -0
- package/dist/migrations/index.d.cts +20 -0
- package/dist/migrations/index.d.ts +20 -0
- package/dist/migrations/index.js +23 -0
- package/dist/migrations/index.js.map +1 -0
- package/dist/query.schema-B-LVNfyX.d.cts +461 -0
- package/dist/query.schema-B-LVNfyX.d.ts +461 -0
- package/dist/{types-Bi-Lg86b.d.cts → types-Bs_9VM9p.d.ts} +16 -583
- package/dist/{types-Bi-Lg86b.d.ts → types-DO-rYZci.d.cts} +16 -583
- package/package.json +17 -7
- package/dist/chunk-H4BHW76Q.js.map +0 -1
- package/dist/chunk-IQM4SQE2.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,45 @@
|
|
|
1
1
|
# @niscorp/vex
|
|
2
2
|
|
|
3
|
+
## 0.4.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 4068f98: Vex keeps what an entry it writes was written from, and says who asks when it looks one up. **Breaking.**
|
|
8
|
+
|
|
9
|
+
BREAKING — approved by moccadroid, 2026-10-14: a `mapToShape` an app writes answers `config`, the Prism config its `ir` was compiled from, beside `ir` and `transformed`. `createShapeMapper` does.
|
|
10
|
+
- **A query vex writes keeps its mapping's Prism config** (`mapping`, on the entry), beside the compiled form. A compiled form can neither be read back as a config nor upgraded when Prism changes.
|
|
11
|
+
- **The Postgres cache's table gets a `mapping` column**, in a new migration, `nisc.vex.cache/2`. A deployment that runs its migrations before it boots runs that one first.
|
|
12
|
+
- **`CacheBackend.get(key, scope?)`**: the two lookups that replay an entry hand the cache the scope of whoever asks, so a cache can answer an entry to some callers and not to others. A backend that takes no scope works as before.
|
|
13
|
+
- **`@niscorp/vex/migrations`** exports `VEX_SEQUENCE`, one stored kind, `nisc.vex/entry` (an entry as written, its `mapping` a `nisc.prism/config`), and `VEX_SCHEMAS`.
|
|
14
|
+
|
|
15
|
+
## 0.3.1
|
|
16
|
+
|
|
17
|
+
### Patch Changes
|
|
18
|
+
|
|
19
|
+
- f62ee50: `applyScope` is marked deprecated, and DESIGN.md describes the scope functions as they are.
|
|
20
|
+
|
|
21
|
+
The engine checks access with `checkScope` and places row rules with `scopeResolved`, after resolution. `applyScope` stayed as an exported function that runs the access check and returns the query as it came, while DESIGN.md still described it as merging the row filters into the query. It now carries `@deprecated` with that sentence, and the Scope section of DESIGN.md describes `checkScope` and `scopeResolved`.
|
|
22
|
+
|
|
23
|
+
No behaviour changed.
|
|
24
|
+
|
|
25
|
+
**What to change:** nothing has to. A caller of `applyScope` gets the same check from `checkScope(entities, policy)`. A caller that relied on `applyScope` to filter rows was not being filtered: it goes through the engine, or calls `scopeResolved` on the resolved query.
|
|
26
|
+
|
|
27
|
+
- b4d24e9: DOCS.md and DESIGN.md state twenty facts about the API that were written only in source comments.
|
|
28
|
+
|
|
29
|
+
Among them: the adapter's `exclude` option and `statementTimeouts: false` on a pool; what `scopeBindings` returns; that a composite foreign key is one relation joined on every pair; that a behavior's `write` rules apply to every write verb; when an `upsert` inserts; that nothing in vex calls `sweepCache`; what the Postgres and tiered caches hand `onError`; that `signal` and `onChange` only work together; what the hono adapter does when `getPolicy` returns `undefined` and when no policy covers a write; and what an adapter's `limitReads` and `validateEntry` return.
|
|
30
|
+
|
|
31
|
+
No behaviour changed.
|
|
32
|
+
|
|
33
|
+
**What to change:** nothing.
|
|
34
|
+
|
|
35
|
+
- bf6496f: A read with more than one parameterised subquery compiles, and each subquery binds its own values.
|
|
36
|
+
|
|
37
|
+
A subquery was compiled apart from its parent, so its parameters were numbered from `$1` again while its values were appended to the parent's list. One parameterised subquery in first place worked. Two of them, or a parameter of the parent ahead of one, produced a statement Postgres refuses (`bind message supplies 2 parameters, but prepared statement requires 1`). A scope rule on a table inside a subquery is such a parameter, so two subqueries over scoped tables were refused as well.
|
|
38
|
+
|
|
39
|
+
A subquery now compiles into its parent's parameter list, as an `exists` already did. A read that compiled before compiles to the same SQL.
|
|
40
|
+
|
|
41
|
+
**What to change:** nothing. A read that was rewritten to avoid two parameterised subqueries (conditional sums over one source, say) can be written with the subqueries again; it does not have to be.
|
|
42
|
+
|
|
3
43
|
## 0.3.0
|
|
4
44
|
|
|
5
45
|
### Minor Changes
|
package/DESIGN.md
CHANGED
|
@@ -151,21 +151,29 @@ JSON Schema and better model adherence.
|
|
|
151
151
|
|
|
152
152
|
### Scope
|
|
153
153
|
|
|
154
|
-
|
|
154
|
+
Three functions, in two stages:
|
|
155
155
|
|
|
156
156
|
- `discoverEntities(dsl)` walks every place an entity name can appear — `from`,
|
|
157
157
|
field paths, filter paths (recursively through `and`/`or`/`not`), compute and
|
|
158
158
|
aggregate references, `groupBy`, `sort`, and into subqueries — and returns the
|
|
159
159
|
set of referenced entities. No schema needed; pure string extraction.
|
|
160
|
-
- `
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
160
|
+
- `checkScope(entities, policy)` looks up each discovered entity in the policy.
|
|
161
|
+
`public` rules pass; `deny` (or no rule under a `default: 'deny'` policy)
|
|
162
|
+
throws `VexScopeError`. It runs before resolution and changes nothing.
|
|
163
|
+
- `scopeResolved(resolved, policy)` places each table's row rules on the
|
|
164
|
+
resolved query, as `column = $scope` predicates: in WHERE for a driving or
|
|
165
|
+
inner-joined table, in the join's ON for a left-joined one, and inside every
|
|
166
|
+
subquery and `exists`. It runs after resolution, because where a rule goes
|
|
167
|
+
depends on how its table is joined (see decision 4 under *Key design
|
|
168
|
+
decisions*).
|
|
169
|
+
|
|
170
|
+
The analyzer and the compiler never know scope exists: they process a resolved
|
|
171
|
+
query that happens to carry extra predicates.
|
|
172
|
+
|
|
173
|
+
`applyScope(dsl, entities, policy)` is deprecated. It runs `checkScope` and
|
|
174
|
+
returns the query as it came, with no row rule added; a caller that needs rows
|
|
175
|
+
filtered goes through the engine, or calls `scopeResolved` on the resolved
|
|
176
|
+
query.
|
|
169
177
|
|
|
170
178
|
### Engine (deterministic pipeline)
|
|
171
179
|
|
|
@@ -221,6 +229,12 @@ Compilation is adapter-internal — there is no shared compiler in `engine/`; ea
|
|
|
221
229
|
adapter owns its full SQL dialect (the Postgres adapter has its own
|
|
222
230
|
filter/compute/aggregate SQL generation under `adapters/postgres/`).
|
|
223
231
|
|
|
232
|
+
An adapter may also implement `limitReads(ms)`. The engine calls it at
|
|
233
|
+
`introspect()` with `config.statementTimeoutMs` (0 leaves reads unbounded), and
|
|
234
|
+
it answers where the limit is held: `'connection'` (the connection's own
|
|
235
|
+
setting already covers it), `'statement'` (set per read) or `'unenforced'`, on
|
|
236
|
+
which the engine warns. An adapter without it runs reads unbounded.
|
|
237
|
+
|
|
224
238
|
A `CompiledQuery` is `{ sql, paramSlots, contextContract }`. The ordered
|
|
225
239
|
`paramSlots` array drives positional binding (`$1`, `$2`, …); each slot knows
|
|
226
240
|
its `kind` (context/scope/semantic), `type`, and (for semantic) `dimensions`.
|
|
@@ -252,14 +266,15 @@ Identity is the **fingerprint** (see Cache v2 below). The supporting hashes:
|
|
|
252
266
|
impossible, so it isn't re-run until the TTL lapses or the schema changes).
|
|
253
267
|
- **Backends.** In-memory (`createMemoryCache`), durable Postgres
|
|
254
268
|
(`createPostgresCache`, jsonb table, server-side TTL, `protected`/
|
|
255
|
-
`last_used_at`/`request_hash` columns; the table is a strata sequence,
|
|
269
|
+
`last_used_at`/`request_hash`/`mapping` columns; the table is a strata sequence,
|
|
256
270
|
`nisc.vex.cache`, applied once through the ledger by `init()`;
|
|
257
271
|
validate-on-write and evict-on-read), and tiered (`createTieredCache`, L1 +
|
|
258
272
|
L2 read-through/write-through with `full`/`lazy`/`partial` warm-up). Every
|
|
259
273
|
backend implements the same `CacheBackend` contract; `init`/`entries` are
|
|
260
274
|
optional capabilities used for warm-up and the discovery overview.
|
|
261
275
|
- **Validation** (`validateEntry`) guards every write and every promotion into
|
|
262
|
-
memory, so a corrupt or schema-drifted row can never poison the cache.
|
|
276
|
+
memory, so a corrupt or schema-drifted row can never poison the cache. It
|
|
277
|
+
returns `null` for a valid entry and the reason, as a string, for any other.
|
|
263
278
|
- **GC** (`sweepCache`) evicts entries idle past `maxIdleMs`
|
|
264
279
|
(`lastUsedAt ?? createdAt`), skipping protected ones. Hygiene, not necessity.
|
|
265
280
|
|
|
@@ -572,8 +587,9 @@ The engine takes two optional hooks:
|
|
|
572
587
|
what the person asking could see — and it is keyed (single-flight, negative
|
|
573
588
|
cache) by request AND policy, because two callers who see different tables
|
|
574
589
|
are asking different agents.
|
|
575
|
-
- `mapToShape(rows, shape) → { ir, transformed }` — raw rows → requested
|
|
576
|
-
returning a compiled Prism IR that is cached for reuse
|
|
590
|
+
- `mapToShape(rows, shape) → { ir, config, transformed }` — raw rows → requested
|
|
591
|
+
shape, returning a compiled Prism IR that is cached for reuse, and the Prism
|
|
592
|
+
config it was compiled from, which is kept beside it (`mapping`).
|
|
577
593
|
|
|
578
594
|
This is the seam that keeps the core deterministic. Vex ships a reference
|
|
579
595
|
implementation of both, built on `@niscorp/cortex` and `@niscorp/prism` and
|
package/DOCS.md
CHANGED
|
@@ -157,7 +157,7 @@ type QueryEngineConfig = {
|
|
|
157
157
|
cache?: CacheBackend; // default: createMemoryCache()
|
|
158
158
|
onEvent?: VexEventHandler; // pipeline event stream
|
|
159
159
|
generateDsl?: (request, schema, caller) => Promise<Query>;
|
|
160
|
-
mapToShape?: (rows, shape) => Promise<{ ir: CompiledIr; transformed: JsonValue }>;
|
|
160
|
+
mapToShape?: (rows, shape) => Promise<{ ir: CompiledIr; config: unknown; transformed: JsonValue }>;
|
|
161
161
|
embed?: (text, dimensions?) => Promise<number[]>; // text→vector for semantic filters
|
|
162
162
|
behaviors?: ScopeBehaviors; // which columns a scope key is bound to (see below)
|
|
163
163
|
rows?: LiveRowsConfig; // the rows cache behind `refresh: 'reactive'`
|
|
@@ -178,9 +178,14 @@ type QueryEngineConfig = {
|
|
|
178
178
|
```
|
|
179
179
|
|
|
180
180
|
- `config.entities`, when set, restricts `introspect()` to those tables.
|
|
181
|
+
- `createPostgresAdapter({ pool, exclude })` names tables the adapter never
|
|
182
|
+
reports: `introspect()` leaves them out. It is for tables the host owns that
|
|
183
|
+
are not application data, such as a migration journal.
|
|
181
184
|
- `config.statementTimeoutMs` is enforced by the database (`statement_timeout`),
|
|
182
185
|
set up at `introspect()`. A database that cannot enforce it (PGlite) runs
|
|
183
|
-
reads unbounded and the engine warns each time `introspect()` runs.
|
|
186
|
+
reads unbounded and the engine warns each time `introspect()` runs. A `PgPool`
|
|
187
|
+
declares such a database with `statementTimeouts: false`, as the pool from
|
|
188
|
+
`createPglitePool` does.
|
|
184
189
|
- `config.maxPresenceVariants` is not a limit on what runs: past it, a response
|
|
185
190
|
carries a warning that the entry has compiled that many distinct
|
|
186
191
|
optional-key combinations.
|
|
@@ -189,6 +194,9 @@ type QueryEngineConfig = {
|
|
|
189
194
|
reads it for one thing: which columns a scope key is bound to, so a generation
|
|
190
195
|
can be told who its caller is (`GenerationCaller.bindings`). `introspect()`
|
|
191
196
|
throws `execution_error` if a rule names a column the database does not have.
|
|
197
|
+
`scopeBindings(behaviors, tables, scope)` returns that list for the given
|
|
198
|
+
tables: one entry per table, column and key, sorted, and only for keys
|
|
199
|
+
`scope` holds a value for.
|
|
192
200
|
- **`rows`** sizes the reactive rows cache — see
|
|
193
201
|
[Reactive reads](#reactive-reads-refresh).
|
|
194
202
|
- `defaultLimit` is applied when a DSL omits `limit`. `maxLimit` clamps a larger
|
|
@@ -584,7 +592,9 @@ outer query as `alias.field` — every selected field (under its `as`, if
|
|
|
584
592
|
aliased) plus every `compute`/`aggregate` alias.
|
|
585
593
|
|
|
586
594
|
**Joins.** String entity sources are joined automatically by foreign key; a
|
|
587
|
-
source with no FK path to the others is an error. A
|
|
595
|
+
source with no FK path to the others is an error. A composite foreign key is
|
|
596
|
+
one relation in the schema (`localFields[i]` pairs with `foreignFields[i]`) and
|
|
597
|
+
joins on every pair. A **nullable** FK compiles to
|
|
588
598
|
a `LEFT JOIN` — a null FK never silently drops the referencing row from the
|
|
589
599
|
read (the joined fields come back null); a non-nullable FK stays an inner
|
|
590
600
|
`JOIN` (equivalent — the column can't be null). Reverse one-to-many joins are
|
|
@@ -738,6 +748,10 @@ type ScopeRules = { read?: ScopeMatch[]; write?: ScopeRule[]; insert?: ScopeRule
|
|
|
738
748
|
type ScopeBehaviors = Record<string, ScopeRules | Record<string, ScopeRules>>;
|
|
739
749
|
```
|
|
740
750
|
|
|
751
|
+
A behavior's `write` rules apply to every write verb the grants carry, ahead of
|
|
752
|
+
that verb's own `insert`/`update`/`delete` rules; a delete takes only the
|
|
753
|
+
`match` rules among them.
|
|
754
|
+
|
|
741
755
|
### Scoping profiles
|
|
742
756
|
|
|
743
757
|
A table carries **either** one rule set — the shape above — **or several named
|
|
@@ -860,6 +874,9 @@ REQUIRE a `where` (a real vex `Filter`).
|
|
|
860
874
|
insert: { deal_id: { $context: 'deal_id' } } }
|
|
861
875
|
```
|
|
862
876
|
|
|
877
|
+
An `upsert` updates the row when the call's context carries its `key`, and
|
|
878
|
+
inserts when the key is absent or an empty string.
|
|
879
|
+
|
|
863
880
|
An array of ops is a batch and runs in ONE transaction (the client must
|
|
864
881
|
expose `transaction`; a batch on a non-transactional client is refused).
|
|
865
882
|
|
|
@@ -1138,6 +1155,7 @@ are not asking the same thing).
|
|
|
1138
1155
|
- A replay stamps `lastUsedAt` (at most once a minute per entry);
|
|
1139
1156
|
`sweepCache(cache, { maxIdleMs })` evicts entries idle past the limit,
|
|
1140
1157
|
skipping protected ones, and returns how many it evicted. Alive = used.
|
|
1158
|
+
Nothing in vex calls it: a host runs it at startup or on a timer.
|
|
1141
1159
|
- `protected: true` is written only by the seed path (`seedCache`) or an
|
|
1142
1160
|
explicit `handleFingerprintPatch` — never by a runtime query.
|
|
1143
1161
|
- `ExecuteOptions.locked` (and `VexHandlerConfig.locked`) makes an engine call
|
|
@@ -1173,6 +1191,8 @@ const cache = createMemoryCache();
|
|
|
1173
1191
|
**Postgres** — durable L2. Stores entries as `jsonb`, enforces TTL server-side,
|
|
1174
1192
|
validates on write, and evicts corrupt/stale rows on read. Used directly it
|
|
1175
1193
|
reads from Postgres on every `get`, so it is meant to sit behind an L1.
|
|
1194
|
+
`onError` receives a write that failed validation and a row evicted on read;
|
|
1195
|
+
without it the write throws and the eviction goes to `console.error`.
|
|
1176
1196
|
|
|
1177
1197
|
```typescript
|
|
1178
1198
|
const l2 = createPostgresCache({
|
|
@@ -1191,7 +1211,9 @@ collects `l2.sequence` (`nisc.vex.cache`) instead of calling `init()`.
|
|
|
1191
1211
|
|
|
1192
1212
|
**Tiered** — L1 (memory) + L2 (durable), read-through/write-through. Reads hit
|
|
1193
1213
|
L1; on an L1 miss it promotes a validated L2 entry into L1. Writes go to L1
|
|
1194
|
-
synchronously and L2 fire-and-forget.
|
|
1214
|
+
synchronously and L2 fire-and-forget. `onError` receives a failed L2 write and
|
|
1215
|
+
an invalid L2 entry that was dropped instead of promoted; without it both go to
|
|
1216
|
+
`console.error`.
|
|
1195
1217
|
|
|
1196
1218
|
```typescript
|
|
1197
1219
|
const cache = createTieredCache({
|
|
@@ -1210,6 +1232,27 @@ demand; `partial` preloads only the listed fingerprints and lazy-fills the
|
|
|
1210
1232
|
rest. The tiered cache is single-instance: separate processes keep separate
|
|
1211
1233
|
L1s.
|
|
1212
1234
|
|
|
1235
|
+
**Who asks.** The engine hands the two lookups that replay an entry the scope
|
|
1236
|
+
of whoever asks (`get(key, scope)`), so a cache a host writes can answer an
|
|
1237
|
+
entry to some callers and not to others. The three backends here answer every
|
|
1238
|
+
caller alike.
|
|
1239
|
+
|
|
1240
|
+
**What a query vex wrote keeps.** The query, the compiled mapping (`prismIr`)
|
|
1241
|
+
and the Prism config it was compiled from (`mapping`), which `mapToShape`
|
|
1242
|
+
answers as `config`. A compiled form can neither be read back as a config nor
|
|
1243
|
+
upgraded when Prism changes, so a host that keeps such an entry for longer
|
|
1244
|
+
keeps the config. The Postgres table has a column for it from
|
|
1245
|
+
`nisc.vex.cache/2` on: a deployment that runs its migrations before it boots
|
|
1246
|
+
runs that one first.
|
|
1247
|
+
|
|
1248
|
+
**An entry as a stored document.** `@niscorp/vex/migrations` exports
|
|
1249
|
+
`VEX_SEQUENCE`, a strata sequence with one kind, `nisc.vex/entry`: an entry as
|
|
1250
|
+
written, `{ dsl, mapping?, shape?, intent?, reach?, refresh? }`, without the
|
|
1251
|
+
fingerprint it is kept under, its `mapping` a `nisc.prism/config`. A host that
|
|
1252
|
+
stores entries stamps them with it and upgrades them where it reads them, as it
|
|
1253
|
+
does nova's and Prism's documents (`VEX_SCHEMAS` is what the grammar check
|
|
1254
|
+
snapshots).
|
|
1255
|
+
|
|
1213
1256
|
### Seeding
|
|
1214
1257
|
|
|
1215
1258
|
`seedCache(cache, entries)` turns authored entries into **protected** cache
|
|
@@ -1277,7 +1320,8 @@ type `Refresh`).
|
|
|
1277
1320
|
|
|
1278
1321
|
- **Following.** Pass `{ signal, onChange }` in `ExecuteOptions`: the returned
|
|
1279
1322
|
promise is the first answer; every later answer that differs goes to
|
|
1280
|
-
`onChange` until `signal` aborts.
|
|
1323
|
+
`onChange` until `signal` aborts. One without the other follows nothing, and
|
|
1324
|
+
both are ignored for a snapshot entry. Over HTTP there is no callback, so
|
|
1281
1325
|
`handleQuery(config, body, scope, live?)` takes an in-process `VexLive`
|
|
1282
1326
|
(`{ signal, onChange }`), and the hono adapter reads one from the request's
|
|
1283
1327
|
env under `VEX_LIVE_ENV` (the third argument of `app.request`).
|
|
@@ -1312,7 +1356,7 @@ free-form requests.
|
|
|
1312
1356
|
```typescript
|
|
1313
1357
|
type GenerateDsl = (request: QueryRequest, schema: DatabaseSchema, caller: GenerationCaller) => Promise<Query>;
|
|
1314
1358
|
type MapToShape = (rows: Row[], shape: unknown) =>
|
|
1315
|
-
Promise<{ ir: CompiledIr; transformed: JsonValue }>;
|
|
1359
|
+
Promise<{ ir: CompiledIr; config: unknown; transformed: JsonValue }>;
|
|
1316
1360
|
|
|
1317
1361
|
type GenerationCaller = {
|
|
1318
1362
|
read: (dsl: Query) => Promise<{ rows: Row[]; sql: string; warnings: string[] }>;
|
|
@@ -1325,8 +1369,9 @@ type GenerationCaller = {
|
|
|
1325
1369
|
`new VexError('unsatisfiable', reason)` — the runtime negative-caches it.
|
|
1326
1370
|
- `mapToShape` runs when a shape is in play (the request's, or the stored one on
|
|
1327
1371
|
a fingerprint-only replay) and the entry has no stored mapping; it returns a
|
|
1328
|
-
compiled Prism `ir
|
|
1329
|
-
only on a miss — a replayed entry that
|
|
1372
|
+
compiled Prism `ir`, the Prism `config` it was compiled from, and the mapped
|
|
1373
|
+
result. Both are stored with the entry only on a miss — a replayed entry that
|
|
1374
|
+
has none calls the hook every time.
|
|
1330
1375
|
Without the hook the raw rows are returned.
|
|
1331
1376
|
|
|
1332
1377
|
You can implement these however you like. Vex also ships a **reference
|
|
@@ -1363,7 +1408,8 @@ await engine.introspect();
|
|
|
1363
1408
|
identity mapping and makes no model call. The `@niscorp/vex/agent` subpath
|
|
1364
1409
|
also exports `vexQueryDslAgent` itself, `createQueryTools` for customizing the
|
|
1365
1410
|
tool set, and `describeCaller`, which turns `caller.bindings` into the
|
|
1366
|
-
context line the agent reads.
|
|
1411
|
+
context line the agent reads. A run of `vexQueryDslAgent` given no `caller`
|
|
1412
|
+
dep tells the model that nothing identifies the caller.
|
|
1367
1413
|
|
|
1368
1414
|
The reference query agent (`vexQueryDslAgent`, id `vex.query`) is a Cortex
|
|
1369
1415
|
agent whose envelope payload is a `QuerySchema` query, with six tools:
|
|
@@ -1423,11 +1469,15 @@ The rest of `VexHonoConfig`, all optional:
|
|
|
1423
1469
|
| Option | Purpose |
|
|
1424
1470
|
|--------|---------|
|
|
1425
1471
|
| `locked` | Replay-only endpoint: no generation, no fingerprint management |
|
|
1426
|
-
| `getPolicy(c)` | Per-request `ScopePolicy`; governs reads, mutation replay and discovery on this endpoint |
|
|
1472
|
+
| `getPolicy(c)` | Per-request `ScopePolicy`; governs reads, mutation replay and discovery on this endpoint. Returning `undefined` leaves the engine's policy and `mutations.policy` in force |
|
|
1427
1473
|
| `getPolicyForReach(c, reach)` | The same principal's policy at a reach an entry demands |
|
|
1428
|
-
| `mutations` | `{ client, policy?, onWrite? }` — enables mutation replay; `policy` is the fallback when `getPolicy` is absent |
|
|
1474
|
+
| `mutations` | `{ client, policy?, onWrite? }` — enables mutation replay; `policy` is the fallback when `getPolicy` is absent. A request that gets a policy from neither replays no write: a mutation fingerprint answers 500 |
|
|
1429
1475
|
| `onExecute` | The execution observer (see [Events](#events)) |
|
|
1430
1476
|
|
|
1477
|
+
`vex` and `VexHonoConfig` are generic over the hono `Env`: `vex<AppEnv>({ … })`
|
|
1478
|
+
hands `getScope`, `getPolicy` and `getPolicyForReach` a `Context<AppEnv>`, so
|
|
1479
|
+
they read the host's typed context variables without a cast.
|
|
1480
|
+
|
|
1431
1481
|
### Express
|
|
1432
1482
|
|
|
1433
1483
|
```typescript
|
|
@@ -1544,7 +1594,9 @@ type ExecuteRecord = {
|
|
|
1544
1594
|
```
|
|
1545
1595
|
|
|
1546
1596
|
With no observer the record is not built. A listener that throws is logged and
|
|
1547
|
-
contained.
|
|
1597
|
+
contained. `startUnixNano` is epoch nanoseconds read from a millisecond clock;
|
|
1598
|
+
`endUnixNano` adds the elapsed time from a monotonic clock, so their difference
|
|
1599
|
+
is a sub-millisecond duration while each value alone is millisecond-accurate.
|
|
1548
1600
|
|
|
1549
1601
|
---
|
|
1550
1602
|
|
|
@@ -1579,7 +1631,7 @@ handlers recognise both.
|
|
|
1579
1631
|
| `invalid_request` | The request failed Zod validation |
|
|
1580
1632
|
| `invalid_dsl` | The analyzer rejected the resolved query (cartesian product, nesting, etc.) |
|
|
1581
1633
|
| `missing_scope` | A `$scope` slot the host did not fill. The host's fault, not the request's: the HTTP handler answers 500 and keeps the key names in its log |
|
|
1582
|
-
| `scope_denied` | An entity is denied by the scope policy (`VexScopeError`) |
|
|
1634
|
+
| `scope_denied` | An entity is denied by the scope policy (`VexScopeError`). `err.entity` names the entity |
|
|
1583
1635
|
| `missing_context` | A required context value was absent. Reads surface it softly via `meta.missingContext`; a WRITE hard-400s with the full derived signature in `details.expected` |
|
|
1584
1636
|
| `execution_error` | Schema not loaded, or a database/runtime failure. Also a batch whose `$returned` found no row, or several, where it needs exactly one — `details: { returned, rows }`, nothing written |
|
|
1585
1637
|
| `agent_failed` | Generation was needed and there is no `generateDsl` hook, or the reference agent's run failed |
|
|
@@ -12,11 +12,6 @@ var ContextSchema = zod.z.object({
|
|
|
12
12
|
'Caller runtime values. Keys referenced from the DSL via { $context: "key" } are bound as SQL parameters. `sortBy` (an entity.field, schema-validated) and `sortDir` ("asc"|"desc") are reserved keys that drive ORDER BY directly and are never bound as parameters.'
|
|
13
13
|
);
|
|
14
14
|
var QueryRequestSchema = zod.z.object({
|
|
15
|
-
// The ONE cache identity. Server-minted (`fp_…`) when absent — returned in
|
|
16
|
-
// meta.cache.fingerprint, an immutable pin. Caller-chosen strings are
|
|
17
|
-
// mutable named slots: the name is yours, its content follows your request.
|
|
18
|
-
// Alone → replay-or-error. With intent/shape → hit when the stored request
|
|
19
|
-
// matches, regenerate-and-replace when it differs (409 when protected).
|
|
20
15
|
fingerprint: zod.z.string().min(1).optional(),
|
|
21
16
|
intent: zod.z.string().optional(),
|
|
22
17
|
shape: zod.z.unknown().optional(),
|
|
@@ -91,12 +86,9 @@ var FilterSchema = zod.z.lazy(
|
|
|
91
86
|
zod.z.object({
|
|
92
87
|
optional: zod.z.object({
|
|
93
88
|
key: zod.z.union([zod.z.string().min(1), zod.z.array(zod.z.string().min(1)).min(1)]).describe("The context key this condition depends on, or EVERY key it depends on. A condition referencing two keys must name both \u2014 gating on one leaves the other conditionally required, which surfaces as an empty result rather than as a condition that did not apply."),
|
|
94
|
-
//
|
|
95
|
-
// detects
|
|
96
|
-
//
|
|
97
|
-
// expands the filter union into itself until the stack goes. Every
|
|
98
|
-
// other recursive slot here (`not`, `and`, `or`) uses it bare for the
|
|
99
|
-
// same reason; the description belongs on the wrapper below.
|
|
89
|
+
// Bare, never `.describe()`d: that call clones the schema, and zod's
|
|
90
|
+
// to-json-schema detects recursion by instance identity, so a clone
|
|
91
|
+
// expands the filter union into itself until the stack overflows.
|
|
100
92
|
then: FilterSchema
|
|
101
93
|
}).strict()
|
|
102
94
|
}).strict().describe(
|
|
@@ -335,13 +327,9 @@ var computeSchemaFingerprint = (schema) => {
|
|
|
335
327
|
primaryKey: f.primaryKey,
|
|
336
328
|
...f.vectorDimensions !== void 0 ? { vectorDimensions: f.vectorDimensions } : {}
|
|
337
329
|
})),
|
|
338
|
-
// Column order within a relation is the key's own order, so it is
|
|
339
|
-
// preserved; relations are sorted by target and columns. This shape
|
|
340
|
-
// changed when keys became composite, so every entry cached before
|
|
341
|
-
// revalidates once on the next boot — the drift eviction, by design.
|
|
330
|
+
// Column order within a relation is the key's own order, so it is not sorted.
|
|
342
331
|
relations: [...e.relations].sort((a, b) => `${a.entity}.${a.localFields.join(",")}`.localeCompare(`${b.entity}.${b.localFields.join(",")}`)).map((r) => ({ type: r.type, entity: r.entity, localFields: r.localFields, foreignFields: r.foreignFields })),
|
|
343
|
-
// Index field order is significant (composite indexes) and stable
|
|
344
|
-
// from introspection, so it is preserved; indexes are sorted by name.
|
|
332
|
+
// Index field order is significant (composite indexes) and stable from introspection.
|
|
345
333
|
indexes: [...e.indexes].sort(byName).map((i) => ({
|
|
346
334
|
name: i.name,
|
|
347
335
|
fields: i.fields,
|
|
@@ -460,8 +448,7 @@ var compileFilter = (filter, ctx) => {
|
|
|
460
448
|
const inner = {
|
|
461
449
|
...ctx,
|
|
462
450
|
resolvedPaths: resolved.filter?.resolvedPaths ?? ctx.resolvedPaths,
|
|
463
|
-
//
|
|
464
|
-
// the inner alias and an outer path — the correlation — still resolves.
|
|
451
|
+
// Inner over outer: an outer path, the correlation, still resolves.
|
|
465
452
|
aliasMap: new Map([...ctx.aliasMap, ...resolved.aliasMap])
|
|
466
453
|
};
|
|
467
454
|
const parts = ["SELECT 1"];
|
|
@@ -682,9 +669,7 @@ var UpsertSchema = zod.z.object({
|
|
|
682
669
|
op: zod.z.literal("upsert"),
|
|
683
670
|
table: zod.z.string(),
|
|
684
671
|
columns: Columns,
|
|
685
|
-
// set on BOTH branches (update SET, and part of the insert)
|
|
686
672
|
insert: Columns.optional(),
|
|
687
|
-
// extra columns set ONLY on insert — immutable-on-create (e.g. a FK)
|
|
688
673
|
key: zod.z.string()
|
|
689
674
|
}).strict().describe('Sugar: insert-or-update by `key` (e.g. "id"). Desugars to update (SET columns WHERE key) when the key is present, else insert (columns + `insert`-only).');
|
|
690
675
|
var MutationSchema = zod.z.discriminatedUnion("op", [InsertSchema, InsertEachSchema, UpdateSchema, DeleteSchema, UpsertSchema]);
|
|
@@ -1301,7 +1286,6 @@ var listFingerprints = async (engine, policy) => {
|
|
|
1301
1286
|
...entry.intent !== void 0 ? { intent: entry.intent } : {},
|
|
1302
1287
|
createdAt: entry.createdAt,
|
|
1303
1288
|
...entry.lastUsedAt !== void 0 ? { lastUsedAt: entry.lastUsedAt } : {},
|
|
1304
|
-
// The derived contract — what to pass, straight from the stored def.
|
|
1305
1289
|
...entry.kind === "ok" ? {
|
|
1306
1290
|
context: collectQueryContext(entry.dsl, schema),
|
|
1307
1291
|
...entry.shape !== void 0 ? { shape: entry.shape } : {}
|
|
@@ -1377,8 +1361,6 @@ var handleQuery = async (config, body, scope, live) => {
|
|
|
1377
1361
|
const result = await runQuery(config, body, scope, probe, live);
|
|
1378
1362
|
const record = {
|
|
1379
1363
|
kind: probe.kind,
|
|
1380
|
-
// 200 succeeded; 403 is a policy/reach refusal (a normal outcome, not a
|
|
1381
|
-
// fault); everything else is an error.
|
|
1382
1364
|
status: result.status === 200 ? "ok" : result.status === 403 ? "refused" : "error",
|
|
1383
1365
|
startUnixNano,
|
|
1384
1366
|
endUnixNano: startUnixNano + (elapsedClock() - t0) * 1e6,
|
|
@@ -1423,7 +1405,7 @@ var runQuery = async (config, body, scope, probe, live) => {
|
|
|
1423
1405
|
try {
|
|
1424
1406
|
let entryReach;
|
|
1425
1407
|
if (parsed.data.fingerprint !== void 0) {
|
|
1426
|
-
const entry = await engine.cache.get(parsed.data.fingerprint);
|
|
1408
|
+
const entry = await engine.cache.get(parsed.data.fingerprint, scope);
|
|
1427
1409
|
if (entry !== void 0 && entry.kind === "ok") entryReach = entry.reach;
|
|
1428
1410
|
if (probe !== void 0 && entryReach !== void 0) probe.reach = entryReach;
|
|
1429
1411
|
if (entry !== void 0 && entry.kind === "mutation") {
|