@quereus/quereus 4.13.1 → 4.15.2

package/dist/src/planner/mutation/capture-correlation.d.ts

@@ -0,0 +1,57 @@
+import type * as AST from '../../parser/ast.js';
+import type { TableSchema } from '../../schema/table.js';
+/**
+ * One identifying key column of a capture correlation, with its **declared**
+ * nullability. Key membership does not imply NOT NULL (docs/schema.md
+ * § Primary-key nullability), and key comparison treats NULL as a value equal to
+ * itself — so a capture reader correlating on a nullable key column must use the
+ * NULL-safe equality {@link captureKeyEquality} emits, or a row keyed NULL is
+ * silently unaddressable.
+ */
+export interface KeyColumnInfo {
+    readonly name: string;
+    /** True when the column's declared type admits NULL (`ColumnSchema.notNull === false`). */
+    readonly nullable: boolean;
+}
+/**
+ * Look one correlation key column up on its base schema (case-insensitively). An
+ * unknown column (defensive — every caller resolves the name off validated
+ * schema/advertisement metadata) reads as **nullable**, so a correlation over it
+ * falls back to the NULL-safe form: semantically identical for a NOT NULL column,
+ * merely less index-friendly. The one place declared nullability is read, so the
+ * decomposition write fan-out and the lens read body cannot drift apart on the
+ * gate that decides {@link captureKeyEquality}'s shape.
+ */
+export declare function keyColumnInfo(schema: TableSchema, name: string): KeyColumnInfo;
+/**
+ * Per-key-column equality for correlating two spellings of one key value — a
+ * capture (`__vmupd_keys`) reader to its target row, and equally a decomposition
+ * lens's stitch-key correlations (the get body's `anchor ⋈ member` ON condition
+ * and EAV entity subquery in `schema/lens-compiler.ts`, and the write fan-out's
+ * anchor EXISTS correlation in `decomposition.ts`):
+ *
+ * ```
+ * left = right                                    -- column declared NOT NULL
+ * left = right or (left is null and right is null) -- column declared nullable
+ * ```
+ *
+ * The nullability gate exists because SQL `=` yields UNKNOWN when either operand
+ * is NULL: a nullable key column needs the NULL-safe disjunction (NULL is a
+ * self-equal key value), while a NOT NULL column keeps the plain `=`, which
+ * stays index-friendly where a disjunction can cost the engine a seek. Sibling
+ * implementation: `planner/analysis/key-filter.ts` emits the same per-column
+ * shape for residual key filters (as plan nodes rather than AST).
+ *
+ * Operands are cloned into each emitted position, so a caller may pass the same
+ * node it uses elsewhere without sharing AST subtrees.
+ *
+ * NOTE: the gate reads the **declared** nullability, so a database run under
+ * `pragma default_column_nullability = nullable` declares every key column nullable
+ * and every capture correlation takes the disjunction — including the ones a NOT NULL
+ * default would have left as a seekable `=`. Correct either way, but if view writes
+ * under that pragma ever show up as slow, narrow the gate to the *reachable* nullability
+ * (a key column with a NOT NULL check, or one the body's predicate already excludes NULL
+ * on) rather than the declared one.
+ */
+export declare function captureKeyEquality(left: AST.Expression, right: AST.Expression, nullable: boolean): AST.Expression;
+//# sourceMappingURL=capture-correlation.d.ts.map

package/dist/src/planner/mutation/capture-correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-correlation.d.ts","sourceRoot":"","sources":["../../../../src/planner/mutation/capture-correlation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAG9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,GAAG,GAAG,CAAC,UAAU,CAUjH"}

package/dist/src/planner/mutation/capture-correlation.js

@@ -0,0 +1,57 @@
+import { cloneExpr } from './scope-transform.js';
+/**
+ * Look one correlation key column up on its base schema (case-insensitively). An
+ * unknown column (defensive — every caller resolves the name off validated
+ * schema/advertisement metadata) reads as **nullable**, so a correlation over it
+ * falls back to the NULL-safe form: semantically identical for a NOT NULL column,
+ * merely less index-friendly. The one place declared nullability is read, so the
+ * decomposition write fan-out and the lens read body cannot drift apart on the
+ * gate that decides {@link captureKeyEquality}'s shape.
+ */
+export function keyColumnInfo(schema, name) {
+    const col = schema.columns.find(c => c.name.toLowerCase() === name.toLowerCase());
+    return { name, nullable: !col || !col.notNull };
+}
+/**
+ * Per-key-column equality for correlating two spellings of one key value — a
+ * capture (`__vmupd_keys`) reader to its target row, and equally a decomposition
+ * lens's stitch-key correlations (the get body's `anchor ⋈ member` ON condition
+ * and EAV entity subquery in `schema/lens-compiler.ts`, and the write fan-out's
+ * anchor EXISTS correlation in `decomposition.ts`):
+ *
+ * ```
+ * left = right                                    -- column declared NOT NULL
+ * left = right or (left is null and right is null) -- column declared nullable
+ * ```
+ *
+ * The nullability gate exists because SQL `=` yields UNKNOWN when either operand
+ * is NULL: a nullable key column needs the NULL-safe disjunction (NULL is a
+ * self-equal key value), while a NOT NULL column keeps the plain `=`, which
+ * stays index-friendly where a disjunction can cost the engine a seek. Sibling
+ * implementation: `planner/analysis/key-filter.ts` emits the same per-column
+ * shape for residual key filters (as plan nodes rather than AST).
+ *
+ * Operands are cloned into each emitted position, so a caller may pass the same
+ * node it uses elsewhere without sharing AST subtrees.
+ *
+ * NOTE: the gate reads the **declared** nullability, so a database run under
+ * `pragma default_column_nullability = nullable` declares every key column nullable
+ * and every capture correlation takes the disjunction — including the ones a NOT NULL
+ * default would have left as a seekable `=`. Correct either way, but if view writes
+ * under that pragma ever show up as slow, narrow the gate to the *reachable* nullability
+ * (a key column with a NOT NULL check, or one the body's predicate already excludes NULL
+ * on) rather than the declared one.
+ */
+export function captureKeyEquality(left, right, nullable) {
+    const eq = { type: 'binary', operator: '=', left: cloneExpr(left), right: cloneExpr(right) };
+    if (!nullable)
+        return eq;
+    const bothNull = {
+        type: 'binary',
+        operator: 'AND',
+        left: { type: 'unary', operator: 'IS NULL', expr: cloneExpr(left) },
+        right: { type: 'unary', operator: 'IS NULL', expr: cloneExpr(right) },
+    };
+    return { type: 'binary', operator: 'OR', left: eq, right: bothNull };
+}
+//# sourceMappingURL=capture-correlation.js.map

package/dist/src/planner/mutation/capture-correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-correlation.js","sourceRoot":"","sources":["../../../../src/planner/mutation/capture-correlation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAgBjD;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,MAAmB,EAAE,IAAY;IAC9D,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAClF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAoB,EAAE,KAAqB,EAAE,QAAiB;IAChG,MAAM,EAAE,GAAmB,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7G,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,MAAM,QAAQ,GAAmB;QAChC,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAmB;QACpF,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,EAAmB;KACtF,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AACtE,CAAC"}

package/dist/src/planner/mutation/decomposition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decomposition.d.ts","sourceRoot":"","sources":["../../../../src/planner/mutation/decomposition.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decomposition.d.ts","sourceRoot":"","sources":["../../../../src/planner/mutation/decomposition.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/mutation/decomposition.js

@@ -1,7 +1,7 @@
 import { FilterNode } from '../nodes/filter.js';
 import { ProjectNode } from '../nodes/project-node.js';
 import { buildTableReference } from '../building/table.js';
-import { combineAnd } from './single-source.js';
+import { combineAnd, SELF_ALIAS } from './single-source.js';
 import { transformExpr, cloneExpr } from './scope-transform.js';
 import { buildExpression } from '../building/expression.js';
 import { columnSchemaToScalarType } from '../type-utils.js';
@@ -10,6 +10,7 @@ import { containsNonDeterministicCall } from '../analysis/check-extraction.js';
 import { FunctionFlags } from '../../common/constants.js';
 import { analyzeBodyLineage } from './backward-body.js';
 import { keyColumnName, capturedValueSubquery } from './multi-source.js';
+import { captureKeyEquality, keyColumnInfo } from './capture-correlation.js';
 import { raiseMutationDiagnostic } from './mutation-diagnostic.js';
 /**
  * Plan the synthesized get body **once** and read its threaded `updateLineage`
@@ -435,19 +436,26 @@ function decomposeDelete(ctx, view, shape, stmt) {
  * One member's delete. No predicate ⇒ an unconditional `delete from <member>`
  * (truncate the component — also the sound singleton path, which has no key to
  * thread). With an anchor predicate ⇒ `delete from <member> where
- * <memberKeyOrEntity> in (select <anchorKey> from <anchor> where <pred>)`.
+ * <memberKeyOrEntity> in (select <anchorKey> from <anchor> where <pred>)` — or
+ * the NULL-safe correlated EXISTS with the target aliased {@link SELF_ALIAS}
+ * when both stitch columns are nullable ({@link anchorKeyCorrelation}), so a
+ * NULL-keyed component row does not survive the fan-out as an orphan.
  */
 function memberDeleteOp(ctx, view, shape, member, pred, stmt) {
     let where;
+    let targetAlias;
     if (pred) {
         const memberCol = member.attributePivot
             ? member.attributePivot.entityColumn // EAV: delete every triple for the matched entities
             : singleKeyColumn(view, shape, member);
-        where = { type: 'in', expr: { type: 'column', name: memberCol }, subquery: anchorKeySubquery(shape, pred) };
+        const correlation = anchorKeyCorrelation(ctx, shape, member, memberCol, pred);
+        where = correlation.where;
+        targetAlias = correlation.targetAlias;
     }
     const statement = {
         type: 'delete',
         table: memberIdentifier(member),
+        alias: targetAlias,
         where,
         contextValues: stmt.contextValues,
         schemaPath: stmt.schemaPath,
@@ -754,19 +762,20 @@ function collectValueScopes(expr) {
     walk(expr);
     return { qualifiers, hasUnqualifiedColumn, hasSubquery };
 }
-/** `update <member> set <cols> where <memberKey> in (select <anchorKey> from <anchor> where <pred>)`. */
+/**
+ * `update <member> set <cols> where <memberKey> in (select <anchorKey> from <anchor>
+ * where <pred>)` — or the NULL-safe correlated EXISTS with the target aliased
+ * {@link SELF_ALIAS} when both stitch columns are nullable ({@link anchorKeyCorrelation}).
+ */
 function memberUpdateOp(ctx, view, shape, member, assignments, pred, stmt) {
     const memberKey = singleKeyColumn(view, shape, member);
-    const where = {
-        type: 'in',
-        expr: { type: 'column', name: memberKey },
-        subquery: anchorKeySubquery(shape, pred),
-    };
+    const correlation = anchorKeyCorrelation(ctx, shape, member, memberKey, pred);
     const statement = {
         type: 'update',
         table: memberIdentifier(member),
+        alias: correlation.targetAlias,
         assignments: assignments.map(a => ({ column: a.column, value: a.value })),
-        where,
+        where: correlation.where,
         contextValues: stmt.contextValues,
         schemaPath: stmt.schemaPath,
         loc: stmt.loc,
@@ -941,7 +950,7 @@ function emitCapturedMemberUpdate(ctx, view, shape, member, cells, pred, stmt, o
     // basis column so the two read-back sites (member key, anchor key) bind the same alias.
     const srcByCell = cells.map(c => registerCapturedExpr(`cap:${member.relationId.toLowerCase()}:${c.basisColumn.toLowerCase()}`, cloneExpr(c.value)));
     // Matched UPDATE (unfiltered over the present rows): each value read back by the member key.
-    ops.push(memberUpdateOp(ctx, view, shape, member, cells.map((c, i) => ({ column: c.basisColumn, value: capturedValueSubquery(srcByCell[i], 0, [memberKey]) })), pred, stmt));
+    ops.push(memberUpdateOp(ctx, view, shape, member, cells.map((c, i) => ({ column: c.basisColumn, value: capturedValueSubquery(srcByCell[i], 0, [keyColumnInfo(schema, memberKey)]) })), pred, stmt));
     // Materialize INSERT (filtered over the absent rows): each value read back by the anchor key.
     ops.push(buildCapturedMaterializeInsert(ctx, view, shape, member, cells, srcByCell, pred, stmt));
 }
@@ -963,6 +972,7 @@ function buildCapturedMaterializeInsert(ctx, view, shape, member, cells, srcByCe
     const ref = resolveMemberTable(ctx, member);
     const schema = ref.tableSchema;
     const anchorKey = singleKeyColumn(view, shape, shape.anchor);
+    const anchorKeyInfo = keyColumnInfo(resolveMemberTable(ctx, shape.anchor).tableSchema, anchorKey);
     const memberKey = singleKeyColumn(view, shape, member);
     const targetColumns = [memberKey];
     const projections = [
@@ -970,14 +980,14 @@ function buildCapturedMaterializeInsert(ctx, view, shape, member, cells, srcByCe
     ];
     cells.forEach((c, i) => {
         targetColumns.push(c.basisColumn);
-        projections.push({ type: 'column', expr: capturedValueSubquery(srcByCell[i], 0, [anchorKey]) });
+        projections.push({ type: 'column', expr: capturedValueSubquery(srcByCell[i], 0, [anchorKeyInfo]) });
     });
     assertNoMissingNotNull(view, schema, targetColumns.map((baseColumn) => ({ baseColumn })));
     // Non-empty image filter: OR over each captured value (read back by the anchor key) being
     // non-null. A fresh `capturedValueSubquery` per disjunct (distinct AST nodes from the
     // projections') keeps the filter self-contained.
     const nonEmpty = cells
-        .map((_, i) => ({ type: 'unary', operator: 'IS NOT NULL', expr: capturedValueSubquery(srcByCell[i], 0, [anchorKey]) }))
+        .map((_, i) => ({ type: 'unary', operator: 'IS NOT NULL', expr: capturedValueSubquery(srcByCell[i], 0, [anchorKeyInfo]) }))
         .reduce((acc, e) => acc ? { type: 'binary', operator: 'OR', left: acc, right: e } : e);
     const where = combineAnd(pred ? cloneExpr(pred) : undefined, nonEmpty);
     const select = {
@@ -1327,34 +1337,34 @@ function emitEavCapturedAttr(ctx, view, shape, member, pivot, cell, pred, stmt,
     // so both read-back sites (entity column, anchor key) bind the same alias.
     const srcAlias = registerCapturedExpr(`cap:${member.relationId.toLowerCase()}:attr:${cell.attribute.toLowerCase()}`, cloneExpr(cell.value));
     // Matched UPDATE: existing triples read the captured value back by the entity column.
-    ops.push(buildEavAttrOp(ctx, view, shape, member, pivot, cell, pred, stmt, 'update', capturedValueSubquery(srcAlias, 0, [pivot.entityColumn])));
+    ops.push(buildEavAttrOp(ctx, view, shape, member, pivot, cell, pred, stmt, 'update', capturedValueSubquery(srcAlias, 0, [keyColumnInfo(resolveMemberTable(ctx, member).tableSchema, pivot.entityColumn)])));
     // Materialize INSERT: entities lacking the triple, value read back by the anchor key, non-null filtered.
     ops.push(buildEavCapturedInsert(ctx, view, shape, member, pivot, cell, srcAlias, pred, stmt));
 }
 /**
  * One matched EAV op for an attribute: `update <pivot> set <valCol> = <value>` (upsert
  * value branch) or `delete from <pivot>` (null branch), each scoped
- * `where <attrCol> = '<attribute>' and <entityCol> in (<anchor subquery>)`. `valueOverride`
+ * `where <attrCol> = '<attribute>' and <entityCol> in (<anchor subquery>)` — the entity
+ * correlation taking the NULL-safe EXISTS form (target aliased {@link SELF_ALIAS}) when
+ * both the entity column and the anchor key are nullable ({@link anchorKeyCorrelation});
+ * the attribute conjunct compares a non-null literal and stays plain `=`. `valueOverride`
  * supplies the matched-UPDATE value for a `captured` cell (the `__vmupd_keys` read-back correlated
  * by the entity column); absent, the cell's own lowered value is used (the `constant` branch).
  */
 function buildEavAttrOp(ctx, view, shape, member, pivot, cell, pred, stmt, op, valueOverride) {
-    const where = combineAnd(eavAttrEquals(pivot, cell.attribute), {
-        type: 'in',
-        expr: { type: 'column', name: pivot.entityColumn },
-        subquery: anchorKeySubquery(shape, pred),
-    });
+    const correlation = anchorKeyCorrelation(ctx, shape, member, pivot.entityColumn, pred);
+    const where = combineAnd(eavAttrEquals(pivot, cell.attribute), correlation.where);
     const table = memberIdentifier(member);
     const resolved = resolveMemberTable(ctx, member);
     if (op === 'delete') {
         const statement = {
-            type: 'delete', table, where,
+            type: 'delete', table, alias: correlation.targetAlias, where,
             contextValues: stmt.contextValues, schemaPath: stmt.schemaPath, loc: stmt.loc,
         };
         return { table: resolved, op: 'delete', statement };
     }
     const statement = {
-        type: 'update', table,
+        type: 'update', table, alias: correlation.targetAlias,
         assignments: [{ column: pivot.valueColumn, value: valueOverride ?? cloneExpr(cell.value) }],
         where,
         contextValues: stmt.contextValues, schemaPath: stmt.schemaPath, loc: stmt.loc,
@@ -1426,8 +1436,9 @@ function buildEavInsertSelect(ctx, view, shape, member, pivot, cell, pred, stmt,
 function buildEavCapturedInsert(ctx, view, shape, member, pivot, cell, srcAlias, pred, stmt) {
     const ref = resolveMemberTable(ctx, member);
     const anchorKey = singleKeyColumn(view, shape, shape.anchor);
+    const anchorKeyInfo = keyColumnInfo(resolveMemberTable(ctx, shape.anchor).tableSchema, anchorKey);
     // A fresh read-back subquery per use (projection + filter) — distinct AST nodes.
-    const capturedVal = () => capturedValueSubquery(srcAlias, 0, [anchorKey]);
+    const capturedVal = () => capturedValueSubquery(srcAlias, 0, [anchorKeyInfo]);
     const projections = [
         { type: 'column', expr: { type: 'column', name: anchorKey, table: shape.anchor.relationId } },
         { type: 'column', expr: { type: 'literal', value: cell.attribute } },
@@ -1627,6 +1638,58 @@ function anchorKeySubquery(shape, pred) {
         where: pred ? cloneExpr(pred) : undefined,
     };
 }
+/**
+ * The identifying correlation a member op routes on: `<memberCol> in (select <anchorKey>
+ * from <anchor> [where <pred>])` when either stitch column is declared NOT NULL, or the
+ * NULL-safe correlated `exists (select 1 from <anchor> where [<pred> and] <per-column
+ * {@link captureKeyEquality}>)` when **both** are nullable — NULL is a self-equal key
+ * value (docs/schema.md § Primary-key nullability), and `NULL IN (…)` is UNKNOWN, so
+ * the IN shape leaves a NULL-keyed member row unreachable (an update misses it; a
+ * fan-out delete strands it as an orphan). The both-sides gate keeps the emitted
+ * statement byte-identical to the legacy IN form for any schema whose stitch key is
+ * NOT NULL on either side. `memberCol` is the member's stitch key, or the EAV pivot's
+ * entity column.
+ *
+ * On the EXISTS branch the member operand is qualified with {@link SELF_ALIAS} — under
+ * a logical-tuple key the anchor and member key columns are spelled identically, so a
+ * bare ref inside the subquery would bind the anchor's column, not the outer target
+ * row. The caller must stamp the returned `targetAlias` onto the emitted UPDATE/DELETE
+ * (`stmt.alias` → `AliasedScope`, `building/update.ts` / `building/delete.ts`);
+ * `targetAlias` is undefined on the IN branch so NOT NULL schemas keep an alias-free
+ * statement. Composite stitch keys are deferred by {@link singleKeyColumn}, so the
+ * per-column shape degenerates to one column here.
+ *
+ * NOTE: the EXISTS branch is **correlated**, so unlike the uncorrelated IN subquery it
+ * cannot be evaluated once per statement. The anchor's own value-column UPDATE routes
+ * through here too (it is a mandatory member of its own fan-out) and so self-correlates
+ * against the table it writes — where {@link anchorDeleteOp} sidesteps the same shape by
+ * applying the bare predicate. Not measured; if a nullable-stitch-key lens write ever
+ * shows up in profiles, give the anchor member the bare-predicate form the delete side
+ * already uses, and consider a NULL-safe uncorrelated membership shape for the rest.
+ */
+function anchorKeyCorrelation(ctx, shape, member, memberCol, pred) {
+    const anchorKey = singleKeyColumn(undefined, shape, shape.anchor);
+    const anchorInfo = keyColumnInfo(resolveMemberTable(ctx, shape.anchor).tableSchema, anchorKey);
+    const memberInfo = keyColumnInfo(resolveMemberTable(ctx, member).tableSchema, memberCol);
+    if (!(anchorInfo.nullable && memberInfo.nullable)) {
+        return {
+            where: { type: 'in', expr: { type: 'column', name: memberCol }, subquery: anchorKeySubquery(shape, pred) },
+        };
+    }
+    const keyEq = captureKeyEquality({ type: 'column', name: anchorKey, table: shape.anchor.relationId }, { type: 'column', name: memberCol, table: SELF_ALIAS }, true);
+    return {
+        where: {
+            type: 'exists',
+            subquery: {
+                type: 'select',
+                columns: [{ type: 'column', expr: { type: 'literal', value: 1 } }],
+                from: [{ ...memberIdentifierSource(shape.anchor), alias: shape.anchor.relationId }],
+                where: combineAnd(pred ? cloneExpr(pred) : undefined, keyEq),
+            },
+        },
+        targetAlias: SELF_ALIAS,
+    };
+}
 /**
  * Substitute references to logical columns (unqualified, or qualified by the
  * logical table's own name) with their backing get-body expression. Base-member-