@simtlix/simfinity-core 3.15.0 → 3.17.0

package/README.md

@@ -12,17 +12,17 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 
 - `connect`, `addNoEndpointType`, and `createSchema` for registration and schema creation;
 - `getModel`, `getType`, `getInputType`, and `getRegistrations` for runtime inspection;
-- `use`, `registerMutation`, and `saveObject` for middleware and write orchestration;
+- `use`, `registerMutation`, and `saveObject` for middleware and write orchestration, and `updateObject`, `deleteObject` and `transitionObject`, which run the lifecycle of the generated update, delete and state action mutations from code;
 - `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, compiled-frame, frame-nesting and nested-operation limits.
+- `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size, compiled-frame, frame-nesting, nested-operation and transaction-operation limits (`maxTransactionOperations`).
 
 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. 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 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, until a version that knows them, so a declaration that listed `CONTAINS_ALL` or `IIN` before they existed starts receiving them on upgrade: list only the operators the 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 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`, an emptiness operator, `IS_EMPTY` or `IS_NOT_EMPTY`, or a list operator, `CONTAINS_ALL` or `IIN`, 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 `IIN` receives an array of strings without U+0000, possibly empty, on a `String` field or list, and must match where `IEQ` would match one of them, under the same case-folding rules, and nothing for `[]`. An adapter that declares `CONTAINS_ALL` receives a non-empty array of non-null scalars, validated but not cast, on a path that ends at a scalar list or at a scalar read through embedded lists and crosses no collection and no reference after an embedded list; it must cast each element as for `IN` and match the records whose values at the path, those of every item of embedded lists included, hold every element, and stay two-valued under negation, where a missing or `null` list holds none. See [filters on lists](https://simtlix.github.io/simfinity.js/guide/queries.html#filters-on-lists). 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.
 
@@ -34,10 +34,16 @@ When a runtime first creates a schema, it binds each GraphQL object type whose n
 
 Registration and `createSchema()` validate `extensions.scope` (`INVALID_SCOPE`) and reject list or embedded relations to unregistered types (`UNREGISTERED_RELATION_TARGET`); `use()` rejects non-functions (`INVALID_MIDDLEWARE`). Before `adapter.prepare()`, `createSchema()` rejects a writable non-embedded list relation without a non-empty child `connectionField` whose resolver it would generate (`INVALID_MODEL`, 400). A collection without `connectionField` that has an application resolver, or is `readOnly`, only logs a `Configuration issue` warning, unless it is both, and nested writes through it fail with `INVALID_MODEL` (500) before anything is written; adapters that describe the whole model, such as PostgreSQL and transactional MongoDB, still reject it in `prepare()`. Fields named like generated query arguments (`sort`, `pagination`, `AND`, `OR`, and `aggregation` on aggregate endpoints) also log a warning once per runtime. Virtual fields (`extensions: { virtual: true }` or `{ virtual: { mcp: 'tool' | 'select' | false } }`, with the field's own `resolve`) are never stored, get no generated input and no filter argument, and resolve wherever their type appears; `createSchema()` rejects an invalid declaration, a virtual field without its own resolver or with `relation`, `unique: true`, `validations`, `queryable: true` or `readOnly: false`, and a virtual identity, index, state-machine `state` or `connectionField` field (`INVALID_MODEL`, 400). A client filter, sort, `groupId` or fact path through a virtual field fails with `FORBIDDEN_FILTER_PATH` (403), and one that middleware or a scope adds fails with `INVALID_MODEL` (500). A `readOnly` field with arguments and its own resolver that is not virtual, a reference or a collection logs a `Configuration issue` warning once per runtime. Generated inputs that would have no fields are left out with a `Configuration issue` warning, with the collection operations, embedded fields and mutations that would take them; a non-null embedded field whose embedded type has no writable fields throws `INVALID_MODEL` (400) when generated mutations reach its owner. An application type named `FieldExtensionsType` or `RelationType` makes Simfinity rename its introspection metadata types to `SimfinityFieldExtensionsType` and `SimfinityRelationType` when it is in the process's first Simfinity schema. That schema fixes the names: in a later `createSchema()`, an application type with one of the current names, the original ones or the fallback names after a rename, throws `RESERVED_TYPE_NAME` (500), before `adapter.prepare()` when it is an included endpoint type, a registered mutation's input or output type, an output type they reach or a field argument's type, and when the schema is constructed otherwise, such as for a type inside an input object's fields.
 
-Generated and custom mutations run through `adapter.withTransaction`. Retried attempts receive fresh clones of GraphQL input objects, lists, and dates while enum values keep their identity. Custom queries run without a transaction: their callback receives `(input, context)` and opens one through the engine's API when it needs it. `createSchema()` takes an optional fourth argument, an options object whose only key, `includedCustomQueries`, selects custom queries by name; any other value or key throws `INVALID_SCHEMA_OPTIONS` (500) before `adapter.prepare()`. A schema without mutation fields has no `Mutation` root. An adapter can define `stateValue` when its persisted enum representation differs from GraphQL enum names.
+Generated and custom mutations run through `adapter.withTransaction`. Retried attempts receive fresh clones of GraphQL input objects, lists, and dates while enum values keep their identity. Custom queries run without a transaction: their callback receives `(input, context)` and opens one through the engine's API when it needs it. `createSchema()` takes an optional fourth argument, an options object whose key `includedCustomQueries` selects custom queries by name and whose key `transaction: { name?, types }` adds the generated transaction mutation; any other value or key throws `INVALID_SCHEMA_OPTIONS` (500) before `adapter.prepare()`. An invalid `transaction` option raises the same code, after the models are prepared when the field name or a derived type name collides with the built schema, or when no operation is left in it. A schema without mutation fields has no `Mutation` root. An adapter can define `stateValue` when its persisted enum representation differs from GraphQL enum names.
 
 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.
 
+## Lifecycle helpers and the transaction mutation
+
+These APIs are available since 3.16.0. `updateObject(typeName, input, session?, context?)`, `deleteObject(typeName, { id, version? }, session?, context?)` and `transitionObject(typeName, actionName, input, session?, context?)` are `Runtime` methods, so SQL runtimes inherit them. They validate and copy their input (declared fields, internal enum values, record keys as strings), run the update, delete and state action lifecycle in an owned transaction or in the active session supplied, skip GraphQL coercion, field authorization and the root record's global middleware like `saveObject()`, and never commit, retry or abort a supplied session themselves. See the [server-side operations guide](https://simtlix.github.io/simfinity.js/guide/server-side-operations.html#update-delete-and-transition-from-code).
+
+`createSchema(…, { transaction: { name?, types } })` adds one mutation field that runs a list of the generated mutations of `types` in one database transaction, with `$K` references to earlier results, the authorization checks of each operation's root and the position of a failing operation in `extensions.operationIndex` and `extensions.operation`. An adapter enables it by implementing the optional, synchronous `assertTransactionModels(models)`, which core calls on each invocation before the session opens with the models the transaction may write; it throws when they cannot share one session, and a promise it returns fails with `TRANSACTION_UNSUPPORTED`. The `withTransaction` of such an adapter must hand its body an object session. See the [mutations guide](https://simtlix.github.io/simfinity.js/guide/mutations.html#run-several-mutations-in-one-transaction).
+
 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
@@ -78,3 +84,5 @@ 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.
+
+`queryFeatures.valuePath: true` opts an adapter into stored-field comparisons and requires `referenceEmptiness: true`; only true enables it. `valuePath` is nullable on all three generated filter inputs and is mutually exclusive with a supplied `value` (including null). Core validates both operand paths, their logical types, visibility and collection correlation, and preserves outer origins internally. `createQueryPlan` adds `operand?: QueryOperand` with `{ up, path, joins? }` and a null value placeholder; same-frame scope unions live in predicate `joins`, ancestor scopes in operand `joins`. Literal nodes stay unchanged. `describeModels` retains additive `enumName` and effective `temporalName` metadata. See [the comparison rules and limits](https://simtlix.github.io/simfinity.js/guide/queries.html#compare-stored-fields) and [compiler contract](https://simtlix.github.io/simfinity.js/guide/sql-plugins.html#query-features).

package/package.json

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

package/src/auth/index.js

@@ -48,6 +48,9 @@ import { isPolicyExpression, createRuleFromExpression, evaluateExpression } from
 import { collectQueryPathEntries, walkQueryPath } from '../query-plan.js';
 import { relationFieldOwners } from '../relation-owners.js';
 import { isThenable } from './thenable.js';
+import {
+  hasOperationEntry, isGeneratedMutationRoot, OPERATION_ENTRY_PROTOCOL, recordOperationEntry,
+} from './operation-entries.js';
 import {
   resolvePath,
   requireAuth,
@@ -286,6 +289,10 @@ const authorizeQueryPaths = async (permissions, defaultPolicy, schema, query, ar
 /**
  * Creates a graphql-middleware compatible authorization middleware.
  *
+ * It denies a generated transaction field (`extensions.simfinityTransaction`) with ForbiddenError
+ * before resolving it, whatever its rules: it cannot apply the rules of each operation's root, which
+ * {@link createAuthPlugin} applies.
+ *
  * @deprecated Use {@link createAuthPlugin} instead. `applyMiddleware` from graphql-middleware
  * can cause duplicate-type errors when the schema contains custom introspection extensions.
  *
@@ -314,9 +321,16 @@ export const createAuthMiddleware = (permissions, options = {}) => {
 
     log(`Checking ${typeName}.${fieldName}`);
 
+    const field = info.parentType?.getFields?.()[fieldName];
+    // The transaction field runs other roots, whose rules this middleware never sees.
+    if (field?.extensions?.simfinityTransaction != null) {
+      log(`The middleware cannot authorize the operations of ${typeName}.${fieldName}`);
+      throw new ForbiddenError(`Access denied to ${typeName}.${fieldName}`);
+    }
+
     // Get rules for this field
     const rules = getFieldRules(permissions, typeName, fieldName);
-    const query = info.parentType?.getFields?.()[fieldName]?.extensions?.simfinityQuery;
+    const query = field?.extensions?.simfinityQuery;
 
     // If no rules found, apply default policy
     if (rules === null) {
@@ -357,6 +371,7 @@ export const createAuthMiddleware = (permissions, options = {}) => {
  * It returns the same function as {@link createAuthMiddleware}. graphql-middleware applies a
  * function middleware to every field, so `'*'` rules and the default policy also apply to fields
  * the permission map does not name. A map of only the named fields would leave the others open.
+ * It denies a generated transaction field, as {@link createAuthMiddleware} does.
  *
  * @deprecated Use {@link createAuthPlugin} instead. `applyMiddleware` from graphql-middleware
  * can cause duplicate-type errors when the schema contains custom introspection extensions.
@@ -377,6 +392,12 @@ export const createFieldMiddleware = (permissions, options = {}) => createAuthMi
  * `onSchemaChange` throws `TypeError` before wrapping any field when a schema type was created by
  * another copy of the graphql module, instead of leaving that type's fields unprotected.
  *
+ * On each generated mutation root it wraps, in whatever type the field sits, the plugin also records
+ * an internal entry with the same rules, default policy and deferral, which the generated transaction
+ * field runs for each operation on that root. A root whose marker cannot take the entry (a frozen or
+ * otherwise non-extensible `extensions.simfinityMutation`) is still wrapped, and the transaction field
+ * refuses its operations with FORBIDDEN.
+ *
  * @param {PermissionSchema} permissions - The permission schema object
  * @param {AuthMiddlewareOptions} [options={}] - Plugin options
  * @returns {Object} An Envelop plugin with an `onSchemaChange` hook
@@ -413,10 +434,17 @@ export const createAuthPlugin = (permissions, options = {}) => {
 
   const log = debug ? console.log.bind(console, '[auth]') : () => {};
   const processedSchemas = new WeakSet();
-  // Schemas built from the same types share their field objects, so each field is wrapped once.
+  // Schemas built from the same types share their field objects, so each field is wrapped once. Each
+  // wrapped field keeps `{ resolver, check, key }`: its wrapper, and the check and permission key an
+  // operation entry needs.
   const wrappers = new WeakMap();
+  // Identifies this instance's entries on the generated mutation roots.
+  const instanceToken = Symbol('simfinity auth plugin instance');
   let warnedAboutQueryRoot = false;
 
+  // In a schema that only other auth plugin instances processed, their rules apply, not these.
+  const isDeferred = (schema) => authorizedSchemas.has(schema) && !processedSchemas.has(schema);
+
   const warnAboutQueryRoot = (schema) => {
     if (warnedAboutQueryRoot || !Object.hasOwn(permissions, 'Query') || schema.getType('Query')) return;
     const queryRoot = schema.getQueryType()?.name;
@@ -425,27 +453,18 @@ export const createAuthPlugin = (permissions, options = {}) => {
     console.warn(`[auth] Permissions for type "Query" match no type in the schema. Its query root is named "${queryRoot}"; did you mean "${queryRoot}"?`);
   };
 
-  const createFieldResolver = (schema, typeName, fieldName, rules, query, originalResolve) => {
-    const key = `${typeName}.${fieldName}`;
+  // A field's rules, or the default policy when it has none, as a check that calls `grant` once access
+  // is granted and returns its result. A denial is a rejected ForbiddenError and an error a rule throws
+  // is rejected unchanged. Rules run in order and synchronously until one returns a promise.
+  const createFieldCheck = (key, rules) => {
     const denied = () => Promise.reject(new ForbiddenError(`Access denied to ${key}`));
 
-    // Errors keep reaching GraphQL as rejections, as they did when the whole check was async.
-    const resolveField = (parent, args, ctx, info) => {
-      try {
-        return originalResolve(parent, args, ctx, info);
-      } catch (error) {
-        return Promise.reject(error);
-      }
-    };
-
-    const grant = (parent, args, ctx, info) => {
-      if (!query) return resolveField(parent, args, ctx, info);
-      return authorizeQueryPaths(permissions, defaultPolicy, info?.schema ?? schema, query, args, ctx, info)
-        .then(() => resolveField(parent, args, ctx, info));
+    const deny = () => {
+      if (debug) log(`Rule denied access to ${key}`);
+      return denied();
     };
 
-    // Rules run in order and synchronously until one returns a promise.
-    const runRules = (index, parent, args, ctx, info) => {
+    const runRules = (index, parent, args, ctx, info, grant) => {
       for (let current = index; current < rules.length; current++) {
         if (debug) log(`Executing rule for ${key}`);
         let result;
@@ -456,7 +475,7 @@ export const createAuthPlugin = (permissions, options = {}) => {
         }
         if (isThenable(result)) {
           return Promise.resolve(result).then(value => (
-            value === true || value === undefined ? runRules(current + 1, parent, args, ctx, info) : deny()
+            value === true || value === undefined ? runRules(current + 1, parent, args, ctx, info, grant) : deny()
           ));
         }
         if (result !== true && result !== undefined) return deny();
@@ -465,23 +484,38 @@ export const createAuthPlugin = (permissions, options = {}) => {
       return grant(parent, args, ctx, info);
     };
 
-    const deny = () => {
-      if (debug) log(`Rule denied access to ${key}`);
-      return denied();
-    };
-
-    const resolver = (parent, args, ctx, info) => {
-      // In a schema that only other auth plugin instances processed, their rules apply, not these.
-      if (info?.schema && authorizedSchemas.has(info.schema) && !processedSchemas.has(info.schema)) {
-        return originalResolve(parent, args, ctx, info);
-      }
+    return (parent, args, ctx, info, grant) => {
       if (debug) log(`Checking ${key}`);
 
       if (rules === null) {
         if (debug) log(`No rules for ${key}, applying default policy: ${defaultPolicy}`);
         return defaultPolicy === 'DENY' ? denied() : grant(parent, args, ctx, info);
       }
-      return runRules(0, parent, args, ctx, info);
+      return runRules(0, parent, args, ctx, info, grant);
+    };
+  };
+
+  const createFieldResolver = (schema, check, query, originalResolve) => {
+    // Errors keep reaching GraphQL as rejections, as they did when the whole check was async.
+    const resolveField = (parent, args, ctx, info) => {
+      try {
+        return originalResolve(parent, args, ctx, info);
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    };
+
+    const grant = (parent, args, ctx, info) => {
+      if (!query) return resolveField(parent, args, ctx, info);
+      return authorizeQueryPaths(permissions, defaultPolicy, info?.schema ?? schema, query, args, ctx, info)
+        .then(() => resolveField(parent, args, ctx, info));
+    };
+
+    const resolver = (parent, args, ctx, info) => {
+      if (info?.schema && isDeferred(info.schema)) {
+        return originalResolve(parent, args, ctx, info);
+      }
+      return check(parent, args, ctx, info, grant);
     };
     // The wrapper still reads through the runtime that generated a relation resolver, so a field
     // copied with it stays bound to that runtime.
@@ -490,6 +524,18 @@ export const createAuthPlugin = (permissions, options = {}) => {
     return resolver;
   };
 
+  // The entry of a generated mutation root: the check its wrapper runs, without resolving the root.
+  // The wrapper's grant also authorizes client query paths, but only fields with
+  // extensions.simfinityQuery have them, and generated mutation roots never do (runtime.js
+  // buildMutation), so for these roots granting resolves nothing more.
+  const createOperationEntry = (check) => Object.freeze({
+    protocol: OPERATION_ENTRY_PROTOCOL,
+    isDeferred,
+    async run(parent, args, ctx, info) {
+      await check(parent, args, ctx, info, () => undefined);
+    },
+  });
+
   const wrapSchemaResolvers = (schema) => {
     if (processedSchemas.has(schema)) return;
     validateConfiguration(permissions, defaultPolicy);
@@ -507,18 +553,33 @@ export const createAuthPlugin = (permissions, options = {}) => {
       const fields = type.getFields();
 
       for (const [fieldName, field] of Object.entries(fields)) {
-        // Skip fields this plugin already wraps; a resolver replaced since then is wrapped again.
-        const wrapper = wrappers.get(field);
-        if (wrapper !== undefined && wrapper === field.resolve) continue;
+        // A transaction runs the entries of each operation's root, in this schema or a copy. A generated
+        // root gets one wherever this instance wraps it, also in a type that is not the mutation root
+        // here, since the field and its wrapper can be the mutation root of another schema.
+        const isOperationRoot = isGeneratedMutationRoot(field);
+
+        // Skip fields this plugin already wraps; a resolver replaced since then is wrapped again. A
+        // wrapped root whose marker lacks this instance's entry for its key gets it again.
+        const wrapped = wrappers.get(field);
+        if (wrapped !== undefined && wrapped.resolver === field.resolve) {
+          if (isOperationRoot && !hasOperationEntry(field, instanceToken, wrapped.key)) {
+            recordOperationEntry(field, instanceToken, wrapped.key, createOperationEntry(wrapped.check));
+          }
+          continue;
+        }
 
         const rules = getFieldRules(permissions, typeName, fieldName);
         const query = field.extensions?.simfinityQuery;
         // An allowed field with no rule and no client query paths has nothing to check.
         if (rules === null && defaultPolicy === 'ALLOW' && !query && !debug) continue;
 
-        const resolver = createFieldResolver(schema, typeName, fieldName, rules, query, field.resolve || defaultFieldResolver);
+        const key = `${typeName}.${fieldName}`;
+        const check = createFieldCheck(key, rules);
+        const resolver = createFieldResolver(schema, check, query, field.resolve || defaultFieldResolver);
+        // The entry is recorded first, so a root this instance wraps always has one.
+        if (isOperationRoot) recordOperationEntry(field, instanceToken, key, createOperationEntry(check));
         field.resolve = resolver;
-        wrappers.set(field, resolver);
+        wrappers.set(field, { resolver, check, key });
       }
     }
 

package/src/auth/operation-entries.js

@@ -0,0 +1,111 @@
+import { ForbiddenError } from './errors.js';
+
+// Internal, and never exported from the package or its auth subpath. The authorization entries of the
+// generated mutation roots (#151): each auth plugin instance that wraps a root records an entry on
+// it, and the generated transaction field runs the entries of each operation's root, so the operation
+// gets the checks a direct call to that root gets in the same schema.
+//
+// Entries live on the root field's extensions.simfinityMutation object, which keeps its identity in
+// schema copies, including copies that rebuild the Mutation type. The key is a registered symbol, so
+// a plugin from another copy of core records entries this copy finds. Each entry is
+// `{ protocol: 1, isDeferred(schema), run(parent, args, ctx, info) }`: isDeferred is the instance's
+// own test for a schema only other instances processed, and run applies the rules of one permission
+// key, or the default policy, rejecting with ForbiddenError on a denial and with any error a rule
+// throws.
+//
+// An entry belongs to a pair: an instance and the `Type.field` permission key it wrapped the root
+// under, in whatever type the field sat, since a field wrapped where its type is not the mutation root
+// keeps that wrapper when the type is the root of another schema. Recording a pair again replaces its
+// entry and makes it the latest, as wrapping a field again makes that wrapper the outermost.
+// authorizeOperation runs every entry of the marker, the latest first. For a generated schema and its
+// copies that equals the wrappers a direct call runs, outermost first, so the first denial is the one
+// a direct call reports. When several keys reach one marker (an alias of a root, a copy that renames
+// the Mutation type), it runs the checks of all of them: never fewer than a direct call to any of
+// them.
+
+export const OPERATION_EVALUATORS = Symbol.for('simfinity.auth.operationEvaluators');
+export const OPERATION_ENTRY_PROTOCOL = 1;
+
+// The operations of the generated roots a transaction runs; registered mutations, marked
+// custom_mutation, never are operations.
+const GENERATED_OPERATIONS = new Set(['save', 'update', 'delete', 'state_changed']);
+
+// Whether a field is a generated mutation root, by its extensions.simfinityMutation marker.
+export const isGeneratedMutationRoot = (field) => {
+  const marker = field?.extensions?.simfinityMutation;
+  return marker !== null && typeof marker === 'object' && GENERATED_OPERATIONS.has(marker.operation);
+};
+
+// The entries Map of a generated root, created on first use in a non-enumerable property that cannot
+// be replaced, or undefined when the marker has none and cannot take one (a frozen, sealed or
+// non-extensible marker): the root's own wrapper still applies its rules, and authorizeOperation denies
+// operations on it. Anything else under the key is an error, never overwritten.
+const entriesOf = (field) => {
+  const marker = field.extensions.simfinityMutation;
+  if (!Object.hasOwn(marker, OPERATION_EVALUATORS)) {
+    if (!Object.isExtensible(marker)) return undefined;
+    Object.defineProperty(marker, OPERATION_EVALUATORS, { value: new Map() });
+  }
+  const entries = marker[OPERATION_EVALUATORS];
+  if (!(entries instanceof Map)) throw new TypeError('The authorization entries of a generated mutation root are not a Map');
+  return entries;
+};
+
+// The Map key of a pair, or undefined. Keys of another core copy may have another shape.
+const findPair = (entries, instanceToken, permissionKey) => {
+  for (const pair of entries.keys()) {
+    if (pair?.instance === instanceToken && pair?.permissionKey === permissionKey) return pair;
+  }
+  return undefined;
+};
+
+// Records the entry of the instance `instanceToken` for the root under `permissionKey`, replacing
+// that pair's earlier entry and making it the latest. A marker that cannot take entries records nothing.
+export const recordOperationEntry = (field, instanceToken, permissionKey, entry) => {
+  const entries = entriesOf(field);
+  if (entries === undefined) return;
+  const pair = findPair(entries, instanceToken, permissionKey);
+  if (pair !== undefined) entries.delete(pair);
+  entries.set(Object.freeze({ instance: instanceToken, permissionKey }), entry);
+};
+
+// Whether the pair has an entry on the root.
+export const hasOperationEntry = (field, instanceToken, permissionKey) => {
+  const entries = field.extensions.simfinityMutation[OPERATION_EVALUATORS];
+  return entries instanceof Map && findPair(entries, instanceToken, permissionKey) !== undefined;
+};
+
+/**
+ * Applies to an operation on the generated root `rootField` the checks a direct call to that root gets
+ * in `info.schema`: every entry on the root runs once, the latest first, unless its instance defers
+ * in that schema. The rules see `info` with the root's field name and return type; the root is a
+ * field of the same Mutation type as the field that runs the operation, `info.parentType`. The path,
+ * field nodes and operation stay the caller's. Fails closed: an entry of an unknown protocol, deferred
+ * or not, denies with ForbiddenError before any entry runs, and so does a marker that has no entries
+ * and cannot take them, since an instance may have wrapped the root without recording its entry. A
+ * root with no entries passes, as a root no instance wrapped does when called directly.
+ * @returns {Promise<void>}
+ */
+export const authorizeOperation = async (rootField, parent, args, ctx, info) => {
+  const marker = rootField.extensions?.simfinityMutation;
+  if (marker === null || typeof marker !== 'object') return;
+  const key = `${info.parentType.name}.${rootField.name}`;
+  if (!Object.hasOwn(marker, OPERATION_EVALUATORS)) {
+    if (!Object.isExtensible(marker)) throw new ForbiddenError(`Access denied to ${key}`);
+    return;
+  }
+  const entries = marker[OPERATION_EVALUATORS];
+  if (!(entries instanceof Map)) throw new ForbiddenError(`Access denied to ${key}`);
+  const latestFirst = [...entries.values()].reverse();
+  if (latestFirst.some((entry) => entry?.protocol !== OPERATION_ENTRY_PROTOCOL)) {
+    throw new ForbiddenError(`Access denied to ${key}`);
+  }
+  // Permissions must see the identity of the root, just as when it is called directly.
+  const operationInfo = {
+    ...info, fieldName: rootField.name, parentType: info.parentType, returnType: rootField.type,
+  };
+  for (const entry of latestFirst) {
+    if (entry.isDeferred(info.schema)) continue;
+    await entry.run(parent, args, ctx, operationInfo);
+  }
+};

package/src/const/QLOperator.js

@@ -21,6 +21,8 @@ const QLOperator = new GraphQLEnumType({
     IEQ: { value: 'IEQ' },
     IS_EMPTY: { value: 'IS_EMPTY' },
     IS_NOT_EMPTY: { value: 'IS_NOT_EMPTY' },
+    CONTAINS_ALL: { value: 'CONTAINS_ALL' },
+    IIN: { value: 'IIN' },
   },
 });
 

package/src/execution-state.js

@@ -0,0 +1,71 @@
+import { nestedOperationsExceededError } from './mutation-limits.js';
+
+// Internal, and never exported from the package. The state of one generated transaction attempt (#151):
+// the mutation limits it snapshotted at its start and its joint count of nested collection entries.
+// A state is attached to the session of its attempt for as long as the attempt runs, so every nested
+// entry that runs on that session counts against the same budget, wherever it started: the
+// operations, their middleware, actions and controllers, and the lifecycle helpers and saveObject
+// calls those controllers make. Nothing public reads it and it never travels in `context`.
+//
+// session -> the attachments it holds, oldest first, as `{ state, holds }`. The latest one is the
+// session's state. Attaching the latest state again adds a hold instead of an entry, and a detach
+// releases one hold, so an attachment lasts until the last caller that made it detaches, and the
+// state it replaced is the session's state again once it is gone.
+const attachments = new WeakMap();
+
+const isUnlimited = (limit) => limit === null || limit === undefined;
+
+// runtimeToken is the identity of the runtime that owns the attempt (see createRuntime), so that a
+// session lent to another runtime finds no state.
+export const createExecutionState = ({ runtimeToken, limits: { maxNestedOperations, maxTransactionOperations } }) => ({
+  runtimeToken,
+  limits: Object.freeze({ maxNestedOperations, maxTransactionOperations }),
+  nestedCount: 0,
+});
+
+// The same state may be attached to more than one session: when the adapter's withTransaction hands a
+// body another object than the one it was given, the state follows it for the duration of the body.
+export const attachExecutionState = (session, state) => {
+  let held = attachments.get(session);
+  if (held === undefined) {
+    held = [];
+    attachments.set(session, held);
+  }
+  const latest = held[held.length - 1];
+  if (latest?.state === state) latest.holds += 1;
+  else held.push({ state, holds: 1 });
+};
+
+// Releases one hold of the latest attachment of that state; a session without it is left as it is.
+export const detachExecutionState = (session, state) => {
+  const held = attachments.get(session);
+  if (held === undefined) return;
+  for (let index = held.length - 1; index >= 0; index -= 1) {
+    if (held[index].state === state) {
+      held[index].holds -= 1;
+      if (held[index].holds === 0) held.splice(index, 1);
+      break;
+    }
+  }
+  if (held.length === 0) attachments.delete(session);
+};
+
+// WeakMap.get answers undefined for a key that is not an object, so a missing session finds no state.
+export const executionStateOf = (session, runtimeToken) => {
+  const held = attachments.get(session);
+  const state = held?.[held.length - 1].state;
+  return state?.runtimeToken === runtimeToken ? state : undefined;
+};
+
+// One call per item that executeItemFunction iterates, before the item runs.
+export const countNestedEntry = (state) => {
+  state.nestedCount += 1;
+  const limit = state.limits.maxNestedOperations;
+  if (!isUnlimited(limit) && state.nestedCount > limit) throw nestedOperationsExceededError(limit);
+};
+
+// The nested entries the attempt may still run, or null when it has no limit.
+export const remainingNestedBudget = (state) => {
+  const limit = state.limits.maxNestedOperations;
+  return isUnlimited(limit) ? null : Math.max(0, limit - state.nestedCount);
+};

package/src/metadata.js

@@ -54,7 +54,7 @@ const scalarDescription = (type) => {
       if (storedValues.has(stored) && !Object.is(storedValues.get(stored), entry.value)) invalid(`Enum storage collision in ${type.name}: distinct internal values serialize to ${stored}`);
       storedValues.set(stored, entry.value);
     }
-    return { scalar: 'Enum', values: [...storedValues.keys()], enumValues: type.getValues().map(({ name, value }) => ({ name, value })) };
+    return { scalar: 'Enum', enumName: type.name, values: [...storedValues.keys()], enumValues: type.getValues().map(({ name, value }) => ({ name, value })) };
   }
   // The walk stops on a type that still has a base only where the chain repeats.
   if (rootScalar(type).baseScalarType) invalid(`Cyclic base scalar ${type.name}`);
@@ -63,7 +63,7 @@ const scalarDescription = (type) => {
   if (!['String', 'ID', 'Int', 'Float', 'Boolean', 'DateTime'].includes(scalar)) {
     invalid(`Unsupported scalar ${type.name}: declare a supported baseScalarType`);
   }
-  return { scalar };
+  return { scalar, ...(scalar === 'DateTime' ? { temporalName: name } : {}) };
 };
 
 // The version field of a protected entity, described the same way whether the type carries Simfinity's

package/src/mutation-limits.js

@@ -1,24 +1,54 @@
 import SimfinityError from './errors/simfinity.error.js';
 
+const OPTION_KEYS = ['maxNestedOperations', 'maxTransactionOperations'];
+const DEFAULT_MAX_TRANSACTION_OPERATIONS = 100;
+
 // Process-wide, like the query limits. null leaves nested collection operations unlimited.
 let maxNestedOperations = null;
+let maxTransactionOperations = DEFAULT_MAX_TRANSACTION_OPERATIONS;
 
+// Each call replaces both values: an omitted or undefined option restores its default.
 export const configureMutationLimits = (options = {}) => {
   if (!options || typeof options !== 'object' || Array.isArray(options)
     || ![Object.prototype, null].includes(Object.getPrototypeOf(options))) {
     throw new SimfinityError('Mutation limit options must be a plain object', 'INVALID_MUTATION_LIMITS', 400);
   }
-  // A misspelled option must not silently reset the limit to unlimited.
-  const unknown = Reflect.ownKeys(options).find((key) => key !== 'maxNestedOperations');
+  // A misspelled option must not silently reset a limit to its default.
+  const unknown = Reflect.ownKeys(options).find((key) => !OPTION_KEYS.includes(key));
   if (unknown !== undefined) {
-    throw new SimfinityError(`Unknown mutation limit option ${String(unknown)}; use maxNestedOperations`,
-      'INVALID_MUTATION_LIMITS', 400);
+    throw new SimfinityError(
+      `Unknown mutation limit option ${String(unknown)}; use maxNestedOperations or maxTransactionOperations`,
+      'INVALID_MUTATION_LIMITS',
+      400,
+    );
   }
-  const { maxNestedOperations: value = null } = options;
-  if (value !== null && (!Number.isSafeInteger(value) || value < 0)) {
+  const {
+    maxNestedOperations: nested = null,
+    maxTransactionOperations: transaction = DEFAULT_MAX_TRANSACTION_OPERATIONS,
+  } = options;
+  if (nested !== null && (!Number.isSafeInteger(nested) || nested < 0)) {
     throw new SimfinityError('maxNestedOperations must be null or a non-negative safe integer', 'INVALID_MUTATION_LIMITS', 400);
   }
-  maxNestedOperations = value;
+  if (!Number.isSafeInteger(transaction) || transaction < 1) {
+    throw new SimfinityError('maxTransactionOperations must be a positive safe integer', 'INVALID_MUTATION_LIMITS', 400);
+  }
+  // Validate everything first: a rejected call keeps both current limits.
+  maxNestedOperations = nested;
+  maxTransactionOperations = transaction;
 };
 
 export const getMaxNestedOperations = () => maxNestedOperations;
+
+export const getMaxTransactionOperations = () => maxTransactionOperations;
+
+// Internal, like the getters: the package exports only configureMutationLimits. The error of a mutation
+// past maxNestedOperations, which the preflights and a transaction attempt's counter (execution-state.js)
+// raise alike.
+export const nestedOperationsExceededError = (limit) => new SimfinityError(
+  `A mutation may perform at most ${limit} nested collection operations`, 'NESTED_OPERATIONS_EXCEEDED', 400,
+);
+
+// The error of a generated transaction (#151) whose list is longer than maxTransactionOperations.
+export const transactionOperationsExceededError = (limit) => new SimfinityError(
+  `A transaction may run at most ${limit} operations`, 'TRANSACTION_OPERATIONS_EXCEEDED', 400,
+);