@loradb/lora-graphql 0.21.0 → 0.22.1

package/README.md

@@ -44,6 +44,7 @@ const lora = new LoraGraphQL({ typeDefs, driver: loraDriver(db) });
 await lora.assertSchema({ create: true }); // the constraints and indexes the API needs
 const yoga = createYoga({
   schema: lora.getSchema(),
+  plugins: [lora.envelopPlugin()], // document guards (and atomic mutations)
   context: ({ request }) => ({
     jwt: verifiedClaims(request),
     signal: request.signal,
@@ -85,6 +86,7 @@ them off):
 | `searchFestivals(query, where, limit)`                         | Full-text search, with `@fulltext`                                                                        |
 | `similarFestivals(vector or to, where, limit)`                 | Vector similarity, with a `@vector` field                                                                 |
 | `node(id:)`                                                    | Any `@relayId` type by global id                                                                          |
+| `nodes(ids:)`                                                  | Many global ids at once, in order; null where unknown or hidden (at most `maxLimit`)                      |
 | `events(where, sort, limit)`                                   | An interface's or union's members together                                                                |
 | `createFestivals`, `upsertFestivals`                           | With `@mutation(CREATE)` (upsert also needs `UPDATE`)                                                     |
 | `updateFestival`, `updateFestivals(where, limit)`              | With `@mutation(UPDATE)`: by key, or bulk by `where`                                                      |
@@ -108,31 +110,41 @@ field, a `@selectable` on a field of an object type without `@node`, a
 position, never silently ignored. `DIRECTIVE_POSITIONS` in
 `src/model/positions.ts` is the full table.
 
+A directive on an extension (`extend type Secret @authorization(...)`,
+`extend interface`, `extend union`, `extend scalar`, `extend schema`)
+applies exactly as on the definition, so a type's rules may live in
+another file. Repeatable directives (`@uniqueTogether`,
+`@authorizationRule`) add up across the definition and its extensions;
+any other directive written on both is an error. `extend type X @node`
+makes a plain `type X` a node type; extending a type that is never
+defined is an error.
+
 Model:
 
-| Directive                                                                                                  | On                | Meaning                                                                                                                                                                                                                                    |
-| ---------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@node(labels:, plural:)`                                                                                  | type              | A node label set; default: the type name                                                                                                                                                                                                   |
-| `@key(generate:)`                                                                                          | field             | Required, unique and immutable. The sort tie-breaker, cursor anchor and mutation address. `generate: true` fills a UUID on create                                                                                                          |
-| `@unique`                                                                                                  | field             | Uniqueness constraint                                                                                                                                                                                                                      |
-| `@index(kind: RANGE \| TEXT \| POINT)`                                                                     | field             | An explicit index, usually inferred                                                                                                                                                                                                        |
-| `@storedAs(type:)`                                                                                         | custom scalar     | How a custom scalar is stored (`STRING`, `INT`, `FLOAT`, `BOOLEAN`, `DATETIME`, `DATE`); its SDL description is what clients see, whatever implementation `scalars` passes                                                                 |
-| `@relationship(type:, direction:, properties:, queryDirection:, onDelete:, nestedOperations:, aggregate:)` | field             | An edge to a `@node` type, interface or union. `queryDirection: UNDIRECTED` reads both ways; `onDelete: DETACH \| CASCADE \| RESTRICT`; `nestedOperations` lists the nested writes inputs offer; `aggregate: false` drops its aggregates   |
-| `@declareRelationship`                                                                                     | interface field   | Every implementation declares this relationship (type and direction may differ); select it on the interface                                                                                                                                |
-| `@relationshipProperties`                                                                                  | type              | Properties on a relationship type                                                                                                                                                                                                          |
-| `@alias(property:)`                                                                                        | field             | API name differs from the stored property                                                                                                                                                                                                  |
-| `@private`                                                                                                 | field             | Stored, never exposed                                                                                                                                                                                                                      |
-| `@readonly`                                                                                                | field             | Exposed, never client-settable; on a relationship, absent from create and update inputs                                                                                                                                                    |
-| `@settable(onCreate:, onUpdate:)`                                                                          | field             | Which mutations may set it, e.g. set once on create; on a relationship, whether the inputs offer it (an upsert of an existing node keeps it); on a relationship property, `onUpdate: false` also refuses a re-connect that would change it |
-| `@selectable(onRead:, onAggregate:)`                                                                       | field             | `onRead: false` makes a field write-only; on a relationship property, it leaves the edge type too (`onAggregate: false`, the edge aggregates); with every property hidden, the edge has no `properties`                                    |
-| `@default(value:)`                                                                                         | field             | Stored on create when the input omits it; on a relationship property, when the relationship is created                                                                                                                                     |
-| `@timestamp(operations: [CREATE, UPDATE])`                                                                 | field             | Set to the current time; never client-settable. On a relationship property: CREATE when the relationship is created, UPDATE on edge updates and re-connects that set properties                                                            |
-| `@populatedBy(callback:, operations:)`                                                                     | field             | Computed by a named callback on write                                                                                                                                                                                                      |
-| `@cardinality(max:)`                                                                                       | list relationship | Declared fan-out, for cost estimates                                                                                                                                                                                                       |
-| `@cypher(statement:, columnName:)`                                                                         | field             | A field backed by a Cypher statement. Returns scalars, `@node` types, interfaces or unions over them, or object types without `@node` (read from a map)                                                                                    |
-| `@fulltext(indexes: [{ name, fields, analyzer, queryName }])`                                              | type              | FULLTEXT indexes, each with a search root field                                                                                                                                                                                            |
-| `@vector(dimensions:, similarity:, queryName:)`                                                            | `[Float!]` field  | A VECTOR index and a similarity root field                                                                                                                                                                                                 |
-| `@plural(value:)`                                                                                          | interface, union  | The root field's name                                                                                                                                                                                                                      |
+| Directive                                                                                                  | On                | Meaning                                                                                                                                                                                                                                      |
+| ---------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@node(labels:, plural:)`                                                                                  | type              | A node label set; default: the type name                                                                                                                                                                                                     |
+| `@key(generate:)`                                                                                          | field             | Required, unique and immutable. The sort tie-breaker, cursor anchor and mutation address. `generate: true` fills a UUID on create                                                                                                            |
+| `@unique`                                                                                                  | field             | Uniqueness constraint                                                                                                                                                                                                                        |
+| `@uniqueTogether(fields:, where:)`                                                                         | type              | No two nodes (matching `where`) share these fields: scalars, single relationships, at most one list relationship as a set. Repeatable; see [Mutations](#mutations)                                                                           |
+| `@index(kind: RANGE \| TEXT \| POINT)`                                                                     | field             | An explicit index, usually inferred                                                                                                                                                                                                          |
+| `@storedAs(type:)`                                                                                         | custom scalar     | How a custom scalar is stored (`STRING`, `INT`, `FLOAT`, `BOOLEAN`, `DATETIME`, `DATE`); its SDL description is what clients see, whatever implementation `scalars` passes                                                                   |
+| `@relationship(type:, direction:, properties:, queryDirection:, onDelete:, nestedOperations:, aggregate:)` | field             | An edge to a `@node` type, interface or union. `queryDirection: UNDIRECTED` reads both ways; `onDelete: DETACH \| CASCADE \| RESTRICT`; `nestedOperations` lists the nested writes inputs offer; `aggregate: false` drops its aggregates     |
+| `@declareRelationship`                                                                                     | interface field   | Every implementation declares this relationship (type and direction may differ); select it on the interface                                                                                                                                  |
+| `@relationshipProperties`                                                                                  | type              | Properties on a relationship type                                                                                                                                                                                                            |
+| `@alias(property:)`                                                                                        | field             | API name differs from the stored property                                                                                                                                                                                                    |
+| `@private`                                                                                                 | field             | Stored, never exposed                                                                                                                                                                                                                        |
+| `@readonly`                                                                                                | field             | Exposed, never client-settable; on a relationship, absent from create and update inputs                                                                                                                                                      |
+| `@settable(onCreate:, onUpdate:)`                                                                          | field             | Which mutations may set it, e.g. set once on create; on a relationship, whether the inputs offer it (an upsert of an existing node keeps it); on a relationship property, `onUpdate: false` also refuses a re-connect that would change it   |
+| `@selectable(onRead:, onAggregate:)`                                                                       | field             | `onRead: false` makes a field write-only; on a relationship property, it leaves the edge type too (`onAggregate: false`, the edge aggregates); with every property hidden, the edge has no `properties`                                      |
+| `@default(value:)`                                                                                         | field             | Stored on create when the input omits it; on a relationship property, when the relationship is created                                                                                                                                       |
+| `@timestamp(operations: [CREATE, UPDATE])`                                                                 | field             | Set to the current time; client-settable only with an explicit `@settable` and a field rule (see Mutations). On a relationship property: CREATE when the relationship is created, UPDATE on edge updates and re-connects that set properties |
+| `@populatedBy(callback:, operations:)`                                                                     | field             | Computed by a named callback on write                                                                                                                                                                                                        |
+| `@cardinality(max:)`                                                                                       | list relationship | Declared fan-out, for cost estimates                                                                                                                                                                                                         |
+| `@cypher(statement:, columnName:)`                                                                         | field             | A field backed by a Cypher statement. Returns scalars, `@node` types, interfaces or unions over them, or object types without `@node` (read from a map)                                                                                      |
+| `@fulltext(indexes: [{ name, fields, analyzer, queryName }])`                                              | type              | FULLTEXT indexes, each with a search root field                                                                                                                                                                                              |
+| `@vector(dimensions:, similarity:, queryName:)`                                                            | `[Float!]` field  | A VECTOR index and a similarity root field                                                                                                                                                                                                   |
+| `@plural(value:)`                                                                                          | interface, union  | The root field's name                                                                                                                                                                                                                        |
 
 API:
 
@@ -145,6 +157,8 @@ API:
 | `@sortable`                                           | field                                        | Sort and paginate by this field (on a relationship property: `sort: [{ edge: { ... } }]`)                     |
 | `@groupBy`                                            | field                                        | A grouping key of `<plural>Grouped(by:)` (needs `@query(aggregate: true)`)                                    |
 | `@limit(default:, max:)`                              | type, interface, union, list relationship    | Page size bounds                                                                                              |
+| `@size(max:)`                                         | list argument of a `@cypher` field           | The most items it takes (default `maxListArgument`)                                                           |
+| `@range(min:, max:)`                                  | Int / Float argument of a `@cypher` field    | Bounds of its value (each item of a list); outside is `BAD_USER_INPUT`                                        |
 | `@relayId`                                            | `@key` field                                 | Adds a global `id` and the `Node` interface                                                                   |
 | `@authentication(operations:, jwt:)`                  | type, field                                  | Needs an authenticated request, whose claims satisfy `jwt`                                                    |
 | `@authorization(filter:, validate:)`                  | type (filter and validate), field (validate) | Row-level rules, compiled into statements                                                                     |
@@ -216,7 +230,10 @@ string), `Date`, `Time`, `LocalTime`, `DateTime`, `LocalDateTime`,
   out of the `OR`, and an `OR` or `NOT` with nothing left is left out
   entirely, so an unset variable never widens a filter to every row; a
   literal `OR: []` matches nothing. A relationship quantifier whose filter
-  is empty is left out too: ask `count: { gt: 0 }` for "has any".
+  is empty is left out too: ask `count: { gt: 0 }` for "has any". A single
+  relationship takes `<field>Exists: Boolean` for "is set" (`venueExists:
+false`: festivals without a venue); as in every relationship filter, a
+  related node the reader may not see counts as none.
 - `count` and `single` count related nodes once each, however many
   relationships lead to them. `all` holds on an empty set, and a missing
   property fails it.
@@ -414,6 +431,21 @@ mutation {
   remain.
 - **`@populatedBy(callback: "slug")`** computes a field with
   `callbacks: { slug: ({ input, key, context, operation }) => … }`.
+- **Supplying a computed field.** `@timestamp` and `@populatedBy` fields
+  are not in the inputs, unless `@settable(onCreate: true)` (or
+  `onUpdate: true`) says so explicitly and a field-level
+  `@authorization(validate:)` rule for that operation decides who may
+  supply the value. A supplied value is stored as given (a seed backfilling
+  history, an import keeping its dates); an omitted one is computed as
+  before. Without such a rule the combination is a model error, so a
+  computed field never becomes client-settable by accident: the schema's
+  bypass and `@authentication` are not rules here, and a bare `@settable`
+  (its defaults) changes nothing. Relationship properties cannot opt in.
+
+  ```graphql
+  createdAt: DateTime! @timestamp(operations: [CREATE]) @settable(onCreate: true)
+    @authorization(validate: [{ operations: [CREATE], where: { jwt: { roles: { includes: "admin" } } } }])
+  ```
 
 Each mutation runs in one interactive transaction and checks, before it
 commits:
@@ -422,19 +454,67 @@ commits:
 - a single relationship stays single and a required one stays set, even
   when written from the other side or when its target is deleted
   (`CONSTRAINT_VIOLATION`);
+- every `@uniqueTogether` holds (`CONSTRAINT_VIOLATION`, below);
 - `@authorization` validate rules, type and field level (`FORBIDDEN`).
 
+`@uniqueTogether` states a uniqueness the engine's per-property constraints
+cannot: over relationship ends.
+
+```graphql
+type ConnectionRequest @node @uniqueTogether(fields: ["from", "to"]) {
+  key: ID! @key(generate: true)
+  from: Person! @relationship(type: "SENT", direction: IN)
+  to: Person! @relationship(type: "TO", direction: OUT)
+}
+type Conversation
+  @node
+  @uniqueTogether(fields: ["participants"], where: { kind: { eq: DIRECT } }) {
+  key: ID! @key
+  kind: ConversationKind!
+  participants: [Person!]! @relationship(type: "IN", direction: IN)
+}
+```
+
+`fields` names scalar fields (compared by value), single relationships (by
+the target's `@key`) and at most one list relationship (by the set of
+target keys, in any order); `where` limits the nodes compared. A
+combination with a null scalar, no target or an empty set is exempt, as a
+null is in a unique index. Every generated mutation checks it after its
+writes — creates, updates, upserts, nested creates, and connects,
+disconnects and deletes from either side — for every caller, the bypass
+included: it is a data invariant, not a rule. Each check seeks the written
+nodes and compares only with nodes sharing their first relationship end
+(or, with scalars only, their first scalar's value).
+
+A `@cypher` mutation's write-set is unknown, so after its statement it
+checks every `@uniqueTogether` type the statement may write: one whose
+label, constrained relationship type or constrained scalar property
+(`.prop`) the statement text names. That check compares every node of the
+type (a scan, in the same transaction), and the model warns about each such
+mutation (`check()` reports it under `warnings`); prefer a generated
+mutation for a constrained type. Cypher of your own (`tx.execute()`, other
+clients) is not checked.
+
 Any failure rolls the whole mutation back. Atomicity is per root field:
 in an operation with several root fields, each runs in its own
 transaction, so a later failure leaves the earlier ones committed. Pass
 `mutationTransaction: "operation"` to run every root field of a mutation
 in one transaction through `execute()` (persisted operations included):
 it commits only when the operation reports no error, and otherwise rolls
-back and returns `data: null`. With another server, put a `lora.begin()`
-transaction in the context (see [Transactions](#transactions)). Engine
+back and returns `data: null`. GraphQL Yoga and other Envelop servers on
+`getSchema()` get the same from `lora.envelopPlugin()`. With another
+server calling graphql-js directly, put a `lora.begin()` transaction in
+the context (see [Transactions](#transactions)); without one, each root
+field commits on its own, and the first such mutation logs a warning. Engine
 constraint errors come
-back as `CONSTRAINT_VIOLATION` naming the type and field. A mutation creates
-or deletes at most `maxBatch` nodes (default 1000). `@key` is not updatable.
+back as `CONSTRAINT_VIOLATION` naming the type and field. A mutation writes
+at most `maxBatch` nodes (default 1000): created and updated nodes count
+together (every `upsert` input, nested creates, each nested `update`
+entry), and a delete reaches at most `maxBatch` nodes through
+`onDelete: CASCADE`. Relationships written (connects, each key of a
+`disconnect` list, nested `update` entries) count up to ten times
+`maxBatch`. Going over is `LIMIT_EXCEEDED`, before the writes that
+would exceed it. `@key` is not updatable.
 `info` reports `nodesCreated`, `nodesUpdated`, `nodesDeleted`,
 `relationshipsCreated` and `relationshipsDeleted`.
 
@@ -446,7 +526,11 @@ bounded like bulk deletes and following `onDelete`. `limit` defaults to
 `maxBatch`; more matches is `LIMIT_EXCEEDED`.
 `@relationship(nestedOperations: [CONNECT])` keeps only the listed nested
 writes in the inputs, and `aggregate: false` removes the relationship's
-aggregates and aggregate filter.
+aggregates and aggregate filter. A nested `update: [{ key, edge, node }]`
+(`UPDATE`) changes the connected node and the relationship's properties;
+`UPDATE_EDGE` offers `update: [{ key, edge }]` alone, so an input can keep
+"set my RSVP" without advertising "edit the festival" (it needs
+relationship properties).
 
 An input left with no field is left out, with what would take it: a
 relationship without settable properties has no `edge` input, and a type
@@ -498,6 +582,18 @@ the library asks it for four times the page when a filter is present.
 read back as `[Float!]`. Both indexes are part of S1 and created by
 `assertSchema({ create: true })`; read rules apply to every result.
 
+An index matches and ranks by stored values, whatever the read rules
+say, so search never reaches a value the reader may not read:
+
+- A `@fulltext` index over a field with a mask, a field-level READ
+  `validate` rule or `@authentication` for READ is a model error naming the
+  field: searching it would tell which rows contain a hidden word. Leave
+  the field out of the index (index a public copy if it must be found).
+- A vector search, with `vector` or `to`, needs the vector field's
+  `@authentication`, and ranks only nodes passing its READ `validate`
+  rules (the anchor of `to` too); a node whose vector the reader may not
+  read is not a candidate. A mask on a `@vector` field is a model error.
+
 Every search also has a connection: `searchDocsConnection(query:, where:,
 first:, after:)` pages by keyset on (score, key). A vector index returns
 its top candidates before any filter, so vector connections page within
@@ -533,23 +629,100 @@ type Mutation {
 ```
 
 `this` is the parent node; arguments are `$parameters`; `$jwt` holds the
-request's claims. `columnName` is inferred when the statement's last
-top-level `RETURN` has one item, `RETURN x` or `RETURN … AS x` (commas
-inside calls, lists, maps and `CALL { }` do not count); with several
-items, set it.
+request's claims; `$viewer` is the caller (below). `columnName` is
+inferred when the statement's last top-level `RETURN` has one item,
+`RETURN x` or `RETURN … AS x` (commas inside calls, lists, maps and
+`CALL { }` do not count); with several items, set it.
 Fields returning `@node` types are projected with the selection like any
 other node, and read filters apply to them.
 
 Statements are checked, not trusted:
 
-- at startup: every `$parameter` must be an argument or `$jwt`, Query and
-  object fields may not contain write clauses, and unused arguments,
-  `OPTIONAL MATCH` and statements that never use `this` are warnings
-  (`lora.model.warnings`);
+- at startup: every `$parameter` must be an argument, `$jwt` or
+  `$viewer`, Query and object fields may not contain write clauses, and
+  unused arguments, `OPTIONAL MATCH` and statements that never use
+  `this` are warnings (`lora.model.warnings`);
 - in `check()`: every statement is planned with `explain()`, so a syntax
   error, an unknown function or a missing column fails CI with the engine's
   message, not the first request.
 
+### The caller: `$viewer`
+
+With a `@viewer` claim, `$viewer` is the caller's node's `@key`, in field
+and mutation statements alike, so a statement names the viewer, not the
+claim:
+
+```graphql
+type Mutation {
+  createPost(key: String!, caption: String!): Post
+    @authentication
+    @cypher(
+      statement: """
+      MATCH (a:Person) WHERE a.key = $viewer
+      CREATE (a)-[:POSTED]->(p:Post {key: $key, caption: $caption})
+      RETURN p
+      """
+    )
+}
+```
+
+When `@viewer` maps to the key, `$viewer` is the claim itself. When it
+maps to another field (an opaque `subject`), it is read in the statement
+with one seek by the claim (`head([(v:Person {subject: $claim}) |
+v.key])`), so the statement above keeps working, and keeps seeking, when
+`@viewer` moves from `Person.key` to `Person.subject`. `$viewer` is null
+signed out, for a claim that is not a string or number, and for a token
+naming no node. A statement using it without a `@viewer` claim is a
+model error, and `viewer` is reserved as an argument name, like `jwt`.
+
+### Guarding root fields
+
+`@authentication` and `@authorization(validate:)` guard a Query or
+Mutation `@cypher` field before its statement runs. With no node, a rule
+tests claims (`jwt`) and the caller's own node (`viewer`); `node` and
+filter rules are model errors, and `operations` / `when` do not matter:
+each rule guards the call.
+
+```graphql
+type Mutation {
+  verify: Person
+    @authentication
+    @authorization(
+      validate: [{ where: { viewer: { verified: { eq: true } } } }]
+    )
+    @cypher(
+      statement: "MATCH (p:Person) WHERE p.key = $viewer SET p.verified = true RETURN p"
+    )
+}
+```
+
+As anywhere, any passing rule grants, and the schema's bypass skips them.
+Claim tests are decided in JavaScript: a refusal (`FORBIDDEN`, or
+`UNAUTHENTICATED` without a token) runs no statement. A `viewer` test is
+one seek, in the mutation's transaction, before the statement. Every root
+`@cypher` field is in the access matrix, guarded or not (Mutation fields
+under the operation `EXECUTE`).
+
+### List and number arguments
+
+The statement sees its arguments as sent, so list arguments are capped:
+at most `@size(max:)` items, or `maxListArgument` (default 1000) without
+it. More is `BAD_USER_INPUT` before any statement runs; each level of a
+nested list counts.
+
+```graphql
+createPost(key: String!, hashtags: [String!] = [] @size(max: 30)): Post
+```
+
+Int and Float arguments take bounds the same way: `@range(min:, max:)`
+(either or both, inclusive) checks the value, or each item of a list,
+before the statement runs, and a default outside the bounds is a model
+error. Null is not checked; that is the type's business.
+
+```graphql
+nearby(lat: Float! @range(min: -90, max: 90), km: Int = 10 @range(min: 1, max: 500)): [Festival!]!
+```
+
 ### Filters, sorts and richer results
 
 A scalar `@cypher` field of a `@node` type may take `@filterable` and
@@ -643,6 +816,19 @@ type Post
   for keys built from the caller's key while the claim is an opaque
   subject: `key: { endsWith: ":${viewer.key}" }`, `key: { eq:
   "${viewer.key}" }`. It stands for one value, not inside a list.
+- **The rule's own node.** `"${node.path}"` in a node part reads the node
+  the rule is about, so a rule can relate two of its paths: "the request's
+  recipient is in the conversation it gates" is
+  `{ node: { conversation: { participants: { some: { key: { eq:
+"${node.to.key}" } } } } } }`. The path ends on a scalar field and steps
+  only through single relationships; the value is read in the statement
+  (the stored one, as rules see it) and stands for one value, not inside a
+  list. In a relationship field's rules, `${source.path}`, `${target.path}`
+  and `${edge.property}` read its ends and properties: "the payer is on the
+  expense's trip" is `{ source: { trip: { members: { some: { key: { eq:
+"${target.key}" } } } } } }` on `Expense.paidBy`'s CONNECT. A named rule
+  that reads `${node.…}` can't stand inside another node's filter, where it
+  would read the outer node.
 - A whole string starting with `$` must be a placeholder (`$jwt.<claim>`,
   `$context.<path>`): a misspelt one (`"$jtw.sub"`) is a model error, not
   a literal. Write a literal `$…` as `"\\$…"`.
@@ -670,6 +856,19 @@ type Post
   own connects, so a filter that depends on the new relationship (a
   request visible to its sender) does not block a nested create. Filter rules for `CREATE_RELATIONSHIP` and
   `DELETE_RELATIONSHIP` guard both ends of connects and disconnects.
+  Update and delete targets (by key, bulk and nested) must pass the
+  type's `READ` filter as well as its `UPDATE` / `DELETE` filter: a key
+  the caller cannot read answers like a missing one (`null`,
+  `nodesDeleted: 0`), never `FORBIDDEN` from a `validate` rule.
+- **Write errors never name a node the caller cannot read.** A delete
+  that would leave such a node without a required relationship fails
+  with `a Secret the caller can't read requires a Person (Secret.holder)`;
+  `onDelete: RESTRICT` held by such nodes fails with `Org "o" cannot be
+deleted: Org.docs has onDelete: RESTRICT`. Replacing a single
+  relationship whose current target the caller cannot read is refused
+  with `FORBIDDEN` (`not allowed to replace F.genre`), and leaves it in
+  place: the caller cannot remove a relationship of a node they cannot
+  see.
 - `validate` rules fail the request with `FORBIDDEN`: `BEFORE` an update or
   delete, `AFTER` a create or update (rolling it back), and for `READ`: on
   any returned node, and on cursors, counts and aggregates that cover one.
@@ -677,7 +876,12 @@ type Post
 - Field-level `@authorization(validate:)` guards one field: reading it on a
   row that fails is `FORBIDDEN`, filtering by it only matches rows that
   pass, sorting or aggregating by it is refused, and writing it checks the
-  rule. A write is what the input sets: a create that leaves the field out
+  rule. On a row failing the rule (or where it is unknown, a null
+  property) the filter is false, never null, so `NOT` over it matches
+  every such row whatever the hidden value: a negated filter reveals no
+  more than the filter itself. The same holds for relationship and
+  `@cypher` fields with READ rules, `<field>Exists` and
+  `<field>Connection`. A write is what the input sets: a create that leaves the field out
   is not checked against it, even when `@default` or `@populatedBy` fills
   it, so a CREATE rule can keep a `verified: Boolean! @default(value: false)`
   settable by admins only while anyone creates the node. Field-level
@@ -801,10 +1005,19 @@ type Post
   and relationship rules included; `@authentication` still applies.
   `bypass` tests claims only, so it is decided before the statement is
   built: an admin's statement carries no rule predicate. A type keeps its
-  rules for everyone with `@authorization(bypass: false)`. `mutations` is
-  the write rule (`CREATE`, `UPDATE`, `DELETE`) of every `@mutation` type
-  that declares no rule for those operations; a type's own rules replace
-  it, never merge with it. `check()` fails on a `@mutation` type whose
+  rules for everyone with `@authorization(bypass: false)`;
+  `@authorization(bypass: true)` is the default made explicit, and quiets
+  `check()`'s note that the bypass skips the type's field rules. `mutations` is
+  the write rule (`CREATE`, `UPDATE`, `DELETE`) of every `@mutation` type,
+  per operation: it guards each of those operations that none of the
+  type's own rules covers. A `validate` rule covers the operations it
+  lists; a `filter` rule covers `UPDATE` and `DELETE` when it lists them
+  (by default it does), never `CREATE`, since there is no node to filter
+  before it exists. So a type with only `@authorization(filter: [...])`
+  keeps the default on `CREATE`, and one with a `validate` rule for
+  `UPDATE` only keeps it on `CREATE` and `DELETE`. Where a type's rule
+  covers an operation, it replaces the default for that operation, never
+  merges with it. `check()` fails on a `@mutation` type whose
   writes nothing guards, unless it says `@authorization(public: [...])`.
 
 Relationship and `@cypher` fields take field-level `@authorization`
@@ -812,14 +1025,33 @@ with READ validate rules: a row failing the rule reads the field as
 `FORBIDDEN`, and filtering through the field applies the rule too.
 
 Relationship properties take field-level `@authentication` and
-`@authorization(validate:)` for `READ`, `CREATE` and `UPDATE`. One
-`@relationshipProperties` type can serve fields on both ends, so these
-rules test claims (`jwt`) only; a `node` part is a model error. Setting
+`@authorization(validate:)` for `READ`, `CREATE` and `UPDATE`. They test
+claims (`jwt`); a `node` part is a model error. Setting
 the property on connect or nested create checks `CREATE` for a new
 relationship and `UPDATE` for one that already exists; `update: { edge }`
 checks `UPDATE`. A request the READ rules refuse reads the property as
 `FORBIDDEN` and cannot filter, sort or aggregate by it.
 
+When every relationship field using the properties type declares the
+same ends (owner and target `@node` types), READ rules may also test the
+relationship's `source`, `target` and `edge`, as a relationship rule
+does, and `viewer`. They decide per relationship: one edge can carry an
+`rsvp` every member reads and a marker only its member reads. A
+relationship failing them reads that property as `FORBIDDEN` (the
+others still read), and nothing may filter, sort or aggregate by it.
+Writes stay claims-only: such a part in a `CREATE` or `UPDATE` rule, or
+on a type whose fields disagree on the ends, is a model error.
+
+```graphql
+type Membership @relationshipProperties {
+  rsvp: String
+  lastReadAt: String
+    @authorization(
+      validate: [{ operations: [READ], where: { target: { isViewer: true } } }]
+    )
+}
+```
+
 ### Rules on relationships
 
 A relationship field also takes validate rules for the relationship's
@@ -943,9 +1175,33 @@ by key starts from that node and expands, instead of scanning the label.
 Every operation has a cost estimate (rows touched, multiplying page sizes
 through nested lists, capped by `@cardinality`), summed across its root
 fields, and an operation over `maxCost` (default 50 000) fails with
-`COST_EXCEEDED` before it runs. `lora.analyze()` samples node counts and
-relationship degrees so estimates use the measured p99 degree instead of
-the page size.
+`COST_EXCEEDED` before it runs. `lora.analyze()` counts nodes and
+measures relationship degrees: a nested list is then estimated at its
+relationship's maximum degree, measured over every node and capped by the
+page size, instead of the page size alone. Not a percentile: the caller
+picks the parents (by key, or by following a hub), so any lower bound is
+one it can exceed at will.
+
+Filters are charged the rows they examine, not only the rows they return:
+
+- a root filter no index answers (`contains`, `endsWith`,
+  `caseInsensitive`, `NOT`, `OR`, a computed field) costs the label's
+  node count, or the page size without statistics; an equality, range,
+  prefix or point predicate seeks and costs nothing extra;
+- each relationship a filter follows (`some`, `none`, `all`, `single`,
+  `count`, `aggregate`, connection filters, single relationships) costs
+  the related nodes it visits per candidate, multiplied per level: the
+  mean degree over a scanned label, the maximum degree from parents the
+  caller picked (by key, or the parents of a nested list), the default
+  page size without statistics;
+- `totalCount` and aggregates read every match: the label's node count
+  when no key narrows them.
+
+`maxFilterDepth` (default 2) refuses a `where` nesting more relationship
+levels with `BAD_USER_INPUT`, counted through single relationships,
+`<field>Exists` and connection filters too. Without `analyze()` a two-level
+filter over a large label still passes, priced at the page size: run it
+in production so estimates use real counts.
 
 **S7: one SDL, two diffs.** `diffSchemas(before, after)` reports the
 database statements a change needs (index and constraint changes, relabels,
@@ -978,6 +1234,33 @@ read carries a read-set (labels and relationship types);
 that falls `maxQueuedChanges` (default 1000) behind is ended with an error
 rather than buffering without bound.
 
+`execute({ ..., readSet: true })` returns the operation's read-set as a
+non-enumerable `readSet` on the result (it never reaches the client), so
+a response cache can drop only the entries a write may have changed
+instead of clearing everything:
+
+```ts
+const cache = new Map<string, LoraExecutionResult>();
+
+async function cachedExecute(key: string, args: ExecuteArgs) {
+  const hit = cache.get(key);
+  if (hit) return hit;
+  const result = await lora.execute({ ...args, readSet: true });
+  if (!result.errors) cache.set(key, result);
+  return result;
+}
+
+lora.onWrite((change) => {
+  for (const [key, result] of cache)
+    if (lora.affects(result.readSet!, change)) cache.delete(key);
+});
+```
+
+A read-set is label-level, and over-approximates: a `@cypher` statement
+can read anything, so a read that ran one (and any mutation) carries
+`opaque: true`, which every change affects. `@customResolver` fields
+are not seen; key the cache so they do not need to be.
+
 ## Subscriptions
 
 ```graphql
@@ -1002,18 +1285,43 @@ writes made elsewhere are not seen). A node that gained or lost a
 relationship is an `UPDATE`. `where` tests the node as it is after the
 write; `node` is read when the event is delivered, through the normal read
 path. Events for nodes the subscriber cannot read are dropped (checked in
-one query per write, not per event), and deletions, which cannot be checked
-after the fact, go only to subscribers following that `key` without a
-`where`. `@authentication(operations: [SUBSCRIBE])` guards the subscription
+one query per write, not per event). A deletion cannot be checked after
+the fact: it goes only to subscribers following that `key` without a
+`where`, and when read rules apply, only to those who could read the node
+as it was, checked inside the deleting transaction (one statement per
+distinct check; claims that settle the rules need none). Under
+`changeFeed` there is no such transaction, so a deletion reaches only
+followers whose claims settle the rules. `@authentication(operations: [SUBSCRIBE])` guards the subscription
 itself. Pass a `signal` in the context to end the stream with the request.
 
+A subscription's `where` runs on every change, so it is bounded when the
+subscription starts: relationship filters may nest
+`maxSubscriptionFilterDepth` (default 1) deep, and its estimated rows per
+changed node (each relationship filter's degree, from `analyze()`, else
+its cardinality, else a page of the target) are charged against
+`maxCost` / `budget` (`COST_EXCEEDED`). One scope, by default the context
+object (one per graphql-ws connection when the server reuses it; set
+`subscriptionScope` to count per connection or user otherwise), holds at
+most `maxSubscriptions` (default 100) live subscriptions; one more is
+`LIMIT_EXCEEDED`. The statements that check a change run under
+`subscriptionTimeoutMs` (default 2000, or `timeoutMs` when lower); one
+that fails or times out ends that subscription with the error.
+
 Every event has a `timestamp` (when the write was committed). With
 `@subscription(relationships: true)` a type also gets `CONNECT` and
 `DISCONNECT` events, one per relationship, with `relationship { field type
-relatedType relatedKey }`. With `@subscription(previousState: true)`,
+relatedType relatedKey }`. Such an event is sent only when the
+subscriber may read the related node (its type's READ rules) through the
+declaring field (that field's READ rules and `@authentication`), checked
+after the write; otherwise it is dropped, not sent with the key left out.
+A related node that is gone (a DISCONNECT by deletion) cannot be checked,
+so its event reaches only subscribers whose claims settle those rules. With `@subscription(previousState: true)`,
 `UPDATE` and `DELETE` events carry `previousState`: the stored values
-before the write (readable scalar fields without field-level rules), at
-the cost of one read per write. Subscribers whose checks compile to the
+before the write (readable scalar fields without field-level validate
+rules), at the cost of one read per write. Field-level `@authentication`
+applies to it as to any read, and masks are decided by the subscriber's
+claims: a mask whose `unless` depends on the node reads as its `value`,
+since the node as it was cannot be tested after the write. Subscribers whose checks compile to the
 same statement share it: twenty subscribers with the same `where` and
 claims cost one visibility query and one node read per write.
 
@@ -1053,7 +1361,15 @@ try {
 With `transaction` in the context, every operation of the request runs in
 it, next to the application's own `tx.execute(cypher)`: they commit or roll
 back together, reads see the transaction's writes, and change events wait
-for the commit. A failed mutation rolls the transaction back.
+for the commit. A failed mutation rolls the transaction back. `@cypher`
+mutations run in it too, like generated ones: their statement shares the
+transaction, and their (broad) change event waits for the commit.
+
+A write transaction holds LoraDB's writer lock until it ends, and other
+writes wait for it. That wait is bounded by `timeoutMs` (and a `signal`
+in the context): a mutation that cannot get the lock in time fails with
+`DATABASE_ERROR` instead of queueing forever. Keep `lora.begin()`
+transactions short.
 
 ## CLI
 
@@ -1063,7 +1379,8 @@ lora-graphql requirements schema.graphql --ddl # constraints and indexes, as DDL
 lora-graphql check schema.graphql --operations src/operations
 lora-graphql compile schema.graphql --operations src/operations --out generated
 lora-graphql analyze schema.graphql --database ./data   # statistics JSON
-lora-graphql diff old.graphql new.graphql      # exit 1 on breaking changes
+lora-graphql diff old.graphql new.graphql      # exit 1 on breaking or destructive changes
+lora-graphql diff --base origin/main schema/   # the same, against a git ref
 lora-graphql directives                        # directive SDL for editors
 ```
 
@@ -1084,17 +1401,67 @@ files, and exits non-zero on any finding. It is the CI gate. Options:
 - `--database dir [--name app]`: check an existing database as it is, and
   report indexes it has that the API does not use.
 
-`access` prints who may do what: for every type and guarded field, each
-operation as each kind of caller (anonymous, authenticated, and each role
+`diff` exits 1 when the change breaks clients or needs a destructive
+database statement (a dropped constraint or index, a relabel, a moved
+property); `--allow-breaking` accepts both, e.g. when a PR is labelled
+for it. `--base <ref>` takes the schema as files or directories (searched
+recursively for `.graphql` / `.gql`), concatenates each side in path
+order, and compares the files at that git ref with the working tree, so
+a schema split over many files needs no script. A ref that has none of
+the paths has nothing to compare (exit 0); a ref that is not a commit is
+an error.
+
+`access` prints who may do what: for every type, guarded field (READ,
+and CREATE / UPDATE where field-level rules guard the write), rule on a
+relationship property (READ, CREATE, UPDATE) and root `@cypher` field,
+each operation as each kind of caller (anonymous, authenticated, and each role
 the rules test, such as `roles:admin`), with the verdict (`allowed`,
 `filtered`, `validated`, `masked`, `denied`, `unauthenticated`) and the
-rules that decide it. `lora.accessMatrix()` returns the same list; its
+rules that decide it. A `@key(scope: VIEWER)` type's CREATE reads
+`unauthenticated` for anonymous callers and `validated` by `key scope`
+for the rest.
+
+`lora.operationAccess(document | persistedId, operationName?)` answers
+the same question for one operation: each root field (fragments
+followed) with its type, the operations it needs (an upsert needs
+`CREATE` and `UPDATE`) and the verdict per caller, plus the most
+restrictive verdict per caller over all root fields. A field over
+several types (`node`, a union) reports the most restrictive member.
+Root fields only: nested selections answer to their own types' rules.
+To keep admin-only operations out of client bundles:
+
+````ts
+const { verdicts } = lora.operationAccess(source);
+const adminOnly = ["anonymous", "authenticated"].every((p) =>
+  ["denied", "unauthenticated"].includes(verdicts[p]!),
+);
+``` `lora.accessMatrix()` returns the same list; its
 order is stable, so a snapshot in CI turns access changes into diffs.
 
-`check` lints authorization too: a filter rule every signed-in caller
-passes, a rule whose default `requireAuthentication` refuses anonymous
-callers a branch that needs no claims, and field rules the schema's
-bypass skips.
+`check` lints authorization too:
+
+- a filter rule every signed-in caller passes;
+- a rule whose default `requireAuthentication` refuses anonymous callers
+  a branch that needs no claims;
+- field rules the schema's bypass skips, on a type that says neither
+  `@authorization(bypass: false)` nor `bypass: true`;
+- an UPDATE rule testing a single relationship the update input can
+  re-point (`connect`, `disconnect`, `create`): the rule sees the node
+  before (and, validated `AFTER`, after) the write, so a caller passing it
+  on two targets moves the node. Tests that name the caller's own node
+  (`isViewer`) are skipped. Fix:
+  `@settable(onCreate: true, onUpdate: false)`;
+- a CREATE validate rule testing a field UPDATE can change while no UPDATE
+  rule (or field-level UPDATE rule) tests it: created as the rule demands,
+  then changed;
+- a validate rule (not `READ` or `CREATE`) or relationship rule testing a
+  masked field the claims do not settle: rules see the stored value, so
+  success versus `FORBIDDEN` tells the caller what the mask hides;
+- nested `create`, `update` or `delete` into a type whose rules for that
+  write refuse every signed-in caller without a role (an admin-only type,
+  or the `@authorizationDefaults(mutations:)` default), offered by an input
+  that caller can use: surface only admins can use. Fix:
+  `nestedOperations: [CONNECT, DISCONNECT]`.
 
 A `@mutation` type with a generated write no rule guards (no
 `@authentication` or `@authorization` rule for it, and no
@@ -1145,7 +1512,7 @@ await expectSeeks(
   `{ festivals(where: { name: { eq: "Sunland" } }) { key } }`,
 );
 t.close();
-```
+````
 
 `createTestLoraGraphQL` builds an in-memory database with the schema
 asserted, runs the seed, and records every statement in `t.statements`.
@@ -1188,10 +1555,17 @@ binding has, so the WASM binding serves reads.
 
 | Option                       | Default       | Meaning                                             |
 | ---------------------------- | ------------- | --------------------------------------------------- |
-| `timeoutMs`                  | 10 000        | Per statement; a `signal` in the context cancels    |
+| `timeoutMs`                  | 10 000        | Per statement and lock wait; a `signal` cancels     |
+| `operationTimeoutMs`         | 2 × timeout   | All root fields of one query; then `TIMEOUT`        |
+| `maxConcurrentStatements`    | 2             | Statements one operation runs at once               |
 | `maxCost`                    | 50 000        | Estimated rows per operation                        |
-| `maxBatch`                   | 1000          | Nodes created or deleted per mutation; bulk `limit` |
+| `maxBatch`                   | 1000          | Nodes written per mutation; bulk `limit` by default |
+| `compileCacheBytes`          | 64 MiB        | Compile cache and document cache, each              |
 | `maxQueuedChanges`           | 1000          | How far a change consumer may fall behind           |
+| `maxSubscriptions`           | 100           | Live subscriptions per `subscriptionScope`          |
+| `subscriptionScope`          | the context   | What `maxSubscriptions` counts per                  |
+| `maxSubscriptionFilterDepth` | 1             | Relationship filter nesting in a subscription where |
+| `subscriptionTimeoutMs`      | 2000          | Per statement checking a change for a subscriber    |
 | `defaultLimit` / `maxLimit`  | 25 / 100      | Global page sizes; `@limit` may only lower `max`    |
 | `callbacks`                  |               | Named callbacks for `@populatedBy`                  |
 | `jwt`                        | `context.jwt` | Where the claims are                                |
@@ -1209,12 +1583,29 @@ binding has, so the WASM binding serves reads.
 | `metrics`                    |               | Counters and histograms (see below)                 |
 
 Errors carry `extensions.code`: `BAD_USER_INPUT`, `INVALID_CURSOR`,
-`LIMIT_EXCEEDED`, `COST_EXCEEDED`, `UNAUTHENTICATED`, `FORBIDDEN`,
+`LIMIT_EXCEEDED`, `COST_EXCEEDED`, `TIMEOUT` (with `operationTimeoutMs`),
+`UNAUTHENTICATED`, `FORBIDDEN`,
 `NOT_FOUND`, `CONSTRAINT_VIOLATION` (with `type` and `field`),
 `DATABASE_ERROR` (with an `id`, also given to `onError`),
 `PERSISTED_QUERY_ONLY` (`execute()` or `subscribe()` got a document under
 `persistedOnly`) and `WRONG_OPERATION_TYPE` (`execute()` got a
-subscription, or `subscribe()` a query or mutation). An invalid SDL
+subscription, or `subscribe()` a query or mutation). Identical errors at
+paths that differ only in list indices (an `@authentication` field read
+anonymously on every row of a page) come back once, at the first path,
+with `extensions.count` and `extensions.pathPattern` (indices as `"*"`);
+`execute()` and `lora.envelopPlugin()` both do this. The same list of
+codes is exported as `LORA_GRAPHQL_ERROR_CODES`, and
+`isLoraGraphQLError(err)` tells a library error (also a serialized one)
+from anything else:
+
+```ts
+import { isLoraGraphQLError } from "@loradb/lora-graphql";
+
+for (const err of result.errors ?? [])
+  if (isLoraGraphQLError(err) && err.extensions.code === "FORBIDDEN") deny();
+```
+
+An invalid SDL
 throws one `ModelError` listing every problem, each located by type and
 field.
 
@@ -1225,20 +1616,43 @@ the document before that. `execute()`, `subscribe()` and `persist()` apply them,
 `lora.validationRules()` / `lora.envelopPlugin()` bring them to any other
 server (GraphQL Yoga takes the plugin as is):
 
-| Guard                   | Default    | Limit                                    |
-| ----------------------- | ---------- | ---------------------------------------- |
-| `maxDepth`              | 12         | Field nesting, through fragments         |
-| `maxIntrospectionDepth` | 20         | Nesting under `__schema` / `__type`      |
-| `maxAliases`            | 30         | Aliased fields per document              |
-| `maxRootFields`         | 20         | Root fields per operation                |
-| `maxTokens`             | 5000       | Lexer tokens per document, while parsing |
-| `introspection`         | production | Off when `NODE_ENV` is `production`      |
+| Guard                   | Default    | Limit                                                                  |
+| ----------------------- | ---------- | ---------------------------------------------------------------------- |
+| `maxDepth`              | 12         | Field nesting, through fragments                                       |
+| `maxIntrospectionDepth` | 20         | Nesting under `__schema` / `__type`                                    |
+| `maxAliases`            | 30         | Aliased fields per document                                            |
+| `maxRootFields`         | 20         | Root fields per operation                                              |
+| `maxTokens`             | 5000       | Lexer tokens per document, while parsing                               |
+| `maxListArgument`       | 1000       | Items per list argument of a `@cypher` field (`@size(max:)` overrides) |
+| `maxFilterDepth`        | 2          | Relationship levels one `where` nests                                  |
+| `maxListFilter`         | 1000       | Items in an `in` filter operand                                        |
+| `maxStringFilter`       | 10 000     | Characters in a string filter operand (`eq`, `contains`, `in` items…)  |
+| `introspection`         | production | Off when `NODE_ENV` is `production`                                    |
+
+One query also has a time budget and a share of the engine: its root
+fields (aliases included) run at most `maxConcurrentStatements` (default 2) statements at once, so one request cannot take every libuv worker
+from the others, and after `operationTimeoutMs` (default twice
+`timeoutMs`, 20 s) its statements are aborted and its unfinished fields
+fail with `TIMEOUT`. Each statement also gets no more than the time the
+operation has left. Mutations keep `timeoutMs` per statement, and
+subscriptions are not bounded by the operation budget.
 
 With `NODE_ENV=production`, database errors are masked and introspection
 is off unless configured otherwise. See
 [the threat model](../../docs/design/graphql-threat-model.md) for what
 the library trusts and where each check runs.
 
+The plugin also checks, once, that the server runs the library's own
+`graphql` copy. With two copies (a nested `node_modules/graphql`, a
+dual CJS/ESM load) the library's errors are not instances of the
+server's `GraphQLError`, so Yoga masks every `FORBIDDEN` or
+`BAD_USER_INPUT` as "Unexpected error". The first schema or validation
+from a foreign copy logs a `console.error` naming the problem and the
+fix: dedupe `graphql` (`npm dedupe`, or `pnpm.overrides` / yarn
+`resolutions`) until `npm ls graphql` shows one copy. The standalone
+`envelopPlugin(guards, onRealmMismatch)` takes a reporter in place of
+`console.error`.
+
 ### Observability
 
 `onStatement` fires before a statement runs; `onStatementEnd` after, with
@@ -1280,7 +1694,9 @@ object with `counter(name, value, attributes)` and
 
 `budget(context)` sets the cost limit per request (a plan, a user), and
 `onCost` sees every estimate. `execute()` also returns the operation's
-estimate as `extensions.cost`, so clients can tune their queries.
+estimate as `extensions.cost`, so clients can tune their queries. The
+limit holds per execution: a context reused across requests (one per
+graphql-ws connection) does not add their costs up.
 
 ### Compile cache
 
@@ -1292,6 +1708,13 @@ drops from 0.14 ms to 0.06 ms end to end. Servers that parse every request
 themselves get new field nodes each time and do not benefit; use
 `execute()` or persisted operations.
 
+Both caches are bounded by size as well as by count: `compileCacheBytes`
+(default 64 MiB, approximate) caps the compile cache and, separately, the
+parsed documents (about 100 bytes per source character), evicting the
+oldest first. A request whose variables for the field exceed 16 KiB (a
+long `in:` list, an embedding vector) is compiled but not cached, and an
+entry does not keep its document alive once the document cache drops it.
+
 `check({ rowBudget })` flags statements whose largest engine row estimate
 exceeds the budget; every plan report carries `estimatedRows` either way.