@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.
Files changed (40) hide show
  1. package/CHANGELOG.md +90 -0
  2. package/DESIGN.md +72 -45
  3. package/DOCS.md +219 -21
  4. package/README.md +18 -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-CoJxInw-.d.ts → handler-DdfaWN_J.d.ts} +7 -1
  28. package/dist/{handler-CsFbanZA.d.cts → handler-kvZkxwaN.d.cts} +7 -1
  29. package/dist/index.cjs +667 -259
  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 +290 -248
  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-B2HEmyNq.d.cts → types-BxkRxTTx.d.cts} +38 -2
  38. package/dist/{types-DC68ZUuq.d.ts → types-DgUZNKii.d.ts} +38 -2
  39. package/package.json +8 -8
  40. 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
- 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