@simtlix/simfinity-core 3.14.0 → 3.15.0

package/README.md

@@ -38,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.
@@ -57,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.14.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/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/runtime.js

@@ -2,6 +2,7 @@ import {
   configureQueryLimits, getQueryMaxPageSize, getQueryMaxReferenceFrames, paginationStages,
 } from './query-limits.js';
 import { configureMutationLimits, getMaxNestedOperations } from './mutation-limits.js';
+import { createAfterCommit } from './after-commit.js';
 import {
   GraphQLObjectType, GraphQLString, GraphQLID, GraphQLSchema, GraphQLList,
   GraphQLNonNull, GraphQLInputObjectType, GraphQLScalarType,
@@ -10,6 +11,7 @@ import {
 } from 'graphql';
 
 import SimfinityError from './errors/simfinity.error.js';
+import { captureSchemaRegistrations } from './schema-registrations.js';
 import InternalServerError from './errors/internal-server.error.js';
 import { ForbiddenError } from './auth/errors.js';
 import QLOperator from './const/QLOperator.js';
@@ -544,6 +546,7 @@ const attemptInputs = (input, type) => {
 };
 
 export const createRuntime = (adapter) => {
+  const afterCommit = createAfterCommit(adapter);
   if (!adapter) {
     throw new SimfinityError('A database adapter is required', 'ADAPTER_REQUIRED', 500);
   }
@@ -1507,6 +1510,7 @@ const assertRecordVersion = async (gqltype, id, record, expectedVersion, advance
 // deletes it only at that version, and a record it deleted at another one, which an adapter wrapper
 // that drops the options would delete, fails with DATABASE_ERROR and rolls back with the transaction.
 const onDelete = async (Model, controller, id, session, context, current, precondition = null) => {
+  afterCommit.validate(controller);
   const hasHook = !!(controller && controller.onDelete);
   let currentObject = current;
   if (currentObject === undefined && (hasHook || !readByIdIsInert(Model))) {
@@ -1625,6 +1629,7 @@ const setsVersion = (update) => [update, ...Object.entries(update)
 // cannot set the version, and a result that did not advance it fails with DATABASE_ERROR.
 const onUpdateSubject = async (Model, gqltype, controller, args, session, linkToParent, context,
   recordChecked = false, { expectedVersion, observedVersion, record } = {}) => {
+  afterCommit.validate(controller);
   const versioned = isProtected(gqltype);
   const materializedModel = await materializeModel(args, gqltype, linkToParent, 'UPDATE', session);
   const objectId = args.id;
@@ -1712,6 +1717,7 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
 // A protected type's version is captured before the action can change `args`, and checked on the
 // plain pre-read record before the from-state check, which reads `state` from that record (#98).
 const onStateChanged = async (Model, gqltype, controller, args, session, actionField, context) => {
+  afterCommit.validate(controller);
   const versioned = isProtected(gqltype);
   const expectedVersion = versioned ? assertVersionInput(args.version) : undefined;
   const storedModel = versioned
@@ -1738,6 +1744,7 @@ const onStateChanged = async (Model, gqltype, controller, args, session, actionF
 };
 
 const onSaveObject = async (Model, gqltype, controller, args, session, linkToParent, context) => {
+  afterCommit.validate(controller);
   const materializedModel = await materializeModel(args, gqltype, linkToParent, 'CREATE', session);
   if (typesDict.types[gqltype.name].stateMachine) {
     materializedModel.modelArgs.state = stateValue(
@@ -1776,9 +1783,13 @@ const saveObject = async (typeName, args, session, context) => {
   const type = typesDict.types[typeName];
   assertCollectionWrites(type.gqltype, args);
   const snapshot = cloneInput(args, type.inputType);
-  return adapter.withTransaction(session, (transaction) => onSaveObject(
-    type.model, type.gqltype, type.controller, cloneInput(snapshot, type.inputType), transaction, null, context,
-  ), type.model);
+  return adapter.withTransaction(session, async (transaction) => {
+    const attemptArgs = cloneInput(snapshot, type.inputType);
+    const record = await onSaveObject(type.model, type.gqltype, type.controller, attemptArgs, transaction, null, context);
+    afterCommit.queue({ typeName, controller: type.controller, operation: operations.SAVE,
+      record, args: attemptArgs, context, session: transaction });
+    return record;
+  }, type.model);
 };
 
 // Counts the added, updated and deleted entries of referenced collections, at every nesting level that
@@ -1860,7 +1871,7 @@ const preReadTopLevel = async (Model, gqltype, { id, version }, advances, contex
 // other operation passes its input, which attemptInputs copies. Either way, a retry checks the version
 // the request sent.
 const executeOperation = (Model, gqltype, controller, args, operation, actionField,
-  session, context, inputType) => {
+  session, context, inputType, actionName) => {
   const limit = getMaxNestedOperations();
   if (limit !== null && operation !== operations.DELETE) assertNestedOperations(gqltype, args, limit);
   if (operation !== operations.DELETE) assertCollectionWrites(gqltype, args);
@@ -1872,26 +1883,36 @@ const executeOperation = (Model, gqltype, controller, args, operation, actionFie
     session,
     async (mySession) => {
       const attemptArgs = nextInput();
+      let record;
       switch (operation) {
         case operations.SAVE:
-          return onSaveObject(Model, gqltype, controller, attemptArgs, mySession, null, context);
+          record = await onSaveObject(Model, gqltype, controller, attemptArgs, mySession, null, context);
+          break;
         case operations.UPDATE: {
           const precondition = versioned
             ? await preReadTopLevel(Model, gqltype, attemptArgs, true, context, mySession) : undefined;
-          return onUpdateSubject(Model, gqltype, controller, attemptArgs, mySession, null, context, false, precondition);
+          record = await onUpdateSubject(Model, gqltype, controller, attemptArgs, mySession, null, context, false, precondition);
+          break;
         }
         case operations.DELETE: {
-          if (!versioned) return onDelete(Model, controller, attemptArgs, mySession, context);
-          const { expectedVersion, record } = await preReadTopLevel(Model, gqltype, attemptArgs, false, context,
-            mySession);
-          return onDelete(Model, controller, attemptArgs.id, mySession, context, record, { gqltype, expectedVersion });
+          if (!versioned) record = await onDelete(Model, controller, attemptArgs, mySession, context);
+          else {
+            const { expectedVersion, record: current } = await preReadTopLevel(Model, gqltype, attemptArgs, false, context,
+              mySession);
+            record = await onDelete(Model, controller, attemptArgs.id, mySession, context, current, { gqltype, expectedVersion });
+          }
+          break;
         }
         case operations.STATE_CHANGED:
-          return onStateChanged(Model, gqltype, controller,
+          record = await onStateChanged(Model, gqltype, controller,
             attemptArgs, mySession, actionField, context);
+          break;
         default:
           return null;
       }
+      afterCommit.queue({ typeName: gqltype.name, controller, operation, record, args: attemptArgs,
+        context, session: mySession, action: actionName });
+      return record;
     },
     Model,
   );
@@ -1956,19 +1977,22 @@ const executeItemFunction = async (gqltype, collectionField, parentKey, session,
       }
     }
 
+    let record;
     switch (operationType) {
       case operations.SAVE:
-        await onSaveObject(type.model, collectionGQLType, type.controller,
+        record = await onSaveObject(type.model, collectionGQLType, type.controller,
           args.input, session, linkToParent, context);
         break;
       case operations.UPDATE:
-        await onUpdateSubject(type.model, collectionGQLType, type.controller,
+        record = await onUpdateSubject(type.model, collectionGQLType, type.controller,
           args.input, session, linkToParent, context, true, versioned ? { expectedVersion, observedVersion, record: child } : undefined);
         break;
       case operations.DELETE:
-        await onDelete(type.model, type.controller, args.id, session, context, child,
+        record = await onDelete(type.model, type.controller, args.id, session, context, child,
           versioned ? { gqltype: collectionGQLType, expectedVersion } : null);
     }
+    afterCommit.queue({ typeName: collectionGQLType.name, controller: type.controller,
+      operation: operationType, record, args: args.input, context, session });
   }
 };
 
@@ -3158,7 +3182,7 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
                   await executeMiddleware(params);
                   return executeOperation(type.model, type.gqltype, type.controller,
                     args.input, operations.STATE_CHANGED, actionField,
-                    null, context, type.inputType);
+                    null, context, type.inputType, actionName);
                 },
               };
             }
@@ -3893,6 +3917,7 @@ const readSchemaOptions = (options) => {
 };
 
 const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomMutations, options) => {
+  Object.values(typesDict.types).forEach(({ controller }) => afterCommit.validate(controller));
   // Reject before models, resolvers or roots are built, so a rejected schema changes nothing.
   const { includedCustomQueries } = readSchemaOptions(options);
   assertQueryNamesAvailable(includedQueryTypes, includedCustomQueries);
@@ -3980,6 +4005,15 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
   }
 
   const schema = constructSchema(query, mutation, reserveVersionNames);
+  captureSchemaRegistrations(schema, Object.values(typesDict.types).map((entry) => ({
+    gqltype: entry.gqltype, endpoint: entry.endpoint,
+    // Only associate roots generated for this schema. Excluded endpoint names can be custom queries.
+    simpleEntityEndpointName: shouldNotBeIncludedInSchema(includedQueryTypes, entry.gqltype)
+      ? null : entry.simpleEntityEndpointName,
+    inputType: entry.inputType, updateInputType: typesDictForUpdate.types[entry.gqltype.name]?.inputType,
+    stateMachine: entry.stateMachine,
+  })), (type, field) => field.extensions?.queryable !== false
+    && (field.extensions?.queryable === true || !hasApplicationResolver(type, field.name)));
   // Reserve reachable types whose relation fields still have no resolver, such as an unregistered
   // custom operation result, so another runtime cannot later generate resolvers this schema executes.
   schemaTypes.forEach((type) => {
@@ -4335,6 +4369,7 @@ function formatArgs(argsArray) {
   return {
     configureQueryLimits,
     configureMutationLimits,
+    configureAfterCommit: afterCommit.configure,
     connect,
     addNoEndpointType,
     createSchema,

package/src/schema-registrations.js

@@ -0,0 +1,18 @@
+// Module-local ownership shared by consumers of this exact core installation. The snapshot is
+// registration data only; descriptor formats and HTTP belong to opt-in consumer packages.
+const registrationsBySchema = new WeakMap();
+
+export const captureSchemaRegistrations = (schema, registrations, queryable) => {
+  const snapshot = registrations.map((entry) => Object.freeze({
+    ...entry,
+    stateMachine: entry.stateMachine ? Object.freeze({
+      initialState: entry.stateMachine.initialState
+        ? Object.freeze({ ...entry.stateMachine.initialState }) : null,
+    }) : null,
+    queryableFields: Object.freeze(Object.fromEntries(Object.values(entry.gqltype.getFields())
+      .map((field) => [field.name, queryable(entry.gqltype, field)]))),
+  }));
+  registrationsBySchema.set(schema, Object.freeze(snapshot));
+};
+
+export const schemaRegistrations = (schema) => registrationsBySchema.get(schema);

package/src/transaction-callbacks.js

@@ -0,0 +1,34 @@
+// The transaction owner creates a new queue for every attempt, even when the driver reuses the
+// session. No session is adopted merely because it reports an active transaction.
+export const createTransactionCallbacks = () => {
+  const active = new WeakMap();
+  const enqueue = (session, run) => {
+    const jobs = active.get(session);
+    if (!jobs) return false;
+    jobs.push(run);
+    return true;
+  };
+  const begin = (session) => {
+    const jobs = [];
+    let state = 'active';
+    const detach = () => { if (active.get(session) === jobs) active.delete(session); };
+    active.set(session, jobs);
+    return {
+      seal() { if (state === 'active') { state = 'sealed'; detach(); } },
+      confirm() { if (state === 'sealed') state = 'confirmed'; },
+      discard() { if (state !== 'confirmed' && state !== 'drained') { state = 'discarded'; detach(); jobs.length = 0; } },
+      async drain() {
+        if (state !== 'confirmed') return;
+        state = 'drained';
+        for (const run of jobs.splice(0)) {
+          try { await run(); } catch {
+            // Runtime jobs report their own failures. A faulty adapter consumer cannot change an
+            // already committed result, stop later jobs, or enter the driver's retry classifier.
+            try { console.error('After-commit callback failed'); } catch { /* Logging is best effort. */ }
+          }
+        }
+      },
+    };
+  };
+  return { begin, enqueue };
+};

package/types/index.d.ts

@@ -333,7 +333,27 @@ export class InternalServerError extends SimfinityError {
  */
 export function buildErrorFormatter(callback?: (error: SimfinityError) => Error | void): (error: unknown) => GraphQLError;
 
-export interface EntityController<Session = any> {
+export interface AfterCommitErrorDetails {
+  committed: true;
+  typeName: string;
+  operation: 'save' | 'update' | 'delete' | 'state_changed';
+  callbackName: 'onSaveCommitted' | 'onUpdateCommitted' | 'onDeleteCommitted' | 'onTransitionCommitted';
+  context: any;
+}
+export interface AfterCommitOptions {
+  /** Operational reporting only. Rejections are caught and never fail the committed write. */
+  onError?: (error: unknown, details: AfterCommitErrorDetails) => void | Promise<void>;
+}
+export interface CommittedControllerCallbacks {
+  /** After the owning transaction commits; a detached result and the successful attempt's input. */
+  onSaveCommitted?(record: any, args: any, context: any): void | Promise<void>;
+  onUpdateCommitted?(record: any, context: any): void | Promise<void>;
+  /** Called only when a record was actually deleted. */
+  onDeleteCommitted?(record: any, context: any): void | Promise<void>;
+  /** Exclusive notification for a state action; action is its registered name. */
+  onTransitionCommitted?(record: any, action: string, context: any): void | Promise<void>;
+}
+export interface EntityController<Session = any> extends CommittedControllerCallbacks {
   onSaving?(record: any, args: any, session: Session | undefined, context: any): void | Promise<void>;
   onSaved?(record: any, args: any, session: Session | undefined, context: any): void | Promise<void>;
   onUpdating?(id: any, update: any, session: Session | undefined, context: any): void | Promise<void>;
@@ -485,6 +505,8 @@ export interface ViewOptions {
 }
 
 export interface Runtime<Model = any, Session = any> {
+  /** Per runtime. No arguments resets to safe default logging; invalid options leave it unchanged. */
+  configureAfterCommit(options?: AfterCommitOptions): void;
   /** The same process-wide setting as the root `configureQueryLimits`. */
   configureQueryLimits(options?: QueryLimitsOptions): void;
   /**
@@ -638,6 +660,15 @@ export interface DatabaseAdapter<Model = any, Session = any> {
   castId(value: any): any;
   stateValue?(state: { name: string; value: any }): any;
   withTransaction<T>(session: Session | null | undefined, callback: (session: Session) => Promise<T> | T, model?: Model): Promise<T>;
+  /**
+   * Optional capability for controller callbacks. Accept only into an active attempt owned by this
+   * adapter; false means the supplied session has no owned attempt. A new queue is required per
+   * retry, including retries on the same native session. Seal before commit, discard on abort or
+   * unresolved uncertainty, and drain once, serially, after confirmed commit and cleanup attempt.
+   * Callback failures must never enter transaction retry/rollback paths or fail a committed write.
+   * Borrowed operations join the owning attempt; this method does not observe external commits.
+   */
+  enqueueAfterCommit?(session: Session, run: () => void | Promise<void>): boolean;
   newRecord(model: Model, data: any, session?: Session): any;
   saveRecord(model: Model, record: any, session?: Session): any;
   toObject(record: any): any;
@@ -1093,3 +1124,6 @@ export const plugins: {
     };
   };
 };
+
+/** Early opt-out. Import its function from /introspection before loading the runtime. */
+export interface IntrospectionOptions { fieldExtensions: false; }

package/types/introspection.d.ts

@@ -0,0 +1,4 @@
+import type { IntrospectionOptions } from './index.js';
+export type { IntrospectionOptions } from './index.js';
+/** Must run before importing the runtime/facades. Never removes installed metadata. */
+export function configureIntrospection(options: IntrospectionOptions): void;