@simtlix/simfinity-core 3.15.0 → 3.17.0

package/src/query-frames.js

@@ -1,4 +1,4 @@
-import { getNamedType, isObjectType } from 'graphql';
+import { getNamedType, isEnumType, isObjectType } from 'graphql';
 import { GROUP_KEYS, QUANTIFIED_LISTS, QUANTIFIERS } from './const/QLQuantifier.js';
 import SimfinityError from './errors/simfinity.error.js';
 import { effectiveScalarName } from './metadata.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, hasValuePath, validateComparisonOperand, validateComparisonTypes,
+} from './query-operators.js';
 import { collectQueryOperators, validateQueryGroupKeys } from './query-plan.js';
 import { getQueryMaxFrameNesting } from './query-limits.js';
 
@@ -53,13 +56,17 @@ const resolve = (path, ctx, onStep, virtualLabel, ordinaryCondition = false) =>
         fail(`Query path ${label} uses the virtual field ${current.gqltype.name}.${name}, which is not stored`, 'INVALID_FILTER_FIELD');
       }
       step = graphqlStep(name, field);
-      step.scalar = effectiveScalarName(getNamedType(field.type));
+      const type = getNamedType(field.type);
+      step.scalar = isEnumType(type) ? 'Enum' : effectiveScalarName(type);
+      step.enumName = isEnumType(type) ? type.name : undefined;
+      step.temporalName = ['Date', 'Time', 'DateTime'].includes(step.scalar) ? step.scalar : undefined;
+      step.version = step.scalar === 'RecordVersion' || step.scalar === 'Version';
       raw.push(field);
     } else {
       const fields = current.fields ?? current.models?.entities.find((entity) => entity.name === current.entity)?.fields;
       const field = fields?.find((item) => item.name === name && !item.private);
       if (!field) fail(`Unknown field ${parts.slice(0, index + 1).join('.')}`, 'INVALID_FILTER_FIELD');
-      step = { ...modelStep(field), scalar: field.scalar };
+      step = { ...field, ...modelStep(field) };
       if (relation(step)) step.node = ctx.models?.entities.find((entity) => entity.name === step.target)?.fields;
       raw.push(field);
     }
@@ -71,6 +78,24 @@ const resolve = (path, ctx, onStep, virtualLabel, ordinaryCondition = false) =>
   return { steps, raw, end: current };
 };
 
+const comparisonDescriptor = (resolved) => {
+  const last = resolved.steps.at(-1);
+  const previous = resolved.steps.at(-2);
+  return { ...last, list: last.kind === 'scalarList', identity: ['id', '_id'].includes(last.name)
+    && (!previous || relation(previous)), version: last.version || ['Version', 'RecordVersion'].includes(last.scalar) };
+};
+const operandContext = (entry, ctx, up) => inFrames({ frames: entry.frames.slice(0, entry.frames.length - up) }, ctx);
+const validateInternalOperand = (entry) => {
+  const operand = entry.operand;
+  if (operand === undefined) return;
+  if (!plain(operand) || !Number.isSafeInteger(operand.up) || operand.up <= 0 || operand.up > entry.frames.length
+    || entry.frames.slice(-operand.up).some((frame) => frame.construct.__implicit !== true)
+    || !Array.isArray(operand.path) || !operand.path.length
+    || operand.path.some((part) => typeof part !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part))
+    || Object.keys(operand).some((key) => !['up', 'path', 'scopes'].includes(key)) || entry.hasValuePath || entry.value !== undefined) {
+    fail('Invalid compiler-generated comparison operand', 'INVALID_FILTER_PATH');
+  }
+};
 const inFrames = (entry, ctx) => {
   let current = ctx;
   for (const frame of entry.frames) {
@@ -121,6 +146,13 @@ const cutAt = (resolved, J) => {
   }
   return null;
 };
+const comparisonInGroup = (group, seen = new Set()) => {
+  if (seen.has(group)) return false;
+  seen.add(group);
+  return list(group.conditions).some((condition) => hasValuePath(condition) || condition.__operand !== undefined)
+    || ['AND', 'OR', ...QUANTIFIED_LISTS].some((key) => list(group[key]).some((child) => comparisonInGroup(child, seen)));
+};
+const comparisonKeys = (resolved) => resolved.steps.flatMap((step, index, steps) => relation(step) ? [steps.slice(0, index + 1).map(({ name }) => name).join('.')] : []);
 const markerKeys = (resolved, J = new Set()) => {
   const cut = cutAt(resolved, J);
   const anchored = resolved.steps.some((step, index, steps) => step.kind === 'collection'
@@ -133,14 +165,25 @@ const markerKeys = (resolved, J = new Set()) => {
 const prefixScopes = (scopes, prefix, keys) => Object.fromEntries(Object.entries(scopes ?? {}).filter(([key]) => (
   keys.includes(key) && (key === prefix || prefix.startsWith(`${key}.`))
 )));
-const cutCondition = (item, rest, prefix, keys) => {
+const cutCondition = (item, rest, prefix, keys, rightKeys = []) => {
   const { __scope, ...operands } = item;
   delete operands.field;
   delete operands.path;
   const condition = { field: rest, ...operands };
+  if (item.__operand) condition.__operand = { ...item.__operand, up: item.__operand.up + 1 };
+  else if (hasValuePath(item)) {
+    if (item.valuePath.startsWith(`${prefix}.`)) condition.valuePath = item.valuePath.slice(prefix.length + 1);
+    else {
+      delete condition.valuePath;
+      condition.__operand = { up: 1, path: item.valuePath.split('.') };
+      if (hasMarker(item) && rightKeys.length) {
+        condition.__operand.scopes = Object.fromEntries(Object.entries(__scope?.scopes ?? {}).filter(([key]) => rightKeys.includes(key)));
+      }
+    }
+  }
   if (hasMarker(item)) {
     const scopes = Object.fromEntries(Object.entries(__scope?.scopes ?? {})
-      .filter(([key]) => keys.includes(key) && key.startsWith(`${prefix}.`)).map(([key, value]) => [key.slice(prefix.length + 1), value]));
+      .filter(([key]) => [...keys, ...rightKeys].includes(key) && key.startsWith(`${prefix}.`)).map(([key, value]) => [key.slice(prefix.length + 1), value]));
     if (Object.keys(scopes).length) condition.__scope = { id: __scope.id, scopes };
   }
   return condition;
@@ -182,11 +225,13 @@ export const frameCollectionPaths = (args, ctx) => {
         if (at.anchor.length) bucket.__anchor = at.anchor;
         buckets.set(prefix, bucket);
       }
-      const keys = markerKeys(resolved, J);
+      const rightResolved = hasValuePath(condition) ? resolve(condition.valuePath, frame) : null;
+      const rightKeys = rightResolved ? comparisonKeys(rightResolved) : [];
+      const keys = hasValuePath(condition) || condition.__operand ? comparisonKeys(resolved) : markerKeys(resolved, J);
       if (hasMarker(condition) && !hasMarker(bucket)) {
-        bucket.__scope = { scopes: prefixScopes(condition.__scope?.scopes, prefix, keys) };
+        bucket.__scope = { scopes: prefixScopes(condition.__scope?.scopes, prefix, [...keys, ...rightKeys]) };
       }
-      bucket.conditions.push(cutCondition(condition, resolved.steps.slice(at.index + 1).map(({ name }) => name).join('.'), prefix, keys));
+      bucket.conditions.push(cutCondition(condition, resolved.steps.slice(at.index + 1).map(({ name }) => name).join('.'), prefix, keys, rightKeys));
       return bucket;
     };
     if (Array.isArray(input.conditions)) {
@@ -226,7 +271,8 @@ export const frameCollectionPaths = (args, ctx) => {
     if (['scalar', 'scalarList'].includes(leaf.kind)) {
       // Native planner inputs may name a scalar through collections. Each entry is its own
       // correlation group; ignored terms and filter metadata never become predicates or markers.
-      const group = { conditions: [{ field: name, operator: value.operator ?? 'EQ', value: value.value }] };
+      const carrier = hasValuePath(value) ? { ...value } : { operator: value.operator ?? 'EQ', value: value.value };
+      const group = { conditions: [{ field: name, ...carrier }] };
       const rewritten = rewriteGroup(group, ctx, ctx.J ?? new Set());
       if (list(rewritten.ANY).length) {
         syntheticGroups.push({ __implicit: true, ANY: rewritten.ANY });
@@ -235,7 +281,7 @@ export const frameCollectionPaths = (args, ctx) => {
       continue;
     }
     if (!Array.isArray(value.terms) || valueLeaf(leaf, ctx)) continue;
-    const group = { conditions: value.terms.map((term) => ({ ...termCondition(term), field: pathless(term.path) ? name : `${name}.${term.path}` })) };
+    const group = { conditions: value.terms.map((term) => ({ ...termCondition(term), field: pathless(term.path) ? name : `${name}.${term.path}`, ...(hasValuePath(term) ? { valuePath: `${name}.${term.valuePath}` } : {}) })) };
     const rewritten = rewriteGroup(group, ctx, ctx.J ?? new Set());
     implicitGroups.push(...list(rewritten.ANY));
     if (rewritten.conditions.length === value.terms.length) continue;
@@ -281,18 +327,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;
   }
-  const array = ['IN', 'NIN', 'BTW'].includes(operator);
+  if (ctx.gqltype && operator === 'IIN') {
+    validateTextListFilterValue(operator, value, scalar, entry.path);
+    return;
+  }
+  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) => {
@@ -363,7 +416,8 @@ export const validateQuantifiedGroups = (args, ctx) => {
     if (ctx.gqltype && leaf.kind === 'abstract') abstractFields.add(name);
     if (value.quantifier == null && valueLeaf(leaf, ctx) && Array.isArray(value.terms) && value.operator === undefined) {
       scalarCarriers.push({ form: 'filter', field: name, path: name, relative: partsOf(name), segments: partsOf(name), frames: [],
-        operator: 'EQ', value: value.value, construct: null });
+        operator: 'EQ', value: value.value, construct: hasValuePath(value) ? value : null,
+        ...(hasValuePath(value) ? { hasValuePath: true, valuePath: value.valuePath } : {}) });
     }
     if (!valueLeaf(leaf, ctx) && value.quantifier == null) {
       if (isEmptinessOperator(value.operator)) fail(`Filter on ${name} takes ${value.operator} only in a term; to test the field itself, use a term `
@@ -386,7 +440,12 @@ export const validateQuantifiedGroups = (args, ctx) => {
   entries.push(...abstractCarriers);
   for (const entry of entries) {
     if (ignoredValueTerm(entry, ctx)) continue;
+    if (entry.hasValuePath) validateComparisonOperand(entry.construct);
+    validateInternalOperand(entry);
+    const comparison = entry.hasValuePath || entry.operand !== undefined;
     const current = inFrames(entry, ctx);
+    let rightResolved;
+    let rightCurrent;
     const implicit = entry.form === 'quantified' && entry.construct.__implicit === true;
     if (entry.form === 'condition' && typeof entry.field !== 'string') fail('Invalid filter path', 'INVALID_FILTER_PATH');
     if (entry.ambiguous) fail('Filter condition cannot use both dotted field syntax and a separate path', 'AMBIGUOUS_FILTER_FIELD');
@@ -407,12 +466,70 @@ 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');
       });
     } else {
-      if (isEmptinessOperator(entry.operator)) {
+      if (comparison) {
+        rightCurrent = entry.operand ? operandContext(entry, ctx, entry.operand.up) : current;
+        const rightPath = entry.operand?.path ?? partsOf(entry.valuePath);
+        rightResolved = resolve(rightPath, rightCurrent);
+        if (!['scalar', 'scalarList'].includes(last.kind) || !['scalar', 'scalarList'].includes(rightResolved.steps.at(-1).kind)) {
+          fail('Field comparison operands must end in scalar fields', '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');
+        const collections = new Set(steps.flatMap((step, index) => step.kind === 'collection' ? [steps.slice(0, index + 1).map(({ name }) => name).join('.')] : []));
+        if (entry.operand) {
+          const chain = entry.frames.slice(entry.frames.length - entry.operand.up)
+            .flatMap((frame) => [...list(frame.construct.__anchor), ...partsOf(frame.path)]);
+          const bound = resolve([...chain, ...path], rightCurrent).steps;
+          for (const [index, step] of bound.entries()) if (step.kind === 'collection') {
+            const key = bound.slice(0, index + 1).map(({ name }) => name).join('.');
+            if (ctx.J?.has(key) && entry.operand.up === entry.frames.length) collections.add(key);
+          }
+        }
+        if (rightResolved.steps.some((step, index, right) => step.kind === 'collection'
+          && !collections.has(right.slice(0, index + 1).map(({ name }) => name).join('.')))) {
+          fail('The right operand introduces an unbound collection; use an explicit group', 'INVALID_FILTER_PATH');
+        }
+        validateComparisonTypes(comparisonDescriptor(resolved), comparisonDescriptor(rightResolved), entry.operator, path.join('.'), rightPath.join('.'));
+        gates.push(() => {
+          if ([...steps, ...rightResolved.steps].some((step) => step.kind === 'embeddedList')) fail('Field comparisons through embedded lists require element frames', 'UNSUPPORTED_QUERY');
+          if (ctx.valuePath !== true || ctx.referenceEmptiness !== true) fail('Field comparisons require valuePath and referenceEmptiness support from this query compiler', 'UNSUPPORTED_QUERY');
+          const J = entry.frames.length ? new Set() : ctx.J ?? new Set();
+          if (ctx.quantifiers !== true && steps.some((step, index) => step.kind === 'collection' && !J.has(steps.slice(0, index + 1).map(({ name }) => name).join('.')))) {
+            fail('Collection field comparisons require quantifiers', 'UNSUPPORTED_QUERY');
+          }
+        });
+      } else if (isEmptinessOperator(entry.operator)) {
         if (ctx.operators && !ctx.operators.has(entry.operator)) fail(`The ${entry.operator} filter operator is not supported by this query compiler`, 'UNSUPPORTED_QUERY');
         if (ctx.quantifiers === true && steps.slice(0, -1).some((step) => step.kind === 'collection')) fail('The shorthand excludes them; use an explicit group', 'INVALID_FILTER_PATH');
         shape = describe(resolved, path, current, entry.operator, entry.value);
@@ -420,15 +537,22 @@ 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);
       }
     }
+    if (entry.operand && ctx.scopeMarkers !== 'pending' && (entry.operand.scopes !== undefined
+      || hasMarker(entry.construct))) markers.push(() => {
+      // An outer binding can still read a collection row owned by aggregate J.
+      const keys = comparisonKeys(rightResolved);
+      const scopes = entry.operand.scopes;
+      if (keys.length && (!plain(scopes) || keys.some((key) => !Object.hasOwn(scopes, key) || scopes[key] === undefined))) detached('Outer operand scope marker is not filled for every crossing');
+      if (!keys.length && scopes !== undefined) detached('Outer operand scope marker reads no reference or collection');
+    });
     const J = entry.frames.length ? new Set() : ctx.J ?? new Set();
     const extra = entry.form === 'quantified' ? 1 : shape ? (emptinessScopePaths(shape, path).frames.length ? 1 : 0) : ctx.quantifiers === true ? steps.filter((step, index) => step.kind === 'collection'
       && !J.has(steps.slice(0, index + 1).map(({ name }) => name).join('.'))).length : 0;
@@ -437,7 +561,7 @@ export const validateQuantifiedGroups = (args, ctx) => {
     });
     if (hasMarker(entry.construct) && ctx.scopeMarkers !== 'pending') markers.push(() => {
       const suffix = '; only the runtime writes and fills client scope markers (docs/guide/middleware.md)';
-      if (!shape && entry.form !== 'quantified' && !entry.frames.length
+      if (!comparison && !shape && entry.form !== 'quantified' && !entry.frames.length
         && (ctx.quantifiers !== true || !cutAt(resolved, ctx.J ?? new Set()))) {
         // Mongo rejects these at its native predicate checkpoint, after parsing/casting once.
         // Every other caller remains fail-closed here, after the common 400 gates above.
@@ -449,6 +573,9 @@ export const validateQuantifiedGroups = (args, ctx) => {
         const paths = emptinessScopePaths(shape, path);
         keys = [...paths.joins, ...paths.frames];
       } else keys = markerKeys(resolved, !entry.frames.length && (implicit || entry.form !== 'quantified') ? ctx.J ?? new Set() : new Set());
+      if (comparison) keys = [...new Set([...comparisonKeys(resolved), ...(!entry.operand ? comparisonKeys(rightResolved) : [])])];
+      const comparisonAnchor = implicit && anchor.length && comparisonInGroup(entry.construct);
+      if (comparisonAnchor) keys = comparisonKeys(resolved);
       const scopes = entry.construct.__scope?.scopes;
       if (shape) {
         // Preserve 2b's direct-compiler diagnostics when the shared validator now runs first.
@@ -461,7 +588,7 @@ export const validateQuantifiedGroups = (args, ctx) => {
         for (const [index, step] of steps.slice(0, anchor.length).entries()) {
           const key = steps.slice(0, index + 1).map(({ name }) => name).join('.');
           if ((step.kind === 'collection' && scopes[key] !== null)
-            || (step.kind === 'reference' && Object.hasOwn(scopes, key))) detached('Aggregate anchors require null J scopes and legacy reference joins');
+            || (step.kind === 'reference' && !comparisonAnchor && Object.hasOwn(scopes, key))) detached('Aggregate anchors require null J scopes and legacy reference joins');
         }
       }
     });
@@ -482,6 +609,7 @@ export const frameUnits = (args, ctx) => {
     return identities.get(construct);
   };
   const frameKey = (entry) => entry.frames.reduce((key, frame) => `${key}/${id(frame.construct)}:${frame.type}:${frame.path}`, 'root');
+  const joinUnit = (frame, path, scoped) => `join:${frame}:${path}${scoped ? ':scoped' : ''}`;
   for (const entry of collectQueryOperators(rewritten, ctx.operation)) {
     if (ignoredValueTerm(entry, ctx)) continue;
     const current = inFrames(entry, ctx);
@@ -492,18 +620,24 @@ export const frameUnits = (args, ctx) => {
       const path = entry.relative;
       const { steps } = resolve(path, current);
       for (const [index, step] of steps.entries()) {
-        if (index >= anchor.length && index < steps.length - 1 && step.kind === 'reference') {
-          units.add(`join:${frame}:${steps.slice(0, index + 1).map(({ name }) => name).join('.')}`);
+        if ((index >= anchor.length || comparisonInGroup(entry.construct)) && index < steps.length - 1 && step.kind === 'reference') {
+          units.add(joinUnit(frame, steps.slice(0, index + 1).map(({ name }) => name).join('.'), hasMarker(entry.construct)));
         }
       }
     } else if (isEmptinessOperator(entry.operator)) {
       const resolved = resolve(entry.relative, current);
       const shape = describe(resolved, entry.relative, current, entry.operator, entry.value);
       const paths = emptinessScopePaths(shape, entry.relative);
-      for (const path of paths.joins) units.add(`join:${frame}:${path}`);
+      for (const path of paths.joins) units.add(joinUnit(frame, path, hasMarker(entry.construct)));
       for (const path of paths.frames) units.add(`emptiness-frame:${frame}:${path}`);
-    } else if (entry.frames.length) {
-      for (const path of crossingKeys(entry.relative, current)) units.add(`join:${frame}:${path}`);
+    } else if (entry.frames.length || entry.hasValuePath || entry.operand) {
+      for (const path of crossingKeys(entry.relative, current)) units.add(joinUnit(frame, path, hasMarker(entry.construct)));
+      if (entry.hasValuePath) for (const path of crossingKeys(entry.valuePath, current)) units.add(joinUnit(frame, path, hasMarker(entry.construct)));
+      if (entry.operand) {
+        const outer = operandContext(entry, ctx, entry.operand.up);
+        const owner = frameKey({ frames: entry.frames.slice(0, entry.frames.length - entry.operand.up) });
+        for (const path of crossingKeys(entry.operand.path, outer)) units.add(joinUnit(owner, path, Object.hasOwn(entry.operand, 'scopes')));
+      }
     }
   }
   return { count: units.size, units: [...units] };

package/src/query-operators.js

@@ -1,10 +1,11 @@
 import QLOperator from './const/QLOperator.js';
 import SimfinityError from './errors/simfinity.error.js';
 
-// Internal: the filter operators and the value rules every backend applies to them. They are shared
-// by the core runtime, the query plan and the MongoDB compiler through the
-// `./internal/query-operators` subpath, which is not public API. The emptiness operators live in
-// query-emptiness.js and are re-exported here, so the subpath stays the only one.
+// Internal: the filter operators and the value rules every backend applies to them, and the path
+// and leaf rules of the list operator CONTAINS_ALL (#108, part 4). They are shared by the core
+// runtime, the query plan and the backend compilers through the `./internal/query-operators`
+// subpath, which is not public API. The emptiness operators live in query-emptiness.js and are
+// re-exported here, so the subpath stays the only one.
 
 export {
   EMPTINESS_QUERY_OPERATORS, describeEmptiness, describeModelEmptiness, emptinessMemberPaths, emptinessScopePaths,
@@ -13,6 +14,7 @@ export {
 export {
   ANCHOR_KEY, GROUP_KEYS, IMPLICIT_KEY, aggregateJoinPrefixes, crossingKeys, frameCollectionPaths, frameUnits, validateQuantifiedGroups,
 } from './query-frames.js';
+export { hasValuePath, validateComparisonOperand, validateComparisonTypes } from './query-comparisons.js';
 export { effectiveScalarName } from './metadata.js';
 
 /** Every `QLOperator` value, in declaration order. QLOperator is the only list of operators. */
@@ -28,7 +30,9 @@ export const LEGACY_QUERY_OPERATORS = Object.freeze(['EQ', 'NE', 'LT', 'LTE', 'G
  * The literal text operators (#108, part 1) and what each one matches: `contains`, `prefix`,
  * `suffix` or `exact` (the whole value), respecting case or ignoring it (`ignoreCase`). Values are
  * literal: `%`, `_`, `.`, `*`, `\`, `^`, `$` and `(` match themselves. `LIKE`, the case-sensitive
- * substring of 3.7.0, keeps its own validation and compilation and is not listed here.
+ * substring of 3.7.0, keeps its own validation and compilation and is not listed here. Neither is
+ * `IIN` (#108, part 4), `IN` ignoring case: it takes a list of such values, which
+ * {@link validateTextListFilterValue} checks.
  */
 export const TEXT_QUERY_OPERATORS = Object.freeze({
   ILIKE: Object.freeze({ match: 'contains', ignoreCase: true }),
@@ -66,26 +70,107 @@ export const validateTextFilterValue = (operator, value, scalar, path) => {
   return value;
 };
 
+/** The operators whose value is an array: IN, NIN and BTW (3.7.0), CONTAINS_ALL and IIN (#108 part 4). */
+export const LIST_VALUE_OPERATORS = Object.freeze(['IN', 'NIN', 'BTW', 'CONTAINS_ALL', 'IIN']);
+
+/** Whether `operator` takes an array value. */
+export const takesListValue = (operator) => LIST_VALUE_OPERATORS.includes(operator);
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+/**
+ * Validates the value of CONTAINS_ALL (#108 section 3.3) before any backend compiles it: a non-empty array of
+ * non-null scalars, none of them an array or a plain object. Anything else fails with INVALID_FILTER_VALUE (400).
+ * Returns the value unchanged: the compilers cast each element as they cast IN elements, and keep duplicates.
+ */
+export const validateContainsAllValue = (value) => {
+  if (value === undefined || value === null) invalidValue('Expected a scalar filter value');
+  // Array.from reads a hole of a sparse array as undefined; `some` would skip it.
+  if (Array.isArray(value) && Array.from(value).some((item) => item == null || Array.isArray(item) || isPlainObject(item))) {
+    invalidValue('Filter lists require non-null scalar elements');
+  }
+  if (!Array.isArray(value)) invalidValue('CONTAINS_ALL requires an array value');
+  if (!value.length) invalidValue('CONTAINS_ALL requires a non-empty list');
+  return value;
+};
+
+/**
+ * Validates the value of IIN, IN ignoring case, before any backend compiles it: the field must be a `String` field
+ * or a `String` list by its effective scalar, as for IEQ, and the value an array of strings without U+0000; the
+ * empty array is valid and matches nothing. Anything else fails with INVALID_FILTER_VALUE (400). Returns the value
+ * unchanged: it is neither folded nor deduplicated.
+ */
+export const validateTextListFilterValue = (operator, value, scalar, path) => {
+  const where = path == null ? '' : ` on ${Array.isArray(path) ? path.join('.') : path}`;
+  if (scalar !== 'String') invalidValue(`${operator} requires a String field${where}`);
+  if (!Array.isArray(value)) invalidValue(`${operator} requires an array value${where}`);
+  // Array.from reads a hole of a sparse array as undefined; `some` would skip it.
+  const items = Array.from(value);
+  if (items.some((item) => typeof item !== 'string')) invalidValue(`${operator} requires non-null string elements${where}`);
+  if (items.some((item) => item.includes('\u0000'))) invalidValue(`${operator} values cannot contain U+0000${where}`);
+  return value;
+};
+
+const failPath = (message, code) => { throw new SimfinityError(message, code, 400); };
+// The validator's steps (graphqlStep, modelStep) and resolveModelPath's field descriptions, read alike.
+const stepKind = (step) => {
+  if (step.kind === 'embedded') return step.list ? 'embeddedList' : 'embedded';
+  if (step.kind === 'scalar') return step.list ? 'scalarList' : 'scalar';
+  if (step.kind === 'reference' && step.inferred) return 'scalar';
+  return step.kind;
+};
+
+/**
+ * The permanent path and leaf rules of CONTAINS_ALL (#108 section 3.3), on the steps of a path relative to its
+ * frame: the path ends at a value, as for every operator (MISSING_FILTER_PATH for one segment, INVALID_FILTER_PATH
+ * otherwise; the validator has applied this rule already, and PostgreSQL's hand-built plans get core's codes from
+ * it), no collection is crossed (INVALID_FILTER_PATH, which the shorthand's exclusion states), no reference follows
+ * an embedded list (INVALID_FILTER_PATH: that join yields one referenced record per row), and the leaf is a list: a
+ * scalar list, or a scalar reached through an embedded list (INVALID_FILTER_OPERATOR otherwise).
+ */
+export const assertContainsAllPath = (steps) => {
+  const kinds = steps.map(stepKind);
+  const names = steps.map(({ name }) => name);
+  // Core's object-end rule first (query-frames.js:420-422), so that every caller gets core's codes in core's order.
+  if (['embedded', 'embeddedList', 'reference', 'collection'].includes(kinds.at(-1))) {
+    failPath('Filter on object field requires a scalar path', steps.length > 1 ? 'INVALID_FILTER_PATH' : 'MISSING_FILTER_PATH');
+  }
+  const crossed = kinds.slice(0, -1);
+  if (crossed.includes('collection')) failPath('The shorthand excludes them; use an explicit group', 'INVALID_FILTER_PATH');
+  const list = crossed.indexOf('embeddedList');
+  const reference = list === -1 ? -1 : crossed.findIndex((kind, index) => index > list && kind === 'reference');
+  if (reference !== -1) {
+    failPath(`CONTAINS_ALL cannot cross the reference ${names.slice(0, reference + 1).join('.')} inside an embedded list, which joins one referenced record per row; combine EQ conditions on the path instead`, 'INVALID_FILTER_PATH');
+  }
+  const leaf = kinds.at(-1);
+  if (leaf !== 'scalarList' && !(leaf === 'scalar' && list !== -1)) {
+    failPath(`CONTAINS_ALL requires a list field, or a field reached through an embedded list; ${names.join('.')} is not one`, 'INVALID_FILTER_OPERATOR');
+  }
+};
+
 const invalidFeatures = (message) => {
   throw new SimfinityError(`DatabaseAdapter queryFeatures ${message}`, 'INVALID_QUERY_FEATURES', 500);
 };
 
 /**
- * Reads an adapter's `queryFeatures` declaration into `{ operators, referenceEmptiness, quantifiers }`:
+ * Reads an adapter's `queryFeatures` declaration into `{ operators, referenceEmptiness, quantifiers, valuePath }`:
  * the operators it compiles and whether it compiles reference emptiness and collection frames.
  * Without a declaration (undefined or null) the adapter supports {@link LEGACY_QUERY_OPERATORS}
  * and neither feature. A declaration is an object whose `operators`
  * is an array of operator names, whose names this version does not know are ignored, and whose
- * optional `referenceEmptiness` and `quantifiers` are booleans, undefined or null (false).
- * Quantifiers require reference emptiness for scoped joins. Other members are left for later
+ * optional `referenceEmptiness`, `quantifiers` and `valuePath` are booleans, undefined or null (false). A name
+ * counts once this version knows it: a declaration that listed `CONTAINS_ALL` or `IIN` before
+ * #108 part 4 added them receives them on upgrade.
+ * Quantifiers and valuePath require reference emptiness for scoped joins. Other members are left for later
  * features. Anything else throws `INVALID_QUERY_FEATURES` (500).
  */
 export const resolveQueryFeatures = (queryFeatures) => {
-  if (queryFeatures == null) return { operators: new Set(LEGACY_QUERY_OPERATORS), referenceEmptiness: false, quantifiers: false };
+  if (queryFeatures == null) return { operators: new Set(LEGACY_QUERY_OPERATORS), referenceEmptiness: false, quantifiers: false, valuePath: false };
   if (typeof queryFeatures !== 'object' || Array.isArray(queryFeatures)) {
     invalidFeatures('must be an object with an operators array');
   }
-  const { operators, referenceEmptiness, quantifiers } = queryFeatures;
+  const { operators, referenceEmptiness, quantifiers, valuePath } = queryFeatures;
   if (!Array.isArray(operators) || operators.some((operator) => typeof operator !== 'string')) {
     invalidFeatures('operators must be an array of operator names');
   }
@@ -98,9 +183,12 @@ export const resolveQueryFeatures = (queryFeatures) => {
   if (quantifiers === true && referenceEmptiness !== true) {
     invalidFeatures('quantifiers require referenceEmptiness: true');
   }
+  if (valuePath != null && typeof valuePath !== 'boolean') invalidFeatures('valuePath must be a boolean');
+  if (valuePath === true && referenceEmptiness !== true) invalidFeatures('valuePath requires referenceEmptiness: true');
   return {
     operators: new Set(operators.filter(isQueryOperator)),
     referenceEmptiness: referenceEmptiness === true,
     quantifiers: quantifiers === true,
+    valuePath: valuePath === true,
   };
 };