@simtlix/simfinity-core 3.17.0 → 3.19.0

package/README.md

@@ -86,3 +86,5 @@ call fails without deleting installed metadata. Migrate clients selecting
 for the format, protected HTTP access and composition limits.
 
 `queryFeatures.valuePath: true` opts an adapter into stored-field comparisons and requires `referenceEmptiness: true`; only true enables it. `valuePath` is nullable on all three generated filter inputs and is mutually exclusive with a supplied `value` (including null). Core validates both operand paths, their logical types, visibility and collection correlation, and preserves outer origins internally. `createQueryPlan` adds `operand?: QueryOperand` with `{ up, path, joins? }` and a null value placeholder; same-frame scope unions live in predicate `joins`, ancestor scopes in operand `joins`. Literal nodes stay unchanged. `describeModels` retains additive `enumName` and effective `temporalName` metadata. See [the comparison rules and limits](https://simtlix.github.io/simfinity.js/guide/queries.html#compare-stored-fields) and [compiler contract](https://simtlix.github.io/simfinity.js/guide/sql-plugins.html#query-features).
+
+Version 3.18.0 adds `queryFeatures.elementFrames: true` for embedded object `ANY`/`ALL`/`NONE` and structural `$parent` operands. It requires `quantifiers`, `referenceEmptiness` and `valuePath`, all true. Missing/null lists and null items contribute no elements; `ALL` and `NONE` are true without elements. Parent traversal includes single embedded containers and stops at entity boundaries. Filters preserve selected arrays and outer row cardinality. See [the syntax and examples](https://simtlix.github.io/simfinity.js/guide/queries.html#embedded-object-lists-and-parent); versions through 3.17.0 do not support this extension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.17.0",
+  "version": "3.19.0",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",

package/src/query-comparisons.js

@@ -14,8 +14,8 @@ export const validateComparisonOperand = (carrier) => {
   if (!hasValuePath(carrier)) return null;
   if (carrier.value !== undefined) fail('A filter cannot supply both value and valuePath');
   if (typeof carrier.valuePath !== 'string') fail('valuePath requires a string field path');
-  if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(carrier.valuePath)) {
-    fail('valuePath requires a nonempty dotted field path; outer paths require an explicit group', 'INVALID_FILTER_PATH');
+  if (!/^(?:\$parent\.)*[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(carrier.valuePath)) {
+    fail('valuePath requires a field path optionally preceded by embedded $parent prefixes', 'INVALID_FILTER_PATH');
   }
   return carrier.valuePath;
 };

package/src/query-context.js

@@ -0,0 +1,117 @@
+import { getNamedType, isEnumType, isObjectType } from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { effectiveScalarName } from './metadata.js';
+import { isVirtualField } from './relation-storage.js';
+import { graphqlStep, modelStep } from './query-emptiness.js';
+
+const fail = (message, code = 'INVALID_FILTER_PATH') => { throw new SimfinityError(message, code, 400); };
+const relation = (step) => ['reference', 'collection'].includes(step.kind);
+const partsOf = (path) => (Array.isArray(path) ? path : typeof path === 'string' ? path.split('.') : []);
+const bindingOf = (ctx) => ctx.binding ?? { depth: 0, path: [] };
+
+const childContext = (ctx, step) => ({
+  ...ctx,
+  ...(ctx.gqltype ? { gqltype: step.node } : { entity: step.target ?? ctx.entity, fields: step.node }),
+  parent: ['embedded', 'embeddedList'].includes(step.kind) ? ctx : undefined,
+  absolute: [...(ctx.absolute ?? []), step.name],
+  binding: { depth: bindingOf(ctx).depth, path: [...bindingOf(ctx).path, step.name] },
+});
+
+// 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.
+export const resolveQueryContext = (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);
+      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 = { ...field, ...modelStep(field) };
+      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);
+  }
+  return { steps, raw, end: current };
+};
+
+/** Bind the endpoint while retaining its actual structural containers. */
+export const enterQueryFrame = (context, path) => {
+  const { end } = resolveQueryContext(path, context);
+  return { ...end, frameParent: context, binding: { depth: bindingOf(context).depth + 1, path: [] } };
+};
+
+/** Resolve public comparison paths from their filter carrier, before normalization. */
+export const resolveComparisonContext = (valuePath, context, prefix = '') => {
+  const parts = partsOf(valuePath);
+  if (parts[0] !== '$parent') {
+    return { resolved: resolveQueryContext([...(prefix ? partsOf(prefix) : []), ...parts], context), context };
+  }
+  let current = prefix ? resolveQueryContext(prefix, context).end : context;
+  while (parts[0] === '$parent') {
+    if (!current.parent) fail('$parent requires an embedded containing object');
+    current = current.parent;
+    parts.shift();
+  }
+  const resolved = resolveQueryContext(parts, current);
+  const binding = bindingOf(current);
+  return { resolved, context: current, path: parts,
+    container: { up: bindingOf(context).depth - binding.depth, path: binding.path } };
+};
+
+/** A structural operand may address only one of this context's bound containers. */
+export const resolveContainerContext = (container, context) => {
+  if (!container || typeof container !== 'object' || Array.isArray(container)
+    || Object.keys(container).some((key) => !['up', 'path'].includes(key))
+    || !Number.isSafeInteger(container.up) || container.up < 0 || !Array.isArray(container.path)
+    || container.path.some((part) => typeof part !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part))) {
+    fail('Invalid embedded comparison container');
+  }
+  for (let parent = context.parent; parent; parent = parent.parent) {
+    const binding = bindingOf(parent);
+    if (bindingOf(context).depth - binding.depth === container.up
+      && binding.path.length === container.path.length && binding.path.every((part, index) => part === container.path[index])) return parent;
+  }
+  fail('Comparison container is not an embedded ancestor');
+};
+
+/** Recover a collector entry's bound context without inferring parents from dotted strings. */
+export const queryEntryContext = (entry, context) => {
+  let current = context;
+  for (const frame of entry.frames) {
+    const anchor = frame.construct.__implicit === true && Array.isArray(frame.construct.__anchor) ? frame.construct.__anchor : [];
+    current = enterQueryFrame(current, [...anchor, ...partsOf(frame.path)]);
+  }
+  return current;
+};
+
+/** Distinct marker namespace for a public parent operand before its binding is normalized. */
+export const parentScopePrefix = (valuePath) => typeof valuePath === 'string' ? valuePath.match(/^(?:\$parent\.)+/)?.[0] ?? '' : '';

package/src/query-frames.js

@@ -1,10 +1,8 @@
-import { getNamedType, isEnumType, isObjectType } from 'graphql';
+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,
@@ -12,6 +10,7 @@ import {
 } 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,79 +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);
-      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 = { ...field, ...modelStep(field) };
-      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);
-  }
-  return { steps, raw, end: current };
-};
-
-const comparisonDescriptor = (resolved) => {
+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)), version: last.version || ['Version', 'RecordVersion'].includes(last.scalar) };
+    && (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) => {
+const validateInternalOperand = (entry, current) => {
   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)
+  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'].includes(key)) || entry.hasValuePath || entry.value !== undefined) {
+    || 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');
   }
+  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;
 };
@@ -135,14 +89,14 @@ 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;
 };
@@ -170,7 +124,9 @@ const cutCondition = (item, rest, prefix, keys, rightKeys = []) => {
   delete operands.field;
   delete operands.path;
   const condition = { field: rest, ...operands };
-  if (item.__operand) condition.__operand = { ...item.__operand, up: item.__operand.up + 1 };
+  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 {
@@ -193,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;
@@ -212,42 +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 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)) {
+      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, rightKeys));
+      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;
@@ -274,19 +260,29 @@ export const frameCollectionPaths = (args, ctx) => {
       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}`, ...(hasValuePath(term) ? { valuePath: `${name}.${term.valuePath}` } : {}) })) };
+    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()));
@@ -441,9 +437,9 @@ export const validateQuantifiedGroups = (args, ctx) => {
   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);
+    validateInternalOperand(entry, current);
     let rightResolved;
     let rightCurrent;
     const implicit = entry.form === 'quantified' && entry.construct.__implicit === true;
@@ -474,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');
       }
@@ -488,26 +487,29 @@ 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 (comparison) {
-        rightCurrent = entry.operand ? operandContext(entry, ctx, entry.operand.up) : current;
-        const rightPath = entry.operand?.path ?? partsOf(entry.valuePath);
-        rightResolved = resolve(rightPath, rightCurrent);
+        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' ? [steps.slice(0, index + 1).map(({ name }) => name).join('.')] : []));
-        if (entry.operand) {
+        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;
@@ -516,13 +518,13 @@ export const validateQuantifiedGroups = (args, ctx) => {
             if (ctx.J?.has(key) && entry.operand.up === entry.frames.length) collections.add(key);
           }
         }
-        if (rightResolved.steps.some((step, index, right) => step.kind === 'collection'
+        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), comparisonDescriptor(rightResolved), entry.operator, path.join('.'), rightPath.join('.'));
+        validateComparisonTypes(comparisonDescriptor(resolved, current), comparisonDescriptor(rightResolved, rightCurrent), 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.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('.')))) {
@@ -554,7 +556,7 @@ export const validateQuantifiedGroups = (args, ctx) => {
       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');
@@ -573,7 +575,7 @@ 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) : [])])];
+      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;
@@ -634,9 +636,11 @@ export const frameUnits = (args, ctx) => {
       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')));
+        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')));
       }
     }
   }

package/src/query-operators.js

@@ -15,6 +15,7 @@ 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. */
@@ -154,23 +155,23 @@ const invalidFeatures = (message) => {
 };
 
 /**
- * Reads an adapter's `queryFeatures` declaration into `{ operators, referenceEmptiness, quantifiers, valuePath }`:
+ * 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`, `quantifiers` and `valuePath` 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 and valuePath require reference emptiness for scoped joins. Other members are left for later
- * features. Anything else throws `INVALID_QUERY_FEATURES` (500).
+ * 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, valuePath: 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, valuePath } = 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');
   }
@@ -185,10 +186,15 @@ export const resolveQueryFeatures = (queryFeatures) => {
   }
   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,
   };
 };

package/src/query-plan.js

@@ -2,6 +2,7 @@ import { GROUP_KEYS, QUANTIFIED_LISTS } from './const/QLQuantifier.js';
 import { aggregateJoinPrefixes, crossingKeys, frameCollectionPaths, validateQuantifiedGroups } from './query-frames.js';
 import { paginationStages } from './query-limits.js';
 import SimfinityError from './errors/simfinity.error.js';
+import { enterQueryFrame, queryEntryContext, resolveComparisonContext, resolveContainerContext, resolveQueryContext } from './query-context.js';
 import {
   describeEmptiness, describeModelEmptiness, emptinessMemberPaths, emptinessScopeTargets, isEmptinessOperator, isQueryOperator,
   hasValuePath, takesListValue, textQueryOperator, validateComparisonOperand, validateContainsAllValue, validateTextFilterValue, validateTextListFilterValue,
@@ -97,17 +98,22 @@ const walkQueryEntries = (args, operation, { paths = false, gqltype, expandMembe
     }
   };
   const operandPath = (item, prefix = '') => hasValuePath(item)
-    ? (prefix ? `${prefix}.${item.valuePath}` : item.valuePath) : undefined;
+    ? (prefix && !(typeof item.valuePath === 'string' && item.valuePath.startsWith('$parent.')) ? `${prefix}.${item.valuePath}` : item.valuePath) : undefined;
   const addPredicatePaths = (path, item, frame, container, group = null, prefix = '') => {
     const comparison = hasValuePath(item) || item?.__operand != null;
     addPath(path, frame, container, group, item?.operator ?? 'EQ', comparison ? item : item ?? null,
       comparison ? { role: 'left', comparison: true } : {});
     if (!comparison) return;
     let origin = frame;
-    if (item.__operand) {
-      for (let up = item.__operand.up; up > 0 && origin.parent; up--) origin = origin.parent;
+    let right = item.__operand ? item.__operand.path?.join('.') : operandPath(item, prefix);
+    let binding = item.__operand?.container;
+    if (!item.__operand && gqltype && typeof item.valuePath === 'string' && item.valuePath.startsWith('$parent.')) {
+      const resolved = resolveComparisonContext(item.valuePath, queryEntryContext(frame, { gqltype }), prefix);
+      binding = resolved.container;
+      right = resolved.path.join('.');
     }
-    const right = item.__operand ? item.__operand.path?.join('.') : operandPath(item, prefix);
+    for (let up = binding?.up ?? item.__operand?.up ?? 0; up > 0 && origin.parent; up--) origin = origin.parent;
+    if (binding?.path.length) right = [...binding.path, right].join('.');
     addPath(right, origin, container, group, item.operator ?? 'EQ', item, { role: 'right', comparison: true });
   };
   const addOperator = (item, form, field, rawPath, depth, frame, container, relativePath, quantifier, prefix = '') => {
@@ -126,7 +132,7 @@ const walkQueryEntries = (args, operation, { paths = false, gqltype, expandMembe
       rawPath,
       value: item.value,
       hasValue: Object.hasOwn(item, 'value'),
-      ...(hasValuePath(item) ? { hasValuePath: true, valuePath: operandPath(item, prefix) } : {}),
+      ...(hasValuePath(item) ? { hasValuePath: true, valuePath: operandPath(item, prefix), ...(prefix && typeof item.valuePath === 'string' && item.valuePath.startsWith('$parent.') ? { valuePathPrefix: prefix } : {}) } : {}),
       ...(Object.hasOwn(item, '__operand') ? { operand: item.__operand } : {}),
       ambiguous: form === 'condition' && typeof field === 'string' && field.includes('.') && !isPathless(rawPath),
       depth,
@@ -315,9 +321,11 @@ export const resolveModelPath = (models, entityName, path) => {
  * paths on the predicate; generated outer operands own their joins in their ancestor frame.
  */
 export const createQueryPlan = (models, entityName, source = {}, {
-  mode = 'find', operators: supported, referenceEmptiness = supported == null, quantifiers = supported == null, valuePath = supported == null,
+  mode = 'find', operators: supported, referenceEmptiness = supported == null, quantifiers = supported == null, valuePath = supported == null, elementFrames = supported == null,
 } = {}) => {
   let input = source;
+  const rootContext = { models, entity: entityName };
+  const modelSteps = (context, path) => resolveQueryContext(path, context).raw;
   const allowed = supported == null ? null : new Set(supported);
   const references = referenceEmptiness === true;
   const combine = (kind, terms) => {
@@ -343,19 +351,19 @@ export const createQueryPlan = (models, entityName, source = {}, {
       if (scopes[path] !== null && (!isObject(scopes[path]) || ![Object.prototype, null].includes(Object.getPrototypeOf(scopes[path])))) detached(`${label} carries a malformed scope of ${path}`);
       lifted[path] = scopes[path] === null
         ? null
-        : createQueryPlan(models, targets[path], scopes[path], { mode: 'find', operators: allowed ?? undefined, referenceEmptiness: references, quantifiers, valuePath }).where;
+        : createQueryPlan(models, targets[path], scopes[path], { mode: 'find', operators: allowed ?? undefined, referenceEmptiness: references, quantifiers, valuePath, elementFrames }).where;
     }
     return lifted;
   };
   const hasMarker = (construct) => construct != null && typeof construct === 'object' && Object.hasOwn(construct, '__scope');
   // Rule 1 has resolved the path; rule 2 is the compiler's operators, rules 3 to 6 describeEmptiness's.
-  const emptiness = (path, steps, operator, value, construct, frameEntity) => {
+  const emptiness = (path, steps, operator, value, construct, frameContext) => {
     if (allowed && !allowed.has(operator)) fail(`The ${operator} filter operator is not supported by this query compiler`, 'UNSUPPORTED_QUERY');
     const segments = Array.isArray(path) ? path : path.split('.');
     const options = {
       operator, value, path: segments.join('.'), referenceEmptiness: references,
     };
-    const gqltype = models.entities.find((item) => item.name === frameEntity)?.gqltype;
+    const gqltype = frameContext.fields ? null : models.entities.find((item) => item.name === frameContext.entity)?.gqltype;
     const shape = gqltype ? describeEmptiness(gqltype, segments, options) : describeModelEmptiness(steps, options);
     const node = {
       kind: 'predicate', path: segments, operator, value: null,
@@ -365,10 +373,10 @@ export const createQueryPlan = (models, entityName, source = {}, {
   };
   // `construct` is the term or group condition that holds the predicate, the only objects whose
   // `__scope` is read; null for a field filter's own operator.
-  const predicate = (path, operator, value, construct = null, frameEntity = entityName, inFrame = false, ancestors = [], prefix = '') => {
-    const steps = resolveModelPath(models, frameEntity, path);
+  const predicate = (path, operator, value, construct = null, frameContext = rootContext, inFrame = false, ancestors = [], prefix = '') => {
+    const steps = modelSteps(frameContext, path);
     const op = operator ?? 'EQ';
-    if (isEmptinessOperator(op)) return emptiness(path, steps, op, value, construct, frameEntity);
+    if (isEmptinessOperator(op)) return emptiness(path, steps, op, value, construct, frameContext);
     const field = steps.at(-1);
     if (field.kind !== 'scalar' && !field.inferred) {
       fail(`Filter on object field ${path} requires a scalar path`, steps.length > 1 ? 'INVALID_FILTER_PATH' : 'MISSING_FILTER_PATH');
@@ -378,24 +386,28 @@ export const createQueryPlan = (models, entityName, source = {}, {
     const comparison = hasValuePath(construct) || construct?.__operand !== undefined;
     if (comparison) {
       const internal = construct.__operand;
-      const rightPath = internal?.path ?? (prefix ? `${prefix}.${validateComparisonOperand(construct)}` : validateComparisonOperand(construct)).split('.');
+      const publicOperand = internal ? null : resolveComparisonContext(validateComparisonOperand(construct), frameContext, prefix);
+      const boundContainer = internal?.container ?? publicOperand?.container;
+      const container = boundContainer?.up === 0 && !internal ? undefined : boundContainer;
+      const rightPath = internal?.path ?? (boundContainer ? (container ? publicOperand.path : [...boundContainer.path, ...publicOperand.path])
+        : [...(prefix ? prefix.split('.') : []), ...construct.valuePath.split('.')]);
       const up = internal?.up ?? 0;
-      const rightEntity = up ? ancestors[ancestors.length - up] : frameEntity;
-      if (!rightEntity) fail('Invalid comparison operand frame', 'INVALID_FILTER_PATH');
-      resolveModelPath(models, rightEntity, rightPath);
+      const rightContext = container ? (publicOperand?.context ?? resolveContainerContext(container, frameContext)) : up ? ancestors[ancestors.length - up] : frameContext;
+      if (!rightContext) fail('Invalid comparison operand frame', 'INVALID_FILTER_PATH');
+      modelSteps(rightContext, rightPath);
       const segments = Array.isArray(path) ? path : path.split('.');
-      const node = { kind: 'predicate', path: segments, operator: op, value: null, operand: { up, path: rightPath } };
-      const scopeTargets = (paths, entity) => Object.fromEntries([...new Set(paths.flatMap((item) => crossingKeys(item, { models, entity })))].map((key) => [key, resolveModelPath(models, entity, key).at(-1).target]));
+      const node = { kind: 'predicate', path: segments, operator: op, value: null, operand: { up, path: rightPath, ...(container ? { container } : {}) } };
+      const scopeTargets = (paths, entity) => Object.fromEntries([...new Set(paths.flatMap((item) => crossingKeys(item, entity)))].map((key) => [key, modelSteps(entity, key).at(-1).target]));
       // J collections retain their existing aggregate row. Validate their provenance, but only
       // references become scoped joins; an empty collection scope must not lose the marker.
-      const anchors = (paths, entity) => [...new Set(paths.flatMap((parts) => resolveModelPath(models, entity, parts)
+      const anchors = (paths, entity) => [...new Set(paths.flatMap((parts) => modelSteps(entity, parts)
         .flatMap((step, index) => step.kind === 'collection' ? [parts.slice(0, index + 1).join('.')] : [])))];
       if (hasMarker(construct)) {
-        const paths = up ? [segments] : [segments, rightPath];
-        node.joins = liftScopes(construct.__scope, scopeTargets(paths, frameEntity), segments, op, anchors(paths, frameEntity));
+        const paths = up || container ? [segments] : [segments, rightPath];
+        node.joins = liftScopes(construct.__scope, scopeTargets(paths, frameContext), segments, op, anchors(paths, frameContext));
       }
       if (internal && Object.hasOwn(internal, 'scopes')) {
-        node.operand.joins = liftScopes({ scopes: internal.scopes }, scopeTargets([rightPath], rightEntity), rightPath, op, anchors([rightPath], rightEntity));
+        node.operand.joins = liftScopes({ scopes: internal.scopes }, scopeTargets([rightPath], rightContext), rightPath, op, anchors([rightPath], rightContext));
       }
       return node;
     }
@@ -410,7 +422,7 @@ export const createQueryPlan = (models, entityName, source = {}, {
     const node = { kind: 'predicate', path: Array.isArray(path) ? path : path.split('.'), operator: op, value: value === undefined ? null : value };
     if (hasMarker(construct)) {
       if (!inFrame) detached(`${op} on ${node.path.join('.')} carries a client scope marker, but is not an emptiness condition`);
-      const targets = Object.fromEntries(crossingKeys(node.path, { models, entity: frameEntity }).map((key) => [key, resolveModelPath(models, frameEntity, key).at(-1).target]));
+      const targets = Object.fromEntries(crossingKeys(node.path, frameContext).map((key) => [key, modelSteps(frameContext, key).at(-1).target]));
       node.joins = liftScopes(construct.__scope, targets, node.path, op);
     }
     return node;
@@ -421,7 +433,7 @@ export const createQueryPlan = (models, entityName, source = {}, {
     if (!value || typeof value !== 'object' || Array.isArray(value)) fail('Expected a filter group object');
     for (const key of keys) if (value[key] != null && !Array.isArray(value[key])) fail(`${key} requires an array`);
   };
-  const group = (value, depth = -1, frameEntity = entityName, inFrame = false, ancestors = []) => {
+  const group = (value, depth = -1, frameContext = rootContext, inFrame = false, ancestors = []) => {
     validateGroup(value);
     const level = depth + (value.__implicit === true ? 0 : 1);
     if (level > 5) fail('Filter nesting too deep', 'FILTER_DEPTH_EXCEEDED');
@@ -429,7 +441,7 @@ export const createQueryPlan = (models, entityName, source = {}, {
     for (const condition of value.conditions || []) {
       if (!condition || typeof condition.field !== 'string') fail('Invalid filter path', 'INVALID_FILTER_PATH');
       if (condition.field.includes('.') && condition.path) fail('Filter condition cannot use both dotted field syntax and a separate path', 'AMBIGUOUS_FILTER_FIELD');
-      terms.push(predicate(condition.path ? `${condition.field}.${condition.path}` : condition.field, condition.operator, condition.value, condition, frameEntity, inFrame, ancestors));
+      terms.push(predicate(condition.path ? `${condition.field}.${condition.path}` : condition.field, condition.operator, condition.value, condition, frameContext, inFrame, ancestors));
     }
     if (quantifiers !== true && QUANTIFIED_LISTS.some((key) => value[key] != null)) {
       fail('Quantified groups are not supported by this query compiler', 'UNSUPPORTED_QUERY');
@@ -437,17 +449,20 @@ export const createQueryPlan = (models, entityName, source = {}, {
     for (const quantifier of QUANTIFIED_LISTS) for (const item of value[quantifier] || []) {
       const anchor = item.__implicit === true ? item.__anchor : undefined;
       const path = item.path.split('.');
-      const target = resolveModelPath(models, frameEntity, [...(anchor ?? []), ...path]).at(-1).target;
-      const node = { kind: 'quantified', quantifier, path, where: group(item, level, target, true, [...ancestors, frameEntity]), scope: null };
+      const fullContextPath = [...(anchor ?? []), ...path];
+      const targetContext = enterQueryFrame(frameContext, fullContextPath);
+      const target = modelSteps(frameContext, fullContextPath).at(-1).target;
+      const node = { kind: 'quantified', quantifier, path, where: group(item, level, targetContext, true, [...ancestors, frameContext]), scope: null };
       if (anchor?.length) node.anchor = anchor;
       if (hasMarker(item)) {
         const fullPath = [...(anchor ?? []), ...path];
         const key = fullPath.join('.');
-        const crossings = anchor?.length && !hasComparisonNode(node.where) ? [] : crossingKeys(fullPath, { models, entity: frameEntity });
-        const targets = Object.fromEntries(crossings.map((prefix) => [prefix, resolveModelPath(models, frameEntity, prefix).at(-1).target]));
-        targets[key] = target;
-        const scopes = liftScopes(item.__scope, targets, fullPath, quantifier);
-        node.scope = scopes[key];
+        const crossings = anchor?.length && !hasComparisonNode(node.where) ? [] : crossingKeys(fullPath, frameContext);
+        const targets = Object.fromEntries(crossings.map((prefix) => [prefix, modelSteps(frameContext, prefix).at(-1).target]));
+        if (target) targets[key] = target;
+        const anchors = anchor?.length ? modelSteps(frameContext, anchor).flatMap((field, index) => field.kind === 'collection' ? [anchor.slice(0, index + 1).join('.')] : []) : [];
+        const scopes = liftScopes(item.__scope, targets, fullPath, quantifier, anchors);
+        node.scope = target ? scopes[key] : null;
         if (anchor?.length) {
           for (const prefix of J) if (key.startsWith(`${prefix}.`)) {
             if (!Object.hasOwn(item.__scope.scopes, prefix) || item.__scope.scopes[prefix] !== null) detached(`${quantifier} on ${key} requires a null aggregate anchor scope for ${prefix}`);
@@ -457,13 +472,13 @@ export const createQueryPlan = (models, entityName, source = {}, {
       }
       terms.push(node);
     }
-    for (const item of value.AND || []) terms.push(group(item, level, frameEntity, inFrame, ancestors));
-    terms.push(combine('or', (value.OR || []).map((item) => group(item, level, frameEntity, inFrame, ancestors))));
+    for (const item of value.AND || []) terms.push(group(item, level, frameContext, inFrame, ancestors));
+    terms.push(combine('or', (value.OR || []).map((item) => group(item, level, frameContext, inFrame, ancestors))));
     return combine('and', terms);
   };
   // Validate received arguments in filled-marker mode before the pure, frame-producing rewrite.
   validateGroup(input, ['AND', 'OR']);
-  const context = { models, entity: entityName, operation: mode, operators: allowed, referenceEmptiness: references, quantifiers, valuePath };
+  const context = { models, entity: entityName, operation: mode, operators: allowed, referenceEmptiness: references, quantifiers, valuePath, elementFrames };
   const J = mode === 'aggregate' ? aggregateJoinPrefixes(input.aggregation, context) : new Set();
   context.J = J;
   validateQuantifiedGroups(input, context);
@@ -490,7 +505,7 @@ export const createQueryPlan = (models, entityName, source = {}, {
         continue;
       }
       if (typeof term.path !== 'string' || !term.path) fail('Relationship terms require a path', 'INVALID_FILTER_PATH');
-      terms.push(predicate(`${name}.${term.path}`, term.operator, term.value, term, entityName, false, [], name));
+      terms.push(predicate(`${name}.${term.path}`, term.operator, term.value, term, rootContext, false, [], name));
     }
   }
   for (const item of input.AND || []) terms.push(group(item));

package/src/runtime.js

@@ -1,3 +1,4 @@
+import { parentScopePrefix, queryEntryContext, resolveComparisonContext } from './query-context.js';
 import {
   configureQueryLimits, getQueryMaxPageSize, getQueryMaxReferenceFrames, paginationStages,
 } from './query-limits.js';
@@ -221,7 +222,7 @@ const prefixScopeGroup = (group, prefix, copyQuantifiedGroup) => {
   return prefixed;
 };
 
-const prefixScopeArgs = (scopeArgs, prefix, typeName, copyQuantifiedGroup) => {
+const prefixScopeArgs = (scopeArgs, prefix, typeName, copyQuantifiedGroup, gqltype) => {
   const conditions = [];
   const groups = [];
   for (const [name, value] of Object.entries(scopeArgs)) {
@@ -244,8 +245,10 @@ const prefixScopeArgs = (scopeArgs, prefix, typeName, copyQuantifiedGroup) => {
         // An emptiness term without a path (omitted, null or "") tests the field itself; other
         // operators keep the path as written.
         const itself = isEmptinessOperator(term?.operator) && (term.path == null || term.path === '');
+        const parent = parentScopePrefix(term?.valuePath) ? resolveComparisonContext(term.valuePath, { gqltype }, name) : null;
+        const rightPath = parent ? [...parent.container.path, ...parent.path].join('.') : `${name}.${term?.valuePath}`;
         conditions.push({ field: itself ? `${prefix}.${name}` : `${prefix}.${name}.${term?.path}`, operator: term?.operator, value: term?.value,
-          ...(hasValuePath(term) ? { valuePath: `${prefix}.${name}.${term.valuePath}` } : {}),
+          ...(hasValuePath(term) ? { valuePath: `${prefix}.${rightPath}` } : {}),
         });
       }
     } else conditions.push({ field: `${prefix}.${name}`, operator: value.operator, value: value.value,
@@ -604,7 +607,7 @@ export const createRuntime = (adapter) => {
   // IS_EMPTY and IS_NOT_EMPTY through references and collections (#108 part 2b), and a client's
   // conditions of that kind carry a scope marker from the runtime (see markClientConstructs).
   const {
-    operators: supportedOperators, referenceEmptiness: supportsReferenceEmptiness, quantifiers: supportsQuantifiers, valuePath: supportsValuePath,
+    operators: supportedOperators, referenceEmptiness: supportsReferenceEmptiness, quantifiers: supportsQuantifiers, valuePath: supportsValuePath, elementFrames: supportsElementFrames,
   } = resolveQueryFeatures(adapter.queryFeatures);
   const supportsEveryOperator = QUERY_OPERATORS.every((operator) => supportedOperators.has(operator));
   // The write features the adapter implements, read once: with optimisticConcurrency, schemas may
@@ -2349,7 +2352,7 @@ let virtualFieldsDeclared = false;
 // (500), the code of model declarations that cannot be honored at request time.
 const assertStoredQueryPaths = (gqltype, args, operation) => {
   if (!virtualFieldsDeclared) return;
-  for (const { segments } of collectQueryPathEntries(args, operation)) {
+  for (const { segments } of collectQueryPathEntries(args, operation, { gqltype })) {
     walkQueryPath(gqltype, segments, ({ type, fieldName, field, index }) => {
       if (!isVirtualField(field)) return;
       throw new SimfinityError(`Query path ${segments.slice(0, index + 1).join('.')}, added by middleware or a `
@@ -2408,7 +2411,7 @@ const assertEmptinessForm = (gqltype, {
 // carriers, which do not become predicates but must not use known undeclared capabilities.
 const queryFrameContext = (gqltype, args, operation) => ({
   gqltype, operation, quantifiers: supportsQuantifiers, referenceEmptiness: supportsReferenceEmptiness,
-  operators: supportedOperators, valuePath: supportsValuePath,
+  operators: supportedOperators, valuePath: supportsValuePath, elementFrames: supportsElementFrames,
   J: operation === 'aggregate' ? aggregateJoinPrefixes(args.aggregation, { gqltype }) : new Set(),
   scopeMarkers: 'pending',
 });
@@ -2492,7 +2495,7 @@ const assertJoinedScopePaths = (rootType, groups, prefix, target) => {
     embeddedPrefix ||= !!(field.extensions?.relation?.embedded && getListShape(field.type));
   });
   const depth = prefix.split('.').length;
-  for (const { segments, quantifier } of collectQueryPathEntries({ AND: groups })) {
+  for (const { segments, quantifier } of collectQueryPathEntries({ AND: groups }, 'find', { gqltype: rootType })) {
     let inList = false;
     walkQueryPath(target.gqltype, segments.slice(depth), ({ type, fieldName, field, index }) => {
       const relation = field.extensions?.relation;
@@ -2549,7 +2552,7 @@ const applyJoinedScopes = async (joinedScopes, params) => {
     const kept = scopeFilterArgs(scopeArgs);
     assertStoredQueryPaths(target.gqltype, kept, 'find');
     assertQueryConditions(target.gqltype, kept, 'find');
-    const groups = prefixScopeArgs(kept, prefix, target.gqltype.name, copyQuantifiedGroup);
+    const groups = prefixScopeArgs(kept, prefix, target.gqltype.name, copyQuantifiedGroup, target.gqltype);
     if (!groups.length) continue;
     if (collection) throw forbiddenPath(`Query path ${prefix} enters the scoped collection ${collection}`);
     assertJoinedScopePaths(params.type.gqltype, groups, prefix, target);
@@ -2623,7 +2626,7 @@ const markClientConstructs = (checked, { aggregation, issued = new Map() } = {})
   for (const { entry, shape } of conditions) {
     const { construct } = entry;
     if (!construct || !(shape || entry.hasValuePath || entry.form === 'quantified' || ordinaryFrameCarrier(gqltype, entry, clientJ))) continue;
-    const comparisonPath = entry.hasValuePath ? [...entry.segments.slice(0, -entry.relative.length), ...entry.valuePath.split('.')] : [];
+    const comparisonPath = entry.hasValuePath ? resolveComparisonContext(entry.valuePath, queryEntryContext(entry, { gqltype }), entry.valuePathPrefix).resolved.end.absolute : [];
     const targets = [...pathRelations(gqltype, entry.segments), ...pathRelations(gqltype, comparisonPath)].map(({ typeName }) => typeName);
     if (shape) targets.push(...Object.values(emptinessScopeTargets(shape, entry.relative)));
     if (!targets.some((name) => getScope(typesDict.types[name]?.gqltype, 'find'))) continue;
@@ -2667,7 +2670,7 @@ const assertClientMarkers = (gqltype, args, operation, issued, clientJ) => {
       throw detachedClientFilter(`The client's ${origin.operator} condition on ${origin.path} is inside a trusted frame`);
     }
     if (supportsQuantifiers && !entry.frames.length && entry.form !== 'quantified' && !isEmptinessOperator(operator)) {
-      const operandPaths = [entry.segments, ...(entry.hasValuePath ? [[...entry.segments.slice(0, -entry.relative.length), ...entry.valuePath.split('.')]] : [])];
+      const operandPaths = [entry.segments, ...(entry.hasValuePath ? [resolveComparisonContext(entry.valuePath, queryEntryContext(entry, { gqltype }), entry.valuePathPrefix).resolved.end.absolute] : [])];
       for (const relation of operandPaths.flatMap((parts) => pathRelations(gqltype, parts))) if (relation.collection && clientJ.has(relation.path) !== J.has(relation.path)) {
         throw detachedClientFilter(`The client's ${origin.operator} condition on ${origin.path} changed aggregate join prefixes`);
       }
@@ -2747,7 +2750,11 @@ const fillClientScopes = async (gqltype, checked, context, issued) => {
       const relations = pathRelations(type, entry.relative);
       if (entry.hasValuePath) {
         const existing = new Set(relations.map(({ path }) => path));
-        relations.push(...pathRelations(type, entry.valuePath.split('.')).filter(({ path }) => !existing.has(path)));
+        const right = resolveComparisonContext(entry.valuePath, queryEntryContext(entry, { gqltype }), entry.valuePathPrefix);
+        const prefix = parentScopePrefix(entry.valuePath);
+        const rightRelations = pathRelations(right.context.gqltype, right.path ?? entry.valuePath.split('.'))
+          .map((relation) => ({ ...relation, path: `${prefix}${relation.path}` }));
+        relations.push(...rightRelations.filter(({ path }) => !existing.has(path)));
       }
       if (!shape && !entry.hasValuePath && entry.form !== 'quantified' && !ordinaryFrameCarrier(gqltype, entry, J)) {
         const relation = relationOnPath(gqltype, entry.segments);
@@ -2767,7 +2774,8 @@ const fillClientScopes = async (gqltype, checked, context, issued) => {
         targets[key] = target;
       }
       if (!Object.keys(keys).length) unread.push(entry.path);
-      for (const relation of relations) if (!relation.collection && relation.insideList && Object.hasOwn(keys, relation.path)) {
+      for (const relation of relations) if (!relation.collection && relation.insideList && Object.hasOwn(keys, relation.path)
+        && !(supportsElementFrames && entry.hasValuePath)) {
         vectors.push({ ...relation, absolute: [...entry.segments.slice(0, -entry.relative.length), ...relation.path.split('.')].join('.') });
       }
     }

package/types/index.d.ts

@@ -164,6 +164,8 @@ export interface QueryFeatures {
   quantifiers?: boolean | null | undefined;
   /** Field operands, including scoped references. Requires referenceEmptiness: true. */
   valuePath?: boolean | null | undefined;
+  /** Embedded element frames and structural parent operands. Requires all three preceding flags. */
+  elementFrames?: boolean | null | undefined;
 }
 
 export interface ModelRegistration {
@@ -910,7 +912,15 @@ export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapt
 export type QueryJoins = Record<string, QueryPredicate | null>;
 
 /** A field operand in the same frame (up: 0) or an enclosing shorthand frame. */
-export type QueryOperand = { up: number; path: string[]; joins?: QueryJoins };
+export type QueryOperand = {
+  up: number;
+  path: string[];
+  joins?: QueryJoins;
+  /** Structural embedded container: bound frame distance and a single-object path within it.
+   * When present, the outer `up` is zero and `path` is relative to this container.
+   * This must identify an actual embedded ancestor, never an arbitrary outer entity. */
+  container?: { up: number; path: string[] };
+};
 
 /**
  * `operator` is a {@link QueryOperator}; the value of a text operator is a validated string. For
@@ -994,9 +1004,9 @@ export interface QueryPlan {
  * `valuePath` selects a compatible stored scalar operand instead of a literal value. It defaults
  * like `quantifiers`; a comparison node has `value: null` and `operand: { up, path, joins? }`.
  * Same-frame operands use the union of scoped paths in `joins`; internal shorthand outer bindings
- * use positive `up` and their own operand joins. Public inputs do not accept outer-frame syntax.
+ * use positive `up` and their own operand joins. Structural $parent operands add container: { up, path } with outer up zero; existing up semantics stay unchanged.
  * Null equality is two-valued, and a left scalar list uses null-safe EQ/NE membership.
- * Embedded-list comparisons, right scalar lists and incompatible logical types fail explicitly.
+ * Embedded-list comparisons require elementFrames; right scalar lists and incompatible logical types fail explicitly.
  *
  * `referenceEmptiness` defaults to true when `operators` is omitted and to false when it is given.
  * When it is false, an emptiness condition that crosses or ends at a reference or a collection, or
@@ -1018,7 +1028,7 @@ export interface QueryPlan {
  * checked before the path rule, the rest after it.
  * A marker not filled for every path fails with `DETACHED_CLIENT_FILTER` (500).
  */
-export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string>; referenceEmptiness?: boolean; quantifiers?: boolean; valuePath?: boolean }): QueryPlan;
+export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string>; referenceEmptiness?: boolean; quantifiers?: boolean; valuePath?: boolean; elementFrames?: boolean }): QueryPlan;
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
 
 /**