@niscorp/vex 0.3.1 → 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.
Files changed (50) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/DESIGN.md +4 -3
  3. package/DOCS.md +26 -4
  4. package/dist/adapters/express/index.cjs +1 -1
  5. package/dist/adapters/express/index.cjs.map +1 -1
  6. package/dist/adapters/express/index.d.cts +3 -2
  7. package/dist/adapters/express/index.d.ts +3 -2
  8. package/dist/adapters/express/index.js +3 -2
  9. package/dist/adapters/express/index.js.map +1 -1
  10. package/dist/adapters/hono/index.cjs +1 -1
  11. package/dist/adapters/hono/index.cjs.map +1 -1
  12. package/dist/adapters/hono/index.d.cts +3 -2
  13. package/dist/adapters/hono/index.d.ts +3 -2
  14. package/dist/adapters/hono/index.js +3 -2
  15. package/dist/adapters/hono/index.js.map +1 -1
  16. package/dist/agent/index.cjs +4 -3
  17. package/dist/agent/index.cjs.map +1 -1
  18. package/dist/agent/index.d.cts +3 -2
  19. package/dist/agent/index.d.ts +3 -2
  20. package/dist/agent/index.js +6 -4
  21. package/dist/agent/index.js.map +1 -1
  22. package/dist/{chunk-3HORTMZ7.js → chunk-7F2OH4IP.js} +5 -4
  23. package/dist/chunk-7F2OH4IP.js.map +1 -0
  24. package/dist/chunk-F7RDSWYF.js +7 -0
  25. package/dist/chunk-F7RDSWYF.js.map +1 -0
  26. package/dist/{chunk-J7JYKCUA.js → chunk-UPQMKAAX.js} +3 -18
  27. package/dist/chunk-UPQMKAAX.js.map +1 -0
  28. package/dist/chunk-XTOK7YOR.js +18 -0
  29. package/dist/chunk-XTOK7YOR.js.map +1 -0
  30. package/dist/{handler-B4NAi4k_.d.cts → handler-Bw7xVmBM.d.ts} +2 -1
  31. package/dist/{handler-BRVhWuNk.d.ts → handler-Cy0gNM6K.d.cts} +2 -1
  32. package/dist/index.cjs +21 -11
  33. package/dist/index.cjs.map +1 -1
  34. package/dist/index.d.cts +6 -4
  35. package/dist/index.d.ts +6 -4
  36. package/dist/index.js +29 -19
  37. package/dist/index.js.map +1 -1
  38. package/dist/migrations/index.cjs +173 -0
  39. package/dist/migrations/index.cjs.map +1 -0
  40. package/dist/migrations/index.d.cts +20 -0
  41. package/dist/migrations/index.d.ts +20 -0
  42. package/dist/migrations/index.js +23 -0
  43. package/dist/migrations/index.js.map +1 -0
  44. package/dist/query.schema-B-LVNfyX.d.cts +461 -0
  45. package/dist/query.schema-B-LVNfyX.d.ts +461 -0
  46. package/dist/{types-DUJp5B3o.d.cts → types-Bs_9VM9p.d.ts} +10 -462
  47. package/dist/{types-DUJp5B3o.d.ts → types-DO-rYZci.d.cts} +10 -462
  48. package/package.json +11 -1
  49. package/dist/chunk-3HORTMZ7.js.map +0 -1
  50. package/dist/chunk-J7JYKCUA.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
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
+
3
15
  ## 0.3.1
4
16
 
5
17
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -266,7 +266,7 @@ Identity is the **fingerprint** (see Cache v2 below). The supporting hashes:
266
266
  impossible, so it isn't re-run until the TTL lapses or the schema changes).
267
267
  - **Backends.** In-memory (`createMemoryCache`), durable Postgres
268
268
  (`createPostgresCache`, jsonb table, server-side TTL, `protected`/
269
- `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,
270
270
  `nisc.vex.cache`, applied once through the ledger by `init()`;
271
271
  validate-on-write and evict-on-read), and tiered (`createTieredCache`, L1 +
272
272
  L2 read-through/write-through with `full`/`lazy`/`partial` warm-up). Every
@@ -587,8 +587,9 @@ The engine takes two optional hooks:
587
587
  what the person asking could see — and it is keyed (single-flight, negative
588
588
  cache) by request AND policy, because two callers who see different tables
589
589
  are asking different agents.
590
- - `mapToShape(rows, shape) → { ir, transformed }` — raw rows → requested shape,
591
- 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`).
592
593
 
593
594
  This is the seam that keeps the core deterministic. Vex ships a reference
594
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'`
@@ -1232,6 +1232,27 @@ demand; `partial` preloads only the listed fingerprints and lazy-fills the
1232
1232
  rest. The tiered cache is single-instance: separate processes keep separate
1233
1233
  L1s.
1234
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
+
1235
1256
  ### Seeding
1236
1257
 
1237
1258
  `seedCache(cache, entries)` turns authored entries into **protected** cache
@@ -1335,7 +1356,7 @@ free-form requests.
1335
1356
  ```typescript
1336
1357
  type GenerateDsl = (request: QueryRequest, schema: DatabaseSchema, caller: GenerationCaller) => Promise<Query>;
1337
1358
  type MapToShape = (rows: Row[], shape: unknown) =>
1338
- Promise<{ ir: CompiledIr; transformed: JsonValue }>;
1359
+ Promise<{ ir: CompiledIr; config: unknown; transformed: JsonValue }>;
1339
1360
 
1340
1361
  type GenerationCaller = {
1341
1362
  read: (dsl: Query) => Promise<{ rows: Row[]; sql: string; warnings: string[] }>;
@@ -1348,8 +1369,9 @@ type GenerationCaller = {
1348
1369
  `new VexError('unsatisfiable', reason)` — the runtime negative-caches it.
1349
1370
  - `mapToShape` runs when a shape is in play (the request's, or the stored one on
1350
1371
  a fingerprint-only replay) and the entry has no stored mapping; it returns a
1351
- compiled Prism `ir` plus the mapped result. The `ir` is stored with the entry
1352
- only on a miss — a replayed entry that has none calls the hook every time.
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.
1353
1375
  Without the hook the raw rows are returned.
1354
1376
 
1355
1377
  You can implement these however you like. Vex also ships a **reference
@@ -1405,7 +1405,7 @@ var runQuery = async (config, body, scope, probe, live) => {
1405
1405
  try {
1406
1406
  let entryReach;
1407
1407
  if (parsed.data.fingerprint !== void 0) {
1408
- const entry = await engine.cache.get(parsed.data.fingerprint);
1408
+ const entry = await engine.cache.get(parsed.data.fingerprint, scope);
1409
1409
  if (entry !== void 0 && entry.kind === "ok") entryReach = entry.reach;
1410
1410
  if (probe !== void 0 && entryReach !== void 0) probe.reach = entryReach;
1411
1411
  if (entry !== void 0 && entry.kind === "mutation") {