@niscorp/vex 0.1.1 → 0.2.2

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 CHANGED
@@ -1,5 +1,65 @@
1
1
  # @niscorp/vex
2
2
 
3
+ ## 0.2.2
4
+
5
+ ### Patch Changes
6
+
7
+ - 008b5e8: README and DOCS corrections. The exported `Query` type requires `dir` on a `sort` entry; in hand-written JSON it may be left out and reads as `asc`. `compile` and `test` work with no model, not with no database: both need the introspected schema, and `test` runs the query. The "N counts in one row" example compiles but throws at execute (`08P01`) under a policy that row-scopes two of its tables, because each such subquery binds its own `$scope` param; under such a policy, read each count on its own. No code changed.
8
+
9
+ **What to change:** nothing.
10
+
11
+ ## 0.2.1
12
+
13
+ ### Patch Changes
14
+
15
+ - fe30458: Every package exports its `package.json`, so an app can say which version of a package it runs by reading it from the package:
16
+
17
+ ```ts
18
+ import prism from '@niscorp/prism/package.json' with { type: 'json' };
19
+ prism.version; // the version that is installed, not the range that asked for it
20
+ ```
21
+
22
+ Until now the `exports` map hid it, and the only way to the version was a path into `node_modules`. `check:packages` installs the tarballs and reads every package's version this way.
23
+
24
+ **What to change:** nothing. An app that read a version by path can read it by name.
25
+
26
+ - 1e6d55d: A pool's `query` and `transaction` are called on the pool, and a transaction's `query` on the transaction — never taken off the object first. A driver's own object has them as methods that need their receiver, and taken off they failed inside the driver, on a property nothing in nisc names:
27
+ - **strata** — `migrate` and `upgradeStore` over a `PGlite` threw `Cannot read properties of undefined (reading '_checkReady')`; `status` and `readLedger` did too, once a ledger existed. A pool whose `transaction` hands a checked-out `pg` client through as the transaction failed in `migrate` the same way.
28
+ - **moss** — `createTideStore` took `query` off the transaction. Over a pool that hands its client through, every transaction of the store failed inside the driver, and tide recorded the run as deferred: nothing threw, and the effect never ran.
29
+ - **vex** — `createPostgresAdapter` with a read limit set (`limitReads`) threw on a pool whose `transaction` is a method.
30
+
31
+ A `PGlite` now works as a pool as it is, and so does a `pg` wrapper that passes its client through. A pool built from closures (`createPglitePool`, a wrapper that builds its own `query`) behaves as before.
32
+
33
+ **What to change:** nothing.
34
+
35
+ - 5c70059: Vex hashes without `node:crypto`, so `@niscorp/vex` and `@niscorp/vex/pglite` build for a browser as they are.
36
+
37
+ Every identity vex computes — `computeRequestHash`, `computeSchemaFingerprint`, the policy key behind the negative cache, a minted `fp_…`, and the row and answer hashes of a reactive read — is a SHA-256, and it came from `createHash` in `node:crypto`. A page has no such module, so a bundler refused the package (`"createHash" is not exported by "__vite-browser-external"`), and every app that runs vex over PGlite in the browser pointed its bundler's `crypto` at a shim of its own.
38
+
39
+ The hash is now vex's own (`src/utils/sha256.ts`): synchronous, self-contained, and the same digests as node's byte for byte. Nothing stored moves — a cache row's `request_hash` and `schema_fingerprint`, a `neg:` key and a fingerprint computed at build time by Node all still match what a page computes. The exported functions keep their signatures. It costs about three times node's own hash: 0.003 ms for a request identity, about 0.6 ms per 100 KB of rows.
40
+
41
+ **What to change:** nothing. An app that aliased `crypto` (or `node:crypto`) to a shim for vex can delete the alias, the shim and the dependency behind it.
42
+
43
+ ## 0.2.0
44
+
45
+ ### Minor Changes
46
+
47
+ - f1cec45: A Prism config that validates no longer names an op Prism does not have. `validate` accepted `{ card: { $fetch: … } }` and `{ $eval: "…" }`: the plain-object branch refused only the names of ops that exist, so any other `$` key passed as a template key. Such a config could be stored — an endpoint request, a vex mapping, a strata migration — and then failed every time it was evaluated (`E_NODE_SHAPE`, "Unsupported node shape").
48
+
49
+ A key that starts with `$` is now an op's name and nothing else. The template branch refuses every `$` key — the rule the evaluator already held — so `validate` reports it with the key and where it is (`card.$fetch: Not a Prism op. A key that starts with "$" names an op; data with such a key goes in $const.`), and `evaluate` and `compile` fail with `E_SCHEMA` before anything runs. An op's name used as a template key keeps its own message. `E_NODE_SHAPE` is left for a tree that never went through the schema: an IR handed to `execute`. Adding an op no longer takes a key away from templates.
50
+ - **prism** — the change, and a grammar narrowing: `nisc.prism` 2, a marker with no document step (a key that never evaluated has nothing to be rewritten to). `$` keys that are data are untouched: a `$const` payload, `$with` names, `$renameKeys` and `$fromEntries` keys. The JSON Schema's template key pattern is `^(?!\$)` instead of a list of every op.
51
+ - **nova, vex, moss, loom, cli, nisc** — no change of their own. They depend on prism and are released with it, so the set installs together; the configs they hand to prism (endpoint `request` and `response`, `$prism` bindings, vex mappings) are held to the same rule.
52
+ - **create-nisc** — the templates' sources are recorded at `nisc.prism` 2.
53
+
54
+ **What to change:** in a config with a `$`-prefixed key that is not a Prism op, remove the key — or put the object in `$const` if it is literal data. An app that keeps a `strata.lock.json` runs `pnpm strata upgrade`, then `pnpm strata verify`; there is nothing to edit unless it has such a config. Everything else: nothing.
55
+
56
+ BREAKING — approved by moccadroid, 2026-10-04: a config with a `$`-prefixed key that is not a Prism op no longer validates, compiles or evaluates — also where evaluation never reached the key (an untaken `$case` branch, a short-circuited `$or`, a `$map` body over an empty array), which used to work. A vex seed mapping with one fails when it is seeded, at boot, instead of on each replay. Code that matched `E_NODE_SHAPE` from `evaluate` gets `E_SCHEMA`. The `@niscorp` packages that depend on prism move with it, so an app moves them together (`@niscorp/nisc` 0.3.0).
57
+
58
+ ### Patch Changes
59
+
60
+ - Updated dependencies [f1cec45]
61
+ - @niscorp/prism@0.2.0
62
+
3
63
  ## 0.1.1
4
64
 
5
65
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -646,6 +646,7 @@ src/
646
646
  utils/
647
647
  context.ts buildValidationContext, resolveParams
648
648
  canonical.ts canonical JSON text + hash
649
+ sha256.ts SHA-256 of a text, synchronous, no node built-in
649
650
 
650
651
  scripts/ Dev-only: docker, seed, dev server, fixtures
651
652
  ```
@@ -668,6 +669,17 @@ scripts/ Dev-only: docker, seed, dev server, fixtures
668
669
  `zod`, `@niscorp/prism` and `@niscorp/strata` are mandatory. Everything else is
669
670
  pulled in only by the path you use.
670
671
 
672
+ **No Node built-in on the path a page takes.** The main entry and
673
+ `@niscorp/vex/pglite` import nothing from Node, so a bundler builds them for a
674
+ browser as they are — vex over PGlite in the page, the client-degrade posture.
675
+ The one thing that stood in the way was hashing: every identity vex computes (a
676
+ request hash, a schema fingerprint, a policy key, the row and answer hashes of a
677
+ reactive read) is a SHA-256, and it came from `node:crypto`. It is now written
678
+ out in `utils/sha256.ts` — synchronous, because three exported functions answer
679
+ with a hash directly and a reactive read's follower compares two inside a
680
+ callback, which rules out WebCrypto's `subtle.digest`. The digests are node's,
681
+ byte for byte, so nothing a cache already holds under one has moved.
682
+
671
683
  ---
672
684
 
673
685
  ## Key design decisions
package/DOCS.md CHANGED
@@ -371,7 +371,7 @@ type Query = {
371
371
  compute?: Record<string, ComputeExpression>; // alias → expression
372
372
  aggregate?: Record<string, AggregateExpression>; // alias → function
373
373
  groupBy?: string[];
374
- sort?: { field: string; dir?: 'asc' | 'desc' }[];
374
+ sort?: { field: string; dir: 'asc' | 'desc' }[]; // in hand-written JSON `dir` may be left out: it reads as 'asc'
375
375
  limit?: number;
376
376
  distinct?: boolean;
377
377
  };
@@ -550,7 +550,11 @@ single read (use an object shape so Vex maps that single row).
550
550
  ```
551
551
 
552
552
  (Limitation: subquery SQL params are embedded verbatim, so at most one bound
553
- `$context`/`$scope` param across all subqueries is supported today.)
553
+ `$context`/`$scope` param across all subqueries is supported today. A policy
554
+ row rule counts: it binds a `$scope` param in every subquery over a table it
555
+ scopes, so the example above compiles but throws at execute (`08P01`, a
556
+ parameter-count mismatch) once two of its tables are row-scoped. Under such a
557
+ policy, read each count on its own.)
554
558
 
555
559
  ### Semantic search
556
560
 
@@ -1126,6 +1130,11 @@ columns as raw strings. Pass the parsers to the adapter's pool; give the
1126
1130
  Postgres cache a pool without them — it reads its own timestamp columns as
1127
1131
  `Date`s.
1128
1132
 
1133
+ `@niscorp/vex` and `@niscorp/vex/pglite` import no Node built-in, so a bundler
1134
+ builds them for a page with no alias and no polyfill. Vex's hashes are the same
1135
+ SHA-256 digests in a page as on a server, so entries prewarmed at build time
1136
+ replay in the browser.
1137
+
1129
1138
  ### Reactive reads (`refresh`)
1130
1139
 
1131
1140
  An entry's `refresh` says when its answer is refreshed: `'snapshot'` (the
package/README.md CHANGED
@@ -45,7 +45,8 @@ const again = await engine.execute({ fingerprint: fp, context: { customerId: 'cu
45
45
  Generating needs an LLM-backed `generateDsl` hook — see
46
46
  [DOCS.md](./DOCS.md#wiring-the-llm-agents). Without one, the engine still serves
47
47
  any request that **replays a fingerprint** (a named slot or a seeded read), and
48
- the `compile`/`test` APIs work fully offline.
48
+ the `compile`/`test` APIs work with no model: both need the introspected
49
+ schema, and `test` runs the query against the database.
49
50
 
50
51
  ## The production shape
51
52
 
@@ -1,7 +1,6 @@
1
1
  'use strict';
2
2
 
3
3
  var zod = require('zod');
4
- var crypto = require('crypto');
5
4
  var strata = require('@niscorp/strata');
6
5
 
7
6
  // src/handler.ts
@@ -184,6 +183,144 @@ var isEntryFresh = (entry, currentFingerprint) => {
184
183
  const stale = entry.schemaFingerprint !== void 0 && currentFingerprint !== void 0 && entry.schemaFingerprint !== currentFingerprint;
185
184
  return !expired && !stale;
186
185
  };
186
+
187
+ // src/utils/sha256.ts
188
+ var ROUND_CONSTANTS = new Uint32Array([
189
+ 1116352408,
190
+ 1899447441,
191
+ 3049323471,
192
+ 3921009573,
193
+ 961987163,
194
+ 1508970993,
195
+ 2453635748,
196
+ 2870763221,
197
+ 3624381080,
198
+ 310598401,
199
+ 607225278,
200
+ 1426881987,
201
+ 1925078388,
202
+ 2162078206,
203
+ 2614888103,
204
+ 3248222580,
205
+ 3835390401,
206
+ 4022224774,
207
+ 264347078,
208
+ 604807628,
209
+ 770255983,
210
+ 1249150122,
211
+ 1555081692,
212
+ 1996064986,
213
+ 2554220882,
214
+ 2821834349,
215
+ 2952996808,
216
+ 3210313671,
217
+ 3336571891,
218
+ 3584528711,
219
+ 113926993,
220
+ 338241895,
221
+ 666307205,
222
+ 773529912,
223
+ 1294757372,
224
+ 1396182291,
225
+ 1695183700,
226
+ 1986661051,
227
+ 2177026350,
228
+ 2456956037,
229
+ 2730485921,
230
+ 2820302411,
231
+ 3259730800,
232
+ 3345764771,
233
+ 3516065817,
234
+ 3600352804,
235
+ 4094571909,
236
+ 275423344,
237
+ 430227734,
238
+ 506948616,
239
+ 659060556,
240
+ 883997877,
241
+ 958139571,
242
+ 1322822218,
243
+ 1537002063,
244
+ 1747873779,
245
+ 1955562222,
246
+ 2024104815,
247
+ 2227730452,
248
+ 2361852424,
249
+ 2428436474,
250
+ 2756734187,
251
+ 3204031479,
252
+ 3329325298
253
+ ]);
254
+ var BLOCK_BYTES = 64;
255
+ var rotateRight = (word, bits) => word >>> bits | word << 32 - bits;
256
+ var wordHex = (word) => (word >>> 0).toString(16).padStart(8, "0");
257
+ var sha256Hex = (text) => {
258
+ const bytes = new TextEncoder().encode(text);
259
+ const padded = new Uint8Array(Math.ceil((bytes.length + 9) / BLOCK_BYTES) * BLOCK_BYTES);
260
+ padded.set(bytes);
261
+ padded[bytes.length] = 128;
262
+ const view = new DataView(padded.buffer);
263
+ const bitLength = bytes.length * 8;
264
+ view.setUint32(padded.length - 8, Math.floor(bitLength / 4294967296));
265
+ view.setUint32(padded.length - 4, bitLength >>> 0);
266
+ let h0 = 1779033703;
267
+ let h1 = 3144134277;
268
+ let h2 = 1013904242;
269
+ let h3 = 2773480762;
270
+ let h4 = 1359893119;
271
+ let h5 = 2600822924;
272
+ let h6 = 528734635;
273
+ let h7 = 1541459225;
274
+ const schedule = new Uint32Array(64);
275
+ for (let offset = 0; offset < padded.length; offset += BLOCK_BYTES) {
276
+ for (let i = 0; i < 16; i += 1) schedule[i] = view.getUint32(offset + i * 4);
277
+ for (let i = 16; i < 64; i += 1) {
278
+ const w15 = schedule[i - 15] ?? 0;
279
+ const w2 = schedule[i - 2] ?? 0;
280
+ const s0 = rotateRight(w15, 7) ^ rotateRight(w15, 18) ^ w15 >>> 3;
281
+ const s1 = rotateRight(w2, 17) ^ rotateRight(w2, 19) ^ w2 >>> 10;
282
+ schedule[i] = (schedule[i - 16] ?? 0) + s0 + (schedule[i - 7] ?? 0) + s1;
283
+ }
284
+ let a = h0;
285
+ let b = h1;
286
+ let c = h2;
287
+ let d = h3;
288
+ let e = h4;
289
+ let f = h5;
290
+ let g = h6;
291
+ let h = h7;
292
+ for (let i = 0; i < 64; i += 1) {
293
+ const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
294
+ const choice = e & f ^ ~e & g;
295
+ const temp1 = h + sum1 + choice + (ROUND_CONSTANTS[i] ?? 0) + (schedule[i] ?? 0) | 0;
296
+ const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
297
+ const majority = a & b ^ a & c ^ b & c;
298
+ const temp2 = sum0 + majority | 0;
299
+ h = g;
300
+ g = f;
301
+ f = e;
302
+ e = d + temp1 | 0;
303
+ d = c;
304
+ c = b;
305
+ b = a;
306
+ a = temp1 + temp2 | 0;
307
+ }
308
+ h0 = h0 + a | 0;
309
+ h1 = h1 + b | 0;
310
+ h2 = h2 + c | 0;
311
+ h3 = h3 + d | 0;
312
+ h4 = h4 + e | 0;
313
+ h5 = h5 + f | 0;
314
+ h6 = h6 + g | 0;
315
+ h7 = h7 + h | 0;
316
+ }
317
+ return wordHex(h0) + wordHex(h1) + wordHex(h2) + wordHex(h3) + wordHex(h4) + wordHex(h5) + wordHex(h6) + wordHex(h7);
318
+ };
319
+
320
+ // src/utils/canonical.ts
321
+ var hashText = (text) => sha256Hex(text);
322
+
323
+ // src/cache/hash.ts
187
324
  var computeSchemaFingerprint = (schema) => {
188
325
  const byName = (a, b) => a.name.localeCompare(b.name);
189
326
  const stable = {
@@ -213,7 +350,7 @@ var computeSchemaFingerprint = (schema) => {
213
350
  }))
214
351
  }))
215
352
  };
216
- return crypto.createHash("sha256").update(JSON.stringify(stable)).digest("hex");
353
+ return hashText(JSON.stringify(stable));
217
354
  };
218
355
 
219
356
  // src/errors.ts