@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.
- package/CHANGELOG.md +78 -0
- package/DESIGN.md +72 -45
- package/DOCS.md +130 -21
- package/README.md +17 -0
- package/dist/adapters/express/index.cjs +606 -173
- package/dist/adapters/express/index.cjs.map +1 -1
- package/dist/adapters/express/index.d.cts +6 -2
- package/dist/adapters/express/index.d.ts +6 -2
- package/dist/adapters/express/index.js +16 -3
- package/dist/adapters/express/index.js.map +1 -1
- package/dist/adapters/hono/index.cjs +597 -173
- package/dist/adapters/hono/index.cjs.map +1 -1
- package/dist/adapters/hono/index.d.cts +5 -2
- package/dist/adapters/hono/index.d.ts +5 -2
- package/dist/adapters/hono/index.js +7 -3
- package/dist/adapters/hono/index.js.map +1 -1
- package/dist/agent/index.cjs +12 -12
- package/dist/agent/index.cjs.map +1 -1
- package/dist/agent/index.d.cts +1 -1
- package/dist/agent/index.d.ts +1 -1
- package/dist/agent/index.js +12 -12
- package/dist/agent/index.js.map +1 -1
- package/dist/{chunk-W5MYFJKT.js → chunk-F7OXXJIH.js} +562 -192
- package/dist/chunk-F7OXXJIH.js.map +1 -0
- package/dist/{chunk-F7RDSWYF.js → chunk-VHNCSQPO.js} +2 -2
- package/dist/{chunk-F7RDSWYF.js.map → chunk-VHNCSQPO.js.map} +1 -1
- package/dist/{handler-O6XslV-S.d.ts → handler-DdfaWN_J.d.ts} +7 -1
- package/dist/{handler-CB0BqKsY.d.cts → handler-kvZkxwaN.d.cts} +7 -1
- package/dist/index.cjs +493 -232
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +5 -3
- package/dist/index.d.ts +5 -3
- package/dist/index.js +118 -221
- package/dist/index.js.map +1 -1
- package/dist/migrations/index.cjs.map +1 -1
- package/dist/migrations/index.js +1 -1
- package/dist/{types-BmHuPfPS.d.cts → types-BxkRxTTx.d.cts} +5 -0
- package/dist/{types-D5CCaqcd.d.ts → types-DgUZNKii.d.ts} +5 -0
- package/package.json +8 -8
- 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
|
-
|
|
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
|
|
780
|
-
schema,
|
|
781
|
-
|
|
782
|
-
|
|
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
|
-
|
|
788
|
-
|
|
789
|
-
|
|
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
|
|
661
|
-
|
|
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
|
|
866
|
-
entry declaring a reach no host can resolve is a 500, and a host
|
|
867
|
-
`undefined` is a 403. Falling back to the caller's own reach would be
|
|
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
|
|
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`
|
|
1642
|
-
(`
|
|
1643
|
-
|
|
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.
|
|
1656
|
-
|
|
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
|
|
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
|
|
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.
|