@simtlix/simfinity-core 3.13.0 → 3.15.0

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

@@ -12,6 +12,8 @@ import type {
 
 /** The filter operator enum; its values are the {@link QueryOperator} names. */
 export const QLOperator: GraphQLEnumType;
+/** The collection and reference quantifier enum. */
+export const QLQuantifier: GraphQLEnumType;
 export const QLSort: GraphQLInputObjectType;
 export const QLValue: GraphQLScalarType<unknown, unknown>;
 
@@ -45,19 +47,57 @@ export const MAX_RECORD_VERSION: number;
  * embedded object or one whose stored members are all empty by these rules; the record identity is
  * never empty. The target's `id` right after a reference is empty exactly when the reference is,
  * including when the target is missing or hidden by its `find` scope. A path that continues inside an
- * embedded list or a collection fails with `INVALID_FILTER_PATH`. With an adapter that declares
+ * embedded list fails with `INVALID_FILTER_PATH`; shorthand through a collection excludes emptiness
+ * on a leaf, so use an explicit group. With an adapter that declares
  * `queryFeatures.referenceEmptiness: true`, a path may also cross single references and end at a
  * reference or a collection, and an embedded object may have reference and collection members: a
  * reference is empty when no record it points to exists that the target's `find` scope admits for
  * the caller, a collection when no such child exists, and a hidden record on the way reads as
  * missing; constructs that middleware and scopes add read stored data. With any other adapter they
- * fail with `UNSUPPORTED_QUERY`. A term or group condition without a path tests the field itself.
+ * fail with `UNSUPPORTED_QUERY`. A term or group condition without a path tests the field itself, except that every term
+ * of a quantified relation filter needs a non-empty element-relative path.
  */
 export type QueryOperator =
   | 'EQ' | 'NE' | 'LT' | 'LTE' | 'GT' | 'GTE' | 'BTW' | 'IN' | 'NIN' | 'LIKE'
   | 'ILIKE' | 'STARTS_WITH' | 'ISTARTS_WITH' | 'ENDS_WITH' | 'IENDS_WITH' | 'IEQ'
   | 'IS_EMPTY' | 'IS_NOT_EMPTY';
 
+/** The quantifier applied to the elements visible in a collection or reference frame. */
+export type QueryQuantifier = 'ANY' | 'ALL' | 'NONE';
+
+/** A condition inside a filter group, with paths relative to the current frame. */
+export interface QLFilterCondition {
+  field: string;
+  operator?: QueryOperator | null;
+  value?: any;
+  path?: string | null;
+}
+
+/** Recursive Boolean groups and quantified frames. */
+export interface QLFilterGroup {
+  conditions?: Array<QLFilterCondition | null> | null;
+  AND?: Array<QLFilterGroup | null> | null;
+  OR?: Array<QLFilterGroup | null> | null;
+  ANY?: Array<QLQuantifiedGroup | null> | null;
+  ALL?: Array<QLQuantifiedGroup | null> | null;
+  NONE?: Array<QLQuantifiedGroup | null> | null;
+}
+
+/** A frame path ends at a collection or single reference without crossing a list; inner paths are element-relative. */
+export interface QLQuantifiedGroup extends QLFilterGroup {
+  path: string;
+}
+
+/** A quantified field filter may omit terms; every supplied term needs a non-empty element-relative path. */
+export interface QLTypeFilterExpression {
+  quantifier?: QueryQuantifier | null;
+  terms?: Array<{
+    operator?: QueryOperator | null;
+    value?: any;
+    path?: string | null;
+  } | null> | null;
+}
+
 /**
  * A condition of a {@link FilterGroup}, as the `QLFilterCondition` input takes it: the field it
  * tests, its {@link QueryOperator} (`EQ` when omitted) and its value. On an object field, `path`
@@ -71,8 +111,11 @@ export interface FilterCondition {
   path?: string;
 }
 
-/** A `QLFilterGroup` value: flat conditions plus nested `AND` and `OR` groups. */
+/** A `QLFilterGroup` value: flat conditions, Boolean groups and element-relative quantified groups. */
 export interface FilterGroup {
+  ANY?: QLQuantifiedGroup[];
+  ALL?: QLQuantifiedGroup[];
+  NONE?: QLQuantifiedGroup[];
   AND?: FilterGroup[];
   OR?: FilterGroup[];
   conditions?: FilterCondition[];
@@ -97,6 +140,15 @@ export interface QueryFeatures {
    * must apply each target scope in `scopes`; constructs without a marker read stored data.
    */
   referenceEmptiness?: boolean | null | undefined;
+  /**
+   * Whether the adapter compiles quantified frames and their scoped joins. Requires
+   * `referenceEmptiness: true`; undefined or null means false. Invalid declarations fail with
+   * `INVALID_QUERY_FEATURES` (500). Client markers have frame-relative scope keys; compilers must
+   * apply frame scopes before quantification and honour scoped joins/aggregate anchors. Without
+   * this flag explicit quantified forms fail with `UNSUPPORTED_QUERY`; collection filters keep
+   * legacy joins. All adapters reject list sorts through collections, including count mode.
+   */
+  quantifiers?: boolean | null | undefined;
 }
 
 export interface ModelRegistration {
@@ -281,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>;
@@ -383,11 +455,17 @@ export interface QueryLimitsOptions {
   /** Positive safe integer; defaults to 1000. Unpaged lists use min(100, maxPageSize). */
   maxPageSize?: number;
   /**
-   * Positive safe integer; defaults to 10. The most distinct scoped joins and frames that the
-   * client's reference and collection emptiness may need in one list, aggregate or collection-field
-   * call; more fail with `FILTER_DEPTH_EXCEEDED` (400).
+   * Positive safe integer; defaults to 10. The most compiled frames and scoped joins that the
+   * client's conditions may need in one list, aggregate or collection-field call; more fail with
+   * `FILTER_DEPTH_EXCEEDED` (400), after every client 400 check and before middleware. Units count
+   * independently of markers: shorthand per group/prefix, explicit frames separately, scoped joins
+   * per containing frame/path/scope chain and emptiness frames per path/shape. Trusted units do
+   * not count toward this total. Named views check client arguments and their `where` groups
+   * against separate budgets of the same size; the `where` budget runs after middleware.
    */
   maxReferenceFrames?: number;
+  /** Positive safe integer; defaults to 3. Maximum client/trusted collection or reference frames on one chain. */
+  maxFrameNesting?: number;
 }
 
 /**
@@ -427,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;
   /**
@@ -580,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;
@@ -697,6 +786,9 @@ export interface DatabaseAdapter<Model = any, Session = any> {
 }
 export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapter<Model, Session>): Runtime<Model, Session>;
 
+/** Scoped single-reference joins, keyed by a dotted prefix relative to the containing frame. */
+export type QueryJoins = Record<string, QueryPredicate | null>;
+
 /**
  * `operator` is a {@link QueryOperator}; the value of a text operator is a validated string. For
  * `IS_EMPTY` and `IS_NOT_EMPTY` the value is null, and `path` may end at an embedded object, an
@@ -705,17 +797,31 @@ export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapt
  * references and end at a reference or a collection.
  *
  * `scopes` exists only on such an emptiness predicate from a client, and only for a compiler that
- * declares `referenceEmptiness: true`. It has one key per dotted path from the queried record: each
+ * declares `referenceEmptiness: true`. It has one key per dotted path relative to its frame: each
  * single reference the path crosses (a scoped join, which admits the target only where the scope
  * admits it), the end when it is a reference or a collection, and each reference and collection
  * member of an embedded object (frames, which keep only the records the scope admits). Each value is
  * the target's `find` scope as a predicate in the target's own frame, or null when the scope added
  * nothing; after a scoped crossing, a null hop still correlates through that scoped join. Without
- * `scopes` the predicate reads stored data, through plain joins.
+ * `scopes` the predicate reads stored data, through plain joins. `joins` carries the scopes of
+ * single references crossed inside a client frame, with keys relative to the containing frame.
+ * A `quantified` node selects elements with `ANY`, `ALL` or `NONE`, applying `scope` before `where`;
+ * both predicates use paths relative to the element, and null means no restriction. Empty elements
+ * give ANY false, ALL/NONE true; scope is never negated, and frames never multiply roots. `anchor` is
+ * an aggregate's legacy join chain; when present, `path` is relative to it and `joins` is absent.
  */
 export type QueryPredicate =
-  | { kind: 'predicate'; path: string[]; operator: string; value: any; scopes?: Record<string, QueryPredicate | null> }
-  | { kind: 'and' | 'or'; terms: QueryPredicate[] };
+  | { kind: 'predicate'; path: string[]; operator: string; value: any; scopes?: Record<string, QueryPredicate | null>; joins?: QueryJoins }
+  | { kind: 'and' | 'or'; terms: QueryPredicate[] }
+  | {
+      kind: 'quantified';
+      quantifier: QueryQuantifier;
+      path: string[];
+      where: QueryPredicate | null;
+      scope: QueryPredicate | null;
+      joins?: QueryJoins;
+      anchor?: string[];
+    };
 export interface QueryPlan {
   entity: string;
   where: QueryPredicate | null;
@@ -738,8 +844,8 @@ export interface QueryPlan {
  * value inside an embedded list or a collection, `INVALID_FILTER_OPERATOR` for an embedded type that
  * reaches itself through single embedded members, `INVALID_FILTER_VALUE` for a value that is not
  * omitted or null, and `UNSUPPORTED_QUERY` for a reference or collection on the path or among the
- * members. A term without a path (omitted, null or `""`) and a group condition without a path test
- * the field itself. For other operators, a filter path of more than one segment that ends at an
+ * members. A nonquantified emptiness term without a path (omitted, null or `""`) and a group
+ * condition without a path test the field itself; quantified filter terms always need a path. For other operators, a filter path of more than one segment that ends at an
  * object fails with `INVALID_FILTER_PATH`, as on MongoDB; a bare object field keeps
  * `MISSING_FILTER_PATH`.
  *
@@ -748,18 +854,22 @@ export interface QueryPlan {
  * reads a reference or collection member, fails with `UNSUPPORTED_QUERY` where the order above has
  * `UNSUPPORTED_QUERY` for references; when it is true, such a condition plans with stored semantics,
  * unless its term or group condition carries a client scope marker that the runtime filled, which
- * becomes the predicate's `scopes`. A marker that is not filled for every path of the condition fails
+ * becomes the predicate's `scopes`. `quantifiers` has the same default rule and requires reference
+ * emptiness; enabled collection filters emit quantified nodes, with per-group/prefix correlation,
+ * element-relative scopes/joins and aggregate anchors beyond legacy J joins. `__scope`, `__implicit`
+ * and `__anchor` are reserved internal input metadata. A marker not filled for every path fails
  * with `DETACHED_CLIENT_FILTER` (500).
  */
-export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string>; referenceEmptiness?: boolean }): QueryPlan;
+export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string>; referenceEmptiness?: boolean; quantifiers?: boolean }): QueryPlan;
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
 
 /**
  * Process-wide. `maxPageSize` (default 1000) caps page sizes. `maxReferenceFrames` (default 10) caps,
- * per list, aggregate or collection-field call, the distinct scoped joins and frames that a client's
- * reference and collection emptiness needs; more fail with `FILTER_DEPTH_EXCEEDED` (400). Each must be
- * a positive safe integer, or the call throws `INVALID_QUERY_LIMITS` (400) and keeps both limits; an
- * omitted option takes its default again.
+ * per list, aggregate or collection-field call, the compiled frames and scoped joins a client's
+ * conditions need. Named views check client arguments and `where` groups separately. `maxFrameNesting` (default 3) caps nested frames along one chain in client and
+ * trusted constructs. Exceeding either frame limit fails with `FILTER_DEPTH_EXCEEDED` (400). Each
+ * option must be a positive safe integer, or the call throws `INVALID_QUERY_LIMITS` (400) and keeps
+ * every current limit; an omitted option takes its default again.
  */
 export function configureQueryLimits(options?: QueryLimitsOptions): void;
 /**
@@ -1014,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;