@niscorp/vex 0.4.5 → 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 +78 -0
  2. package/DESIGN.md +72 -45
  3. package/DOCS.md +130 -21
  4. package/README.md +17 -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-O6XslV-S.d.ts → handler-DdfaWN_J.d.ts} +7 -1
  28. package/dist/{handler-CB0BqKsY.d.cts → handler-kvZkxwaN.d.cts} +7 -1
  29. package/dist/index.cjs +493 -232
  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 +118 -221
  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-BmHuPfPS.d.cts → types-BxkRxTTx.d.cts} +5 -0
  38. package/dist/{types-D5CCaqcd.d.ts → types-DgUZNKii.d.ts} +5 -0
  39. package/package.json +8 -8
  40. package/dist/chunk-W5MYFJKT.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,83 @@
1
1
  # @niscorp/vex
2
2
 
3
+ ## 0.5.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 4c6300e: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app's discovery endpoint has an engine created with `scope` and a handler with no policy of its own (Express without `getPolicy`, Hono without `getPolicy`, or `handleDiscovery` called directly) and relied on that endpoint listing tables and entries the engine's policy refuses to run.
8
+
9
+ Discovery now lists each table and entry under the policy it runs under. Tables and read entries go by the handler's (or the request's) policy when there is one, otherwise the engine's. A write entry goes by `mutations.policy`, the policy its write runs under, when the handler has `mutations`. `QueryEngine` gains an optional read-only `scopePolicy`, the policy given to `createQueryEngine`.
10
+
11
+ - b1e314e: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on `session.answerIntent` replaying an entry that declares a `reach` with more rows than `/api/vex` answers the same person; such a replay now answers fewer rows or `scope_denied`.
12
+
13
+ `engine.execute` can serve a replayed entry at the `reach` it declares: pass `policyForReach`, as the handler takes it. Without it the run is as before, with one warning per entry. moss's `session.answerIntent` passes it, so a replay of an entry that declares a reach answers what `/api/vex` answers the same person: fewer rows, or `scope_denied` for roles with no such reach.
14
+
15
+ - b2b2d8d: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app merges hand-written policies with `mergeScopePolicies` and relied on a `public` entity being refused, or on `{ write: [...], update: [] }` merging to an `update` with no rule.
16
+
17
+ `mergeScopePolicies` now reads each entity as the phases it grants. A `public` entity grants all four phases with no rule, where it was dropped and so refused. A `write` list is added to insert, update and delete, where it was dropped: `{ write: [tenant], update: [] }` merges to `update: [tenant]` (narrower than before, and as narrow as the policy itself), and a `write`-only entity gains its three write phases. Policies made by `createScopePolicy` merge exactly as before.
18
+
19
+ - f995714: BREAKING — approved by moccadroid (owner), 2026-11-22: an app whose update writes a column a `match` rule pins (handing a row over, e.g. setting `owner_id` under an `owner_id = me` rule) sets `mutations: { …, checkMovedRows: false }` to keep today's behaviour.
20
+
21
+ An update can no longer move a row out of the caller's own update rules: when it writes a column a `match` rule pins (say `project_id` under `match: 'project_id', in: 'projectIds'`) to a value that rule does not allow, it is refused with 400 `scope_denied` naming the rule and the column, and nothing is written. An insert's `onConflict … set` that would move the existing row out does not move it and answers `[]` for it, not 400. A setup that hands rows over this way (setting `owner_id` under an `owner_id = me` rule) keeps today's behaviour with `mutations: { …, checkMovedRows: false }`.
22
+
23
+ - a002748: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a table joined to itself being filtered on one copy only, or on a semantic `$scope` text sent by the client; the server supplies that value, or the request is refused with `missing_scope`.
24
+
25
+ A table joined to itself now gets its row rules on both copies, a semantic `$scope` text comes from the server, and discovery leaves out entries whose `exists` reads a table the caller cannot read. Tables, subqueries and columns with capitals or reserved names can be read and written, and the query agent's tools accept `null` for an argument the model leaves out.
26
+
27
+ - 2233113: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a host wraps a built-in cache by spreading it and overriding `set` to watch writes: the "last used" stamps go through the `touch` the wrapper inherits and do not reach that `set`.
28
+
29
+ The "last used" stamp a replay writes now writes `lastUsedAt` alone, through a new optional `CacheBackend.touch(key, lastUsedAt)`, wherever the cache the engine is given has `touch`. There, a `PATCH` (unprotect) or a reseed that lands between a replay's read and its stamp is kept, and a tiered cache stamps L1 and L2 without copying L1's entry over L2. The memory, Postgres and tiered caches implement `touch`; a backend without it is stamped through `set` with the whole entry, as before, and keeps the race. moss's entry cache has no `touch`, so every moss app keeps stamping through `set`.
30
+
31
+ - 04f5821: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app sends `null` as an `upsert` key on a table whose key column the database fills (a default or an identity column) and relied on that writing nothing and answering 200 `[]`. Such a request now inserts a row, or, for a caller whose policy grants update but not insert, answers 400 `scope_denied` as an absent key does.
32
+
33
+ An `upsert` whose key is `null` now inserts a row where the database makes the key: the introspected key column has a default (such as `gen_random_uuid()` or a sequence) or is an identity column, and the entry does not write the key itself in `columns` or `insert`. Before, it ran an update of no row and answered 200 `[]`. Anywhere else a `null` key answers as before. Introspection now gives an identity column a `defaultValue` (`GENERATED ALWAYS AS IDENTITY` or `GENERATED BY DEFAULT AS IDENTITY`), where it had none.
34
+
35
+ ### Patch Changes
36
+
37
+ - 8b4d6cd: A write can now be told to answer only the rows the caller's read rules show: `mutations: { …, answerReadableRows: true }` on the handler and on the Hono and Express adapters, and `answerReadableRows: true` in moss's runtime for its `/api/vex` surfaces. It is off by default, and with it off a write runs and answers exactly as before.
38
+ - be6e7af: The handler's log line for an unexpected error no longer prints the error object, which under PGlite carries the statement's bound values (the caller's scope among them). It prints the error's code, message and stack, and the SQL text where the driver's error carries it.
39
+ - d8dc7d9: An unlocked endpoint can now refuse fingerprint management: `manageFingerprints: false` on the handler and the Hono and Express adapters answers `PATCH` and `DELETE` with 403 `locked`. It stays on by default, as before, and an adapter mounting an unlocked endpoint with it on logs one warning as it starts.
40
+ - df44b8e: DESIGN.md's first design decision states the rule without the history of the defect it replaced.
41
+
42
+ An `exists` inside a `case` inside an aggregate (`sum`, `avg`, `min`, `max`) compiles, with the caller's row rules inside it, as it already did inside `compute`. Before, the query was refused with "An `exists` filter was not resolved".
43
+
44
+ The Express adapter takes `getPolicy(req)`, `getPolicyForReach(req, reach)` and `onExecute`, as the Hono adapter does. An entry that declares a reach is served there; before, it answered 500 on Express. Without these options the adapter behaves as before.
45
+
46
+ A request whose `intent` or `fingerprint` is `null` is read as one without that key, by `engine.execute` and by the adapters; before, it was refused as `invalid_request`. The exported schemas are unchanged.
47
+
48
+ `createPostgresAdapter` takes `qualifyTables: true`: with it, reads and mutations name every table with the adapter's `schema` (`FROM "app".tasks`), so an app need not set `search_path`. `introspect()` then reports that name as `namespace` on the `DatabaseSchema`, a new optional field left out of the schema fingerprint. Without the option nothing changes.
49
+
50
+ - Updated dependencies [48138de]
51
+ - Updated dependencies [da3037e]
52
+ - Updated dependencies [e957628]
53
+ - Updated dependencies [c30562a]
54
+ - Updated dependencies [efd2368]
55
+ - Updated dependencies [ca26810]
56
+ - Updated dependencies [800a541]
57
+ - Updated dependencies [9c5367b]
58
+ - Updated dependencies [322f241]
59
+ - Updated dependencies [a41edf9]
60
+ - Updated dependencies [eb4ffb9]
61
+ - Updated dependencies [ae647e8]
62
+ - Updated dependencies [2effb54]
63
+ - Updated dependencies [bd996ea]
64
+ - Updated dependencies [180787b]
65
+ - Updated dependencies [d53910e]
66
+ - Updated dependencies [276f457]
67
+ - Updated dependencies [413afbd]
68
+ - Updated dependencies [1f6d37d]
69
+ - Updated dependencies [d77baf9]
70
+ - Updated dependencies [3f92c52]
71
+ - Updated dependencies [841c010]
72
+ - Updated dependencies [d93170b]
73
+ - Updated dependencies [61b15e4]
74
+ - Updated dependencies [7e8f6d4]
75
+ - Updated dependencies [5c52ef5]
76
+ - Updated dependencies [66eb934]
77
+ - @niscorp/cortex@0.2.0
78
+ - @niscorp/prism@0.4.0
79
+ - @niscorp/strata@0.2.0
80
+
3
81
  ## 0.4.5
4
82
 
5
83
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -167,7 +167,9 @@ Three functions, in two stages:
167
167
  inner-joined table, in the join's ON for a left-joined one, and inside every
168
168
  subquery and `exists`. It runs after resolution, because where a rule goes
169
169
  depends on how its table is joined (see decision 4 under *Key design
170
- decisions*).
170
+ decisions*). A rule is placed per source, on that source's alias: a table
171
+ listed twice in `from` gets its rule on both copies. (Every path names the
172
+ last copy; the DSL has no way to name the first.)
171
173
 
172
174
  The analyzer and the compiler never know scope exists: they process a resolved
173
175
  query that happens to carry extra predicates.
@@ -273,7 +275,9 @@ Identity is the **fingerprint** (see Cache v2 below). The supporting hashes:
273
275
  validate-on-write and evict-on-read), and tiered (`createTieredCache`, L1 +
274
276
  L2 read-through/write-through with `full`/`lazy`/`partial` warm-up). Every
275
277
  backend implements the same `CacheBackend` contract; `init`/`entries` are
276
- optional capabilities used for warm-up and the discovery overview.
278
+ optional capabilities used for warm-up and the discovery overview, and
279
+ `touch` stamps `lastUsedAt` alone, so a replay's stamp never writes back an
280
+ entry another writer changed after the replay read it.
277
281
  - **Validation** (`validateEntry`) guards every write and every promotion into
278
282
  memory, so a corrupt or schema-drifted row can never poison the cache. It
279
283
  returns `null` for a valid entry and the reason, as a string, for any other.
@@ -353,7 +357,7 @@ identity stays global.
353
357
  - `POST /api/<scope>/vex` — execute (the three postures above). Errors:
354
358
  unknown fingerprint replay → 404 `cache_miss`; protected slot + differing
355
359
  request → 409 `fingerprint_protected`; locked endpoint asked to generate →
356
- 403 `locked`.
360
+ 400 `locked`.
357
361
  - `GET /api/<scope>/vex` — self-description: `{ protection:
358
362
  "all"|"some"|"none", locked, fingerprints: [{ fingerprint, protected,
359
363
  schemaFresh, intent, lastUsedAt }] }` plus the schema/DSL/body docs. Doubles
@@ -361,7 +365,11 @@ identity stays global.
361
365
  call.
362
366
  - `PATCH /…/vex` with `{ fingerprint, protected }` — flip the bit. `DELETE`
363
367
  with `{ fingerprint }` — evict (unprotected only). Fingerprints ride the
364
- body, not the path — names contain `/`.
368
+ body, not the path — names contain `/`. A locked endpoint refuses both with
369
+ 403 `locked`, and so does one with `manageFingerprints: false`. Otherwise
370
+ they check nobody, so whoever reaches it can unprotect any entry, a seeded
371
+ one included, and delete it; an adapter that mounts such an endpoint says so
372
+ once, as it is made.
365
373
 
366
374
  **What dies with v1:**
367
375
 
@@ -418,6 +426,23 @@ values bind as SQL parameters exactly like reads) → execute. Batches run in
418
426
  one transaction; the client is structural (`MutationClient` — PGlite, a pg
419
427
  wrapper, a test double), so the core imports no driver.
420
428
 
429
+ A `match` rule pins the rows a write leaves behind as well as the rows it
430
+ touches: an update that writes a pinned column must leave a value the rule
431
+ allows, or it is refused (`checkMovedRows`, on unless the host turns it off).
432
+ A query run before the UPDATE finds a row that would move and names the
433
+ rule, so a refused move writes nothing; the UPDATE carries the same check
434
+ in its WHERE for a row that changes in between. The new value is cast to
435
+ its column's type there, because a parameter the check shares with the SET
436
+ is otherwise read as text.
437
+
438
+ What a write answers is every row it wrote, unless the host asks for the
439
+ rows the caller's read rules show (`answerReadableRows`). It is off by
440
+ default because an entry may be built on the whole answer: a sign-in that
441
+ deletes a one-time link and reads who signs in from it, run by a role with
442
+ no read grant on the link. With it on, the read rules are compiled into one
443
+ extra returned column that vex strips; `rows` keeps every written row for
444
+ the write observer, `$returned` and invalidation.
445
+
421
446
  **A batch that uses what it wrote (`$returned`).** `{ $returned: 'table.column' }`
422
447
  in a later statement reads the one row an earlier statement of the same batch
423
448
  wrote — the create-a-parent-then-its-children case, where the parent's id is
@@ -676,6 +701,7 @@ src/
676
701
  apply.ts checkScope, scopeResolved, applyScope, VexScopeError
677
702
  grants.ts createScopePolicy, mergeScopePolicies, scopeGrants, scopeProfiles, scopeBindings
678
703
  scope.types.ts ScopePolicy, ScopeEntityRule, ScopeMatch, ScopeSet
704
+ index.ts Barrel
679
705
 
680
706
  engine/
681
707
  runtime.ts createQueryEngine — orchestration + cache + single-flight
@@ -685,6 +711,7 @@ src/
685
711
  optional.ts pruneOptional, presenceOf — optional conditions
686
712
  live.ts createLiveRows — the rows cache and follows behind refresh: 'reactive'
687
713
  engine.types.ts ResolvedQuery and friends, AnalysisConfig, TestResult
714
+ index.ts Barrel
688
715
 
689
716
  adapters/
690
717
  adapter.types.ts DatabaseAdapter, CompiledQuery, ParamSlot, capabilities
@@ -692,9 +719,10 @@ src/
692
719
  postgres.adapter.ts createPostgresAdapter
693
720
  introspect.ts schema discovery from pg_catalog
694
721
  compile.ts ResolvedQuery → parameterized SQL
695
- operators.ts per-operator SQL generation
722
+ operators.ts per-operator SQL generation; how a table, alias or column name is written
696
723
  statement-timeout.ts how a read's time limit is enforced
697
724
  date-parsers.ts RAW_DATE_PARSERS, shared by the two pool shims
725
+ index.ts Barrel
698
726
  pglite/index.ts createPglitePool (@niscorp/vex/pglite)
699
727
  pg/index.ts createPgPool (@niscorp/vex/pg)
700
728
  hono/index.ts vex() Hono app (@niscorp/vex/hono)
@@ -776,22 +804,18 @@ byte for byte, so nothing a cache already holds under one has moved.
776
804
 
777
805
  A validated JSON union is only injection-proof if every string in it reaches
778
806
  SQL as something the union can vouch for. Authored text reaches a statement
779
- exactly three ways: a **column** that resolved against the introspected
780
- schema, a **literal** quoted the way Postgres's `quote_literal` does (safe
781
- under either `standard_conforming_strings`), or an **output name** held to
782
- `ident` and quoted. Values from a request bind as parameters and never reach
807
+ exactly three ways: a **table, alias or column name** that resolved against
808
+ the introspected schema, written bare where Postgres reads it back as itself
809
+ and quoted otherwise; a **literal** quoted the way Postgres's `quote_literal`
810
+ does (safe under either `standard_conforming_strings`); or an **output name**
811
+ checked against `ident` and quoted. Values from a request bind as parameters and never reach
783
812
  text at all. The name grammar (`identifier.schema.ts`) is checked three
784
813
  times — at parse, in the resolver for a DSL that skipped parsing, and by a
785
- compiler that refuses any field position that did not resolve.
786
-
787
- ⟲ It was not, until 2026-09-24. Field positions (`isNull`, `in`, `like`,
788
- aggregate arguments) were typed `z.string()`; the resolver skipped any
789
- string without a dot and the compiler pasted it into the statement, so
790
- `{ isNotNull: "(SELECT secret FROM …)" }` was a boolean oracle over a table
791
- the policy denied. Output names went into `AS "…"` unescaped, and a literal
792
- containing a backslash could close its own string on a server with
793
- `standard_conforming_strings` off. `test/security/injection.test.ts` is the
794
- attack list, against a real Postgres; it failed 35 of 41 before the fix.
814
+ compiler that refuses any field position that did not resolve. With
815
+ `qualifyTables`, one more piece of text reaches a statement: the adapter's
816
+ `schema` option, set by the operator and never by a query, quoted before
817
+ each table name. `test/security/injection.test.ts` is the attack list,
818
+ against a real Postgres.
795
819
 
796
820
  2. **The LLM is injected, not embedded.** Making `generateDsl`/`mapToShape`
797
821
  plain hooks keeps the engine deterministic and testable without a model,
@@ -849,6 +873,32 @@ byte for byte, so nothing a cache already holds under one has moved.
849
873
  engine-trusted field, so there is no key to strip at intake and no forgery
850
874
  surface to remember.
851
875
 
876
+ 5. **Negative caching with a TTL.** An "impossible" request is expensive to
877
+ re-discover every time, so a `cannotSatisfy` result is cached — but TTL'd and
878
+ fingerprinted, because a schema change can make yesterday's impossible
879
+ request possible.
880
+
881
+ 6. **Single-flight on the default path.** A burst of identical cache misses
882
+ collapses to one generation; the rest await it. (The `refresh`/`bypass`
883
+ cache modes that opted out died with v1 — see *Cache v2*.)
884
+
885
+ 7. **Adapters own compilation.** The DSL and agent loop are database-agnostic;
886
+ only SQL generation is not. Keeping the entire compile step inside the
887
+ adapter means a new backend is a self-contained unit and the core never grows
888
+ dialect knowledge.
889
+
890
+ 8. **A discovery endpoint, not just a query endpoint.** A self-describing
891
+ resource (`GET` → entities + contract + DSL JSON Schema) lets a client — or
892
+ another agent — learn how to query it without out-of-band documentation.
893
+
894
+ 9. **Writes are replay-only, one wire shape with reads.** Mutations are
895
+ dev-authored cache entries (`kind: 'mutation'`) invoked by fingerprint;
896
+ the def never travels and no generation path exists. The client-facing
897
+ API is uniformly `{ fingerprint, context }` — the entry's kind picks the
898
+ pipeline. Context signatures are DERIVED from the stored def (typed from
899
+ the schema by position), so the input contract can't drift.
900
+
901
+
852
902
  10. **`exists` shadows SQL rather than inventing a vocabulary.** Correlated
853
903
  subqueries were the one thing the filter grammar could not express, so
854
904
  "issues nobody was sent to" and "rooms nobody is in" became two round trips
@@ -884,31 +934,6 @@ byte for byte, so nothing a cache already holds under one has moved.
884
934
  an answer about somebody else's rows, and an uncorrelated `exists` over a
885
935
  scoped table would otherwise report whether ANY tenant had one.
886
936
 
887
- 5. **Negative caching with a TTL.** An "impossible" request is expensive to
888
- re-discover every time, so a `cannotSatisfy` result is cached — but TTL'd and
889
- fingerprinted, because a schema change can make yesterday's impossible
890
- request possible.
891
-
892
- 6. **Single-flight on the default path.** A burst of identical cache misses
893
- collapses to one generation; the rest await it. (The `refresh`/`bypass`
894
- cache modes that opted out died with v1 — see *Cache v2*.)
895
-
896
- 7. **Adapters own compilation.** The DSL and agent loop are database-agnostic;
897
- only SQL generation is not. Keeping the entire compile step inside the
898
- adapter means a new backend is a self-contained unit and the core never grows
899
- dialect knowledge.
900
-
901
- 8. **A discovery endpoint, not just a query endpoint.** A self-describing
902
- resource (`GET` → entities + contract + DSL JSON Schema) lets a client — or
903
- another agent — learn how to query it without out-of-band documentation.
904
-
905
- 9. **Writes are replay-only, one wire shape with reads.** Mutations are
906
- dev-authored cache entries (`kind: 'mutation'`) invoked by fingerprint;
907
- the def never travels and no generation path exists. The client-facing
908
- API is uniformly `{ fingerprint, context }` — the entry's kind picks the
909
- pipeline. Context signatures are DERIVED from the stored def (typed from
910
- the schema by position), so the input contract can't drift.
911
-
912
937
  ---
913
938
 
914
939
  ## Deferred
@@ -981,7 +1006,9 @@ AND A CALLER IS NOT ONE ROLE. Reach belongs to a role, and people hold several
981
1006
  the instructor who trains at the studio they teach at is the ordinary case, not
982
1007
  the edge. So the unit of compilation is the ROLE: one policy each, merged
983
1008
  (`mergeScopePolicies`), broadest rule set winning per entity and phase. A
984
- principal may do anything any of their roles permits.
1009
+ principal may do anything any of their roles permits, as far as one rule set can
1010
+ say it: two rule sets with the same number of matches are not combined, and the
1011
+ role listed first wins.
985
1012
 
986
1013
  That merge has a consequence worth stating plainly: for somebody holding both, a
987
1014
  staff role's studio-wide reach WINS over a member role's personal one on the
package/DOCS.md CHANGED
@@ -185,6 +185,21 @@ type QueryEngineConfig = {
185
185
  - `createPostgresAdapter({ pool, exclude })` names tables the adapter never
186
186
  reports: `introspect()` leaves them out. It is for tables the host owns that
187
187
  are not application data, such as a migration journal.
188
+ - `createPostgresAdapter({ pool, schema })` makes `introspect()` list the tables
189
+ of that Postgres schema (`public` without it). Queries and mutations name
190
+ their tables without a schema, so they resolve through the connection's
191
+ `search_path`: with `schema`, set the `search_path` to that schema too, or
192
+ reads and writes reach the tables of another schema.
193
+ - `createPostgresAdapter({ pool, schema, qualifyTables: true })` writes the
194
+ schema's name on every table instead (`FROM "app".tasks`), in reads and in
195
+ mutations, so the `search_path` does not matter. `introspect()` then returns
196
+ the name as `namespace` on the `DatabaseSchema`, and the mutation compiler
197
+ reads it there. It is not part of the schema fingerprint, so cached entries
198
+ stay fresh when the option is turned on. Without the option, tables are named
199
+ bare, as above: a host that points the `search_path` at a schema per tenant
200
+ keeps doing so. With the option, `adapter.introspect({ schema: 'other' })`
201
+ lists `other`'s tables but still names them, and reports `namespace`, with the
202
+ adapter's own `schema`.
188
203
  - `config.statementTimeoutMs` is enforced by the database (`statement_timeout`),
189
204
  set up at `introspect()`. A database that cannot enforce it (PGlite) runs
190
205
  reads unbounded and the engine warns each time `introspect()` runs. A `PgPool`
@@ -225,6 +240,7 @@ type ExecuteOptions = {
225
240
  entities?: string[]; // restrict generation to this entity subset for this call
226
241
  locked?: boolean; // replay-only: unknown/changed fingerprints throw `locked` instead of generating
227
242
  scopePolicy?: ScopePolicy; // per-request policy; overrides the engine's configured one for this call
243
+ policyForReach?: (reach: string) => ScopePolicy | undefined | Promise<ScopePolicy | undefined>; // the same principal's policy at a reach a replayed entry declares
228
244
  signal?: AbortSignal; // with onChange: follow a `refresh: 'reactive'` entry until it aborts
229
245
  onChange?: (response: QueryResponse) => void; // every later answer that differs from the last
230
246
  };
@@ -257,6 +273,8 @@ type QueryRequest = {
257
273
  ```
258
274
 
259
275
  The request is Zod-validated; `execute` throws `invalid_request` on failure.
276
+ A `fingerprint` or `intent` sent as `null` is read as left out. A `null` in
277
+ `context` is a value and stays.
260
278
  It must carry a `fingerprint`, a `shape`, or both — the three postures:
261
279
 
262
280
  1. **Explore** — `{ intent, shape, context }`: generate, cache, mint a
@@ -361,6 +379,7 @@ type QueryEngine = {
361
379
  getDslSchema: () => object;
362
380
  getSchema: () => DatabaseSchema | undefined;
363
381
  cache: CacheBackend;
382
+ readonly scopePolicy?: ScopePolicy;
364
383
  invalidate: (tables: readonly string[]) => void;
365
384
  rows: { stats: () => LiveRowsStats; stop: () => void };
366
385
  };
@@ -384,6 +403,9 @@ type QueryEngine = {
384
403
  feed an LLM so it learns the DSL.
385
404
  - **`getSchema()`** — the last introspected `DatabaseSchema`, or `undefined`.
386
405
  - **`cache`** — the live `CacheBackend` for inspection or manual eviction.
406
+ - **`scopePolicy`** — the policy given to `createQueryEngine` (`scope`), absent
407
+ when none was. A call that passes no policy of its own runs under it, and
408
+ discovery lists under it when the handler has none.
387
409
  - **`invalidate(tables)`** — these tables were written: every reactive read
388
410
  over any of them is refetched (once per burst). The vex handler calls it after
389
411
  every committed mutation; a host calls it for writes vex did not make.
@@ -469,7 +491,13 @@ Each entry is `entity.field`, or `{ field, as }` to set a distinct output key
469
491
  without a compute). There is no `SELECT *`. `fields` is **optional** — omit it
470
492
  for an aggregate-only query (e.g. a bare `COUNT(*)`); a query must have at least
471
493
  one of `fields` / `aggregate`. Every entity referenced anywhere must also appear
472
- in `from`.
494
+ in `from`. A table with a foreign key to itself can be listed twice and is
495
+ joined to itself along it; every path names the last copy, and scope rules
496
+ apply to both.
497
+
498
+ A query is refused when an optional key is `null`: `"limit": null` is an
499
+ error, not a missing limit. The query agent's tools read a top-level `null`
500
+ argument as left out.
473
501
 
474
502
  ```json
475
503
  { "from": ["order", "customer"],
@@ -657,8 +685,10 @@ const engine = createQueryEngine({
657
685
  });
658
686
  ```
659
687
 
660
- At execution, the `query` ref's text is read from context, embedded, and bound
661
- as the vector parameter. (Never select a vector column directly in `fields` — it
688
+ At execution, the `query` ref's text is read from context (`$context`) or from
689
+ the scope values the host supplies (`$scope`), embedded, and bound as the vector
690
+ parameter. A missing `$scope` value is refused with `missing_scope`, as any
691
+ other scope slot is. (Never select a vector column directly in `fields` — it
662
692
  is for `semantic` filters only.)
663
693
 
664
694
  ---
@@ -842,6 +872,16 @@ holding two additive rather than a conflict to arbitrate.
842
872
  practice. A phase only one role grants keeps that role's rules intact, which is
843
873
  what carries a member's identity stamp onto a write no other role grants.
844
874
 
875
+ Two rule sets with the same number of matches are not combined: the role listed
876
+ first wins, and the principal reads only the rows its rules allow. The merged
877
+ policy is `default: 'deny'`, so a role's `default: 'allow'` is not carried over.
878
+ Each entity is read as the phases it grants before the rule sets are compared: a
879
+ `public` entity grants all four phases with no rule; a `write` list is added to
880
+ insert, update and delete (its `match` rules only, for delete), as
881
+ `createScopePolicy` does; a `deny` entity grants nothing, so another role's grant
882
+ stands. `{ write: [tenant], update: [] }` therefore merges to
883
+ `update: [tenant]`.
884
+
845
885
  ### A read that must stay narrow
846
886
 
847
887
  The merge above widens. For a read whose answer legitimately widens with the
@@ -861,11 +901,18 @@ only narrow rows, never widen phases. A caller with no verb for the table is
861
901
  still refused. A mutation entry takes `reach` the same way (`SeedMutation.reach`),
862
902
  and the write is compiled at that profile whoever asks.
863
903
 
864
- The host supplies `policyForReach(reach)` (hono: `getPolicyForReach(c, reach)`),
865
- because vex holds neither grants nor behaviors. **It fails closed both ways:** an
866
- entry declaring a reach no host can resolve is a 500, and a host returning
867
- `undefined` is a 403. Falling back to the caller's own reach would be silent,
868
- and silence is the whole risk — the read would answer, with too much.
904
+ The host supplies `policyForReach(reach)` (hono: `getPolicyForReach(c, reach)`; express: `getPolicyForReach(req, reach)`),
905
+ because vex knows neither grants nor behaviors. **The handler fails closed both
906
+ ways:** an entry declaring a reach no host can resolve is a 500, and a host
907
+ returning `undefined` is a 403. Falling back to the caller's own reach would be
908
+ silent, and silence is the whole risk — the read would answer, with too much.
909
+
910
+ That is `handleQuery` and the hono and express adapters. `engine.execute`
911
+ serves a replayed entry's `reach` through `ExecuteOptions.policyForReach`: the
912
+ run uses the policy it returns, and `undefined` throws `scope_denied`. Without
913
+ `policyForReach` it runs under the policy it is handed (`scopePolicy`, else the
914
+ engine's own), whatever reach the entry declares, and logs one warning per
915
+ fingerprint saying so.
869
916
 
870
917
  ## Upgraded columns
871
918
 
@@ -983,7 +1030,16 @@ REQUIRE a `where` (a real vex `Filter`).
983
1030
  ```
984
1031
 
985
1032
  An `upsert` updates the row when the call's context carries its `key`, and
986
- inserts when the key is absent or an empty string.
1033
+ inserts when the key is absent or an empty string. A `null` key inserts where
1034
+ the database makes the key: the introspected key column has a default (such as
1035
+ `gen_random_uuid()` or a sequence) or is an identity column, and the entry does
1036
+ not write the key itself in `columns` or `insert`. Like an absent key, it is
1037
+ then refused with `scope_denied` for a caller who may update but not insert.
1038
+ Anywhere else a `null` key is an update of no row and answers `[]`, since an
1039
+ insert there would write NULL into the key. A write that matched no row answers
1040
+ `[]`: check the length. Introspection gives an identity column the
1041
+ `defaultValue` `GENERATED ALWAYS AS IDENTITY` or `GENERATED BY DEFAULT AS
1042
+ IDENTITY`.
987
1043
 
988
1044
  An array of ops is a batch and runs in ONE transaction (the client must
989
1045
  expose `transaction`; a batch on a non-transactional client is refused).
@@ -1165,6 +1221,34 @@ handleQuery({ engine, locked: true, mutations: { client: db, policy } }, body, s
1165
1221
  double). `locked` does not affect writes: they are replay-only under every
1166
1222
  posture. Direct library use: `executeMutation(client, def, { context, scope, policy, schema })`.
1167
1223
 
1224
+ **A write keeps its rows inside the caller's update rules.** When an
1225
+ `update`, the update half of an `upsert`, or an insert's `onConflict … set`
1226
+ writes a column one of the caller's update `match` rules names, the new value
1227
+ must match that rule too. An update that would move a row out is refused before
1228
+ anything is written: 400 `scope_denied`, naming the rule and the column (`the
1229
+ new "tasks.project_id" is not one of the scope's "projectIds"`); in a batch,
1230
+ the whole batch is refused. An `onConflict` update leaves such a row as it is
1231
+ and answers no row for it, as for a conflicting row outside the rules; a host
1232
+ with `default: 'allow'` and only update rules on a table gets this check on
1233
+ its `onConflict … set` too. A column
1234
+ a `set` rule stamps is the policy's own value and is not checked. To let a write
1235
+ move a row out of its own rules — handing a task over by setting `owner_id`
1236
+ under an `owner_id = me` rule — set `mutations: { …, checkMovedRows: false }`
1237
+ (`executeWrites(client, def, { …, checkMovedRows: false })` at the library
1238
+ level).
1239
+
1240
+ **What a write answers.** By default a write answers every row it wrote,
1241
+ whole (`RETURNING *`), whatever the caller's read rules say: renaming a task
1242
+ the update rules reach answers the whole row, columns and all, even when the
1243
+ read rules would not show it. `mutations: { …, answerReadableRows: true }`
1244
+ answers only the rows the caller's read rules show; the write itself is
1245
+ unchanged. An `update`, a `delete`, and an insert with `onConflict … set` are
1246
+ filtered; a plain insert answers the row it created. A read rule whose scope
1247
+ value the host left out hides the row; it does not refuse the write. Off by
1248
+ default, because some setups depend on the whole answer: a sign-in entry that
1249
+ deletes a one-time link and reads who signs in from the deleted row, run by a
1250
+ role that has no read grant on the link table, would answer `[]` with it on.
1251
+
1168
1252
  A host that resolves a policy **per principal** (e.g. compiled from an ACL
1169
1253
  layer) passes it per request: `VexHandlerConfig.scopePolicy` overrides the
1170
1254
  engine's configured read policy for that request (`ExecuteOptions.scopePolicy`
@@ -1217,9 +1301,10 @@ successful mutation replay, AFTER the commit:
1217
1301
  mutations: {
1218
1302
  client, policy,
1219
1303
  onWrite: ({ fingerprint, writes, scope }) => { … },
1220
- // writes: [{ table, op, rows }] — per statement, resolved post-desugar
1304
+ // writes: [{ table, op, rows, readable? }] — per statement, resolved post-desugar
1221
1305
  // (an upsert reports the branch it took; insertEach reports 'insert'),
1222
- // rows as the database returned them. scope: what the request could
1306
+ // rows as the database returned them; readable, under answerReadableRows,
1307
+ // the ones the caller's read rules show. scope: what the request could
1223
1308
  // not forge.
1224
1309
  }
1225
1310
  ```
@@ -1267,7 +1352,14 @@ are not asking the same thing).
1267
1352
 
1268
1353
  ### Lifetime and protection
1269
1354
 
1270
- - A replay stamps `lastUsedAt` (at most once a minute per entry);
1355
+ - A replay stamps `lastUsedAt` (at most once a minute per entry). It calls the
1356
+ backend's optional `touch(key, lastUsedAt)`, which writes that field alone, so
1357
+ a `PATCH` or a reseed landing between the replay's read and its stamp is kept.
1358
+ The memory, Postgres and tiered caches have it (the tiered one when both its
1359
+ levels do). A backend without it is stamped through `set` with the whole entry
1360
+ the replay read, and keeps the race. A wrapper that spreads a built-in cache
1361
+ and overrides `set` inherits that cache's `touch`, so its stamps go through
1362
+ `touch` and never reach the wrapper's `set`.
1271
1363
  `sweepCache(cache, { maxIdleMs })` evicts entries idle past the limit,
1272
1364
  skipping protected ones, and returns how many it evicted. Alive = used.
1273
1365
  Nothing in vex calls it: a host runs it at startup or on a timer.
@@ -1613,9 +1705,10 @@ The rest of `VexHonoConfig`, all optional:
1613
1705
  | Option | Purpose |
1614
1706
  |--------|---------|
1615
1707
  | `locked` | Replay-only endpoint: no generation, no fingerprint management |
1708
+ | `manageFingerprints` | `false` refuses `PATCH` and `DELETE` with 403 `locked` on an unlocked endpoint, which still generates. Default on: an unlocked endpoint with it on logs one warning as it is mounted |
1616
1709
  | `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 |
1617
1710
  | `getPolicyForReach(c, reach)` | The same principal's policy at a reach an entry demands |
1618
- | `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 |
1711
+ | `mutations` | `{ client, policy?, onWrite?, checkMovedRows?, answerReadableRows? }` — 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 |
1619
1712
  | `onExecute` | The execution observer (see [Events](#events)) |
1620
1713
 
1621
1714
  `vex` and `VexHonoConfig` are generic over the hono `Env`: `vex<AppEnv>({ … })`
@@ -1638,9 +1731,12 @@ app.all('/api/orders/vex', vex({
1638
1731
  }));
1639
1732
  ```
1640
1733
 
1641
- `VexExpressConfig` also takes `locked` and `mutations`
1642
- (`{ client, policy, onWrite? }`). It has no per-request policy hook. Any method
1643
- other than `GET`/`POST`/`PATCH`/`DELETE` answers 405.
1734
+ `VexExpressConfig` also takes `locked`, `manageFingerprints`, `mutations` (`{ client, policy, onWrite?, checkMovedRows?, answerReadableRows? }`),
1735
+ `getPolicy(req)`, `getPolicyForReach(req, reach)` and `onExecute`. These mean
1736
+ what they mean for Hono: `getPolicy` governs reads, mutation replay and
1737
+ discovery, and when it returns `undefined` the engine's policy and
1738
+ `mutations.policy` stay in force. `PATCH` and `DELETE` carry no per-request
1739
+ policy. Any method other than `GET`/`POST`/`PATCH`/`DELETE` answers 405.
1644
1740
 
1645
1741
  ### The endpoints
1646
1742
 
@@ -1652,8 +1748,12 @@ other than `GET`/`POST`/`PATCH`/`DELETE` answers 405.
1652
1748
  shape|effect }]` — `context` is the derived, typed input signature; `effect`
1653
1749
  summarizes a write), and the full DSL JSON Schema. A client or agent can read
1654
1750
  this to learn how to call the resource — and exactly what each fingerprint
1655
- takes. Under a per-request policy, entities and entries the policy cannot
1656
- touch are not listed.
1751
+ takes. Each is listed only where the policy it runs under lets it run.
1752
+ Entities and read entries go by the policy a query there runs under: the
1753
+ per-request policy when there is one, otherwise the engine's
1754
+ (`createQueryEngine({ scope })`). A write entry goes by the policy its write
1755
+ runs under, `mutations.policy` (the per-request policy on an adapter with
1756
+ `getPolicy`).
1657
1757
  - **`POST`** → runs a query OR replays a write, one body shape. A
1658
1758
  `fingerprint` naming a `kind: 'mutation'` entry dispatches to the write
1659
1759
  pipeline (when `mutations` is configured); anything else is the read path
@@ -1671,11 +1771,20 @@ other than `GET`/`POST`/`PATCH`/`DELETE` answers 405.
1671
1771
  principal → 403 `scope_denied`. 500s are the host's faults: `missing_scope`
1672
1772
  (key names stay in the log), an entry demanding a reach with no
1673
1773
  `policyForReach`, a mutation fingerprint on a handler with no `mutations`
1674
- configured, and unexpected errors.
1774
+ configured, and unexpected errors, a context value that does not fit its
1775
+ column among them. The log line of an unexpected error carries its code,
1776
+ message and stack, and the SQL text where the driver's error carries it
1777
+ (PGlite's does, node-postgres's does not); never the error object, which can
1778
+ hold the statement's bound values.
1675
1779
  - **`PATCH`** with `{ fingerprint, protected }` → flip the protection bit.
1676
1780
  **`DELETE`** with `{ fingerprint }` → evict (a protected entry, read or mutation,
1677
1781
  is refused with 409 `fingerprint_protected`). Both are refused with 403 `locked` on a
1678
- locked endpoint and answer 404 `cache_miss` for an unknown fingerprint.
1782
+ locked endpoint, or one with `manageFingerprints: false`, and answer 404
1783
+ `cache_miss` for an unknown fingerprint. Otherwise they check nobody: no
1784
+ policy, no scope. Whoever reaches the endpoint can unprotect any entry, a
1785
+ seeded one included, and delete it; the adapter logs one warning saying so
1786
+ when it mounts such an endpoint. An agent's endpoint that generates but
1787
+ should manage nothing sets `manageFingerprints: false`.
1679
1788
  Fingerprints ride the body — names contain `/` — and a body that is not
1680
1789
  JSON, or carries no fingerprint, is a 400 `invalid_request` before anything
1681
1790
  else is checked.
@@ -1720,7 +1829,7 @@ log); the engine itself emits the `query.*` and `rows.*` events.
1720
1829
 
1721
1830
  ### The execution observer
1722
1831
 
1723
- `onExecute` (handler config; the hono adapter passes it through) fires once per
1832
+ `onExecute` (handler config; the hono and express adapters pass it through) fires once per
1724
1833
  `handleQuery`, read or write, after the outcome is known:
1725
1834
 
1726
1835
  ```typescript
package/README.md CHANGED
@@ -64,6 +64,23 @@ Then keep **one** unlocked endpoint (wired with `generateDsl`) for genuine
64
64
  ad-hoc queries — an agent, an admin console — under its own scope policy. Built
65
65
  surfaces are locked; exploration is open and scoped.
66
66
 
67
+ An unlocked endpoint also answers `PATCH` and `DELETE`, and they check nobody:
68
+ whoever reaches it can unprotect any entry, a seeded one included, and then
69
+ delete it or generate over it. Fingerprints are global, so that changes what
70
+ the locked endpoints replay. An endpoint for an agent turns that off:
71
+
72
+ ```typescript
73
+ app.route('/api/agent/vex', vex({
74
+ engine, // wired with generateDsl
75
+ getScope: async (c) => ({ accountId: await resolveAccount(c) }),
76
+ getPolicy: (c) => agentPolicy(c),
77
+ manageFingerprints: false, // PATCH and DELETE answer 403 `locked`
78
+ }));
79
+ ```
80
+
81
+ Left on, the adapter logs one warning as it mounts the endpoint; keep it on
82
+ only where everybody who reaches the endpoint may manage every entry.
83
+
67
84
  ## Documentation
68
85
 
69
86
  - **[DOCS.md](./DOCS.md)** — Full usage guide: configuration, DSL reference, scope, caching, framework adapters, error handling, local dev.