@simtlix/simfinity-core 3.10.0 → 3.11.0

package/README.md

@@ -15,13 +15,13 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 - `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;
 - `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.11.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 };
 };

package/src/query-plan.js

@@ -1,11 +1,16 @@
 import { paginationStages } from './query-limits.js';
 import SimfinityError from './errors/simfinity.error.js';
 import {
-  QUERY_OPERATORS, describeEmptiness, describeModelEmptiness, emptinessMemberPaths, isEmptinessOperator, textQueryOperator,
-  validateTextFilterValue,
+  QUERY_OPERATORS, describeEmptiness, describeModelEmptiness, emptinessMemberPaths, emptinessScopeTargets, isEmptinessOperator,
+  textQueryOperator, validateTextFilterValue,
 } from './query-operators.js';
 
 const fail = (message, code = 'INVALID_FILTER_VALUE') => { throw new SimfinityError(message, code, 400); };
+// A client scope marker that cannot be honored: only the runtime writes `__scope` on a term or group
+// condition, and fills it after middleware (#108 part 2b).
+const detached = (message) => {
+  throw new SimfinityError(`${message}; only the runtime writes and fills client scope markers (docs/guide/middleware.md)`, 'DETACHED_CLIENT_FILTER', 500);
+};
 const operators = new Set(QUERY_OPERATORS);
 const reserved = new Set(['AND', 'OR', 'sort', 'pagination', 'aggregation']);
 // `aggregation` is a generated argument only on aggregate endpoints; on find and count a field of
@@ -19,37 +24,45 @@ const isPathless = (path) => path == null || path === '';
 const hasTermPath = (term) => typeof term?.path === 'string' && term.path !== '';
 
 /**
- * Internal: the model paths named by generated query arguments, as `{ segments, group }` entries.
- * Covers filter keys and relation terms, AND/OR conditions, list sort terms, and aggregation
- * groupId and fact paths; aggregate sort terms name result keys. Outside aggregate mode a key
- * named `aggregation` is a field filter like any other. `group` is the AND/OR group
- * object whose `conditions` hold the path, or null for the other forms. Malformed entries are
- * left to the backends. An emptiness term without a path (omitted, null or "") names its field,
- * also next to sibling terms that have paths.
+ * Internal: the model paths named by generated query arguments, as `{ segments, group, operator,
+ * construct }` entries. Covers filter keys and relation terms, AND/OR conditions, list sort terms,
+ * and aggregation groupId and fact paths; aggregate sort terms name result keys. Outside aggregate
+ * mode a key named `aggregation` is a field filter like any other. `group` is the AND/OR group
+ * object whose `conditions` hold the path, or null for the other forms. `operator` is the operator
+ * that reads the path, an omitted one read as `EQ`, or null for sort, groupId and fact paths.
+ * `construct` is the term or group condition object that names the path, or null for a field
+ * filter's own operator and for sort, groupId and fact paths. Malformed entries are left to the
+ * backends. An emptiness term without a path (omitted, null or "") names its field, also next to
+ * sibling terms that have paths.
  *
  * With `expandMembers` and the queried `gqltype`, the path of each emptiness condition is followed by
- * the stored member paths that condition reads (emptinessMemberPaths), as `{ segments, group,
- * member: true }` entries, so that the checks of client paths apply to them. Only client arguments
- * are expanded.
+ * the stored member paths that condition reads (emptinessMemberPaths), as entries with the same
+ * group, operator and construct and `member: true`, so that the checks of client paths apply to them.
+ * Only client arguments are expanded.
  */
 export const collectQueryPathEntries = (args, operation = 'find', { gqltype, expandMembers = false } = {}) => {
   const entries = [];
-  const add = (path, group = null) => {
-    if (typeof path === 'string' && path) entries.push({ segments: path.split('.'), group });
+  const add = (path, group = null, operator = null, construct = null) => {
+    if (typeof path === 'string' && path) entries.push({ segments: path.split('.'), group, operator, construct });
   };
-  const addEmptiness = (path, group = null) => {
-    add(path, group);
+  const addEmptiness = (path, group, operator, construct) => {
+    add(path, group, operator, construct);
     if (!expandMembers || typeof path !== 'string' || !path) return;
-    for (const segments of emptinessMemberPaths(gqltype, path.split('.'))) entries.push({ segments, group, member: true });
+    for (const segments of emptinessMemberPaths(gqltype, path.split('.'))) {
+      entries.push({
+        segments, group, operator, construct, member: true,
+      });
+    }
   };
   if (!args || typeof args !== 'object') return entries;
+  const operatorOf = (item) => item?.operator ?? 'EQ';
   const visit = (group) => {
     if (!group || typeof group !== 'object') return;
     for (const condition of listOf(group.conditions)) {
       if (typeof condition?.field !== 'string') continue;
       const path = isPathless(condition.path) ? condition.field : `${condition.field}.${condition.path}`;
-      if (isEmptinessOperator(condition.operator)) addEmptiness(path, group);
-      else add(path, group);
+      if (isEmptinessOperator(condition.operator)) addEmptiness(path, group, condition.operator, condition);
+      else add(path, group, operatorOf(condition), condition);
     }
     for (const item of nestedGroups(group)) visit(item);
   };
@@ -59,22 +72,24 @@ export const collectQueryPathEntries = (args, operation = 'find', { gqltype, exp
     const terms = listOf(value.terms);
     const pathless = (term) => isEmptinessOperator(term?.operator) && isPathless(term.path);
     if (!terms.some(hasTermPath)) {
-      if (isEmptinessOperator(value.operator) || terms.some(pathless)) addEmptiness(name);
-      else add(name);
+      const term = terms.find(pathless);
+      if (term) addEmptiness(name, null, term.operator, term);
+      else if (isEmptinessOperator(value.operator)) addEmptiness(name, null, value.operator, null);
+      else add(name, null, operatorOf(value));
       continue;
     }
     let field = false;
     for (const term of terms) {
       if (hasTermPath(term)) {
-        if (isEmptinessOperator(term.operator)) addEmptiness(`${name}.${term.path}`);
-        else add(`${name}.${term.path}`);
+        if (isEmptinessOperator(term.operator)) addEmptiness(`${name}.${term.path}`, null, term.operator, term);
+        else add(`${name}.${term.path}`, null, operatorOf(term), term);
       } else if (!field && pathless(term)) {
-        addEmptiness(name);
+        addEmptiness(name, null, term.operator, term);
         field = true;
       }
     }
     // An emptiness operator beside terms is rejected later; until then it reads the field too.
-    if (!field && isEmptinessOperator(value.operator)) addEmptiness(name);
+    if (!field && isEmptinessOperator(value.operator)) addEmptiness(name, null, value.operator, null);
   }
   for (const item of nestedGroups(args)) visit(item);
   if (operation === 'aggregate') {
@@ -86,8 +101,8 @@ export const collectQueryPathEntries = (args, operation = 'find', { gqltype, exp
 
 /**
  * Internal: every condition the arguments hold, as `{ operator, path, segments, form, field, rawPath,
- * value, hasValue, ambiguous, depth }` entries: field filters, relation terms and AND/OR group
- * conditions at any depth, with an omitted operator read as `EQ`.
+ * value, hasValue, ambiguous, depth, construct, emptiness }` entries: field filters, relation terms
+ * and AND/OR group conditions at any depth, with an omitted operator read as `EQ`.
  * - `form` is 'filter' (an argument's own operator, without a terms array), 'beside-terms' (an
  *   operator written next to a terms array, which the compilers read only to reject an emptiness
  *   operator), 'term' or 'condition'.
@@ -98,6 +113,10 @@ export const collectQueryPathEntries = (args, operation = 'find', { gqltype, exp
  * - `ambiguous` marks a condition with both a dotted field and a non-empty path.
  * - `depth` is 0 for argument filters and for the groups listed in args.AND and args.OR, and one more
  *   for each nested group; a group reached at several depths reports the deepest.
+ * - `construct` is the term or group condition object itself, or null for a field filter's own
+ *   operator ('filter' and 'beside-terms'). These objects are the only ones that carry a client scope
+ *   marker, `__scope` (#108 part 2b).
+ * - `emptiness` tells whether the operator is IS_EMPTY or IS_NOT_EMPTY.
  * Sort, pagination and aggregation hold no operators. Malformed entries are skipped and left to the
  * backends; a group reached twice is read once.
  */
@@ -108,8 +127,9 @@ export const collectQueryOperators = (args, operation = 'find') => {
   const add = (item, form, field, rawPath, depth, ambiguous = false) => {
     if (!isObject(item)) return;
     const path = isPathless(rawPath) ? field : `${field}.${rawPath}`;
+    const operator = item.operator ?? 'EQ';
     entries.push({
-      operator: item.operator ?? 'EQ',
+      operator,
       path,
       segments: typeof path === 'string' && path ? path.split('.') : [],
       form,
@@ -119,6 +139,8 @@ export const collectQueryOperators = (args, operation = 'find') => {
       hasValue: Object.hasOwn(item, 'value'),
       ambiguous,
       depth,
+      construct: form === 'term' || form === 'condition' ? item : null,
+      emptiness: isEmptinessOperator(operator),
     });
   };
   // The deepest level of each group, as the backends' depth limit counts it; a group inside itself is
@@ -210,27 +232,68 @@ export const resolveModelPath = (models, entityName, path) => {
  * operator on an object filter without terms, or beside terms, fails with MISSING_FILTER_PATH. A
  * filter path of other operators that has more than one segment and ends at an object fails with
  * INVALID_FILTER_PATH; a bare object field keeps MISSING_FILTER_PATH.
+ *
+ * With `referenceEmptiness` (#108 part 2b; by default true when `operators` is omitted and false
+ * when it is given), an emptiness path may also cross single references, end at a reference or a
+ * collection, or read reference and collection members; without it they fail with UNSUPPORTED_QUERY.
+ * Such a predicate is trusted, with stored semantics, unless its term or group condition carries the
+ * client scope marker the runtime fills, `__scope: { id, scopes }`. Then the predicate gets `scopes:
+ * { [path]: where | null }`, with one key for each path emptinessScopePaths lists for it: the plan of
+ * that path's target find scope arguments, planned on the target type in its own frame, or null when
+ * the scope added nothing. A `__scope` without filled `scopes`, without one of those keys, or on a
+ * construct that reads no reference or collection fails with DETACHED_CLIENT_FILTER (500) after the
+ * checks above; a `__scope` anywhere else is never read.
  */
-export const createQueryPlan = (models, entityName, input = {}, { mode = 'find', operators: supported } = {}) => {
+export const createQueryPlan = (models, entityName, input = {}, {
+  mode = 'find', operators: supported, referenceEmptiness = supported == null,
+} = {}) => {
   const allowed = supported == null ? null : new Set(supported);
+  const references = referenceEmptiness === true;
   const combine = (kind, terms) => {
     const active = terms.filter(Boolean);
     return active.length > 1 ? { kind, terms: active } : active[0] || null;
   };
+  // The client scope marker of a construct, lifted into the predicate's `scopes`: each target scope's
+  // arguments are planned on the target type, as trusted find arguments in their own frame, whatever
+  // the query's mode, with the operator names already read (`operators` may be a one-time iterable).
+  const liftScopes = (marker, shape, segments, operator) => {
+    const label = `${operator} on ${segments.join('.')}`;
+    const targets = emptinessScopeTargets(shape, segments);
+    const paths = Object.keys(targets);
+    if (!paths.length) detached(`${label} carries a client scope marker, but reads no reference or collection`);
+    const scopes = marker?.scopes;
+    if (!scopes || typeof scopes !== 'object' || Array.isArray(scopes)) detached(`${label} carries a client scope marker whose scopes are not filled`);
+    const lifted = {};
+    for (const path of paths) {
+      if (!Object.hasOwn(scopes, path) || scopes[path] === undefined) detached(`${label} carries a client scope marker without the scope of ${path}`);
+      lifted[path] = scopes[path] === null
+        ? null
+        : createQueryPlan(models, targets[path], scopes[path], { mode: 'find', operators: allowed ?? undefined, referenceEmptiness: references }).where;
+    }
+    return lifted;
+  };
+  const hasMarker = (construct) => construct != null && typeof construct === 'object' && Object.hasOwn(construct, '__scope');
   // Rule 1 has resolved the path; rule 2 is the compiler's operators, rules 3 to 6 describeEmptiness's.
-  const emptiness = (path, steps, operator, value) => {
+  const emptiness = (path, steps, operator, value, construct) => {
     if (allowed && !allowed.has(operator)) fail(`The ${operator} filter operator is not supported by this query compiler`, 'UNSUPPORTED_QUERY');
     const segments = Array.isArray(path) ? path : path.split('.');
-    const options = { operator, value, path: segments.join('.') };
+    const options = {
+      operator, value, path: segments.join('.'), referenceEmptiness: references,
+    };
     const gqltype = models.entities.find((item) => item.name === entityName)?.gqltype;
-    if (gqltype) describeEmptiness(gqltype, segments, options);
-    else describeModelEmptiness(steps, options);
-    return { kind: 'predicate', path: segments, operator, value: null };
+    const shape = gqltype ? describeEmptiness(gqltype, segments, options) : describeModelEmptiness(steps, options);
+    const node = {
+      kind: 'predicate', path: segments, operator, value: null,
+    };
+    if (hasMarker(construct)) node.scopes = liftScopes(construct.__scope, shape, segments, operator);
+    return node;
   };
-  const predicate = (path, operator, value) => {
+  // `construct` is the term or group condition that holds the predicate, the only objects whose
+  // `__scope` is read; null for a field filter's own operator.
+  const predicate = (path, operator, value, construct = null) => {
     const steps = resolveModelPath(models, entityName, path);
     const op = operator ?? 'EQ';
-    if (isEmptinessOperator(op)) return emptiness(path, steps, op, value);
+    if (isEmptinessOperator(op)) return emptiness(path, steps, op, value, construct);
     const field = steps.at(-1);
     if (field.kind !== 'scalar' && !field.inferred) {
       fail(`Filter on object field ${path} requires a scalar path`, steps.length > 1 ? 'INVALID_FILTER_PATH' : 'MISSING_FILTER_PATH');
@@ -243,6 +306,7 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find',
     if (['IN', 'NIN', 'BTW'].includes(op) && !Array.isArray(value)) fail(`${op} requires an array value`);
     if (op === 'BTW' && value.length !== 2) fail('BTW requires two values');
     if (textQueryOperator(op)) validateTextFilterValue(op, value, field.scalar, path);
+    if (hasMarker(construct)) detached(`${op} on ${Array.isArray(path) ? path.join('.') : path} carries a client scope marker, but is not an emptiness condition`);
     return { kind: 'predicate', path: Array.isArray(path) ? path : path.split('.'), operator: op, value: value === undefined ? null : value };
   };
   const validateGroup = (value, keys = ['conditions', 'AND', 'OR']) => {
@@ -256,7 +320,7 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find',
     for (const condition of value.conditions || []) {
       if (!condition || typeof condition.field !== 'string') fail('Invalid filter path', 'INVALID_FILTER_PATH');
       if (condition.field.includes('.') && condition.path) fail('Filter condition cannot use both dotted field syntax and a separate path', 'AMBIGUOUS_FILTER_FIELD');
-      terms.push(predicate(condition.path ? `${condition.field}.${condition.path}` : condition.field, condition.operator, condition.value));
+      terms.push(predicate(condition.path ? `${condition.field}.${condition.path}` : condition.field, condition.operator, condition.value, condition));
     }
     for (const item of value.AND || []) terms.push(group(item, depth + 1));
     terms.push(combine('or', (value.OR || []).map((item) => group(item, depth + 1))));
@@ -282,11 +346,11 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find',
     else for (const term of value.terms) {
       if (!term || typeof term !== 'object' || Array.isArray(term)) fail('Expected a relationship filter term');
       if (isEmptinessOperator(term.operator) && isPathless(term.path)) {
-        terms.push(predicate(name, term.operator, term.value));
+        terms.push(predicate(name, term.operator, term.value, term));
         continue;
       }
       if (typeof term.path !== 'string' || !term.path) fail('Relationship terms require a path', 'INVALID_FILTER_PATH');
-      terms.push(predicate(`${name}.${term.path}`, term.operator, term.value));
+      terms.push(predicate(`${name}.${term.path}`, term.operator, term.value, term));
     }
   }
   for (const item of input.AND || []) terms.push(group(item));

package/src/runtime.js

@@ -1,4 +1,6 @@
-import { configureQueryLimits, getQueryMaxPageSize, paginationStages } from './query-limits.js';
+import {
+  configureQueryLimits, getQueryMaxPageSize, getQueryMaxReferenceFrames, paginationStages,
+} from './query-limits.js';
 import { configureMutationLimits, getMaxNestedOperations } from './mutation-limits.js';
 import {
   GraphQLObjectType, GraphQLString, GraphQLID, GraphQLSchema, GraphQLList,
@@ -17,7 +19,9 @@ import {
   collectQueryOperators, collectQueryPathEntries, collectQueryPaths, walkQueryPath,
 } from './query-plan.js';
 import { QUERY_OPERATORS, isQueryOperator, resolveQueryFeatures } from './query-operators.js';
-import { assertEmptinessPath, describeEmptiness, isEmptinessOperator } from './query-emptiness.js';
+import {
+  assertEmptinessPath, describeEmptiness, emptinessScopePaths, emptinessScopeTargets, isEmptinessOperator,
+} from './query-emptiness.js';
 import { relationFieldOwners } from './relation-owners.js';
 import { isThenable } from './auth/thenable.js';
 import {
@@ -468,8 +472,12 @@ export const createRuntime = (adapter) => {
     throw new SimfinityError('A database adapter is required', 'ADAPTER_REQUIRED', 500);
   }
   // The filter operators the adapter compiles, read once: its queryFeatures.operators, or the 3.7.0
-  // operators when it declares none.
-  const supportedOperators = resolveQueryFeatures(adapter.queryFeatures).operators;
+  // operators when it declares none. With queryFeatures.referenceEmptiness, it also compiles
+  // IS_EMPTY and IS_NOT_EMPTY through references and collections (#108 part 2b), and a client's
+  // conditions of that kind carry a scope marker from the runtime (see markClientConstructs).
+  const {
+    operators: supportedOperators, referenceEmptiness: supportsReferenceEmptiness,
+  } = resolveQueryFeatures(adapter.queryFeatures);
   const supportsEveryOperator = QUERY_OPERATORS.every((operator) => supportedOperators.has(operator));
 
   const stateValue = adapter.stateValue || ((state) => state.name);
@@ -1750,31 +1758,69 @@ const executeScope = async (params) => {
   return scopeFunction({ type, args, operation, context });
 };
 
-// Copies AND/OR group lists with new group objects and arrays, leaving conditions and other values
-// shared.
-const copyFilterGroups = (groups) => (Array.isArray(groups) ? groups.map((group) => {
-  if (!group || typeof group !== 'object' || Array.isArray(group)) return group;
-  const copy = { ...group };
-  if (Array.isArray(group.conditions)) copy.conditions = [...group.conditions];
-  if (Object.hasOwn(group, 'AND')) copy.AND = copyFilterGroups(group.AND);
-  if (Object.hasOwn(group, 'OR')) copy.OR = copyFilterGroups(group.OR);
+// The arguments of a list, aggregate or collection field call that are not filters. On aggregate
+// endpoints `aggregation` is one; elsewhere a field of that name is filtered like any other.
+const LIST_CONTROL_ARGS = new Set(['sort', 'pagination']);
+const AGGREGATE_CONTROL_ARGS = new Set(['sort', 'pagination', 'aggregation']);
+const isFilterObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+// A new object with the same prototype and own enumerable properties: graphql-js builds inline literals
+// with a null prototype and variables with Object's, and childArgsKey tells them apart.
+const copyFilterObject = (value) => Object.assign(Object.create(Object.getPrototypeOf(value)), value);
+// A term, a group condition or a field filter: a value array becomes a new Array with the same items.
+const copyFilterCondition = (condition) => {
+  if (!isFilterObject(condition)) return condition;
+  const copy = copyFilterObject(condition);
+  if (Array.isArray(condition.value)) copy.value = [...condition.value];
+  return copy;
+};
+const copyFilterGroup = (group) => {
+  if (!isFilterObject(group)) return group;
+  const copy = copyFilterObject(group);
+  if (Array.isArray(group.conditions)) copy.conditions = group.conditions.map(copyFilterCondition);
+  if (Array.isArray(group.AND)) copy.AND = group.AND.map(copyFilterGroup);
+  if (Array.isArray(group.OR)) copy.OR = group.OR.map(copyFilterGroup);
+  return copy;
+};
+const copyFieldFilter = (filter) => {
+  const copy = copyFilterCondition(filter);
+  if (isFilterObject(filter) && Array.isArray(filter.terms)) copy.terms = filter.terms.map(copyFilterCondition);
   return copy;
-}) : groups);
+};
+
+// A tree copy of the query-language structure of one call's filter arguments, onto that call's args:
+// field filters and their terms, AND/OR groups and their conditions. Every place gets its own object,
+// also where graphql-js hands one variable object to several arguments or list items, so that a
+// middleware edit or a client scope marker stays within the call. Value arrays are copied shallowly,
+// and every other value, sort, pagination and aggregation included, is kept as it is. GraphQL input
+// has no cycles, so nothing is memoized.
+const copyClientFilters = (args, operation) => {
+  const controls = operation === 'aggregate' ? AGGREGATE_CONTROL_ARGS : LIST_CONTROL_ARGS;
+  for (const [name, value] of Object.entries(args)) {
+    if (name === 'AND' || name === 'OR') {
+      if (Array.isArray(value)) args[name] = value.map(copyFilterGroup);
+    } else if (!controls.has(name)) args[name] = copyFieldFilter(value);
+  }
+};
 
 // Checks the filter, sort and aggregation paths a client supplied, before middleware and scopes
 // add trusted paths. Returns the scoped relations those paths enter, keyed by path, with the
 // client AND/OR groups whose conditions use each path, or `topLevel` for every other form.
 // graphql-js passes the same variable values to every resolver call of a request, so the client's
-// AND/OR groups are first copied onto this call's args, and joined scopes are only placed in those copies.
+// filters are first copied onto this call's args (copyClientFilters), and joined scopes are only
+// placed in those copies.
 // An emptiness condition on an embedded object reads its stored members, so their paths are checked
 // as client paths too (#108 part 2a); a member path only gets the 403 checks, and enters no joined
-// scope.
+// scope. When the adapter compiles reference emptiness (#108 part 2b), a client's emptiness term or
+// condition reads its references and collections through scoped joins and frames instead, so it
+// enters no joined scope either; every other entry, beside it or on the same path, records its own.
 const inspectClientPaths = (gqltype, args, operation) => {
-  for (const key of ['AND', 'OR']) {
-    if (Object.hasOwn(args, key)) args[key] = copyFilterGroups(args[key]);
-  }
+  copyClientFilters(args, operation);
   const joinedScopes = new Map();
-  for (const { segments, group, member } of collectQueryPathEntries(args, operation, { gqltype, expandMembers: true })) {
+  const entries = collectQueryPathEntries(args, operation, { gqltype, expandMembers: true });
+  for (const {
+    segments, group, member, operator,
+  } of entries) {
+    const joins = !member && !(supportsReferenceEmptiness && isEmptinessOperator(operator));
     walkQueryPath(gqltype, segments, ({ type, fieldName, field, index }) => {
       const path = segments.slice(0, index + 1).join('.');
       if (isVirtualField(field)) {
@@ -1784,7 +1830,7 @@ const inspectClientPaths = (gqltype, args, operation) => {
       if (queryable === false || (queryable !== true && hasApplicationResolver(type, fieldName))) {
         throw forbiddenPath(`Query path ${path} uses the non-queryable field ${type.name}.${fieldName}`);
       }
-      if (member) return;
+      if (!joins) return;
       const relation = field.extensions?.relation;
       if (!relation || relation.embedded) return;
       const target = typesDict.types[unwrapListAndNonNull(field.type).name];
@@ -1870,18 +1916,28 @@ const assertEmptinessForm = (gqltype, {
 // Rejects a QLOperator value that the adapter does not declare in queryFeatures, with
 // UNSUPPORTED_QUERY (400), so an adapter never drops or misreads a condition it does not compile,
 // and applies to every IS_EMPTY or IS_NOT_EMPTY condition the order of checks of #108 part 2a,
-// whatever the adapter declares. Runs on the client's arguments before middleware and on the final
-// arguments before the adapter call, which covers what middleware, scopes and joined scopes added,
-// so that an emptiness condition gets the code that a direct createQueryPlan call gives, whoever
-// wrote it and whatever the caller may read. Operators that QLOperator does not list are left to the
-// adapter, which reports them as before.
+// whatever the adapter declares, rule 6 only when it does not declare reference emptiness. Runs on
+// the client's arguments before middleware and on the final arguments before the adapter call,
+// which covers what middleware, scopes and joined scopes added, so that an emptiness condition gets
+// the code that a direct createQueryPlan call gives, whoever wrote it and whatever the caller may
+// read. Operators that QLOperator does not list are left to the adapter, which reports them as before.
+// Returns every condition as `{ entry, shape }`: its collectQueryOperators entry, and the shape of an
+// emptiness condition that the backends read as one, or null.
 const assertQueryConditions = (gqltype, args, operation) => {
+  const checked = [];
   for (const entry of collectQueryOperators(args, operation)) {
     const { operator, path } = entry;
+    let shape = null;
     if (isEmptinessOperator(operator)) {
-      if (assertEmptinessForm(gqltype, entry)) describeEmptiness(gqltype, entry.segments, { operator, value: entry.value, path });
+      if (assertEmptinessForm(gqltype, entry)) {
+        shape = describeEmptiness(gqltype, entry.segments, {
+          operator, value: entry.value, path, referenceEmptiness: supportsReferenceEmptiness,
+        });
+      }
     } else if (!supportsEveryOperator && isQueryOperator(operator)) assertDeclaredOperator(gqltype, operator, path);
+    checked.push({ entry, shape });
   }
+  return checked;
 };
 
 // Decision 3 of #108 part 2a: a target find scope with an emptiness condition is not applied below a
@@ -1894,6 +1950,8 @@ const assertQueryConditions = (gqltype, args, operation) => {
 // adds more than a reference crossing. After its form and operator, each prefixed condition is checked
 // on `rootType`, the queried type, where rule 3, which comes before rules 4 to 6, rejects it with the
 // permanent INVALID_FILTER_PATH that the final gate and createQueryPlan give it wherever it is written.
+// An adapter that compiles reference emptiness lifts decision 3 (#108 part 2b): after the same checks,
+// the prefixed conditions are applied as trusted ones, which read stored data.
 const assertJoinedScopeConditions = (rootType, scopeArgs, groups, prefix, target) => {
   const { gqltype } = target;
   const entries = collectQueryOperators(scopeArgs, 'find').filter(({ operator }) => isEmptinessOperator(operator));
@@ -1909,17 +1967,21 @@ const assertJoinedScopeConditions = (rootType, scopeArgs, groups, prefix, target
       if (!(error instanceof SimfinityError) || error.getCode() !== 'UNSUPPORTED_QUERY') throw error;
     }
   };
+  const referenceEmptiness = supportsReferenceEmptiness;
   for (const entry of entries) {
     if (!assertEmptinessForm(gqltype, entry)) continue;
     const { operator, value } = entry;
-    if (throughList) exceptRule6(() => describeEmptiness(rootType, `${prefix}.${entry.path}`, { operator, value }));
-    exceptRule6(() => describeEmptiness(gqltype, entry.segments, { operator, value, path: entry.path }));
+    if (throughList) exceptRule6(() => describeEmptiness(rootType, `${prefix}.${entry.path}`, { operator, value, referenceEmptiness }));
+    exceptRule6(() => describeEmptiness(gqltype, entry.segments, {
+      operator, value, path: entry.path, referenceEmptiness,
+    }));
   }
+  if (referenceEmptiness) return;
   const prefixed = collectQueryOperators({ AND: groups }).find(({ operator }) => isEmptinessOperator(operator))
     ?? { operator: entries[0].operator, path: `${prefix}.${entries[0].path}` };
   throw new SimfinityError(`Query path ${prefix} enters ${gqltype.name}, whose find scope tests ${prefixed.path} with `
-    + `${prefixed.operator}: emptiness through references and collections arrives with reference emptiness (#108); `
-    + `until then, use EQ null in the ${gqltype.name} find scope`, 'UNSUPPORTED_QUERY', 400);
+    + `${prefixed.operator}: the database adapter does not support emptiness through references and collections; `
+    + `use EQ null in the ${gqltype.name} find scope`, 'UNSUPPORTED_QUERY', 400);
 };
 
 // A joined scope must not repeat the rows it restricts: its paths may not cross a collection, nor
@@ -1989,6 +2051,181 @@ const applyJoinedScopes = async (joinedScopes, params) => {
   }
 };
 
+// Client scope markers (#108 part 2b). When the adapter compiles reference emptiness, each IS_EMPTY or
+// IS_NOT_EMPTY term or group condition that a client sends and that crosses or ends at a reference or a
+// collection, or reads one as a member, gets `__scope: { id }` on this call's copy, before middleware.
+// After middleware, the query's own scope and joined scopes, the runtime checks that every marker it
+// issued is still there and that no other one is, gates the final arguments, then fills each marker
+// with the raw find scope arguments of every type the construct reads through, `__scope: { id, scopes:
+// { [path]: args | null } }`, which the compilers apply as scoped joins and frames, so that a record
+// those scopes hide reads as missing. Constructs without a marker are trusted and read stored data.
+// Markers live only on the terms and group conditions collectQueryOperators returns; a `__scope`
+// anywhere else, inside a value for one, is never read.
+const SCOPE_MARKER = '__scope';
+const DETACHED_ADVICE = 'middleware and scopes must keep the client\'s filter objects: copy them instead of rebuilding '
+  + 'them, and append restrictions instead of assigning over them (docs/guide/middleware.md)';
+const detachedClientFilter = (message) => new SimfinityError(`${message}; ${DETACHED_ADVICE}`, 'DETACHED_CLIENT_FILTER', 500);
+const hasScopeMarker = (construct) => construct != null && Object.hasOwn(construct, SCOPE_MARKER);
+
+// Marks the client's constructs that read references or collections, from the gate's conditions on the
+// client's arguments, then applies maxReferenceFrames to the distinct (kind, path) pairs of their
+// scoped joins and frames in this call, so every 2a code comes first. Returns the issued markers, as
+// id -> the client's operator and path, or null when the adapter does not compile reference
+// emptiness. Ids are ordinals in the order of the conditions, so identical arguments get identical
+// markers and sibling collection reads keep one batch key.
+const markClientConstructs = (checked) => {
+  if (!supportsReferenceEmptiness) return null;
+  const issued = new Map();
+  const pairs = new Set();
+  for (const { entry, shape } of checked) {
+    const { construct } = entry;
+    if (!shape || !construct || hasScopeMarker(construct)) continue;
+    const { joins, frames } = emptinessScopePaths(shape, entry.segments);
+    if (!joins.length && !frames.length) continue;
+    const id = issued.size;
+    construct[SCOPE_MARKER] = { id };
+    issued.set(id, { operator: entry.operator, path: entry.path });
+    for (const path of joins) pairs.add(`join ${path}`);
+    for (const path of frames) pairs.add(`frame ${path}`);
+  }
+  const limit = getQueryMaxReferenceFrames();
+  if (pairs.size > limit) {
+    throw new SimfinityError(`Emptiness conditions through references and collections need ${pairs.size} scoped joins and `
+      + `frames in one query field, more than the limit of ${limit} (maxReferenceFrames)`, 'FILTER_DEPTH_EXCEEDED', 400);
+  }
+  return issued;
+};
+
+// The detach check: every marker issued in this call sits, well formed (an object whose only own key
+// is its id), on a term or group condition of the final arguments, possibly on several when middleware
+// copied or duplicated the construct; no other marker sits on one.
+const assertClientMarkers = (args, operation, issued) => {
+  const found = new Set();
+  for (const { construct, operator, path } of collectQueryOperators(args, operation)) {
+    if (!hasScopeMarker(construct)) continue;
+    const marker = construct[SCOPE_MARKER];
+    const origin = isFilterObject(marker) ? issued.get(marker.id) : undefined;
+    if (!isFilterObject(marker) || Reflect.ownKeys(marker).length !== 1 || !Object.hasOwn(marker, 'id')) {
+      const named = origin ? `, the client's ${origin.operator} condition on ${origin.path},` : '';
+      throw detachedClientFilter(`The ${operator} condition on ${path}${named} carries a malformed client scope marker`);
+    }
+    if (!origin) {
+      throw detachedClientFilter(`The ${operator} condition on ${path} carries a client scope marker that this query field did not issue`);
+    }
+    found.add(marker.id);
+  }
+  for (const [id, origin] of issued) {
+    if (!found.has(id)) {
+      throw detachedClientFilter(`The client's ${origin.operator} condition on ${origin.path} is no longer in the arguments `
+        + 'after middleware and scopes');
+    }
+  }
+};
+
+// The first reference or collection a path crosses or ends at, as its dotted path, or null.
+const relationOnPath = (gqltype, segments) => {
+  let found = null;
+  walkQueryPath(gqltype, segments, ({ field, index }) => {
+    const relation = field.extensions?.relation;
+    if (!found && relation && !relation.embedded) found = segments.slice(0, index + 1).join('.');
+  });
+  return found;
+};
+
+// The find scope arguments of a type that a client's constructs read through, once per call and type
+// (`cache`): its find scope runs with empty arguments, operation 'find' and the request context, as
+// joined scopes do; its sort and pagination are checked for shape and dropped; the rest gets the final
+// gate on the type, where everything is trusted. Null when the type has no find scope or the scope
+// added nothing.
+const clientScopeArgs = async (typeName, context, cache) => {
+  if (cache.has(typeName)) return cache.get(typeName);
+  const target = typesDict.types[typeName];
+  let result = null;
+  if (getScope(target?.gqltype, 'find')) {
+    const scopeArgs = {};
+    await executeScope({ type: target, args: scopeArgs, operation: 'find', context });
+    const kept = {};
+    for (const [name, value] of Object.entries(scopeArgs)) {
+      if (!SCOPE_IGNORED_ARGS.has(name)) kept[name] = value;
+      else if (value != null) assertScopeControlArg(name, value);
+    }
+    assertStoredQueryPaths(target.gqltype, kept, 'find');
+    assertQueryConditions(target.gqltype, kept, 'find');
+    if (Object.values(kept).some((value) => value != null && !(Array.isArray(value) && !value.length))) result = kept;
+  }
+  cache.set(typeName, result);
+  return result;
+};
+
+// The fill, on the final arguments the gate passed (`checked`). Each marked object is read at each of
+// its final positions, with its final operator and path:
+// - an emptiness condition that crosses, ends at or has as members references or collections gets a
+//   fresh `__scope: { id, scopes }`, one key per scoped join and frame path, with the union of the
+//   keys of every position when middleware placed the object at several;
+// - an emptiness condition narrowed to the record's own fields loses its marker, and is trusted;
+// - another operator loses it too, unless its path still crosses or ends at a reference or a
+//   collection: no joined scope was recorded for it, so it fails with DETACHED_CLIENT_FILTER.
+// An object that reads references at one position and none at another fails the same way, since one
+// marker cannot serve both. Every check comes before any target scope runs.
+const fillClientScopes = async (gqltype, checked, context, issued) => {
+  const marked = new Map();
+  for (const item of checked) {
+    const { construct } = item.entry;
+    if (!hasScopeMarker(construct)) continue;
+    if (!marked.has(construct)) marked.set(construct, []);
+    marked.get(construct).push(item);
+  }
+  const fills = [];
+  for (const [construct, positions] of marked) {
+    const { id } = construct[SCOPE_MARKER];
+    const origin = issued.get(id);
+    const targets = {};
+    const unread = [];
+    for (const { entry, shape } of positions) {
+      if (!entry.emptiness) {
+        const relation = relationOnPath(gqltype, entry.segments);
+        if (relation) {
+          throw detachedClientFilter(`The client's ${origin.operator} condition on ${origin.path} now uses ${entry.operator} on `
+            + `${entry.path}, which reads through ${relation} without its scope`);
+        }
+        unread.push(entry.path);
+      } else {
+        const keys = shape ? emptinessScopeTargets(shape, entry.segments) : {};
+        if (Object.keys(keys).length) Object.assign(targets, keys);
+        else unread.push(entry.path);
+      }
+    }
+    const paths = Object.keys(targets);
+    if (paths.length && unread.length) {
+      throw detachedClientFilter(`The client's ${origin.operator} condition on ${origin.path} is used where it reads `
+        + `references or collections and where it reads none (${unread.join(', ')})`);
+    }
+    fills.push({ construct, id, targets: paths.length ? targets : null });
+  }
+  const cache = new Map();
+  for (const { construct, id, targets } of fills) {
+    if (!targets) {
+      delete construct[SCOPE_MARKER];
+      continue;
+    }
+    const scopes = {};
+    for (const [path, typeName] of Object.entries(targets)) scopes[path] = await clientScopeArgs(typeName, context, cache);
+    construct[SCOPE_MARKER] = { id, scopes };
+  }
+};
+
+// After middleware, the query's own scope and joined scopes, and before the adapter call: the detach
+// check, the final gate (stored paths, then every condition), then the fill. Markers exist only when
+// the adapter compiles reference emptiness. get_by_id builds its own arguments and never runs it.
+// Returns the fill's promise, or null when no marker was issued, so that a call without one reaches
+// the adapter after as many promise jobs as before.
+const settleClientArgs = (gqltype, params, operation, issued) => {
+  if (issued) assertClientMarkers(params.args, operation, issued);
+  assertStoredQueryPaths(gqltype, params.args, operation);
+  const checked = assertQueryConditions(gqltype, params.args, operation);
+  return issued?.size ? fillClientScopes(gqltype, checked, params.context, issued) : null;
+};
+
 // Unscoped relation reads of one request, grouped by related type until the promise jobs queued so
 // far have run, and keyed by cast ID. Nothing is cached: each batch is read once and dropped.
 const referenceBatches = new WeakMap();
@@ -2595,7 +2832,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'find', countSink: true } },
           async resolve(parent, args, context, info) {
             const joinedScopes = inspectClientPaths(type.gqltype, args, 'find');
-            assertQueryConditions(type.gqltype, args, 'find');
+            const issued = markClientConstructs(assertQueryConditions(type.gqltype, args, 'find'));
             const params = {
               type,
               args,
@@ -2605,8 +2842,8 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeMiddleware(params);
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
-            assertStoredQueryPaths(type.gqltype, params.args, 'find');
-            assertQueryConditions(type.gqltype, params.args, 'find');
+            const filling = settleClientArgs(type.gqltype, params, 'find', issued);
+            if (filling) await filling;
             const queryArgs = params.args;
             const wantsCount = !!(queryArgs.pagination && queryArgs.pagination.count)
               && canReportCount(parent, info, context);
@@ -2643,7 +2880,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'aggregate' } },
           async resolve(parent, args, context) {
             const joinedScopes = inspectClientPaths(type.gqltype, args, 'aggregate');
-            assertQueryConditions(type.gqltype, args, 'aggregate');
+            const issued = markClientConstructs(assertQueryConditions(type.gqltype, args, 'aggregate'));
             const params = {
               type,
               args,
@@ -2653,8 +2890,8 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeMiddleware(params);
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
-            assertStoredQueryPaths(type.gqltype, params.args, 'aggregate');
-            assertQueryConditions(type.gqltype, params.args, 'aggregate');
+            const filling = settleClientArgs(type.gqltype, params, 'aggregate', issued);
+            if (filling) await filling;
             return adapter.aggregate(type.model, type.gqltype, params.args, null);
           },
         };
@@ -3193,13 +3430,13 @@ const autoGenerateResolvers = (gqltype) => {
           throw new Error(`Related type ${relatedType.name} not found or not connected. Make sure it's connected with simfinity.connect() or simfinity.addNoEndpointType().`);
         }
         const joinedScopes = inspectClientPaths(relatedType, args, 'find');
-        assertQueryConditions(relatedType, args, 'find');
+        const issued = markClientConstructs(assertQueryConditions(relatedType, args, 'find'));
         const params = { type: relatedTypeInfo, args, operation: 'find', context };
         await executeMiddleware(params);
         await executeScope(params);
         await applyJoinedScopes(joinedScopes, params);
-        assertStoredQueryPaths(relatedType, params.args, 'find');
-        assertQueryConditions(relatedType, params.args, 'find');
+        const filling = settleClientArgs(relatedType, params, 'find', issued);
+        if (filling) await filling;
         return loadChildren(relatedTypeInfo, connection, parent._id ?? parent.id, params.args, context);
       }, { simfinityQuery: { typeName: relatedType.name, operation: 'find' } });
       runtimeBoundTypes.set(gqltype, runtimeIdentity);

package/types/index.d.ts

@@ -27,11 +27,15 @@ export const QLValue: GraphQLScalarType<unknown, unknown>;
  * missing, null or `""` String (`" "` is not empty), a missing or null value of any other scalar or
  * enum, a missing, null or `[]` list (`[null]` and `[""]` are not empty), and a missing or null
  * embedded object or one whose stored members are all empty by these rules; the record identity is
- * never empty. They apply to the queried record's own fields: a path that continues inside an
- * embedded list or a collection fails with `INVALID_FILTER_PATH`, and a path that crosses or ends
- * at a reference, a path that ends at a collection, and an embedded object with a reference or
- * collection member fail with `UNSUPPORTED_QUERY` until reference emptiness arrives. A term or
- * group condition without a path tests the field itself.
+ * never empty. The target's `id` right after a reference is empty exactly when the reference is,
+ * including when the target is missing or hidden by its `find` scope. A path that continues inside an
+ * embedded list or a collection fails with `INVALID_FILTER_PATH`. With an adapter that declares
+ * `queryFeatures.referenceEmptiness: true`, a path may also cross single references and end at a
+ * reference or a collection, and an embedded object may have reference and collection members: a
+ * reference is empty when no record it points to exists that the target's `find` scope admits for
+ * the caller, a collection when no such child exists, and a hidden record on the way reads as
+ * missing; constructs that middleware and scopes add read stored data. With any other adapter they
+ * fail with `UNSUPPORTED_QUERY`. A term or group condition without a path tests the field itself.
  */
 export type QueryOperator =
   | 'EQ' | 'NE' | 'LT' | 'LTE' | 'GT' | 'GTE' | 'BTW' | 'IN' | 'NIN' | 'LIKE'
@@ -48,6 +52,15 @@ export interface QueryFeatures {
    * version of Simfinity does not know are ignored.
    */
   operators: readonly (QueryOperator | (string & {}))[];
+  /**
+   * Whether the adapter compiles `IS_EMPTY` and `IS_NOT_EMPTY` through single references and at
+   * references and collections, including reference and collection members of embedded objects.
+   * Undefined or null means false; any other value that is not a boolean fails `createRuntime` with
+   * `INVALID_QUERY_FEATURES` (500). An adapter that declares it receives client constructs that carry
+   * a filled client scope marker, `__scope: { id, scopes }`, on their term or group condition, and
+   * must apply each target scope in `scopes`; constructs without a marker read stored data.
+   */
+  referenceEmptiness?: boolean | null | undefined;
 }
 
 export interface ModelRegistration {
@@ -303,8 +316,20 @@ export interface CreateSchemaOptions {
   includedCustomQueries?: string[] | null;
 }
 
+export interface QueryLimitsOptions {
+  /** Positive safe integer; defaults to 1000. Unpaged lists use min(100, maxPageSize). */
+  maxPageSize?: number;
+  /**
+   * Positive safe integer; defaults to 10. The most distinct scoped joins and frames that the
+   * client's reference and collection emptiness may need in one list, aggregate or collection-field
+   * call; more fail with `FILTER_DEPTH_EXCEEDED` (400).
+   */
+  maxReferenceFrames?: number;
+}
+
 export interface Runtime<Model = any, Session = any> {
-  configureQueryLimits(options?: { maxPageSize?: number }): void;
+  /** The same process-wide setting as the root `configureQueryLimits`. */
+  configureQueryLimits(options?: QueryLimitsOptions): void;
   /**
    * Process-wide; calling it without options restores the unlimited default. Invalid options,
    * including unknown or misspelled option keys, throw `INVALID_MUTATION_LIMITS` (400) and keep
@@ -395,15 +420,16 @@ export interface DatabaseAdapter<Model = any, Session = any> {
   /**
    * Optional. The filter operators this adapter compiles. `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 it the adapter supports the operators of 3.7.0 (`EQ`, `NE`, `LT`,
-   * `LTE`, `GT`, `GTE`, `BTW`, `IN`, `NIN` and `LIKE`). A list, aggregate or collection read, or a
+   * array of strings and whose `referenceEmptiness`, if present, is a boolean or null. Without it the
+   * adapter supports the operators of 3.7.0 (`EQ`, `NE`, `LT`, `LTE`, `GT`, `GTE`, `BTW`, `IN`, `NIN`
+   * and `LIKE`) and no reference emptiness. A list, aggregate or collection read, or a
    * by-ID read through a `get_by_id` scope, whose arguments use a `QLOperator` value the adapter
    * does not support fails with `UNSUPPORTED_QUERY` (400), before middleware runs for the client's
    * arguments and before `find`, `count`, `aggregate`, `findChildren` or `findChildrenBatch` for
    * conditions that middleware, scopes and joined scopes added. Operators outside `QLOperator` still
    * reach the adapter, which reports them as before. Declaring `IS_EMPTY` and `IS_NOT_EMPTY` means
-   * compiling their semantics on the record's own fields; it does not lift the `UNSUPPORTED_QUERY`
-   * that emptiness through references and collections gets in this release.
+   * compiling their semantics on the record's own fields; emptiness through references and
+   * collections also needs `referenceEmptiness: true`, and fails with `UNSUPPORTED_QUERY` without it.
    */
   queryFeatures?: QueryFeatures | null | undefined;
   bind?(runtime: Pick<Runtime<Model, Session>, 'getModel' | 'getType' | 'getRegistrations'>): void;
@@ -527,9 +553,21 @@ export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapt
  * `operator` is a {@link QueryOperator}; the value of a text operator is a validated string. For
  * `IS_EMPTY` and `IS_NOT_EMPTY` the value is null, and `path` may end at an embedded object, an
  * embedded list or a scalar list as well as at a scalar; `IS_NOT_EMPTY` is the exact complement,
- * which the compiler builds.
+ * which the compiler builds. With `referenceEmptiness: true`, their `path` may also cross single
+ * references and end at a reference or a collection.
+ *
+ * `scopes` exists only on such an emptiness predicate from a client, and only for a compiler that
+ * declares `referenceEmptiness: true`. It has one key per dotted path from the queried record: each
+ * single reference the path crosses (a scoped join, which admits the target only where the scope
+ * admits it), the end when it is a reference or a collection, and each reference and collection
+ * member of an embedded object (frames, which keep only the records the scope admits). Each value is
+ * the target's `find` scope as a predicate in the target's own frame, or null when the scope added
+ * nothing; after a scoped crossing, a null hop still correlates through that scoped join. Without
+ * `scopes` the predicate reads stored data, through plain joins.
  */
-export type QueryPredicate = { kind: 'predicate'; path: string[]; operator: string; value: any } | { kind: 'and' | 'or'; terms: QueryPredicate[] };
+export type QueryPredicate =
+  | { kind: 'predicate'; path: string[]; operator: string; value: any; scopes?: Record<string, QueryPredicate | null> }
+  | { kind: 'and' | 'or'; terms: QueryPredicate[] };
 export interface QueryPlan {
   entity: string;
   where: QueryPredicate | null;
@@ -556,11 +594,26 @@ export interface QueryPlan {
  * the field itself. For other operators, a filter path of more than one segment that ends at an
  * object fails with `INVALID_FILTER_PATH`, as on MongoDB; a bare object field keeps
  * `MISSING_FILTER_PATH`.
+ *
+ * `referenceEmptiness` defaults to true when `operators` is omitted and to false when it is given.
+ * When it is false, an emptiness condition that crosses or ends at a reference or a collection, or
+ * reads a reference or collection member, fails with `UNSUPPORTED_QUERY` where the order above has
+ * `UNSUPPORTED_QUERY` for references; when it is true, such a condition plans with stored semantics,
+ * unless its term or group condition carries a client scope marker that the runtime filled, which
+ * becomes the predicate's `scopes`. A marker that is not filled for every path of the condition fails
+ * with `DETACHED_CLIENT_FILTER` (500).
  */
-export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string> }): QueryPlan;
+export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string>; referenceEmptiness?: boolean }): QueryPlan;
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
 
-export function configureQueryLimits(options?: { maxPageSize?: number }): void;
+/**
+ * Process-wide. `maxPageSize` (default 1000) caps page sizes. `maxReferenceFrames` (default 10) caps,
+ * per list, aggregate or collection-field call, the distinct scoped joins and frames that a client's
+ * reference and collection emptiness needs; more fail with `FILTER_DEPTH_EXCEEDED` (400). Each must be
+ * a positive safe integer, or the call throws `INVALID_QUERY_LIMITS` (400) and keeps both limits; an
+ * omitted option takes its default again.
+ */
+export function configureQueryLimits(options?: QueryLimitsOptions): void;
 /**
  * Same process-wide setting as `Runtime.configureMutationLimits`. Unknown or misspelled options
  * throw `INVALID_MUTATION_LIMITS` (400) and keep the current limit.