@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.
- package/CHANGELOG.md +12 -0
- package/DESIGN.md +4 -3
- package/DOCS.md +26 -4
- package/dist/adapters/express/index.cjs +1 -1
- 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 +1 -1
- 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/agent/index.cjs +4 -3
- 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 +6 -4
- package/dist/agent/index.js.map +1 -1
- package/dist/{chunk-3HORTMZ7.js → chunk-7F2OH4IP.js} +5 -4
- 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-J7JYKCUA.js → chunk-UPQMKAAX.js} +3 -18
- 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-B4NAi4k_.d.cts → handler-Bw7xVmBM.d.ts} +2 -1
- package/dist/{handler-BRVhWuNk.d.ts → handler-Cy0gNM6K.d.cts} +2 -1
- package/dist/index.cjs +21 -11
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +6 -4
- package/dist/index.d.ts +6 -4
- package/dist/index.js +29 -19
- 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-DUJp5B3o.d.cts → types-Bs_9VM9p.d.ts} +10 -462
- package/dist/{types-DUJp5B3o.d.ts → types-DO-rYZci.d.cts} +10 -462
- package/package.json +11 -1
- package/dist/chunk-3HORTMZ7.js.map +0 -1
- 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
|
|
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
|
|
1352
|
-
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.
|
|
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") {
|