@niscorp/vex 0.4.4 → 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 +90 -0
- package/DESIGN.md +72 -45
- package/DOCS.md +219 -21
- package/README.md +18 -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-CoJxInw-.d.ts → handler-DdfaWN_J.d.ts} +7 -1
- package/dist/{handler-CsFbanZA.d.cts → handler-kvZkxwaN.d.cts} +7 -1
- package/dist/index.cjs +667 -259
- 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 +290 -248
- 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-B2HEmyNq.d.cts → types-BxkRxTTx.d.cts} +38 -2
- package/dist/{types-DC68ZUuq.d.ts → types-DgUZNKii.d.ts} +38 -2
- package/package.json +8 -8
- package/dist/chunk-W5MYFJKT.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,95 @@
|
|
|
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
|
+
|
|
81
|
+
## 0.4.5
|
|
82
|
+
|
|
83
|
+
### Patch Changes
|
|
84
|
+
|
|
85
|
+
- 637d412: **A vex read returns stamped JSON columns upgraded.** A JSON column whose values carry the grammar stamp they were written at in another JSON column of the row can now be named once on the engine, with a strata upgrader beside it: `createQueryEngine({ upgrader: await createUpgrader(grammars, { transform: evaluate }), upgradedColumns: { answers: { plan: { stamp: 'grammar', kind: 'acme.answers/plan' } } } })`. A kind can also be read from the row: `kind: { grammar: 'acme.notes', column: 'kind' }`. Every read that returns the column (a replay, a generated read, a reactive read's every answer, `engine.test`) hands its mapping and its caller the value upgraded, with the stamp set to the stamp the upgrade gives back. A read returns the column only as one of its own fields, with its stamp (and kind) column beside it; vex refuses any other read of it when the read is compiled. A row that does not upgrade refuses the read, or, where the column says `unreadable: 'omit'` or `'null'`, is left out or has that value set to null, with a line in `meta.warnings`. New exports: `UpgradedColumnsSchema`, `UNREADABLE_MODES`, and the types `UpgradedColumn`, `UpgradedColumns`, `ColumnUpgrader`.
|
|
86
|
+
|
|
87
|
+
**Moss takes them on the manifest.** `defineApp({ upgradedColumns })` hands them to the app's engine and to the one that answers intents, with the upgrader moss builds from nova's, Prism's and vex's grammars and the app's `grammars`. Only the app's own tables can be named. The boot is refused where a table named is a feature's, the artifactory's or the generation pointer's (their owners read them as stored), where a kind is in none of those grammars, where a column or its stamp is not a json column of the database, or where a seeded read does not compile: an app that names `upgradedColumns` has every seeded read compiled at boot and on a refresh, so a read of an upgraded column that vex refuses stops the boot rather than its first replay.
|
|
88
|
+
|
|
89
|
+
**The rulebook** says so under "Using Vex" and in rule 19.
|
|
90
|
+
|
|
91
|
+
**What to change:** nothing. An app or engine that names no `upgradedColumns` reads every column as stored, as before. No grammar, table, entry or cache format changes.
|
|
92
|
+
|
|
3
93
|
## 0.4.4
|
|
4
94
|
|
|
5
95
|
### 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
|