@simtlix/simfinity-core 3.14.0 → 3.16.0

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/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/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,
+);

package/src/operation-input.js

@@ -0,0 +1,345 @@
+import {
+  GraphQLID, getNamedType, isEnumType, isInputObjectType, isListType, isNonNullType,
+} from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { RecordVersionRef } from './record-version.js';
+
+// Internal, and never exported from the package. The typed walk that validates the inputs of the
+// lifecycle helpers and of the generated transaction (#151) and builds the snapshots they work on.
+// It is pure: it reads the value and its GraphQL input type, calls no scalar function and no hook,
+// and never changes what it is given. Every container, list and plain-data scalar of the result is
+// new, so no two positions of a snapshot share an object and a hook that rewrites one cannot change
+// another, a retry or the caller's input.
+
+// Programmatic callers get the whole check; a transaction's operations arrive already coerced by
+// GraphQL, so they only get the scalar and record-key rules; a copy of a snapshot gets no check.
+const MODES = ['programmatic', 'coerced', 'copy'];
+
+const UNKNOWN_FIELD = 'unknown field';
+const STATE_FIELD = 'state changes only through transitionObject';
+const EXPECTED_OBJECT = 'expected a plain object';
+const EXPECTED_LIST = 'expected a list';
+const EXPECTED_DENSE_LIST = 'expected a dense list';
+const ACCESSOR = 'accessor property';
+const HIDDEN_PROPERTY = 'non-enumerable or symbol-keyed property';
+const CYCLE = 'cycle';
+const UNSUPPORTED_SCALAR = 'unsupported scalar value';
+const STRING_KEY = 'pass the ID as a string, for example String(record._id)';
+const PRIMITIVE_KEY = 'pass the ID as a primitive value';
+const NESTED_TOO_DEEPLY = 'input is nested too deeply';
+
+const requiredValueError = (path) => new SimfinityError(`Required value ${path} is missing`, 'REQUIRED_VALUE', 400);
+
+// The message names the path and the rule, never a value.
+const invalidInputError = (path, reason) => new SimfinityError(`Invalid input at ${path}: ${reason}`,
+  'INVALID_INPUT', 400);
+
+// How many containers one scalar value may nest. Past it the copy would recurse without a bound: a JSON
+// value of a few thousand nested arrays is a client's to send, and it must be refused as input, not
+// crash with a stack overflow.
+const MAX_SCALAR_DEPTH = 256;
+
+// How many input objects and lists an input may nest, the top-level input object included. Past it the walk
+// would recurse without a bound and end in a stack overflow, a 500 where GraphQL's own roots give a 400.
+// Scalar values inside count on their own, against MAX_SCALAR_DEPTH.
+const MAX_INPUT_DEPTH = 256;
+
+const intrinsicGetTime = Date.prototype.getTime;
+
+// The time of a real Date, read with the intrinsic so that nothing the caller put on the value runs, or
+// undefined when the value is not one (an object that only has the Date prototype, a Proxy of a Date).
+const dateTime = (value) => {
+  try {
+    return intrinsicGetTime.call(value);
+  } catch {
+    return undefined;
+  }
+};
+
+const isPrimitive = (value) => ['string', 'number', 'boolean', 'bigint'].includes(typeof value);
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+// Every copied property is an own data property, even `__proto__`, which assignment would turn into a
+// change of prototype.
+const defineData = (target, key, value) => Object.defineProperty(target, key,
+  { value, writable: true, enumerable: true, configurable: true });
+
+// The keys the walk visits: with checks, every own key, so that a symbol key is seen and rejected;
+// without them, the enumerable string keys.
+const ownKeysOf = (source, checked) => (checked ? Reflect.ownKeys(source) : Object.keys(source));
+
+// The value of an own property, read from its descriptor so that a getter is never run. Only an
+// enumerable data property qualifies. The caller has already refused symbol keys.
+const dataProperty = (source, key, path) => {
+  const descriptor = Object.getOwnPropertyDescriptor(source, key);
+  // A key that was reported and then has no descriptor (a Proxy, or a property that caller code removed
+  // while the walk was running) is as hidden as one that is not enumerable.
+  if (descriptor === undefined) throw invalidInputError(path, HIDDEN_PROPERTY);
+  if (!('value' in descriptor)) throw invalidInputError(path, ACCESSOR);
+  if (!descriptor.enumerable) throw invalidInputError(path, HIDDEN_PROPERTY);
+  return descriptor.value;
+};
+
+// The items of a list, in order. With checks the list must be dense and made of enumerable data
+// properties; without them it is read as it is.
+const listItems = (list, path, checked) => {
+  const items = [];
+  for (let index = 0; index < list.length; index += 1) {
+    if (!checked) {
+      items.push(list[index]);
+    } else if (Object.hasOwn(list, index)) {
+      items.push(dataProperty(list, index, `${path}[${index}]`));
+    } else {
+      throw invalidInputError(path, EXPECTED_DENSE_LIST);
+    }
+  }
+  return items;
+};
+
+// Cycles are looked for along the path from the root to the value being copied, so an object that two
+// positions share without containing itself is not one. `state.depth` counts the input objects and lists
+// entered, and the one past MAX_INPUT_DEPTH is refused at its own path.
+const enter = (source, path, state) => {
+  if (state.ancestors.has(source)) throw invalidInputError(path, CYCLE);
+  if (state.depth >= MAX_INPUT_DEPTH) throw invalidInputError(path, NESTED_TOO_DEEPLY);
+  state.ancestors.add(source);
+  state.depth += 1;
+};
+
+const leave = (source, state) => {
+  state.ancestors.delete(source);
+  state.depth -= 1;
+};
+
+// A scalar value as plain data: primitives as they are, `Date` by time, and arrays and objects with
+// the Object or a null prototype deeply. `shared` maps the objects already copied within this one
+// value, so a reference it repeats stays shared in the copy; a position never shares with another.
+// Each copied object keeps its source's prototype and is never frozen. Anything else (a function, a
+// symbol, an instance of another class such as ObjectId, Buffer or Map) is unsupported, and so is a
+// value nested in more than MAX_SCALAR_DEPTH containers. `depth` counts the containers above the value.
+const copyData = (value, path, state, shared, depth = 0) => {
+  if (typeof value === 'function' || typeof value === 'symbol') {
+    if (state.checkValues) throw invalidInputError(path, UNSUPPORTED_SCALAR);
+    return value;
+  }
+  if (value === null || typeof value !== 'object') return value;
+  const isList = Array.isArray(value);
+  const time = !isList && Object.getPrototypeOf(value) === Date.prototype ? dateTime(value) : undefined;
+  const isDate = time !== undefined;
+  if (!isList && !isDate && !isPlainObject(value)) {
+    if (state.checkValues) throw invalidInputError(path, UNSUPPORTED_SCALAR);
+    return value;
+  }
+  if (state.ancestors.has(value)) throw invalidInputError(path, CYCLE);
+  if (shared.has(value)) return shared.get(value);
+  let copy;
+  if (isDate) {
+    copy = new Date(time);
+  } else {
+    if (depth >= MAX_SCALAR_DEPTH) throw invalidInputError(path, UNSUPPORTED_SCALAR);
+    state.ancestors.add(value);
+    if (isList) {
+      copy = listItems(value, path, state.checkValues)
+        .map((item, index) => copyData(item, `${path}[${index}]`, state, shared, depth + 1));
+    } else {
+      copy = Object.create(Object.getPrototypeOf(value));
+      for (const key of ownKeysOf(value, state.checkValues)) {
+        if (typeof key === 'symbol') throw invalidInputError(path, HIDDEN_PROPERTY);
+        const keyPath = `${path}.${key}`;
+        const item = state.checkValues ? dataProperty(value, key, keyPath) : value[key];
+        defineData(copy, key, copyData(item, keyPath, state, shared, depth + 1));
+      }
+    }
+    state.ancestors.delete(value);
+  }
+  shared.set(value, copy);
+  return copy;
+};
+
+// A record key: where the declared type is ID, and for IdInputType.id, only a string; where it is
+// another scalar, any primitive. Plain objects, arrays, dates and class instances such as ObjectId are
+// refused, because on a database that casts nothing an `id` of { $ne: null } would select a record (D1).
+const assertRecordKey = (value, kind, path) => {
+  const accepted = kind === 'string' ? typeof value === 'string' : isPrimitive(value);
+  if (!accepted) throw invalidInputError(path, kind === 'string' ? STRING_KEY : PRIMITIVE_KEY);
+};
+
+const keyKind = (declaredType, isIdInput = false) => (
+  isIdInput || getNamedType(declaredType) === GraphQLID ? 'string' : 'primitive'
+);
+
+const walkScalar = (value, path, state, position) => {
+  if (state.checkValues && position.key !== undefined) assertRecordKey(value, position.key, path);
+  return copyData(value, path, state, new Map());
+};
+
+// The matched internal value is kept by identity. The test is membership under SameValueZero, which is
+// what `includes` uses; it is not parseValue, and only programmatic input needs it, as GraphQL has
+// already checked a transaction's.
+const walkEnum = (value, type, path, state) => {
+  if (state.checkShape && !type.getValues().map((entry) => entry.value).includes(value)) {
+    throw invalidInputError(path, `not a value of enum ${type.name}`);
+  }
+  return value;
+};
+
+const walkList = (value, type, path, state, position) => {
+  if (!Array.isArray(value)) {
+    if (state.checkShape) throw invalidInputError(path, EXPECTED_LIST);
+    return walkValue(value, type.ofType, path, state, position);
+  }
+  enter(value, path, state);
+  // walkValue turns an `undefined` item into `null`, which executeItemFunction skips.
+  const items = listItems(value, path, state.checkShape)
+    .map((item, index) => walkValue(item, type.ofType, `${path}[${index}]`, state, position));
+  leave(value, state);
+  return items;
+};
+
+const walkObject = (value, type, path, state, position) => {
+  if (state.checkShape && !isPlainObject(value)) throw invalidInputError(path, EXPECTED_OBJECT);
+  // Only a coerced or copied value can get here without being an object, and GraphQL does not
+  // produce one: it is copied as plain data.
+  if (typeof value !== 'object' || Array.isArray(value)) return copyData(value, path, state, new Map());
+  enter(value, path, state);
+  const fields = type.getFields();
+  const isCollection = state.collectionInputTypes?.has(type) === true;
+  // The top-level id of an update, a transition or a delete is required whatever its declared type,
+  // and it is a record key.
+  const isTopLevelId = (key) => key === 'id' && position.topLevel === true && state.requireId;
+  const copy = {};
+  for (const key of ownKeysOf(value, state.checkShape)) {
+    if (typeof key === 'symbol') throw invalidInputError(path, HIDDEN_PROPERTY);
+    const fieldPath = `${path}.${key}`;
+    const item = state.checkShape ? dataProperty(value, key, fieldPath) : value[key];
+    // An own `undefined` is an omitted field, as GraphQL never delivers one.
+    if (item === undefined) continue;
+    const field = Object.hasOwn(fields, key) ? fields[key] : undefined;
+    if (field === undefined) {
+      if (state.checkShape) {
+        const managedState = position.topLevel && state.stateManaged && key === 'state';
+        throw invalidInputError(fieldPath, managedState ? STATE_FIELD : UNKNOWN_FIELD);
+      }
+      // GraphQL leaves no undeclared field in a coerced input, so there is no rule to apply: the
+      // value is kept as plain data.
+      defineData(copy, key, walkScalar(item, fieldPath, state, {}));
+      continue;
+    }
+    const fieldPosition = {};
+    if (key === 'id' && (isTopLevelId(key) || position.idIsKey || type === state.idInputType
+      || type === state.recordVersionRef)) {
+      fieldPosition.key = keyKind(field.type, type === state.idInputType);
+    }
+    if (isCollection && key === 'updated') fieldPosition.idIsKey = true;
+    if (isCollection && key === 'deleted') fieldPosition.key = keyKind(field.type);
+    if (item === null && isTopLevelId(key)) throw requiredValueError(fieldPath);
+    defineData(copy, key, walkValue(item, field.type, fieldPath, state, fieldPosition));
+  }
+  leave(value, state);
+  for (const [name, field] of Object.entries(fields)) {
+    const required = (state.checkShape && isNonNullType(field.type)) || isTopLevelId(name);
+    if (required && !Object.hasOwn(copy, name)) throw requiredValueError(`${path}.${name}`);
+  }
+  return copy;
+};
+
+const walkValue = (value, type, path, state, position) => {
+  if (isNonNullType(type)) {
+    if (state.checkShape && (value === null || value === undefined)) throw requiredValueError(path);
+    return walkValue(value, type.ofType, path, state, position);
+  }
+  if (value === null || value === undefined) return null;
+  if (isListType(type)) return walkList(value, type, path, state, position);
+  if (isInputObjectType(type)) return walkObject(value, type, path, state, position);
+  if (isEnumType(type)) return walkEnum(value, type, path, state);
+  return walkScalar(value, path, state, position);
+};
+
+const createWalkState = ({
+  mode = 'programmatic', topLevelId = false, stateManaged = false, collectionInputTypes, idInputType,
+  recordVersionRef = RecordVersionRef,
+}) => {
+  if (!MODES.includes(mode)) throw new TypeError(`Unknown input walk mode: ${typeof mode === 'string' ? mode : typeof mode}`);
+  return {
+    // Containers, lists, fields, nullability and enums.
+    checkShape: mode === 'programmatic',
+    // Scalars and record keys.
+    checkValues: mode !== 'copy',
+    requireId: topLevelId === true && mode !== 'copy',
+    stateManaged: stateManaged === true,
+    collectionInputTypes,
+    idInputType,
+    recordVersionRef,
+    ancestors: new Set(),
+    depth: 0,
+  };
+};
+
+/**
+ * Validates `value` against an input object type and returns a snapshot of it.
+ *
+ * `options.mode` is 'programmatic' (the default: the structure rules and the scalar rules, for the
+ * lifecycle helpers), 'coerced' (the scalar rules and the record keys only, for the operations of a
+ * transaction, which GraphQL has already coerced) or 'copy' (no check, a type-directed copy of an
+ * existing snapshot for one attempt). `path` names the root in errors (default `input`). `topLevelId`
+ * makes the top-level `id` required and a record key. `collectionInputTypes` is the set of generated
+ * collection inputs (`added`, `updated`, `deleted`), `idInputType` the input of a single reference and
+ * `recordVersionRef` the input of a versioned delete (default: Simfinity's own), which the walk knows
+ * by identity to find their record keys. With `stateManaged`, an undeclared top-level `state` says that
+ * state changes only through transitionObject; elsewhere it is an unknown field.
+ *
+ * Input objects and lists may nest 256 levels, the top-level input included, in every mode; the next one
+ * is refused with `input is nested too deeply`.
+ *
+ * A missing or null value throws REQUIRED_VALUE (400) and any other violation INVALID_INPUT (400), both
+ * naming a path such as `input.lines.added[1].price` and never a value. The value is never changed.
+ * The result has new, extensible, plain containers; dates and plain data are copied and enum values
+ * are kept by identity.
+ */
+export const snapshotOperationInput = (value, inputType, options = {}) => {
+  const state = createWalkState(options);
+  const path = options.path ?? 'input';
+  if (!isInputObjectType(isNonNullType(inputType) ? inputType.ofType : inputType)) {
+    throw new TypeError('snapshotOperationInput needs an input object type');
+  }
+  if (value === undefined || value === null) {
+    if (state.checkValues) throw requiredValueError(path);
+    return value;
+  }
+  return walkValue(value, inputType, path, state, { topLevel: true });
+};
+
+/**
+ * The target of `deleteObject`: a plain object with `id` and, on a protected type only, `version`. The
+ * id is a record key and must be a string, as the `ID` of the delete root is (D1). Any other key,
+ * including `version` on a type that is not protected, is an unknown field. A missing id, or a missing
+ * version on a protected type, throws REQUIRED_VALUE; a version that is present but invalid is left for
+ * the OCC check inside the attempt. Returns `{ id }` or `{ id, version }`, which are new objects.
+ */
+export const readDeleteTarget = (value, { protectedType, path = 'input' } = {}) => {
+  if (value === undefined || value === null) throw requiredValueError(path);
+  if (!isPlainObject(value)) throw invalidInputError(path, EXPECTED_OBJECT);
+  const state = createWalkState({});
+  let id;
+  let version;
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key === 'symbol') throw invalidInputError(path, HIDDEN_PROPERTY);
+    const keyPath = `${path}.${key}`;
+    const item = dataProperty(value, key, keyPath);
+    if (item === undefined) continue;
+    if (key !== 'id' && !(key === 'version' && protectedType)) throw invalidInputError(keyPath, UNKNOWN_FIELD);
+    if (item === null) throw requiredValueError(keyPath);
+    if (key === 'id') {
+      assertRecordKey(item, 'string', keyPath);
+      id = item;
+    } else {
+      version = copyData(item, keyPath, state, new Map());
+    }
+  }
+  if (id === undefined) throw requiredValueError(`${path}.id`);
+  if (!protectedType) return { id };
+  if (version === undefined) throw requiredValueError(`${path}.version`);
+  return { id, version };
+};

package/src/query-frames.js

@@ -6,7 +6,10 @@ import { isVirtualField } from './relation-storage.js';
 import {
   describeEmptiness, describeModelEmptiness, emptinessScopePaths, graphqlStep, isEmptinessOperator, modelStep,
 } from './query-emptiness.js';
-import { isQueryOperator, textQueryOperator, validateTextFilterValue } from './query-operators.js';
+import {
+  assertContainsAllPath, isQueryOperator, takesListValue, textQueryOperator, validateContainsAllValue, validateTextFilterValue,
+  validateTextListFilterValue,
+} from './query-operators.js';
 import { collectQueryOperators, validateQueryGroupKeys } from './query-plan.js';
 import { getQueryMaxFrameNesting } from './query-limits.js';
 
@@ -281,18 +284,25 @@ const validateShapes = (args) => {
 };
 const validateValue = (entry, resolved, ctx) => {
   const { operator, value } = entry;
+  const scalar = resolved.steps.at(-1).scalar;
   // GraphQL compilers historically report the text operator's own type/value diagnostic.
   // Model planning retains its generic scalar-shape checks before text validation.
   if (ctx.gqltype && textQueryOperator(operator)) {
-    validateTextFilterValue(operator, value, resolved.steps.at(-1).scalar, entry.path);
+    validateTextFilterValue(operator, value, scalar, entry.path);
+    return;
+  }
+  if (ctx.gqltype && operator === 'IIN') {
+    validateTextListFilterValue(operator, value, scalar, entry.path);
     return;
   }
-  const array = ['IN', 'NIN', 'BTW'].includes(operator);
+  const array = takesListValue(operator);
   if (value === undefined || (!array && Array.isArray(value)) || (value === null && !['EQ', 'NE'].includes(operator))) fail('Expected a scalar filter value');
   if (array && Array.isArray(value) && value.some((item) => item == null || Array.isArray(item))) fail('Filter lists require non-null scalar elements');
   if (array && !Array.isArray(value)) fail(`${operator} requires an array value`);
   if (operator === 'BTW' && value.length !== 2) fail('BTW requires two values');
-  if (textQueryOperator(operator)) validateTextFilterValue(operator, value, resolved.steps.at(-1).scalar, entry.path);
+  if (operator === 'CONTAINS_ALL') validateContainsAllValue(value);
+  if (textQueryOperator(operator)) validateTextFilterValue(operator, value, scalar, entry.path);
+  if (operator === 'IIN') validateTextListFilterValue(operator, value, scalar, entry.path);
 };
 /** Internal: check sort shape and path syntax without resolving or authorizing model fields. */
 export const assertSortSyntax = (sort) => {
@@ -407,6 +417,32 @@ export const validateQuantifiedGroups = (args, ctx) => {
     if (entry.form === 'quantified') {
       if (!implicit && (steps.slice(0, -1).some((step) => ['collection', 'embeddedList'].includes(step.kind))
         || !['reference', 'collection', 'embeddedList'].includes(last.kind))) fail('A quantified path must end at a relation without crossing a list', 'INVALID_FILTER_PATH');
+      // A hand-built anchor (#108 part 4) is first a non-empty array of single path segments, before the path rule,
+      // which counts the anchor's steps by its elements; list() reads any other present value as [].
+      const anchored = implicit && entry.construct.__anchor != null;
+      if (anchored && (!anchor.length || anchor.some((name) => typeof name !== 'string' || name.includes('.')))) {
+        fail('An implicit quantified anchor must name the aggregate\'s join prefixes', 'INVALID_FILTER_PATH');
+      }
+      // A hand-built implicit group, whatever its operators (#108 part 4): after any anchor, its path ends at a collection,
+      // whatever it crosses first, or at a reference without crossing a list, the explicit groups' rule for references.
+      if (implicit && last.kind !== 'collection' && (last.kind !== 'reference'
+        || steps.slice(anchor.length, -1).some((step) => ['collection', 'embeddedList'].includes(step.kind)))) {
+        fail('An implicit quantified path must end at a collection, or at a reference without crossing a list', 'INVALID_FILTER_PATH');
+      }
+      // Then the shape the rewrite writes (cutAt): in an aggregate, on a group at the root, an anchor that crosses at
+      // least one collection, every one a J prefix, with any embedded lists, embedded objects and references between,
+      // and after it one step, a collection.
+      if (anchored) {
+        const prefixes = ctx.J ?? new Set();
+        const crossed = steps.slice(0, anchor.length);
+        const prefix = (index) => crossed.slice(0, index + 1).map(({ name }) => name).join('.');
+        if (ctx.operation !== 'aggregate' || entry.frames.length
+          || !crossed.some((step) => step.kind === 'collection')
+          || crossed.some((step, index) => step.kind === 'collection' && !prefixes.has(prefix(index)))
+          || partsOf(entry.construct.path).length !== 1 || last.kind !== 'collection') {
+          fail('An implicit quantified anchor must name the aggregate\'s join prefixes', 'INVALID_FILTER_PATH');
+        }
+      }
       if (!implicit && !QUANTIFIERS.has(entry.quantifier)) fail('Unknown quantifier', 'INVALID_FILTER_VALUE');
       if (!implicit) gates.push(() => {
         if (ctx.quantifiers !== true || last.kind === 'embeddedList') fail('Quantified groups are not supported by this query compiler', 'UNSUPPORTED_QUERY');
@@ -420,11 +456,10 @@ export const validateQuantifiedGroups = (args, ctx) => {
         if (!valueLeaf(last, current)) fail(ordinaryCondition && steps.length === 1
           ? `Filter on object field "${last.name}" requires a path` : 'Filter on object field requires a scalar path',
         steps.length > 1 ? 'INVALID_FILTER_PATH' : 'MISSING_FILTER_PATH');
-        // CONTAINS_ALL has no semantics in this release; its excluded shorthand form has
-        // the permanent path error specified for it, while every other use stays unknown.
-        if (entry.operator === 'CONTAINS_ALL' && steps.slice(0, -1).some((step) => step.kind === 'collection')) fail('The shorthand excludes them; use an explicit group', 'INVALID_FILTER_PATH');
         if (!isQueryOperator(entry.operator)) fail(`Unknown filter operator: ${entry.operator}`, 'INVALID_FILTER_OPERATOR');
         if (ctx.operators && !ctx.operators.has(entry.operator)) fail(`The ${entry.operator} filter operator is not supported by this query compiler`, 'UNSUPPORTED_QUERY');
+        // CONTAINS_ALL's permanent path rules, then its leaf rule (#108 section 3.3), on the frame-relative path.
+        if (entry.operator === 'CONTAINS_ALL') assertContainsAllPath(steps);
         if (current.gqltype && last.kind === 'abstract' && entry.value === undefined) fail(`Expected a scalar value for ${entry.path}`);
         validateValue(entry, resolved, current);
       }