@simtlix/simfinity-core 3.16.0 → 3.18.0

package/src/query-plan.js

@@ -2,9 +2,10 @@ 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,
-  takesListValue, textQueryOperator, validateContainsAllValue, validateTextFilterValue, validateTextListFilterValue,
+  hasValuePath, takesListValue, textQueryOperator, validateComparisonOperand, validateContainsAllValue, validateTextFilterValue, validateTextListFilterValue,
 } from './query-operators.js';
 
 const fail = (message, code = 'INVALID_FILTER_VALUE') => { throw new SimfinityError(message, code, 400); };
@@ -45,7 +46,7 @@ const walkQueryEntries = (args, operation, { paths = false, gqltype, expandMembe
   const records = [];
   const open = new Set();
   const childFrame = (parent, path, quantifier, construct, anchor = []) => ({
-    base: [...parent.base, ...anchor, ...pathSegments(path)],
+    parent, base: [...parent.base, ...anchor, ...pathSegments(path)],
     frames: [...parent.frames, { path, type: quantifier, construct }],
     groups: new Map(),
   });
@@ -96,7 +97,26 @@ const walkQueryEntries = (args, operation, { paths = false, gqltype, expandMembe
       entries.push({ ...entry, segments, relative: segments.slice(frame.base.length), member: true });
     }
   };
-  const addOperator = (item, form, field, rawPath, depth, frame, container, relativePath, quantifier) => {
+  const operandPath = (item, prefix = '') => hasValuePath(item)
+    ? (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;
+    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('.');
+    }
+    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 = '') => {
     if (!isObject(item)) return;
     const quantified = form === 'quantified';
     const relative = pathSegments(relativePath);
@@ -112,9 +132,11 @@ 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), ...(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,
-      construct: quantified || form === 'term' || form === 'condition' ? item : null,
+      construct: quantified || form === 'term' || form === 'condition' || hasValuePath(item) || item.__operand ? item : null,
       emptiness: isEmptinessOperator(operator),
       ...(quantified ? { quantifier } : {}),
     });
@@ -134,7 +156,7 @@ const walkQueryEntries = (args, operation, { paths = false, gqltype, expandMembe
         const field = condition?.field;
         const path = conditionPath(field, condition?.path);
         if (paths) {
-          if (typeof field === 'string') addPath(path, inner, group, group, condition.operator ?? 'EQ', condition);
+          if (typeof field === 'string') addPredicatePaths(path, condition, inner, group, group);
         } else addOperator(condition, 'condition', field, condition?.path, depth, inner, group, path);
       }
       continue;
@@ -149,7 +171,7 @@ const walkQueryEntries = (args, operation, { paths = false, gqltype, expandMembe
         if (paths) {
           // Invalid path-less terms still name the field, as before; validation rejects them
           // before authorization marking. Their relative path names nothing in the child.
-          if (hasTermPath(term)) addPath(term.path, frame, value, null, term.operator ?? 'EQ', term);
+          if (hasTermPath(term)) addPredicatePaths(term.path, term, frame, value);
           else if (isPathless(term.path)) {
             entries.push({ ...metadata([], frame, value), group: null, operator: term.operator ?? 'EQ', construct: term });
           }
@@ -159,20 +181,21 @@ const walkQueryEntries = (args, operation, { paths = false, gqltype, expandMembe
     }
     if (!paths) {
       const hasTerms = Array.isArray(value.terms);
-      if (!hasTerms || value.operator !== undefined) addOperator(value, hasTerms ? 'beside-terms' : 'filter', name, undefined, 0, root, value, name);
-      if (hasTerms) for (const term of terms) addOperator(term, 'term', name, term?.path, 0, root, value, conditionPath(name, term?.path));
+      if (!hasTerms || value.operator !== undefined || hasValuePath(value)) addOperator(value, hasTerms ? 'beside-terms' : 'filter', name, undefined, 0, root, value, name);
+      if (hasTerms) for (const term of terms) addOperator(term, 'term', name, term?.path, 0, root, value, conditionPath(name, term?.path), undefined, name);
       continue;
     }
     const pathless = (term) => isEmptinessOperator(term?.operator) && isPathless(term.path);
     if (!terms.some(hasTermPath)) {
       const term = terms.find(pathless);
       if (term) addPath(name, root, value, null, term.operator, term);
+      else if (hasValuePath(value)) addPredicatePaths(name, value, root, value);
       else addPath(name, root, value, null, value.operator ?? 'EQ');
       continue;
     }
     let field = false;
     for (const term of terms) {
-      if (hasTermPath(term)) addPath(`${name}.${term.path}`, root, value, null, term.operator ?? 'EQ', term);
+      if (hasTermPath(term)) addPredicatePaths(`${name}.${term.path}`, term, root, value, null, name);
       else if (!field && pathless(term)) {
         addPath(name, root, value, null, term.operator, term);
         field = true;
@@ -198,7 +221,9 @@ const walkQueryEntries = (args, operation, { paths = false, gqltype, expandMembe
  * A quantified carrier names its path in the containing frame, with `quantifier` and its own
  * construct; children enter its frame. The legacy `group` remains the conditions owner, otherwise
  * null; operator and construct retain their old meanings except that quantifier filters now carry
- * their own construct. An omitted filter operator is EQ; non-filter reads and quantified carriers
+ * their own construct. Comparisons emit left/right roles with comparison:true and one owning
+ * construct, including ordinary field filters; RHS paths preserve their lexical term/frame origin.
+ * An omitted filter operator is EQ; non-filter reads and quantified carriers
  * have no operator. `expandMembers` appends stored emptiness member paths, preserving metadata.
  */
 export const collectQueryPathEntries = (args, operation = 'find', options = {}) => (
@@ -209,7 +234,8 @@ export const collectQueryPathEntries = (args, operation = 'find', options = {})
  * Internal: filter constructs only, with the same frame metadata as the path collector. Preserves
  * form, field, rawPath, value, hasValue, ambiguous, deepest depth and emptiness. Quantified carriers
  * have form `quantified`, operator null and their own construct; ordinary own filter operators keep
- * construct null. Explicit groups add a depth level, implicit ones none. Invalid entries are left
+ * construct null. Comparisons add hasValuePath:true and a frame-relative valuePath; their owning
+ * construct is always retained. Generated outer comparisons carry operand instead. Explicit groups add a depth level, implicit ones none. Invalid entries are left
  * to the validator; unknown group keys and path on a plain group fail closed here.
  */
 export const collectQueryOperators = (args, operation = 'find') => walkQueryEntries(args, operation);
@@ -290,11 +316,16 @@ export const resolveModelPath = (models, entityName, path) => {
  * explicit ANY/ALL/NONE and quantifier filters retain their quantifier, and scoped reference
  * crossings inside a frame lift into `joins`. Aggregate collection joins remain legacy; later
  * frames carry their legacy chain in `anchor`. Sorts through collections fail even in count mode.
+ * With `valuePath` (the same default as `quantifiers`), comparisons preserve their literal-free
+ * value:null placeholder and add operand:{up,path}. Same-frame scoped joins are the union of both
+ * 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,
+  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) => {
@@ -304,31 +335,35 @@ export const createQueryPlan = (models, entityName, source = {}, {
   // The client scope marker of a construct, lifted into the predicate's `scopes`: each target scope's
   // arguments are planned on the target type, as trusted find arguments in their own frame, whatever
   // the query's mode, with the operator names already read (`operators` may be a one-time iterable).
-  const liftScopes = (marker, targets, segments, operator) => {
+  const liftScopes = (marker, targets, segments, operator, anchors = []) => {
     const label = `${operator} on ${segments.join('.')}`;
-    const paths = Object.keys(targets);
+    const paths = [...Object.keys(targets), ...anchors];
     if (!paths.length) detached(`${label} carries a client scope marker, but reads no reference or collection`);
     const scopes = marker?.scopes;
     if (!scopes || typeof scopes !== 'object' || Array.isArray(scopes)) detached(`${label} carries a client scope marker whose scopes are not filled`);
     const lifted = {};
     for (const path of paths) {
       if (!Object.hasOwn(scopes, path) || scopes[path] === undefined) detached(`${label} carries a client scope marker without the scope of ${path}`);
+      if (anchors.includes(path)) {
+        if (scopes[path] !== null) detached(`${label} requires a null aggregate anchor scope for ${path}`);
+        continue;
+      }
       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 }).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,
@@ -338,16 +373,44 @@ 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) => {
-    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');
     }
     if (!isQueryOperator(op)) fail(`Unknown filter operator: ${op}`, 'INVALID_FILTER_OPERATOR');
     if (allowed && !allowed.has(op)) fail(`The ${op} filter operator is not supported by this query compiler`, 'UNSUPPORTED_QUERY');
+    const comparison = hasValuePath(construct) || construct?.__operand !== undefined;
+    if (comparison) {
+      const internal = construct.__operand;
+      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 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, ...(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) => modelSteps(entity, parts)
+        .flatMap((step, index) => step.kind === 'collection' ? [parts.slice(0, index + 1).join('.')] : [])))];
+      if (hasMarker(construct)) {
+        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], rightContext), rightPath, op, anchors([rightPath], rightContext));
+      }
+      return node;
+    }
     const collection = takesListValue(op);
     if (value === undefined || (!collection && Array.isArray(value)) || (value === null && !['EQ', 'NE'].includes(op))) fail('Expected a scalar filter value');
     if (collection && Array.isArray(value) && value.some((item) => item == null || Array.isArray(item))) fail('Filter lists require non-null scalar elements');
@@ -359,16 +422,18 @@ 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;
   };
+  const hasComparisonNode = (node) => Boolean(node && (node.operand || hasComparisonNode(node.where)
+    || node.terms?.some(hasComparisonNode)));
   const validateGroup = (value, keys = ['conditions', 'AND', 'OR']) => {
     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) => {
+  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');
@@ -376,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));
+      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');
@@ -384,32 +449,36 @@ 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), 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 ? [] : crossingKeys(path, { 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}`);
           }
-        } else if (crossings.length) node.joins = Object.fromEntries(crossings.map((prefix) => [prefix, scopes[prefix]]));
+        }
+        if (crossings.length) node.joins = Object.fromEntries(crossings.map((prefix) => [prefix, scopes[prefix]]));
       }
       terms.push(node);
     }
-    for (const item of value.AND || []) terms.push(group(item, level, frameEntity, inFrame));
-    terms.push(combine('or', (value.OR || []).map((item) => group(item, level, frameEntity, inFrame))));
+    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 };
+  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);
@@ -428,7 +497,7 @@ export const createQueryPlan = (models, entityName, source = {}, {
         + `${name}: { terms: [{ operator: ${value.operator} }] }`, 'MISSING_FILTER_PATH');
     }
     if (object && (!Array.isArray(value.terms) || !value.terms.length)) fail('Object filters require non-empty terms', 'MISSING_FILTER_PATH');
-    if (!object) terms.push(predicate(name, value.operator, value.value));
+    if (!object) terms.push(predicate(name, value.operator, value.value, hasValuePath(value) || value.__operand ? value : null));
     else for (const term of value.terms) {
       if (!term || typeof term !== 'object' || Array.isArray(term)) fail('Expected a relationship filter term');
       if (isEmptinessOperator(term.operator) && isPathless(term.path)) {
@@ -436,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));
+      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';
@@ -26,7 +27,7 @@ import QLSort from './const/QLSort.js';
 import {
   collectQueryOperators, collectQueryPathEntries, walkQueryPath,
 } from './query-plan.js';
-import { QUERY_OPERATORS, isQueryOperator, resolveQueryFeatures } from './query-operators.js';
+import { QUERY_OPERATORS, hasValuePath, isQueryOperator, resolveQueryFeatures } from './query-operators.js';
 import {
   assertEmptinessPath, describeEmptiness, emptinessScopeTargets, isEmptinessOperator,
 } from './query-emptiness.js';
@@ -210,6 +211,7 @@ const prefixScopeGroup = (group, prefix, copyQuantifiedGroup) => {
       field: `${prefix}.${condition?.path != null && condition.path !== '' ? `${condition.field}.${condition.path}` : condition?.field}`,
       operator: condition?.operator,
       value: condition?.value,
+      ...(hasValuePath(condition) ? { valuePath: `${prefix}.${condition.valuePath}` } : {}),
     }));
   }
   if (group.AND != null) prefixed.AND = [].concat(group.AND).map((item) => prefixScopeGroup(item, prefix, copyQuantifiedGroup));
@@ -220,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)) {
@@ -243,9 +245,15 @@ 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 === '');
-        conditions.push({ field: itself ? `${prefix}.${name}` : `${prefix}.${name}.${term?.path}`, operator: term?.operator, value: term?.value });
+        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}.${rightPath}` } : {}),
+        });
       }
-    } else conditions.push({ field: `${prefix}.${name}`, operator: value.operator, value: value.value });
+    } else conditions.push({ field: `${prefix}.${name}`, operator: value.operator, value: value.value,
+      ...(hasValuePath(value) ? { valuePath: `${prefix}.${value.valuePath}` } : {}),
+    });
   }
   return conditions.length ? [{ conditions }, ...groups] : groups;
 };
@@ -599,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,
+    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
@@ -735,6 +743,7 @@ const QLFilter = new GraphQLInputObjectType({
   fields: () => ({
     operator: { type: QLOperator },
     value: { type: QLValue },
+    valuePath: { type: GraphQLString, description: 'Compare with a stored field path; mutually exclusive with value.' },
   }),
 });
 
@@ -743,6 +752,7 @@ const QLTypeFilter = new GraphQLInputObjectType({
   fields: () => ({
     operator: { type: QLOperator },
     value: { type: QLValue },
+    valuePath: { type: GraphQLString, description: 'Compare with a stored field path; mutually exclusive with value.' },
     path: { type: GraphQLString },
   }),
 });
@@ -768,6 +778,7 @@ const QLFilterCondition = new GraphQLInputObjectType({
     field: { type: new GraphQLNonNull(GraphQLString) },
     operator: { type: QLOperator },
     value: { type: QLValue },
+    valuePath: { type: GraphQLString, description: 'Compare with a stored field path; mutually exclusive with value.' },
     path: { type: GraphQLString },
   }),
 });
@@ -2291,13 +2302,13 @@ const inspectClientPaths = (gqltype, args, operation, { checkQueryable = true }
   const J = operation === 'aggregate' ? aggregateJoinPrefixes(args.aggregation, { gqltype }) : new Set();
   const entries = collectQueryPathEntries(args, operation, { gqltype, expandMembers: true });
   for (const {
-    segments, group, member, operator, use, frames, quantifier,
+    segments, group, member, operator, use, frames, quantifier, comparison,
   } of entries) {
     const filter = use === 'filter';
     const relations = filter && supportsQuantifiers ? pathRelations(gqltype, segments) : [];
     const cut = relations.find((relation) => relation.collection && !J.has(relation.path));
     const anchored = cut && relations.some((relation) => relation.collection && J.has(relation.path));
-    const joins = !member && !(supportsReferenceEmptiness && isEmptinessOperator(operator))
+    const joins = !member && !comparison && !(supportsReferenceEmptiness && isEmptinessOperator(operator))
       && !(filter && (frames.length || quantifier || (cut && !anchored)));
     walkQueryPath(gqltype, segments, ({ type, fieldName, field, index }) => {
       const path = segments.slice(0, index + 1).join('.');
@@ -2341,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 `
@@ -2400,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,
+  operators: supportedOperators, valuePath: supportsValuePath, elementFrames: supportsElementFrames,
   J: operation === 'aggregate' ? aggregateJoinPrefixes(args.aggregation, { gqltype }) : new Set(),
   scopeMarkers: 'pending',
 });
@@ -2484,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;
@@ -2541,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);
@@ -2614,8 +2625,9 @@ const markClientConstructs = (checked, { aggregation, issued = new Map() } = {})
   };
   for (const { entry, shape } of conditions) {
     const { construct } = entry;
-    if (!construct || !(shape || entry.form === 'quantified' || ordinaryFrameCarrier(gqltype, entry, clientJ))) continue;
-    const targets = pathRelations(gqltype, entry.segments).map(({ typeName }) => typeName);
+    if (!construct || !(shape || entry.hasValuePath || entry.form === 'quantified' || ordinaryFrameCarrier(gqltype, entry, clientJ))) continue;
+    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;
     const origin = { operator: entry.operator ?? entry.quantifier, path: entry.path };
@@ -2658,7 +2670,8 @@ 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)) {
-      for (const relation of pathRelations(gqltype, entry.segments)) if (relation.collection && clientJ.has(relation.path) !== J.has(relation.path)) {
+      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`);
       }
     }
@@ -2735,7 +2748,15 @@ const fillClientScopes = async (gqltype, checked, context, issued) => {
     const vectors = [];
     for (const { entry, shape, type } of positions) {
       const relations = pathRelations(type, entry.relative);
-      if (!shape && entry.form !== 'quantified' && !ordinaryFrameCarrier(gqltype, entry, J)) {
+      if (entry.hasValuePath) {
+        const existing = new Set(relations.map(({ path }) => 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);
         if (relation) throw detachedClientFilter(`The client's ${origin.operator} condition on ${origin.path} now uses ${entry.operator} on `
           + `${entry.path}, which reads through ${relation} without its scope`);
@@ -2744,7 +2765,7 @@ const fillClientScopes = async (gqltype, checked, context, issued) => {
       const anchored = rootShorthand && relations.some(({ collection, path }) => collection && J.has(path));
       const cut = anchored ? relations.find(({ collection, path }) => collection && !J.has(path)) : null;
       const keys = shape ? emptinessScopeTargets(shape, entry.relative) : Object.fromEntries(relations
-        .filter((relation) => !anchored || relation.collection || (cut && relation.index >= cut.index))
+        .filter((relation) => entry.hasValuePath || !anchored || relation.collection || (cut && relation.index >= cut.index))
         .map(({ path, typeName, collection }) => [path, rootShorthand && collection && J.has(path) ? null : typeName]));
       for (const [key, target] of Object.entries(keys)) {
         if (Object.hasOwn(targets, key) && targets[key] !== target) {
@@ -2753,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

@@ -77,6 +77,8 @@ export interface QLFilterCondition {
   field: string;
   operator?: QueryOperator | null;
   value?: any;
+  /** A stored field path, mutually exclusive with a supplied value; null preserves literal behavior. */
+  valuePath?: string | null;
   path?: string | null;
 }
 
@@ -101,6 +103,8 @@ export interface QLTypeFilterExpression {
   terms?: Array<{
     operator?: QueryOperator | null;
     value?: any;
+    /** A stored field path, mutually exclusive with a supplied value; null preserves literal behavior. */
+    valuePath?: string | null;
     path?: string | null;
   } | null> | null;
 }
@@ -115,6 +119,8 @@ export interface FilterCondition {
   field: string;
   operator?: QueryOperator | (string & {});
   value?: any;
+  /** A stored field path, mutually exclusive with a supplied value; null preserves literal behavior. */
+  valuePath?: string | null;
   path?: string;
 }
 
@@ -156,6 +162,10 @@ export interface QueryFeatures {
    * legacy joins. All adapters reject list sorts through collections, including count mode.
    */
   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 {
@@ -176,6 +186,10 @@ export interface FieldDescription {
   scalar?: 'ID' | 'String' | 'Int' | 'Float' | 'Boolean' | 'DateTime' | 'Enum' | 'Version';
   values?: string[];
   enumValues?: { name: string; value: unknown }[];
+  /** Logical GraphQL enum identity, required for field comparisons. */
+  enumName?: string;
+  /** Effective temporal base before storage normalizes Date and Time to DateTime. */
+  temporalName?: 'DateTime' | 'Date' | 'Time';
   target?: string;
   connectionField?: string;
   fields?: FieldDescription[];
@@ -897,6 +911,17 @@ export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapt
 /** Scoped single-reference joins, keyed by a dotted prefix relative to the containing frame. */
 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;
+  /** 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
  * `CONTAINS_ALL` the value is a non-empty array of non-null scalars, validated and not cast; the
@@ -918,10 +943,11 @@ export type QueryJoins = Record<string, QueryPredicate | null>;
  * A `quantified` node selects elements with `ANY`, `ALL` or `NONE`, applying `scope` before `where`;
  * both predicates use paths relative to the element, and null means no restriction. Empty elements
  * give ANY false, ALL/NONE true; scope is never negated, and frames never multiply roots. `anchor` is
- * an aggregate's legacy join chain; when present, `path` is relative to it and `joins` is absent.
+ * an aggregate's legacy join chain; when present, `path` is relative to it. Comparison-bearing
+ * anchored frames may carry full-prefix joins as visibility guards, preserving the existing J row.
  */
 export type QueryPredicate =
-  | { kind: 'predicate'; path: string[]; operator: string; value: any; scopes?: Record<string, QueryPredicate | null>; joins?: QueryJoins }
+  | { kind: 'predicate'; path: string[]; operator: string; value: any; operand?: QueryOperand; scopes?: Record<string, QueryPredicate | null>; joins?: QueryJoins }
   | { kind: 'and' | 'or'; terms: QueryPredicate[] }
   | {
       kind: 'quantified';
@@ -975,6 +1001,13 @@ export interface QueryPlan {
  * `quantifiers`, a row filter on an aggregate's join prefix, a legacy join otherwise. `CONTAINS_ALL`
  * is never cut into a frame.
  *
+ * `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. 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 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
  * reads a reference or collection member, fails with `UNSUPPORTED_QUERY` where the order above has
@@ -995,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 }): 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[];
 
 /**