@simtlix/simfinity-core 3.16.0 → 3.18.0

package/src/query-frames.js

@@ -1,17 +1,16 @@
 import { getNamedType, 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';
-import { isVirtualField } from './relation-storage.js';
 import {
-  describeEmptiness, describeModelEmptiness, emptinessScopePaths, graphqlStep, isEmptinessOperator, modelStep,
+  describeEmptiness, describeModelEmptiness, emptinessScopePaths, isEmptinessOperator,
 } from './query-emptiness.js';
 import {
   assertContainsAllPath, isQueryOperator, takesListValue, textQueryOperator, validateContainsAllValue, validateTextFilterValue,
-  validateTextListFilterValue,
+  validateTextListFilterValue, hasValuePath, validateComparisonOperand, validateComparisonTypes,
 } from './query-operators.js';
 import { collectQueryOperators, validateQueryGroupKeys } from './query-plan.js';
 import { getQueryMaxFrameNesting } from './query-limits.js';
+import { enterQueryFrame, parentScopePrefix, resolveComparisonContext, resolveContainerContext, resolveQueryContext } from './query-context.js';
 
 export { GROUP_KEYS };
 export const IMPLICIT_KEY = '__implicit';
@@ -28,57 +27,34 @@ const controls = (operation) => new Set(['AND', 'OR', 'sort', 'pagination', ...(
 const hasMarker = (value) => object(value) && Object.hasOwn(value, '__scope');
 const nonemptyPath = (path) => typeof path === 'string' && path.length > 0;
 const partsOf = (path) => (Array.isArray(path) ? path : typeof path === 'string' ? path.split('.') : []);
-const childContext = (ctx, step) => (ctx.gqltype
-  ? { ...ctx, gqltype: step.node }
-  : { ...ctx, entity: step.target ?? ctx.entity, fields: step.node });
+const resolve = (path, ctx, onStep, virtualLabel, ordinaryCondition = false) => resolveQueryContext(path, ctx, { onStep, virtualLabel, ordinaryCondition });
 
-// One schema-path resolver for these operations, using the same step classifications as emptiness.
-// Model contexts retain embedded fields locally; relation steps switch to the target entity.
-const resolve = (path, ctx, onStep, virtualLabel, ordinaryCondition = false) => {
-  const parts = partsOf(path);
-  const invalid = parts.findIndex((part) => typeof part !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part));
-  if (!parts.length || invalid !== -1) {
-    if (ordinaryCondition && invalid > 0) fail(`Invalid filter path segment: "${parts[invalid]}"`, 'INVALID_FILTER_PATH');
-    fail('Invalid filter path', 'INVALID_FILTER_PATH');
-  }
-  let current = ctx;
-  const steps = [];
-  const raw = [];
-  for (const [index, name] of parts.entries()) {
-    let step;
-    if (ctx.gqltype) {
-      const fields = isObjectType(current.gqltype) ? current.gqltype.getFields() : null;
-      const field = fields && Object.hasOwn(fields, name) ? fields[name] : null;
-      if (!field) fail(ordinaryCondition && index === 0 ? `Unknown filter field: ${name}`
-        : `Unknown field ${parts.slice(0, index + 1).join('.')}`, 'INVALID_FILTER_FIELD');
-      if (isVirtualField(field)) {
-        const label = virtualLabel?.(field) ?? parts.join('.');
-        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));
-      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 };
-      if (relation(step)) step.node = ctx.models?.entities.find((entity) => entity.name === step.target)?.fields;
-      raw.push(field);
-    }
-    onStep?.(step, current);
-    steps.push(step);
-    if (index < parts.length - 1 && !step.node) fail(`Field ${name} cannot be traversed`, 'INVALID_FILTER_PATH');
-    current = childContext(current, step);
+const comparisonDescriptor = (resolved, context) => {
+  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) : !context.parent), 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, current) => {
+  const operand = entry.operand;
+  if (operand === undefined) return;
+  const structural = operand?.container !== undefined;
+  if (!plain(operand) || !Number.isSafeInteger(operand.up)
+    || (structural ? operand.up !== 0 : 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', 'container'].includes(key)) || entry.hasValuePath || entry.value !== undefined) {
+    fail('Invalid compiler-generated comparison operand', 'INVALID_FILTER_PATH');
   }
-  return { steps, raw, end: current };
+  if (structural) resolveContainerContext(operand.container, current);
 };
-
 const inFrames = (entry, ctx) => {
   let current = ctx;
   for (const frame of entry.frames) {
     const anchor = frame.construct.__implicit === true ? list(frame.construct.__anchor) : [];
-    current = resolve([...anchor, ...partsOf(frame.path)], current).end;
+    current = enterQueryFrame(current, [...anchor, ...partsOf(frame.path)]);
   }
   return current;
 };
@@ -113,17 +89,24 @@ export const aggregateJoinPrefixes = (aggregation, ctx) => {
 };
 
 // The first non-J collection and its optional legacy-join anchor. J is supplied only at the root.
-const cutAt = (resolved, J) => {
+const cutAt = (resolved, J, elements = false) => {
   let joined = false;
   for (const [index, step] of resolved.steps.entries()) {
-    if (step.kind !== 'collection') continue;
+    if (step.kind !== 'collection' && !(elements && step.kind === 'embeddedList')) continue;
     const prefix = resolved.steps.slice(0, index + 1).map(({ name }) => name);
-    if (J.has(prefix.join('.'))) { joined = true; continue; }
+    if (step.kind === 'collection' && J.has(prefix.join('.'))) { joined = true; continue; }
     const anchor = joined ? prefix.slice(0, -1) : [];
-    return { index, prefix, anchor, path: prefix.slice(anchor.length).join('.') };
+    return { index, prefix, anchor, path: prefix.slice(anchor.length).join('.'), element: step.kind === 'embeddedList' };
   }
   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'
@@ -136,14 +119,27 @@ 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.container
+    ? { ...item.__operand, container: { ...item.__operand.container, up: item.__operand.container.up + 1 } }
+    : { ...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;
@@ -153,6 +149,31 @@ const termCondition = (term) => {
   return { field: path, ...operands };
 };
 
+// Public parent syntax is resolved once at its carrier. Rewrites must retain that binding.
+const normalizeParentOperand = (item, frame, prefix = '') => {
+  if (!hasValuePath(item) || !item.valuePath.startsWith('$parent.')) return item;
+  const { container, path, resolved } = resolveComparisonContext(item.valuePath, frame, prefix);
+  const result = container.up === 0 ? { ...item, valuePath: [...container.path, ...path].join('.') }
+    : { ...item, __operand: { up: 0, path, container } };
+  if (container.up !== 0) delete result.valuePath;
+  if (!hasMarker(item)) return result;
+  const scopePrefix = parentScopePrefix(item.valuePath);
+  if (plain(item.__scope?.scopes)) {
+    const entries = Object.entries(item.__scope.scopes);
+    const parentScopes = Object.fromEntries(entries.filter(([key]) => key.startsWith(scopePrefix)).map(([key, value]) => [key.slice(scopePrefix.length), value]));
+    const localScopes = Object.fromEntries(entries.filter(([key]) => !key.startsWith(scopePrefix)));
+    if (container.up === 0) {
+      for (const [key, value] of Object.entries(parentScopes)) localScopes[[...container.path, key].join('.')] = value;
+    } else if (Object.keys(parentScopes).length) result.__operand.scopes = parentScopes;
+    if (Object.keys(localScopes).length) result.__scope = { ...item.__scope, scopes: localScopes };
+    else delete result.__scope;
+  } else if (container.up !== 0 && comparisonKeys(resolved).length) {
+    // Pending runtime provenance still counts this separately scoped outer read in the budget.
+    result.__operand.scopes = undefined;
+  }
+  return result;
+};
+
 /** Internal: pure collection-frame rewrite. The same J must be threaded through repeated passes. */
 export const frameCollectionPaths = (args, ctx) => {
   if (ctx.quantifiers !== true) return args;
@@ -172,40 +193,47 @@ export const frameCollectionPaths = (args, ctx) => {
     positions.set(position, output);
     active.set(input, output);
     const buckets = new Map();
+    const bucketKinds = new Map();
     const cut = (condition, path) => {
       const resolved = resolve(path, frame);
       const operator = condition.operator ?? 'EQ';
       if (isEmptinessOperator(operator) || operator === 'CONTAINS_ALL') return null;
-      const at = cutAt(resolved, J);
+      const at = cutAt(resolved, J, ctx.elementFrames === true && (hasValuePath(condition) || condition.__operand !== undefined));
       if (!at) return null;
       const prefix = at.prefix.join('.');
-      let bucket = buckets.get(prefix);
+      const bucketKey = at.element ? Symbol(prefix) : prefix;
+      let bucket = buckets.get(bucketKey);
       if (!bucket) {
         bucket = { path: at.path, conditions: [], __implicit: true };
         if (at.anchor.length) bucket.__anchor = at.anchor;
-        buckets.set(prefix, bucket);
+        buckets.set(bucketKey, bucket);
+        bucketKinds.set(bucket, at.element && operator === 'NE' ? 'NONE' : 'ANY');
       }
-      const keys = markerKeys(resolved, J);
-      if (hasMarker(condition) && !hasMarker(bucket)) {
-        bucket.__scope = { scopes: prefixScopes(condition.__scope?.scopes, prefix, keys) };
+      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)
+        && [...keys, ...rightKeys].some((key) => key === prefix || prefix.startsWith(`${key}.`))) {
+        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(at.element && operator === 'NE' ? { ...condition, operator: 'EQ' } : condition, resolved.steps.slice(at.index + 1).map(({ name }) => name).join('.'), prefix, keys, rightKeys));
       return bucket;
     };
     if (Array.isArray(input.conditions)) {
-      output.conditions = input.conditions.filter((item) => !cut(item, pathless(item.path) ? item.field : `${item.field}.${item.path}`));
+      output.conditions = input.conditions.map((item) => normalizeParentOperand(item, frame)).filter((item) => !cut(item, pathless(item.path) ? item.field : `${item.field}.${item.path}`));
     }
     for (const key of ['AND', 'OR']) if (Array.isArray(input[key])) output[key] = input[key].map((group) => rewriteGroup(group, frame, J, position));
     for (const type of QUANTIFIED_LISTS) if (Array.isArray(input[type])) {
       output[type] = input[type].map((group) => {
         const anchor = group.__implicit === true ? list(group.__anchor) : [];
-        return rewriteGroup(group, resolve([...anchor, ...partsOf(group.path)], frame).end, new Set(), positionOf(position, group, type, group.path));
+        return rewriteGroup(group, enterQueryFrame(frame, [...anchor, ...partsOf(group.path)]), new Set(), positionOf(position, group, type, group.path));
       });
     }
     for (const bucket of buckets.values()) {
       const path = [...list(bucket.__anchor), ...partsOf(bucket.path)];
-      const rewritten = rewriteGroup(bucket, resolve(path, frame).end, new Set(), positionOf(position, bucket, 'ANY', bucket.path));
-      output.ANY = [...list(output.ANY), rewritten];
+      const type = bucketKinds.get(bucket);
+      const rewritten = rewriteGroup(bucket, enterQueryFrame(frame, path), new Set(), positionOf(position, bucket, type, bucket.path));
+      output[type] = [...list(output[type]), rewritten];
     }
     active.delete(input);
     return output;
@@ -229,21 +257,32 @@ 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 });
+      if (QUANTIFIED_LISTS.some((key) => list(rewritten[key]).length)) {
+        syntheticGroups.push({ __implicit: true, ...Object.fromEntries(QUANTIFIED_LISTS.filter((key) => list(rewritten[key]).length).map((key) => [key, rewritten[key]])) });
         delete output[name];
       }
       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) => {
+      const parent = hasValuePath(term) && term.valuePath.startsWith('$parent.');
+      const carrier = parent ? normalizeParentOperand(term, ctx, name) : term;
+      return { ...termCondition(carrier), field: pathless(term.path) ? name : `${name}.${term.path}`,
+        ...(hasValuePath(carrier) && !parent ? { valuePath: `${name}.${carrier.valuePath}` } : {}) };
+    }) };
     const rewritten = rewriteGroup(group, ctx, ctx.J ?? new Set());
+    if (list(rewritten.NONE).length) syntheticGroups.push({ __implicit: true, NONE: rewritten.NONE });
     implicitGroups.push(...list(rewritten.ANY));
-    if (rewritten.conditions.length === value.terms.length) continue;
-    if (!rewritten.conditions.length) delete output[name];
-    else output[name] = { ...value, terms: value.terms.filter((term, index) => rewritten.conditions.includes(group.conditions[index])) };
+    const parentIndices = new Set(value.terms.flatMap((term, index) => parentScopePrefix(term.valuePath) ? [index] : []));
+    const parentConditions = group.conditions.filter((condition, index) => parentIndices.has(index) && rewritten.conditions.includes(condition));
+    if (parentConditions.length) syntheticGroups.push({ __implicit: true, conditions: parentConditions });
+    if (rewritten.conditions.length === value.terms.length && !parentIndices.size) continue;
+    const remaining = value.terms.filter((term, index) => !parentIndices.has(index) && rewritten.conditions.includes(group.conditions[index]));
+    if (!remaining.length) delete output[name];
+    else output[name] = { ...value, terms: remaining };
   }
   if (implicitGroups.length) syntheticGroups.push({ __implicit: true, ANY: implicitGroups });
   for (const key of ['AND', 'OR']) if (Array.isArray(args[key])) output[key] = args[key].map((group) => rewriteGroup(group, ctx, ctx.J ?? new Set()));
@@ -373,7 +412,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 `
@@ -396,7 +436,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);
+    const comparison = entry.hasValuePath || entry.operand !== undefined;
     const current = inFrames(entry, ctx);
+    validateInternalOperand(entry, current);
+    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');
@@ -425,7 +470,10 @@ export const validateQuantifiedGroups = (args, ctx) => {
       }
       // 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'
+      if (implicit && last.kind !== 'collection'
+        && !(ctx.elementFrames === true && last.kind === 'embeddedList' && comparisonInGroup(entry.construct)
+          && !steps.slice(anchor.length, -1).some((step) => ['collection', 'embeddedList'].includes(step.kind)))
+        && (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');
       }
@@ -439,16 +487,51 @@ export const validateQuantifiedGroups = (args, ctx) => {
         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') {
+          || partsOf(entry.construct.path).length !== 1
+          || (last.kind !== 'collection' && !(ctx.elementFrames === true && last.kind === 'embeddedList' && comparisonInGroup(entry.construct)))) {
           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');
+        if (ctx.quantifiers !== true || (last.kind === 'embeddedList' && ctx.elementFrames !== true)) fail('Quantified groups are not supported by this query compiler', 'UNSUPPORTED_QUERY');
       });
     } else {
-      if (isEmptinessOperator(entry.operator)) {
+      if (comparison) {
+        const publicOperand = entry.operand ? null : resolveComparisonContext(entry.valuePath, current, entry.valuePathPrefix);
+        rightCurrent = entry.operand?.container ? resolveContainerContext(entry.operand.container, current)
+          : entry.operand ? operandContext(entry, ctx, entry.operand.up) : publicOperand.context;
+        const rightPath = entry.operand?.path ?? publicOperand.path ?? partsOf(entry.valuePath);
+        rightResolved = entry.operand ? resolve(rightPath, rightCurrent) : publicOperand.resolved;
+        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' || (ctx.elementFrames === true && step.kind === 'embeddedList')) ? [steps.slice(0, index + 1).map(({ name }) => name).join('.')] : []));
+        if (entry.operand && !entry.operand.container) {
+          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' || (ctx.elementFrames === true && step.kind === 'embeddedList'))
+          && !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, current), comparisonDescriptor(rightResolved, rightCurrent), entry.operator, path.join('.'), rightPath.join('.'));
+        gates.push(() => {
+          if (ctx.elementFrames !== true && ([...steps, ...rightResolved.steps].some((step) => step.kind === 'embeddedList') || publicOperand?.container || entry.operand?.container)) 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);
@@ -464,15 +547,23 @@ export const validateQuantifiedGroups = (args, ctx) => {
         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'
+    const extra = entry.form === 'quantified' ? 1 : shape ? (emptinessScopePaths(shape, path).frames.length ? 1 : 0) : ctx.quantifiers === true ? steps.filter((step, index) => (step.kind === 'collection' || (ctx.elementFrames === true && comparison && step.kind === 'embeddedList'))
       && !J.has(steps.slice(0, index + 1).map(({ name }) => name).join('.'))).length : 0;
     gates.push(() => {
       if (entry.frames.length + extra > getQueryMaxFrameNesting()) fail('Frame nesting too deep (maxFrameNesting)', 'FILTER_DEPTH_EXCEEDED');
     });
     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.
@@ -484,6 +575,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).map((key) => `${parentScopePrefix(entry.valuePath)}${key}`) : [])])];
+      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.
@@ -496,7 +590,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');
         }
       }
     });
@@ -517,6 +611,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);
@@ -527,18 +622,26 @@ 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 container = entry.operand.container;
+        const up = container?.up ?? entry.operand.up;
+        const outer = operandContext(entry, ctx, up);
+        const owner = frameKey({ frames: entry.frames.slice(0, entry.frames.length - up) });
+        for (const path of crossingKeys([...(container?.path ?? []), ...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

@@ -14,6 +14,8 @@ 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 { enterQueryFrame, resolveContainerContext, resolveQueryContext } from './query-context.js';
 export { effectiveScalarName } from './metadata.js';
 
 /** Every `QLOperator` value, in declaration order. QLOperator is the only list of operators. */
@@ -153,23 +155,23 @@ const invalidFeatures = (message) => {
 };
 
 /**
- * Reads an adapter's `queryFeatures` declaration into `{ operators, referenceEmptiness, quantifiers }`:
+ * Reads an adapter's `queryFeatures` declaration into `{ operators, referenceEmptiness, quantifiers, valuePath, elementFrames }`:
  * 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). A name
+ * optional `referenceEmptiness`, `quantifiers`, `valuePath` and `elementFrames` 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 require reference emptiness for scoped joins. Other members are left for later
- * features. Anything else throws `INVALID_QUERY_FEATURES` (500).
+ * Quantifiers and valuePath require reference emptiness for scoped joins. Other members are left for later
+ * features. Element frames require all three other flags. 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, elementFrames: 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, elementFrames } = queryFeatures;
   if (!Array.isArray(operators) || operators.some((operator) => typeof operator !== 'string')) {
     invalidFeatures('operators must be an array of operator names');
   }
@@ -182,9 +184,17 @@ 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');
+  if (elementFrames != null && typeof elementFrames !== 'boolean') invalidFeatures('elementFrames must be a boolean');
+  if (elementFrames === true && (referenceEmptiness !== true || quantifiers !== true || valuePath !== true)) {
+    invalidFeatures('elementFrames requires quantifiers, referenceEmptiness and valuePath: true');
+  }
   return {
     operators: new Set(operators.filter(isQueryOperator)),
     referenceEmptiness: referenceEmptiness === true,
     quantifiers: quantifiers === true,
+    valuePath: valuePath === true,
+    elementFrames: elementFrames === true,
   };
 };