@simtlix/simfinity-core 3.13.0 → 3.15.0

package/README.md

@@ -16,13 +16,17 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 - `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, reference-frame and nested-operation limits.
+- `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size, compiled-frame, frame-nesting 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 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).
+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. Unknown operators on actual filter predicates fail with `INVALID_FILTER_OPERATOR` (400) before the adapter is called. 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 relative to the containing frame, 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` reads stored data, as server conditions and unmarked clients on unscoped chains do. `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).
+
+An adapter opts into collection frames with `queryFeatures.quantifiers: true` and `referenceEmptiness: true`; omission/null means false and invalid combinations give `INVALID_QUERY_FEATURES`. Every generated schema exposes `QLQuantifier`, `QLQuantifiedGroup`, group `ANY`/`ALL`/`NONE` lists and relation `quantifier`, with request-time capability gates. Collection shorthand becomes correlated `ANY`, with one child per group/prefix and no duplicated roots; explicit `ALL`/`NONE` use the same element-relative frame. Client scope keys are relative to their containing frame and apply `find` visibility before quantification; server conditions range over stored elements. `get_by_id` scopes are trusted, so `NE`, `NIN` and `EQ null` collection terms no longer admit childless records.
+
+`createQueryPlan()` enables quantifiers by default without `operators`; with `operators`, declare capabilities explicitly. Its `QueryPredicate` includes `quantified`, element `scope`/`where`, scoped-reference `joins` and aggregate `anchor`. Compilers must honour these members and fail closed on incomplete metadata. `configureQueryLimits` adds `maxFrameNesting` (default 3), while `maxReferenceFrames` (10) counts compiled client units, even when unmarked, after all client 400 checks. Named views preserve separate client-argument and `where` budgets of that size. Every adapter rejects list sorts through collections, including count mode. See the [plugin contract](https://simtlix.github.io/simfinity.js/guide/sql-plugins.html#query-features) and [upgrade notes](https://simtlix.github.io/simfinity.js/resources/compatibility.html#collection-frames).
 
 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()`.
 
@@ -34,6 +38,8 @@ Generated and custom mutations run through `adapter.withTransaction`. Retried at
 
 Importing the runtime installs Simfinity's `__Field.extensions` introspection field once per GraphQL module instance; its `readOnly` flag reads `true` for virtual fields. Multiple runtimes and driver packages can be imported together without cloning schemas or duplicating introspection types.
 
+Controller `onSaveCommitted`, `onUpdateCommitted`, `onDeleteCommitted` and `onTransitionCommitted` callbacks use the optional `DatabaseAdapter.enqueueAfterCommit(session, run)` capability. It accepts jobs only for an active owned attempt, discards aborted/retried queues, and drains a confirmed queue serially after cleanup is attempted. Core preserves existing transactional hooks and exposes per-runtime `configureAfterCommit({ onError })` for operational reporting. Unsupported adapters reject configured committed callbacks with `UNSUPPORTED_AFTER_COMMIT`. External commit ownership is not inferred. See [callback guarantees and limits](https://simtlix.github.io/simfinity.js/guide/controllers.html#after-commit-callbacks).
+
 ## Shared metadata and helpers
 
 `describeModels([{ gqltype, endpoint }])` discovers the persistent entity graph from `GraphQLObjectType` definitions and `extensions.relation`, leaving virtual fields out and describing no type that only virtual fields reach. Types registered with `endpoint: false` are still included when referenced. Reciprocal one-to-many definitions resolve to one child reference; explicit linking entities represent many-to-many relationships.
@@ -42,7 +48,7 @@ Importing the runtime installs Simfinity's `__Field.extensions` introspection fi
 
 `isVirtualField(field)` tells whether a GraphQL field is virtual, and `virtualFieldOptions(field)` returns its normalized options, `{ mcp }`, or `null` for any other field. Adapters that build storage from GraphQL types use them to skip virtual fields.
 
-The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `UnauthenticatedError` and `ForbiddenError` (the same classes as `auth.UnauthenticatedError` and `auth.ForbiddenError`), `buildErrorFormatter`, `configureQueryLimits`, `configureMutationLimits`, `QLOperator`, `QLSort`, and `QLValue`. `buildErrorFormatter` returns a `GraphQLError` whose `originalError` is the classified Simfinity error. Database packages reuse these exports so helpers, errors, and globally named GraphQL types retain one identity.
+The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `UnauthenticatedError` and `ForbiddenError` (the same classes as `auth.UnauthenticatedError` and `auth.ForbiddenError`), `buildErrorFormatter`, `configureQueryLimits`, `configureMutationLimits`, `QLOperator`, `QLQuantifier`, `QLSort`, and `QLValue`. `buildErrorFormatter` returns a `GraphQLError` whose `originalError` is the classified Simfinity error. Database packages reuse these exports so helpers, errors, and globally named GraphQL types retain one identity.
 
 The same helpers are available from the `@simtlix/simfinity-core/auth`, `/auth/errors`, `/auth/expressions`, `/auth/rules`, `/plugins`, `/scalars` and `/validators` subpaths, each with TypeScript declarations whose types match the root namespaces. `moduleResolution` `node16`, `nodenext` and `bundler` read them through the export map, and `node10` through `typesVersions`. The `internal/*` subpaths are not public API and have no declarations.
 
@@ -53,3 +59,22 @@ The same helpers are available from the `@simtlix/simfinity-core/auth`, `/auth/e
 An adapter advertises `writeFeatures: { optimisticConcurrency: true }`; `createRuntime()` snapshots/freezes this declaration and rejects invalid shapes with `INVALID_WRITE_FEATURES` (500). A protected schema rejects an adapter without support. `update(model, id, changes, session, { expectedVersion })` must atomically match ID/version, apply changes and set `expectedVersion + 1`, returning the updated record; `delete(model, id, session, { expectedVersion })` must atomically match both and return the deleted record. An update at the maximum skips the write. After no match, read the same cast key in the same session: return `null` if absent, report `VERSION_CONFLICT` if stale or `VERSION_EXHAUSTED` for an equal maximum on update, otherwise return `null`. MongoDB missing/null versions count as 1. Without `expectedVersion`, existing writes and call paths remain unchanged.
 
 Support also requires `find(model, type, args, session, { requiredId, context })` to honor the session, required key and context for scoped visibility checks. Wrappers must forward every argument, including options. Core's update result diagnostic requires `expected + 1` and advancement beyond its immutable pre-read version; delete results must carry the expected version. These diagnostics raise `DATABASE_ERROR` for inconsistent results but cannot prove arbitrary wrappers kept the atomic predicate. They retain supplied-session ownership; adapters must preserve their own guarded-write abort semantics. The `get_by_id` scope defers stale/exhausted errors for hidden callers until write hooks authorize the operation, but malformed stored versions can fail before hooks. Protected writes always perform their required pre-read, regardless of `readByIdIsInert`.
+
+## Client metadata
+
+Since 3.15.0, install the optional `@simtlix/simfinity-descriptor` package,
+aligned with your Simfinity version. It exports `buildClientDescriptor(schema)`
+and `createClientDescriptorHandler(schema, { authorize: 'public' })`. The builder
+describes the exact `createSchema()` result; the explicitly mounted handler can
+instead use an application access function. These functions are not facade/core
+exports. The descriptor does not evaluate dynamic permissions or serialize
+arbitrary validators.
+
+Legacy introspection stays enabled by default in 3.x. To opt out, import
+`configureIntrospection` from `@simtlix/simfinity-core/introspection` in a separate
+bootstrap module and call it with `{ fieldExtensions: false }` **before importing
+the runtime or facades**. That direct import requires core as a direct dependency
+pinned to the facade's exact version, including under pnpm or Yarn PnP. A late
+call fails without deleting installed metadata. Migrate clients selecting
+`__Field.extensions` before opting out. See the [descriptor reference](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html)
+for the format, protected HTTP access and composition limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.13.0",
+  "version": "3.15.0",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",
@@ -27,6 +27,9 @@
       ],
       "validators": [
         "types/validators.d.ts"
+      ],
+      "introspection": [
+        "types/introspection.d.ts"
       ]
     }
   },
@@ -52,6 +55,7 @@
       "default": "./src/auth/rules.js"
     },
     "./internal/object-id": "./src/auth/object-id.js",
+    "./internal/transaction-callbacks": "./src/transaction-callbacks.js",
     "./internal/query-operators": "./src/query-operators.js",
     "./internal/record-version": "./src/record-version.js",
     "./internal/relation-storage": "./src/relation-storage.js",
@@ -66,7 +70,13 @@
     "./validators": {
       "types": "./types/validators.d.ts",
       "default": "./src/validators.js"
-    }
+    },
+    "./introspection": {
+      "types": "./types/introspection.d.ts",
+      "default": "./src/introspection-config.js"
+    },
+    "./internal/schema-registrations": "./src/schema-registrations.js",
+    "./internal/errors": "./src/errors/simfinity.error.js"
   },
   "files": [
     "src",

package/src/after-commit.js

@@ -0,0 +1,83 @@
+import SimfinityError from './errors/simfinity.error.js';
+
+const callbackNames = {
+  save: 'onSaveCommitted', update: 'onUpdateCommitted', delete: 'onDeleteCommitted',
+  state_changed: 'onTransitionCommitted',
+};
+
+// Copy ordinary values without JSON coercion, preserving opaque custom scalar instances.
+const snapshot = (value, copies = new Map()) => {
+  if (!value || typeof value !== 'object') return value;
+  if (copies.has(value)) return copies.get(value);
+  if (value instanceof Date) return new Date(value.getTime());
+  const prototype = Object.getPrototypeOf(value);
+  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) return value;
+  const copy = Array.isArray(value) ? new Array(value.length) : Object.create(prototype);
+  copies.set(value, copy);
+  for (const [key, entry] of Object.entries(value)) {
+    Object.defineProperty(copy, key, { value: snapshot(entry, copies), writable: true, enumerable: true, configurable: true });
+  }
+  return copy;
+};
+
+const reportFailure = (typeName, operation, callbackName) => {
+  // Never log the record, request, or arbitrary error contents by default.
+  try { console.error('After-commit callback failed', { typeName, operation, callbackName }); } catch { /* Best effort. */ }
+};
+
+export const createAfterCommit = (adapter) => {
+  let onError;
+  const warned = new Set();
+  const configure = (options = {}) => {
+    if (!options || typeof options !== 'object' || Array.isArray(options)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(options))
+      || Reflect.ownKeys(options).some((key) => key !== 'onError')
+      || (options.onError !== undefined && typeof options.onError !== 'function')) {
+      throw new SimfinityError('Invalid after-commit configuration', 'INVALID_AFTER_COMMIT_OPTIONS', 400);
+    }
+    onError = options.onError;
+  };
+  const validate = (controller) => {
+    for (const name of Object.values(callbackNames)) {
+      const callback = controller?.[name];
+      if (callback == null) continue;
+      if (typeof callback !== 'function') {
+        throw new SimfinityError(`${name} must be a function`, 'INVALID_CONTROLLER', 400);
+      }
+      if (typeof adapter.enqueueAfterCommit !== 'function') {
+        throw new SimfinityError('The adapter does not support after-commit callbacks', 'UNSUPPORTED_AFTER_COMMIT', 500);
+      }
+    }
+  };
+  const queue = ({ typeName, controller, operation, record, args, context, session, action }) => {
+    const callbackName = callbackNames[operation];
+    const callback = controller?.[callbackName];
+    if (!callback || record == null) return;
+    validate(controller);
+    const reporter = onError;
+    let payload;
+    const accepted = adapter.enqueueAfterCommit(session, async () => {
+      try {
+        let values = [payload.record, context];
+        if (operation === 'save') values = [payload.record, payload.args, context];
+        if (operation === 'state_changed') values = [payload.record, action, context];
+        await callback.apply(controller, values);
+      } catch (error) {
+        if (reporter) {
+          try {
+            await reporter(error, { committed: true, typeName, operation, callbackName, context });
+            return;
+          } catch { /* The reporter cannot fail the committed operation either. */ }
+        }
+        reportFailure(typeName, operation, callbackName);
+      }
+    });
+    if (accepted) {
+      payload = { record: snapshot(adapter.toObject(record)), args: operation === 'save' ? snapshot(args) : undefined };
+    } else if (!warned.has(typeName)) {
+      warned.add(typeName);
+      try { console.warn(`After-commit callbacks for ${typeName} skipped: this adapter does not own the transaction`); } catch { /* Best effort. */ }
+    }
+  };
+  return { configure, validate, queue };
+};

package/src/const/QLQuantifier.js

@@ -0,0 +1,21 @@
+import { GraphQLEnumType } from 'graphql';
+
+const QLQuantifier = new GraphQLEnumType({
+  name: 'QLQuantifier',
+  values: {
+    ANY: { value: 'ANY' },
+    ALL: { value: 'ALL' },
+    NONE: { value: 'NONE' },
+  },
+});
+
+export const QUANTIFIED_LISTS = Object.freeze(QLQuantifier.getValues().map(({ value }) => value));
+export const QUANTIFIERS = new Set(QUANTIFIED_LISTS);
+
+// Shared by the collector and the quantified-group validator. `path` is allowed only on a
+// quantified member; reserved metadata is interpreted by its owning phase.
+export const GROUP_KEYS = new Set([
+  'conditions', 'AND', 'OR', ...QUANTIFIED_LISTS, 'path', '__scope', '__implicit', '__anchor',
+]);
+
+export default QLQuantifier;

package/src/index.js

@@ -10,6 +10,7 @@ export {
 } from './runtime.js';
 export { createQueryPlan, resolveModelPath } from './query-plan.js';
 export { default as QLOperator } from './const/QLOperator.js';
+export { default as QLQuantifier } from './const/QLQuantifier.js';
 export { default as QLSort } from './const/QLSort.js';
 export { default as QLValue } from './const/QLValue.js';
 export { configureQueryLimits, paginationStages } from './query-limits.js';

package/src/introspection-config.js

@@ -0,0 +1,17 @@
+import { __Field } from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { introspectionState } from './introspection-state.js';
+
+/** Configure before importing the runtime or either database facade. Never removes an extension. */
+export const configureIntrospection = (options) => {
+  if (!options || ![Object.prototype, null].includes(Object.getPrototypeOf(options))
+    || Reflect.ownKeys(options).length !== 1 || options.fieldExtensions !== false) {
+    throw new SimfinityError('configureIntrospection requires only { fieldExtensions: false }',
+      'INVALID_INTROSPECTION_CONFIGURATION', 500);
+  }
+  if (__Field.getFields().extensions) {
+    throw new SimfinityError('Configure fieldExtensions before importing the Simfinity runtime; __Field.extensions is already installed',
+      'INVALID_INTROSPECTION_CONFIGURATION', 500);
+  }
+  introspectionState().disabled = true;
+};

package/src/introspection-state.js

@@ -0,0 +1,10 @@
+import { __Field } from 'graphql';
+
+// Shared only by cooperating core evaluations using the same GraphQL peer. No schema/type mutation.
+const KEY = Symbol.for('simfinity.introspectionConfiguration.v1');
+const states = globalThis[KEY] || new WeakMap();
+if (!globalThis[KEY]) Object.defineProperty(globalThis, KEY, { value: states });
+export const introspectionState = () => {
+  if (!states.has(__Field)) states.set(__Field, { disabled: false });
+  return states.get(__Field);
+};

package/src/introspection.js

@@ -5,6 +5,7 @@ import {
   __Field,
 } from 'graphql';
 import { isVirtualField } from './relation-storage.js';
+import { introspectionState } from './introspection-state.js';
 
 // The object types of `__Field.extensions`: FieldExtensionsType and the RelationType of its
 // `relation` field, under the given names.
@@ -39,7 +40,7 @@ const fieldMetadataOf = (field) => (isVirtualField(field)
 // getFields() supports both lazy and already materialized introspection fields.
 // Reuse the shared field on repeated module evaluation to preserve type identity.
 const introspectionFields = __Field.getFields();
-if (!introspectionFields.extensions) {
+if (!introspectionState().disabled && !introspectionFields.extensions) {
   introspectionFields.extensions = {
     type: createFieldMetadataType('FieldExtensionsType', 'RelationType'),
     name: 'extensions',
@@ -56,14 +57,15 @@ const extensionsField = () => __Field.getFields().extensions;
 
 /** The metadata types `__Field.extensions` returns now: [FieldExtensionsType, RelationType]. */
 export const fieldMetadataTypes = () => {
+  if (introspectionState().disabled) return [];
   const extensionsType = extensionsField().type;
   return [extensionsType, extensionsType.getFields().relation.type];
 };
 
-export const fieldMetadataNamesFixed = () => extensionsField()[NAMES_FIXED] === true;
+export const fieldMetadataNamesFixed = () => extensionsField()?.[NAMES_FIXED] === true;
 
 export const fixFieldMetadataNames = () => {
-  extensionsField()[NAMES_FIXED] = true;
+  if (!introspectionState().disabled) extensionsField()[NAMES_FIXED] = true;
 };
 
 // Every schema constructed afterwards, in the whole process, contains the metadata types under the

package/src/query-emptiness.js

@@ -45,7 +45,7 @@ const LISTS = { embeddedList: 'an embedded list', collection: 'a collection' };
 // 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) => {
+export const graphqlStep = (name, field) => {
   const type = getNamedType(field.type);
   const list = !!getListShape(field.type);
   if (isInterfaceType(type) || isUnionType(type)) return { name, kind: 'abstract' };
@@ -69,7 +69,7 @@ const graphqlMembers = (type) => Object.entries(type.getFields())
 // 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, and describeModels
 // has already normalized a collection's connectionField to the child's storage column.
-const modelStep = (field) => {
+export 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', target: field.target, connectionField: field.connectionField };
   if (field.kind === 'reference' && !field.inferred) return { name: field.name, kind: 'reference', target: field.target };