@simtlix/simfinity-core 3.10.0 → 3.12.0

package/README.md

@@ -8,20 +8,21 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 
 ## Runtime
 
-`createRuntime(adapter)` creates a Simfinity runtime. Each instance owns its registrations, generated input types, middleware, scopes, hooks, custom queries and mutations, and state machines; the GraphQL type objects it builds resolvers for are bound to it, and query and mutation limits are process-wide. It exposes:
+`createRuntime(adapter)` creates a Simfinity runtime. Each instance owns its registrations, generated input types, middleware, scopes, hooks, custom queries and mutations, views, and state machines; the GraphQL type objects it builds resolvers for are bound to it, and query and mutation limits are process-wide. It exposes:
 
 - `connect`, `addNoEndpointType`, and `createSchema` for registration and schema creation;
 - `getModel`, `getType`, `getInputType`, and `getRegistrations` for runtime inspection;
 - `use`, `registerMutation`, and `saveObject` for middleware and write orchestration;
 - `registerCustomQuery` for reads whose results are not stored records, such as previews, other sources or permission evaluations;
+- `registerView` for a named list read of one registered type, with params and a fixed predicate, run through the type's scope;
 - `preventCreatingCollection` to pass validation-only storage setup to an adapter;
-- `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size and nested-operation limits.
+- `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size, reference-frame and nested-operation limits.
 
 The adapter supplies model creation, identifiers, transactions, record reads and writes, queries, counts, aggregations, and inverse collection reads. `DatabaseAdapter`, `Runtime`, controller, middleware, registration, and state-machine interfaces are exported in the TypeScript declarations. A runtime binds one adapter; create another runtime to use another database or configuration. The GraphQL types that `prepare()` and `createModel()` receive still contain virtual fields, which must never be stored: an adapter that builds storage from a type's fields skips each field for which `isVirtualField(field)`, exported by this package with `virtualFieldOptions(field)`, returns true, on entities and embedded types alike, or builds it from `describeModels()`, which leaves them out. Generated writes, filters, sorts and aggregations never name a virtual field, but a controller hook can still assign one. An adapter can also define `getByIds(model, ids, { context })`, which returns the records it finds in `getById` shape and any order; the runtime then batches generated single-reference reads per request and type, matching records by `castId`, splitting batches at `maxPageSize`, and reading an ID with `getById` when a batch read fails or when `castId` would normalize or reject it. `castId` should throw a `NOT_VALID_ID` (400) `SimfinityError` for a malformed value and must not create a new identifier. An adapter can define `readByIdIsInert(model)`, returning `true` when a `getById` of that model has no side effects and `update()` and `delete()` reject the same malformed IDs with `NOT_VALID_ID` (400) and return null for a missing record; the runtime then skips the reads before deletes without an `onDelete` hook and before updates that merge no embedded value and have neither `onUpdating` nor nested collection items. The SQL adapter always reports it, and the MongoDB adapter does for models without `find`, `findOne`, `findOneAndUpdate` or `findOneAndDelete` middleware and without application `_id` setters or overrides of the statics those reads and writes call. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError` (500), since the client did not send the value. `update()` resolves to the updated record as stored, or null; nested collection children of that record are linked to and checked against its `_id`, else `id`, else the requested ID. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. Simfinity then reads as `null` an object that holds no data when a required member would read as `null`, not counting `id`, `readOnly` and virtual members, interface and union members, members with an application resolver and referenced collections; runtimes that share the type read the same. It reads the stored members, never calling a getter, and counts a stored `_id` as `id`; it reads nothing from objects whose type has no member that counts, and an error while reading returns the object unchanged. An adapter whose hydrated records render members through getters can also define `rawEmbeddedValue(value)`, which returns a record's stored data as a plain object, or the record unchanged when that data does not show what it renders; a value that is not a plain object counts as data. The MongoDB adapter defines both.
 
 An adapter can also define `findChildrenBatch(model, type, connectionField, parentIds, args, { context })`, the batch form of `findChildren` for generated collection fields, and a synchronous `batchesChildren(model, type, connectionField)` predicate. The runtime calls both as adapter methods and checks them on every read. When the method is missing or the predicate returns `false`, each field calls `findChildren` at once with the arguments object it built, as before. Otherwise, within one request (a context object), the runtime groups the collection reads of one related type and connection storage field whose effective arguments (after middleware, the scope and joined scopes) hold the same plain data and are requested in the same tick, that is before the promise jobs queued so far have run. It calls the method with 2 to 100 distinct parent IDs, each a raw ID that `castId` accepts without changing its string form, and with a copy of the arguments that the method may change; a group with one distinct parent calls `findChildren`. Return one array per parent ID, in order, each holding exactly the records, order and page that `findChildren` returns for that parent; records should show their parent under the connection field, or not show one. Fields of one parent share its records, each with its own array. After a rejection, or a result of another shape or with records of another parent, each field reads alone with `findChildren`; failures other than a `SimfinityError`, and results of another shape, are logged once per type. Pairing rule: the batch must reproduce `this.findChildren`, so `batchesChildren` must return `false` when `this.findChildren` is not the adapter's own function, as with a spread copy or an `Object.assign` override that changes how children are read. The bundled adapters follow this rule: both define the two members only with `batchedCollections: true`: the SQL adapter when the schema is prepared and its plugin's `compileChildrenQuery` is paired with its `compileQuery`, and the MongoDB adapter at creation. To opt out on one adapter instance, set `adapter.findChildrenBatch = undefined` (deleting it does nothing for a class whose method is on the prototype), or make `batchesChildren` return `false`. A copy that overrides `getById` still inherits the base `getByIds`, as before.
 
-An adapter declares the filter operators it compiles as `queryFeatures: { operators }`, a list of `QLOperator` values that includes `EQ`, which a condition without an operator means; names this version does not know are ignored. `createRuntime()` reads it once and throws `INVALID_QUERY_FEATURES` (500) unless it is `undefined`, `null` or an object whose `operators` is an array of strings. Without a declaration the adapter supports the operators of 3.7.0, `EQ`, `NE`, `LT`, `LTE`, `GT`, `GTE`, `BTW`, `IN`, `NIN` and `LIKE`, so it never receives a text operator such as `ILIKE`, or an emptiness operator, `IS_EMPTY` or `IS_NOT_EMPTY`, that it would drop or misread. A list, count, aggregate or collection read, or a by-ID read through a `get_by_id` scope, that uses another `QLOperator` value fails with `UNSUPPORTED_QUERY` (400): the runtime checks the client's arguments before middleware runs and the final arguments, with what middleware, scopes and joined scopes added, before it calls the adapter. Operators that `QLOperator` does not list still reach the adapter. An adapter that receives the text operators must apply their rules: literal values, a `String` field or list, and `INVALID_FILTER_VALUE` (400) for a value that is not a string or contains U+0000. `createQueryPlan(models, entity, args, { operators })` validates them and rejects operators outside `operators` with `UNSUPPORTED_QUERY`. An adapter that declares `IS_EMPTY` and `IS_NOT_EMPTY` must compile their semantics on the queried record's own fields, where `IS_NOT_EMPTY` is the exact complement of `IS_EMPTY`: a `String` is empty when missing, `null` or `""`, any other scalar or enum when missing or `null`, a list when missing, `null` or `[]`, and an embedded object when missing, `null` or every stored member is empty. The runtime rejects a value other than `null`, a path inside a list, and emptiness through references and collections before it calls the adapter, so the adapter receives conditions whose `value` may be absent and whose term or group `path` may be omitted, `null` or `""` to name the field itself; `createQueryPlan` plans them as `{ kind: 'predicate', path, operator, value: null }`, whose `path` may end at a scalar list, an embedded list or an embedded object. See [empty values](https://simtlix.github.io/simfinity.js/guide/queries.html#empty-values).
+An adapter declares the filter operators it compiles as `queryFeatures: { operators }`, a list of `QLOperator` values that includes `EQ`, which a condition without an operator means; names this version does not know are ignored. `createRuntime()` reads it once and throws `INVALID_QUERY_FEATURES` (500) unless it is `undefined`, `null` or an object whose `operators` is an array of strings and whose optional `referenceEmptiness` is a boolean, `undefined` or `null`. Without a declaration the adapter supports the operators of 3.7.0, `EQ`, `NE`, `LT`, `LTE`, `GT`, `GTE`, `BTW`, `IN`, `NIN` and `LIKE`, so it never receives a text operator such as `ILIKE`, or an emptiness operator, `IS_EMPTY` or `IS_NOT_EMPTY`, that it would drop or misread. A list, count, aggregate or collection read, or a by-ID read through a `get_by_id` scope, that uses another `QLOperator` value fails with `UNSUPPORTED_QUERY` (400): the runtime checks the client's arguments before middleware runs and the final arguments, with what middleware, scopes and joined scopes added, before it calls the adapter. Operators that `QLOperator` does not list still reach the adapter. An adapter that receives the text operators must apply their rules: literal values, a `String` field or list, and `INVALID_FILTER_VALUE` (400) for a value that is not a string or contains U+0000. `createQueryPlan(models, entity, args, { operators })` validates them and rejects operators outside `operators` with `UNSUPPORTED_QUERY`. An adapter that declares `IS_EMPTY` and `IS_NOT_EMPTY` must compile their semantics on the queried record's own fields, where `IS_NOT_EMPTY` is the exact complement of `IS_EMPTY`: a `String` is empty when missing, `null` or `""`, any other scalar or enum when missing or `null`, a list when missing, `null` or `[]`, and an embedded object when missing, `null` or every stored member is empty. The runtime rejects a value other than `null` and a path inside a list before it calls the adapter, and also emptiness through references and collections unless the adapter declares `referenceEmptiness: true`, so the adapter receives conditions whose `value` may be absent and whose term or group `path` may be omitted, `null` or `""` to name the field itself; `createQueryPlan` plans them as `{ kind: 'predicate', path, operator, value: null }`, whose `path` may end at a scalar list, an embedded list or an embedded object. See [empty values](https://simtlix.github.io/simfinity.js/guide/queries.html#empty-values). An adapter that declares `referenceEmptiness: true` also receives emptiness conditions whose path crosses single references and ends at a reference or a collection, and embedded objects with reference and collection members. A client's such term or group condition carries the key `__scope: { id, scopes }`, where `scopes` holds, for each reference it crosses and each reference, collection or member it ends at or reads, keyed by the dotted path from the queried record, the arguments that the target type's `find` scope produced, or `null` when it added nothing. The adapter must join a crossed reference only where that scope admits the target, and count at an end or member only the records that the scope admits, so that a record the caller may not see reads as a missing one, also on a later hop with a `null` scope; a condition without `__scope` comes from middleware or a scope and reads stored data. `createQueryPlan(models, entity, args, { operators, referenceEmptiness: true })` lifts each filled `__scope` into the predicate's `scopes`, planning each scope on its target type, and throws `DETACHED_CLIENT_FILTER` (500) for a `__scope` that lacks a path; its `referenceEmptiness` option defaults to `true` when `operators` is omitted and to `false` otherwise. See [references and collections](https://simtlix.github.io/simfinity.js/guide/queries.html#references-and-collections).
 
 Entity types, those registered with `connect()` and the targets of non-embedded relations, resolve `id` to `_id`, falling back to `id`, whatever the `createSchema()` allowlists include; types used only as embedded values keep their declared `id`. Embedded copies of an entity type resolve the same way, so they return their declared `id` unless the adapter stores an `_id` for them, as MongoDB does for embedded list items. The resolver is set on the type object, so it applies in every runtime that shares the type. `createSchema()` marks these registrations with `storedIdentity: true` before calling `adapter.prepare()`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",

package/src/query-emptiness.js

@@ -3,10 +3,10 @@ import {
 } from 'graphql';
 import SimfinityError from './errors/simfinity.error.js';
 import { effectiveScalarName } from './metadata.js';
-import { getListShape, isVirtualField } from './relation-storage.js';
+import { getListShape, isVirtualField, normalizeConnectionField } from './relation-storage.js';
 
-// Internal: what the emptiness operators IS_EMPTY and IS_NOT_EMPTY (#108, part 2a) mean for a path,
-// shared by the runtime gate, the query plan and the MongoDB compiler through the
+// Internal: what the emptiness operators IS_EMPTY and IS_NOT_EMPTY (#108, parts 2a and 2b) mean for a
+// path, shared by the runtime gate, the query plan and the MongoDB compiler through the
 // `./internal/query-operators` subpath, which re-exports it and is not public API. Each backend
 // compiles the shape described here to its own forms.
 
@@ -32,15 +32,19 @@ export const validateEmptinessValue = (operator, value, path) => {
 };
 
 const PATH_SEGMENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
-// The record identity, the queried entity's own `id` or `_id`, is never empty in practice: PostgreSQL
-// stores it as a uuid primary key even when it is declared String.
+// The record identity, an entity's own `id` or `_id`, is never empty in practice: PostgreSQL stores it
+// as a uuid primary key even when it is declared String. It is the queried entity's at the root, and
+// the target's right after a single reference.
 const IDENTITY = ['id', '_id'];
 const LISTS = { embeddedList: 'an embedded list', collection: 'a collection' };
 
 // A path step or a member, classified as MongoDB reads paths: interface and union types first, then an
 // object field without a relation or with `embedded: true` is embedded, and any other object field is
 // a collection when it is a list and a reference otherwise. `node` is what members are read from (an
-// object type, or a description's `fields`), and `string` tells a String scalar.
+// object type, or a description's `fields`), and `string` tells a String scalar. A reference or a
+// collection names its `target` type, and a collection the child's storage column that links it,
+// `connectionField`, derived as MongoDB derives it; without a declared connectionField a collection
+// reads through its own field name.
 const graphqlStep = (name, field) => {
   const type = getNamedType(field.type);
   const list = !!getListShape(field.type);
@@ -48,9 +52,13 @@ const graphqlStep = (name, field) => {
   if (isObjectType(type)) {
     const relation = field.extensions?.relation;
     const embedded = !relation || relation.embedded;
-    return {
-      name, typeName: type.name, node: type, kind: embedded ? (list ? 'embeddedList' : 'embedded') : (list ? 'collection' : 'reference'),
-    };
+    const kind = embedded ? (list ? 'embeddedList' : 'embedded') : (list ? 'collection' : 'reference');
+    const step = { name, typeName: type.name, node: type, kind };
+    if (kind === 'reference') step.target = type.name;
+    if (kind === 'collection') {
+      Object.assign(step, { target: type.name, connectionField: normalizeConnectionField(type, relation.connectionField || name).storageFieldName });
+    }
+    return step;
   }
   return { name, kind: list ? 'scalarList' : 'scalar', string: isScalarType(type) && effectiveScalarName(type) === 'String' };
 };
@@ -59,30 +67,40 @@ const graphqlMembers = (type) => Object.entries(type.getFields())
   .filter(([, field]) => !isVirtualField(field)).map(([name, field]) => graphqlStep(name, field));
 
 // The same classification of a describeModels field description: inferred inverse references are ID
-// scalars, as GraphQL exposes them. Descriptions hold no interface or union fields.
+// scalars, as GraphQL exposes them. Descriptions hold no interface or union fields, and describeModels
+// has already normalized a collection's connectionField to the child's storage column.
 const modelStep = (field) => {
   if (field.kind === 'embedded') return { name: field.name, kind: field.list ? 'embeddedList' : 'embedded', node: field.fields ?? [] };
-  if (field.kind === 'collection') return { name: field.name, kind: 'collection' };
-  if (field.kind === 'reference' && !field.inferred) return { name: field.name, kind: 'reference' };
+  if (field.kind === 'collection') return { name: field.name, kind: 'collection', target: field.target, connectionField: field.connectionField };
+  if (field.kind === 'reference' && !field.inferred) return { name: field.name, kind: 'reference', target: field.target };
   return { name: field.name, kind: field.list ? 'scalarList' : 'scalar', string: field.scalar === 'String' };
 };
 const modelMembers = (fields) => fields.filter((field) => !field.private).map(modelStep);
 
-const leafShape = (step, atRoot) => {
+const isRelation = (step) => step.kind === 'reference' || step.kind === 'collection';
+const leafShape = (step, identity) => {
   if (step.kind === 'scalarList' || step.kind === 'embeddedList') return { rule: 'list' };
-  if (atRoot && IDENTITY.includes(step.name)) return { rule: 'null' };
+  if (identity && IDENTITY.includes(step.name)) return { rule: 'null' };
   return { rule: step.string ? 'string' : 'null' };
 };
+const relationShape = (step) => (step.kind === 'reference'
+  ? { rule: 'reference', target: step.target }
+  : { rule: 'collection', target: step.target, connectionField: step.connectionField });
 
 // Rules 3 to 6 of the order of checks, on a path whose fields resolved (rule 1): rule 3 throws as
 // soon as it is found; a cycle (rule 4) and a reference or collection (rule 6) are recorded, are not
 // entered, and throw only once the whole path and its members passed rule 3, with the value (rule 5)
-// checked between them.
-const describeSteps = (steps, { operator, value, label, membersOf }) => {
+// checked between them. Rule 6 throws only when the caller does not support reference emptiness;
+// otherwise a reference or collection end or member gets its own shape, and each single reference the
+// path crosses is listed in `crossings`.
+const describeSteps = (steps, {
+  operator, value, label, membersOf, referenceEmptiness,
+}) => {
   const segments = steps.map((step) => step.name);
   const prefix = (index) => segments.slice(0, index + 1).join('.');
   let cycle = null;
   let unsupported = null;
+  const crossings = [];
   const abstract = (path) => fail(`${operator} cannot test ${label}: ${path} is an interface or union field, whose emptiness is not defined`, 'INVALID_FILTER_PATH');
   for (const [index, step] of steps.entries()) {
     const list = index > 0 ? LISTS[steps[index - 1].kind] : null;
@@ -90,19 +108,23 @@ const describeSteps = (steps, { operator, value, label, membersOf }) => {
       fail(`${operator} cannot test ${label}: emptiness of a value inside a list is not defined, and ${prefix(index - 1)} is ${list}`, 'INVALID_FILTER_PATH');
     }
     if (step.kind === 'abstract') abstract(prefix(index));
-    if (!unsupported && (step.kind === 'reference' || step.kind === 'collection')) {
+    if (!unsupported && isRelation(step)) {
       unsupported = `${operator} on ${label} ${index === steps.length - 1 ? 'ends at' : 'crosses'} the ${step.kind} ${prefix(index)}`;
     }
+    // Only a single reference can be crossed: rule 3 rejects any step after a collection.
+    if (step.kind === 'reference' && index < steps.length - 1) crossings.push({ path: prefix(index), target: step.target });
   }
   // The member rule: each stored member by its own rule, single embedded members recursively, lists
-  // by the list rule without looking inside their items.
+  // by the list rule without looking inside their items, references and collections by their own
+  // rules without entering them.
   const expand = (node, base, ancestors) => {
     const members = [];
     for (const member of membersOf(node)) {
       const memberPath = [...base, member.name].join('.');
       if (member.kind === 'abstract') abstract(memberPath);
-      if (member.kind === 'reference' || member.kind === 'collection') {
+      if (isRelation(member)) {
         unsupported ??= `${operator} on ${label} reads the ${member.kind} member ${memberPath}`;
+        members.push({ name: member.name, shape: relationShape(member) });
       } else if (member.kind !== 'embedded') {
         members.push({ name: member.name, shape: leafShape(member, false) });
       } else if (ancestors.includes(member.node)) {
@@ -114,15 +136,16 @@ const describeSteps = (steps, { operator, value, label, membersOf }) => {
     return members;
   };
   const last = steps.at(-1);
-  const shape = last.kind === 'embedded'
-    ? { rule: 'object', members: expand(last.node, segments, [last.node]) }
-    : leafShape(last, steps.length === 1);
+  let shape;
+  if (last.kind === 'embedded') shape = { rule: 'object', members: expand(last.node, segments, [last.node]) };
+  else if (isRelation(last)) shape = relationShape(last);
+  else shape = leafShape(last, steps.length === 1 || steps.at(-2).kind === 'reference');
   if (cycle) fail(cycle, 'INVALID_FILTER_OPERATOR');
   validateEmptinessValue(operator, value, label);
-  if (unsupported) {
-    fail(`${unsupported}: emptiness through references and collections arrives with reference emptiness (#108)`, 'UNSUPPORTED_QUERY');
+  if (unsupported && !referenceEmptiness) {
+    fail(`${unsupported}: the database adapter does not support emptiness through references and collections`, 'UNSUPPORTED_QUERY');
   }
-  return shape;
+  return crossings.length ? { ...shape, crossings } : shape;
 };
 
 // Rule 1 on GraphQL types: segment syntax and declared, stored fields, with resolveModelPath's codes
@@ -156,17 +179,29 @@ const graphqlSteps = (gqltype, segments, path) => {
  * then rule 3 (INVALID_FILTER_PATH for a segment after an embedded list or a collection, and for an
  * interface or union field on the path or among the members), rule 4 (INVALID_FILTER_OPERATOR when
  * the members re-enter an embedded type through single embedded members), rule 5 (the value, as
- * validateEmptinessValue checks it) and rule 6 (UNSUPPORTED_QUERY when the path crosses or ends at a
- * reference or a collection, or a member is one). Form, depth and the adapter's operators are the
- * caller's checks. `segments` is an array or a dotted string; `path` names the condition in messages.
+ * validateEmptinessValue checks it) and, with `referenceEmptiness: false`, rule 6 (UNSUPPORTED_QUERY
+ * when the path crosses or ends at a reference or a collection, or a member is one, for a caller whose
+ * database adapter does not support reference emptiness, #108 part 2b). Form, depth and the adapter's
+ * operators are the caller's checks. `segments` is an array or a dotted string; `path` names the
+ * condition in messages.
  *
  * Returns the shape: `{ rule: 'string' }` (missing, null or ""), `{ rule: 'null' }` (missing or
- * null; the record identity always), `{ rule: 'list' }` (missing, null or []), or
- * `{ rule: 'object', members: [{ name, shape }] }` (missing, null, or every stored member empty).
+ * null; the record identity, at the root or right after a single reference, always, whatever scalar
+ * it is declared with), `{ rule: 'list' }` (missing, null or []), `{ rule: 'object', members: [{
+ * name, shape }] }` (missing, null, or every stored member empty), `{ rule: 'reference', target }`
+ * (no record the reference points to) or `{ rule: 'collection', target, connectionField }` (no child
+ * record whose `connectionField`, the child's storage column, points to the record); `target` is the
+ * type name. The members of an object take these shapes too. When the path crosses single references,
+ * the shape also lists them in path order as `crossings: [{ path, target }]`, with `path` the dotted
+ * path of the reference from the queried type; emptinessScopePaths reads them.
  */
-export const describeEmptiness = (gqltype, segments, { operator = 'IS_EMPTY', value, path } = {}) => {
+export const describeEmptiness = (gqltype, segments, {
+  operator = 'IS_EMPTY', value, path, referenceEmptiness = true,
+} = {}) => {
   const { steps, label } = graphqlSteps(gqltype, segments, path);
-  return describeSteps(steps, { operator, value, label, membersOf: graphqlMembers });
+  return describeSteps(steps, {
+    operator, value, label, membersOf: graphqlMembers, referenceEmptiness,
+  });
 };
 
 /**
@@ -183,13 +218,53 @@ export const assertEmptinessPath = (gqltype, segments, { path } = {}) => {
  * `steps` are the field descriptions resolveModelPath returns for the path, so rule 1 is already
  * done. Gives the shapes, codes and messages of {@link describeEmptiness} for the same types.
  */
-export const describeModelEmptiness = (steps, { operator = 'IS_EMPTY', value, path } = {}) => {
+export const describeModelEmptiness = (steps, {
+  operator = 'IS_EMPTY', value, path, referenceEmptiness = true,
+} = {}) => {
   if (!Array.isArray(steps) || !steps.length) fail('Invalid filter path', 'INVALID_FILTER_PATH');
   const classified = steps.map(modelStep);
   const label = path == null ? classified.map((step) => step.name).join('.') : pathName(path);
-  return describeSteps(classified, { operator, value, label, membersOf: modelMembers });
+  return describeSteps(classified, {
+    operator, value, label, membersOf: modelMembers, referenceEmptiness,
+  });
+};
+
+// The scoped joins and frames of one emptiness construct, as `[{ path, kind, target }]`: each crossing
+// in path order, then the end and the reference and collection members, depth first in field order.
+const scopeEntries = (shape, path) => {
+  const entries = (shape?.crossings ?? []).map(({ path: crossing, target }) => ({ path: crossing, kind: 'join', target }));
+  const visit = (node, at) => {
+    if (node?.rule === 'reference' || node?.rule === 'collection') entries.push({ path: at, kind: 'frame', target: node.target });
+    else if (node?.rule === 'object') for (const member of node.members) visit(member.shape, `${at}.${member.name}`);
+  };
+  visit(shape, pathName(path));
+  return entries;
+};
+
+/**
+ * The reference and collection paths that one emptiness construct reads, from the shape that
+ * describeEmptiness or describeModelEmptiness gave for its `path` (an array or a dotted string):
+ * `joins` are the single references the path crosses (one scoped join each, for a client construct),
+ * and `frames` the end when it is a reference or a collection, then each reference and collection
+ * member (one frame each). Every path is dotted and starts at the queried type. A construct on the
+ * record's own fields gives two empty lists.
+ */
+export const emptinessScopePaths = (shape, path) => {
+  const entries = scopeEntries(shape, path);
+  return {
+    joins: entries.filter((entry) => entry.kind === 'join').map((entry) => entry.path),
+    frames: entries.filter((entry) => entry.kind === 'frame').map((entry) => entry.path),
+  };
 };
 
+/**
+ * The target type name of every path {@link emptinessScopePaths} lists, as `{ [path]: target }`,
+ * joins first: the type whose `find` scope restricts that join or frame.
+ */
+export const emptinessScopeTargets = (shape, path) => Object.fromEntries(
+  scopeEntries(shape, path).map((entry) => [entry.path, entry.target]),
+);
+
 /**
  * The stored member paths an emptiness condition reads when its path, on `gqltype`, ends at a single
  * embedded object: absolute segment arrays, depth first in field order, entering single embedded

package/src/query-limits.js

@@ -1,21 +1,33 @@
 import SimfinityError from './errors/simfinity.error.js';
 
 let queryMaxPageSize = 1000;
+let queryMaxReferenceFrames = 10;
 
+const isPositiveSafeInteger = (value) => Number.isSafeInteger(value) && value >= 1;
+
+// Process-wide. Each omitted option takes its default again, and every option is checked before any
+// is assigned, so a call that fails keeps every current limit. `maxReferenceFrames` caps, per resolver
+// call, the distinct scoped joins and frames of a client's reference emptiness (#108 part 2b).
 export const configureQueryLimits = (options = {}) => {
   if (!options || typeof options !== 'object' || Array.isArray(options)
     || ![Object.prototype, null].includes(Object.getPrototypeOf(options))) {
     throw new SimfinityError('Query limit options must be a plain object', 'INVALID_QUERY_LIMITS', 400);
   }
-  const { maxPageSize = 1000 } = options;
-  if (!Number.isSafeInteger(maxPageSize) || maxPageSize < 1) {
+  const { maxPageSize = 1000, maxReferenceFrames = 10 } = options;
+  if (!isPositiveSafeInteger(maxPageSize)) {
     throw new SimfinityError('maxPageSize must be a positive safe integer', 'INVALID_QUERY_LIMITS', 400);
   }
+  if (!isPositiveSafeInteger(maxReferenceFrames)) {
+    throw new SimfinityError('maxReferenceFrames must be a positive safe integer', 'INVALID_QUERY_LIMITS', 400);
+  }
   queryMaxPageSize = maxPageSize;
+  queryMaxReferenceFrames = maxReferenceFrames;
 };
 
 export const getQueryMaxPageSize = () => queryMaxPageSize;
 
+export const getQueryMaxReferenceFrames = () => queryMaxReferenceFrames;
+
 export const paginationStages = (pagination, withDefault) => {
   if (pagination == null) return withDefault ? [{ $skip: 0 }, { $limit: Math.min(100, queryMaxPageSize) }] : [];
   const { page, size } = pagination;

package/src/query-operators.js

@@ -7,8 +7,8 @@ import SimfinityError from './errors/simfinity.error.js';
 // query-emptiness.js and are re-exported here, so the subpath stays the only one.
 
 export {
-  EMPTINESS_QUERY_OPERATORS, describeEmptiness, describeModelEmptiness, emptinessMemberPaths, isEmptinessOperator,
-  validateEmptinessValue,
+  EMPTINESS_QUERY_OPERATORS, describeEmptiness, describeModelEmptiness, emptinessMemberPaths, emptinessScopePaths,
+  emptinessScopeTargets, isEmptinessOperator, validateEmptinessValue,
 } from './query-emptiness.js';
 export { effectiveScalarName } from './metadata.js';
 
@@ -68,20 +68,25 @@ const invalidFeatures = (message) => {
 };
 
 /**
- * Reads an adapter's `queryFeatures` declaration into the set of operators it compiles. Without a
- * declaration (undefined or null) the adapter supports {@link LEGACY_QUERY_OPERATORS}. A declaration
- * is an object whose `operators` is an array of operator names; names this version does not
- * know are ignored, and other members are left for later features. Anything else throws
- * `INVALID_QUERY_FEATURES` (500).
+ * Reads an adapter's `queryFeatures` declaration into `{ operators, referenceEmptiness }`: the set of
+ * operators it compiles, and whether it compiles emptiness through references and collections (#108
+ * part 2b). Without a declaration (undefined or null) the adapter supports {@link
+ * LEGACY_QUERY_OPERATORS} and no reference emptiness. A declaration is an object whose `operators`
+ * is an array of operator names, whose names this version does not know are ignored, and whose
+ * optional `referenceEmptiness` is a boolean, undefined or null (false); other members are left for
+ * later features. Anything else throws `INVALID_QUERY_FEATURES` (500).
  */
 export const resolveQueryFeatures = (queryFeatures) => {
-  if (queryFeatures == null) return { operators: new Set(LEGACY_QUERY_OPERATORS) };
+  if (queryFeatures == null) return { operators: new Set(LEGACY_QUERY_OPERATORS), referenceEmptiness: false };
   if (typeof queryFeatures !== 'object' || Array.isArray(queryFeatures)) {
     invalidFeatures('must be an object with an operators array');
   }
-  const { operators } = queryFeatures;
+  const { operators, referenceEmptiness } = queryFeatures;
   if (!Array.isArray(operators) || operators.some((operator) => typeof operator !== 'string')) {
     invalidFeatures('operators must be an array of operator names');
   }
-  return { operators: new Set(operators.filter(isQueryOperator)) };
+  if (referenceEmptiness != null && typeof referenceEmptiness !== 'boolean') {
+    invalidFeatures('referenceEmptiness must be a boolean');
+  }
+  return { operators: new Set(operators.filter(isQueryOperator)), referenceEmptiness: referenceEmptiness === true };
 };