@simtlix/simfinity-core 3.16.0 → 3.17.0

package/README.md

@@ -84,3 +84,5 @@ pinned to the facade's exact version, including under pnpm or Yarn PnP. A late
 call fails without deleting installed metadata. Migrate clients selecting
 `__Field.extensions` before opting out. See the [descriptor reference](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html)
 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).

package/package.json

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

package/src/metadata.js

@@ -54,7 +54,7 @@ const scalarDescription = (type) => {
       if (storedValues.has(stored) && !Object.is(storedValues.get(stored), entry.value)) invalid(`Enum storage collision in ${type.name}: distinct internal values serialize to ${stored}`);
       storedValues.set(stored, entry.value);
     }
-    return { scalar: 'Enum', values: [...storedValues.keys()], enumValues: type.getValues().map(({ name, value }) => ({ name, value })) };
+    return { scalar: 'Enum', enumName: type.name, values: [...storedValues.keys()], enumValues: type.getValues().map(({ name, value }) => ({ name, value })) };
   }
   // The walk stops on a type that still has a base only where the chain repeats.
   if (rootScalar(type).baseScalarType) invalid(`Cyclic base scalar ${type.name}`);
@@ -63,7 +63,7 @@ const scalarDescription = (type) => {
   if (!['String', 'ID', 'Int', 'Float', 'Boolean', 'DateTime'].includes(scalar)) {
     invalid(`Unsupported scalar ${type.name}: declare a supported baseScalarType`);
   }
-  return { scalar };
+  return { scalar, ...(scalar === 'DateTime' ? { temporalName: name } : {}) };
 };
 
 // The version field of a protected entity, described the same way whether the type carries Simfinity's

package/src/query-comparisons.js

@@ -0,0 +1,54 @@
+import SimfinityError from './errors/simfinity.error.js';
+
+const fail = (message, code = 'INVALID_FILTER_VALUE') => { throw new SimfinityError(message, code, 400); };
+const equality = new Set(['EQ', 'NE']);
+const ordered = new Set(['LT', 'LTE', 'GT', 'GTE']);
+const text = new Set(['LIKE', 'STARTS_WITH', 'ENDS_WITH']);
+const temporal = new Set(['DateTime', 'Date', 'Time']);
+
+/** A nullable optional path selects a field operand only when non-null and non-undefined. */
+export const hasValuePath = (carrier) => carrier?.valuePath !== undefined && carrier?.valuePath !== null;
+
+/** Validate the public operand syntax before resolving either path. Literal carriers are unchanged. */
+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');
+  }
+  return carrier.valuePath;
+};
+
+const typeOf = (field, path) => {
+  if (field.identity || field.scalar === 'ID') return 'ID';
+  if (field.scalar === 'Enum') {
+    if (!field.enumName) fail(`Field comparison on ${path} requires logical enumName metadata`, 'UNSUPPORTED_QUERY');
+    return `Enum:${field.enumName}`;
+  }
+  if (temporal.has(field.scalar)) {
+    if (!field.temporalName) fail(`Field comparison on ${path} requires effective temporalName metadata`, 'UNSUPPORTED_QUERY');
+    return field.temporalName;
+  }
+  return field.scalar;
+};
+
+/** Logical comparison rules shared by runtime/model validation and hand-built engine plans. */
+export const validateComparisonTypes = (left, right, operator = 'EQ', leftPath = 'left', rightPath = 'right') => {
+  if (right.list) fail(`The right operand ${rightPath} must be a scalar, not a list`, 'INVALID_FILTER_PATH');
+  if (!equality.has(operator) && !ordered.has(operator) && !text.has(operator)) {
+    fail(`${operator} does not accept valuePath`, 'INVALID_FILTER_OPERATOR');
+  }
+  if (left.list && !equality.has(operator)) fail(`${operator} does not accept a list left operand`, 'INVALID_FILTER_OPERATOR');
+  const a = typeOf(left, leftPath);
+  const b = typeOf(right, rightPath);
+  const numeric = ['Int', 'Float'].includes(a) && ['Int', 'Float'].includes(b);
+  const supported = numeric || (a === b && (['String', 'Boolean', 'ID'].includes(a) || temporal.has(a) || a?.startsWith('Enum:')));
+  if (!supported || left.version || right.version) {
+    fail(`Incompatible field comparison: ${leftPath} (${a}) and ${rightPath} (${b})`);
+  }
+  if (text.has(operator) && a !== 'String') fail(`${operator} requires String operands`, 'INVALID_FILTER_OPERATOR');
+  if (ordered.has(operator) && !numeric && a !== 'String' && !temporal.has(a)) {
+    fail(`${operator} does not order ${a} operands`, 'INVALID_FILTER_OPERATOR');
+  }
+};

package/src/query-frames.js

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

package/src/query-operators.js

@@ -14,6 +14,7 @@ export {
 export {
   ANCHOR_KEY, GROUP_KEYS, IMPLICIT_KEY, aggregateJoinPrefixes, crossingKeys, frameCollectionPaths, frameUnits, validateQuantifiedGroups,
 } from './query-frames.js';
+export { hasValuePath, validateComparisonOperand, validateComparisonTypes } from './query-comparisons.js';
 export { effectiveScalarName } from './metadata.js';
 
 /** Every `QLOperator` value, in declaration order. QLOperator is the only list of operators. */
@@ -153,23 +154,23 @@ const invalidFeatures = (message) => {
 };
 
 /**
- * Reads an adapter's `queryFeatures` declaration into `{ operators, referenceEmptiness, quantifiers }`:
+ * Reads an adapter's `queryFeatures` declaration into `{ operators, referenceEmptiness, quantifiers, valuePath }`:
  * the operators it compiles and whether it compiles reference emptiness and collection frames.
  * Without a declaration (undefined or null) the adapter supports {@link LEGACY_QUERY_OPERATORS}
  * and neither feature. A declaration is an object whose `operators`
  * is an array of operator names, whose names this version does not know are ignored, and whose
- * optional `referenceEmptiness` and `quantifiers` are booleans, undefined or null (false). A name
+ * optional `referenceEmptiness`, `quantifiers` and `valuePath` are booleans, undefined or null (false). A name
  * counts once this version knows it: a declaration that listed `CONTAINS_ALL` or `IIN` before
  * #108 part 4 added them receives them on upgrade.
- * Quantifiers require reference emptiness for scoped joins. Other members are left for later
+ * Quantifiers and valuePath require reference emptiness for scoped joins. Other members are left for later
  * features. Anything else throws `INVALID_QUERY_FEATURES` (500).
  */
 export const resolveQueryFeatures = (queryFeatures) => {
-  if (queryFeatures == null) return { operators: new Set(LEGACY_QUERY_OPERATORS), referenceEmptiness: false, quantifiers: false };
+  if (queryFeatures == null) return { operators: new Set(LEGACY_QUERY_OPERATORS), referenceEmptiness: false, quantifiers: false, valuePath: false };
   if (typeof queryFeatures !== 'object' || Array.isArray(queryFeatures)) {
     invalidFeatures('must be an object with an operators array');
   }
-  const { operators, referenceEmptiness, quantifiers } = queryFeatures;
+  const { operators, referenceEmptiness, quantifiers, valuePath } = queryFeatures;
   if (!Array.isArray(operators) || operators.some((operator) => typeof operator !== 'string')) {
     invalidFeatures('operators must be an array of operator names');
   }
@@ -182,9 +183,12 @@ export const resolveQueryFeatures = (queryFeatures) => {
   if (quantifiers === true && referenceEmptiness !== true) {
     invalidFeatures('quantifiers require referenceEmptiness: true');
   }
+  if (valuePath != null && typeof valuePath !== 'boolean') invalidFeatures('valuePath must be a boolean');
+  if (valuePath === true && referenceEmptiness !== true) invalidFeatures('valuePath requires referenceEmptiness: true');
   return {
     operators: new Set(operators.filter(isQueryOperator)),
     referenceEmptiness: referenceEmptiness === true,
     quantifiers: quantifiers === true,
+    valuePath: valuePath === true,
   };
 };

package/src/query-plan.js

@@ -4,7 +4,7 @@ import { paginationStages } from './query-limits.js';
 import SimfinityError from './errors/simfinity.error.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 +45,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 +96,21 @@ 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 ? `${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;
+    }
+    const right = item.__operand ? item.__operand.path?.join('.') : operandPath(item, prefix);
+    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 +126,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) } : {}),
+      ...(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 +150,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 +165,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 +175,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 +215,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 +228,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,9 +310,12 @@ 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,
 } = {}) => {
   let input = source;
   const allowed = supported == null ? null : new Set(supported);
@@ -304,19 +327,23 @@ 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 }).where;
     }
     return lifted;
   };
@@ -338,7 +365,7 @@ 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 predicate = (path, operator, value, construct = null, frameEntity = entityName, inFrame = false, ancestors = [], prefix = '') => {
     const steps = resolveModelPath(models, frameEntity, path);
     const op = operator ?? 'EQ';
     if (isEmptinessOperator(op)) return emptiness(path, steps, op, value, construct, frameEntity);
@@ -348,6 +375,30 @@ export const createQueryPlan = (models, entityName, source = {}, {
     }
     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 rightPath = internal?.path ?? (prefix ? `${prefix}.${validateComparisonOperand(construct)}` : validateComparisonOperand(construct)).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 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]));
+      // 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)
+        .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));
+      }
+      if (internal && Object.hasOwn(internal, 'scopes')) {
+        node.operand.joins = liftScopes({ scopes: internal.scopes }, scopeTargets([rightPath], rightEntity), rightPath, op, anchors([rightPath], rightEntity));
+      }
+      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');
@@ -364,11 +415,13 @@ export const createQueryPlan = (models, entityName, source = {}, {
     }
     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, frameEntity = entityName, 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 +429,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, frameEntity, inFrame, ancestors));
     }
     if (quantifiers !== true && QUANTIFIED_LISTS.some((key) => value[key] != null)) {
       fail('Quantified groups are not supported by this query compiler', 'UNSUPPORTED_QUERY');
@@ -385,12 +438,12 @@ export const createQueryPlan = (models, entityName, source = {}, {
       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 node = { kind: 'quantified', quantifier, path, where: group(item, level, target, true, [...ancestors, frameEntity]), 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 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);
@@ -399,17 +452,18 @@ export const createQueryPlan = (models, entityName, source = {}, {
           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, frameEntity, inFrame, ancestors));
+    terms.push(combine('or', (value.OR || []).map((item) => group(item, level, frameEntity, 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 };
   const J = mode === 'aggregate' ? aggregateJoinPrefixes(input.aggregation, context) : new Set();
   context.J = J;
   validateQuantifiedGroups(input, context);
@@ -428,7 +482,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 +490,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, entityName, false, [], name));
     }
   }
   for (const item of input.AND || []) terms.push(group(item));

package/src/runtime.js

@@ -26,7 +26,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 +210,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));
@@ -243,9 +244,13 @@ 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 });
+        conditions.push({ field: itself ? `${prefix}.${name}` : `${prefix}.${name}.${term?.path}`, operator: term?.operator, value: term?.value,
+          ...(hasValuePath(term) ? { valuePath: `${prefix}.${name}.${term.valuePath}` } : {}),
+        });
       }
-    } 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 +604,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,
   } = 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 +740,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 +749,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 +775,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 +2299,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('.');
@@ -2400,7 +2408,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,
   J: operation === 'aggregate' ? aggregateJoinPrefixes(args.aggregation, { gqltype }) : new Set(),
   scopeMarkers: 'pending',
 });
@@ -2614,8 +2622,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 ? [...entry.segments.slice(0, -entry.relative.length), ...entry.valuePath.split('.')] : [];
+    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 +2667,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 ? [[...entry.segments.slice(0, -entry.relative.length), ...entry.valuePath.split('.')]] : [])];
+      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 +2745,11 @@ 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));
+        relations.push(...pathRelations(type, entry.valuePath.split('.')).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 +2758,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) {

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,8 @@ 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;
 }
 
 export interface ModelRegistration {
@@ -176,6 +184,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 +909,9 @@ 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 };
+
 /**
  * `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 +933,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 +991,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. Public inputs do not accept outer-frame syntax.
+ * 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.
+ *
  * `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 +1018,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 }): QueryPlan;
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
 
 /**