@component-compass/reference-graph 0.1.15 → 0.1.18

package/dist/engine/wrapper-folding.js

@@ -1,9 +1,21 @@
 import { resolveType, resolveToFunctions, DYNAMIC_MEMBER_KEY } from "./resolve-type.js";
+import { argumentRefKey } from "./argument-map.js";
 import { createCycleGuard } from "./cycle-detection.js";
-import { fileGraphForRef } from "./resolve-reference.js";
+import { fileGraphForRef, resolveReference } from "./resolve-reference.js";
 import { packageNameFromSpecifier } from "./specifier.js";
 import { followReExportChain } from "./re-export-chain.js";
-import { unparsedMemberDefinition, effectiveExportName } from "./member-identity.js";
+import { unparsedMemberDefinition, effectiveExportName, residualMemberChain, compoundExportName } from "./member-identity.js";
+import { evalKind, isImportBackedLeaf } from "./component-shape.js";
+import { assertNever } from "./assert-never.js";
+/** Ruling 19: true when a `ReturnTypeOf`'s callee is a data-method render
+ *  call (`items.map(render)`) rather than a wrapper taking a component as a
+ *  prop — the exact structural condition `component-shape.ts`'s rule (ii)
+ *  uses to answer `"jsx"` instead of `"component"`. Shared, not re-derived:
+ *  a `MemberOf` callee that is NOT an import-backed leaf (`Sentry.x` stays a
+ *  wrapper; `items.map`/a hook result/a parameter does not). */
+function isDataMethodRenderCall(type, graph, fileGraph, guard) {
+    return type.callee.kind === "MemberOf" && !isImportBackedLeaf(type.callee, graph, fileGraph, guard);
+}
 /**
  * THE single seam for unreducible-leaf identity synthesis (#135 / #274).
  *
@@ -13,7 +25,8 @@ import { unparsedMemberDefinition, effectiveExportName } from "./member-identity
  * synthesize a JSX terminal carrying the identity derived FROM THE TERMINAL
  * ITSELF: the reference is real even though its target can't be parsed
  * (external package, CJS, unresolvable specifier). Every other terminal
- * derives identity from `source ?? fallback`, exactly as before.
+ * derives identity from `source`, falling back to `fallback` only when the
+ * branch itself carries none.
  *
  * Do NOT re-derive this salvage logic at individual fold sites — call this
  * seam. Named in docs/CONTEXT.md ("unreducible-leaf identity synthesis").
@@ -26,27 +39,69 @@ function foldTerminals(graph, fileGraph, results, fallback) {
                 return { type: { kind: "JSX" }, viaTrail: [], identity };
             }
         }
+        // A fan-out branch (Union / dynamic-map) is stamped as `source`. Derive
+        // from it FIRST — a branch that has its own binding must win (#131) —
+        // and only fall back to the resolved binding when the branch carries no
+        // identity of its own (e.g. a bare `{kind:"JSX"}` branch from a lowered
+        // ternary/logical render body). Committing to `source ?? fallback` before
+        // deriving discarded the fallback entirely once any fanout occurred, even
+        // when the branch itself resolved to nothing.
+        const identity = (source && deriveIdentity(source, fileGraph, graph)) ?? deriveIdentity(fallback, fileGraph, graph);
         return {
             type: t,
             viaTrail: [],
-            identity: deriveIdentity(source ?? fallback, fileGraph, graph),
+            identity,
         };
     });
 }
 /**
- * Build the `hoc-wrapper` via for a ReturnTypeOf wrapper call. The via.import
- * names the wrapped last arg (imported binding when there is one, else the
- * anonymous-arg resolution); hocCallee names the wrapper. Shared by the
- * pass-through recovery (step 3b) and the opaque HOC fallback (step 4) so both
- * paths attribute composition identically.
+ * Fold a wrapper call to its wrapped argument's terminals. Shared by the
+ * structural pass-through step (2b) and the opaque-HOC fallback (step 4) so
+ * a seen-through wrapper and an opaque one attribute identically. Inner
+ * terminals pass through with the wrapper hop prepended. When the inner walk
+ * bottomed out at Unknown but carried an identity hint (imported, or
+ * local-promoted via #101), synthesise a JSX terminal from it — without this
+ * rescue, HOC-wrapped occurrences drop silently (~128 in example-web's
+ * connect/flow/withTranslators patterns, diagnosed on PR #141). Truly
+ * nothing → a single Unknown terminal, as before.
  */
-function buildHocVia(type, lastArg, fileGraph) {
-    const hocCallee = deriveHocCallee(type.callee);
-    const importRecord = findImportForLastArg(lastArg, fileGraph);
+function foldToWrappedArg(inner, via) {
+    const innerHasNonUnknown = inner.some((t) => t.type.kind !== "Unknown");
+    if (innerHasNonUnknown) {
+        return inner.map((t) => ({ type: t.type, viaTrail: [via, ...t.viaTrail], identity: t.identity }));
+    }
+    const synthesisIdentity = inner.find((t) => t.identity !== null)?.identity ?? null;
+    if (synthesisIdentity) {
+        return [{ type: { kind: "JSX" }, viaTrail: [via], identity: synthesisIdentity }];
+    }
+    return [{ type: { kind: "Unknown" }, viaTrail: [], identity: null }];
+}
+/**
+ * Provenance of ONE argument of a wrapper call: the wrapper's `callee` name
+ * and the `{ specifier, import }` pair naming the argument's own binding —
+ * its import record when it is import-backed, else the anonymous-argument
+ * resolution. THE single helper for both via kinds that describe a wrapped
+ * argument (`hoc-wrapper` when the wrapper folds to the argument,
+ * `passed-as-argument` when the holder is its own identity and the argument
+ * is seeded at its site — spec §4), so the two name a binding identically.
+ * Never re-derive `{ specifier, import }` for an argument elsewhere.
+ */
+export function argumentProvenance(type, arg, fileGraph) {
+    const importRecord = findImportForLastArg(arg, fileGraph);
     const resolved = importRecord
         ? { specifier: importRecord.specifier, import: importRecord.imported }
-        : resolveAnonymousLastArg(lastArg, fileGraph);
-    return { kind: "hoc-wrapper", hocCallee, specifier: resolved.specifier, import: resolved.import };
+        : resolveAnonymousLastArg(arg, fileGraph);
+    return { callee: deriveHocCallee(type.callee), specifier: resolved.specifier, import: resolved.import };
+}
+/**
+ * Build the `hoc-wrapper` via for a ReturnTypeOf wrapper call. Shared by the
+ * structural pass-through (step 2b), the pass-through recovery (step 3b) and
+ * the opaque HOC fallback (step 4) so all three paths attribute composition
+ * identically; the binding is named through `argumentProvenance`.
+ */
+function buildHocVia(type, lastArg, fileGraph) {
+    const { callee, specifier, import: imported } = argumentProvenance(type, lastArg, fileGraph);
+    return { kind: "hoc-wrapper", hocCallee: callee, specifier, import: imported };
 }
 /**
  * Stable comparison key for a TerminalIdentity. Mirrors the collapse rule in
@@ -71,9 +126,13 @@ function identityKey(id) {
  * returns a DIFFERENT component fails this and keeps its richer algebra result.
  */
 function isPassThroughWrapper(algResult, inner) {
-    const innerKeys = new Set(inner.filter((t) => t.type.kind !== "Unknown").map((t) => identityKey(t.identity)));
+    const innerKeys = new Set(inner.filter((t) => t.type.kind !== "Unknown" && t.identity !== null).map((t) => identityKey(t.identity)));
     const algKeys = algResult.filter((t) => t.type.kind !== "Unknown");
-    return algKeys.length > 0 && algKeys.every((t) => innerKeys.has(identityKey(t.identity)));
+    // A null identity on either side is "no information", never a match — the
+    // old null-equals-null comparison folded factory calls onto their
+    // rehydrate/config argument once the callee unwrap stopped inventing an
+    // identity for the algebra side.
+    return algKeys.length > 0 && algKeys.every((t) => t.identity !== null && innerKeys.has(identityKey(t.identity)));
 }
 /**
  * Walker layered above `resolveType`. Applies three folding rules
@@ -87,7 +146,21 @@ function isPassThroughWrapper(algResult, inner) {
  *
  * See spec: docs/superpowers/specs/2026-05-19-wrapper-folding-engine-extension-design.md §4.3
  */
-export function walkWithFolding(graph, fileGraph, type, argMap, guard = createCycleGuard()) {
+export function walkWithFolding(graph, fileGraph, type, argMap, guard = createCycleGuard(), 
+// Ruling 20: the identity `foldTerminals` falls back to when a terminal
+// carries no identity of its own (no `source`, no unreducible TypeOf/
+// DynamicImport leaf). Defaults to `type` (the walked node itself) —
+// unchanged behaviour for every caller that doesn't pass this. The
+// `Function` arm below is the ONE place that overrides it: a component's
+// own return (`return priceElement;`, `return contactModals;` — a bare
+// JSX-value alias or a hook-return leaf) must keep deriving identity as
+// "nothing", so the engine's own fallback (the rendered declaration, e.g.
+// `OfferPrice`) wins — never a same-file local alias like `priceElement`
+// that happens to sit in `foldTerminals`' fallback slot. Per-branch
+// identity from a fanout `source` (#131 — Union([TypeOf A, TypeOf B])) is
+// untouched: `source` is checked BEFORE this fallback in `foldTerminals`.
+identityFallback) {
+    const fallback = identityFallback ?? type;
     switch (type.kind) {
         case "ReturnTypeOf":
             return walkReturnTypeOf(graph, fileGraph, type, argMap, guard);
@@ -95,13 +168,165 @@ export function walkWithFolding(graph, fileGraph, type, argMap, guard = createCy
             if (type.member === DYNAMIC_MEMBER_KEY) {
                 return walkDynamicMember(graph, fileGraph, type, argMap, guard);
             }
-            // Static member access — fall through to default handling.
-            {
-                return foldTerminals(graph, fileGraph, resolveType(graph, fileGraph, type, argMap, guard), type);
-            }
-        default: {
-            return foldTerminals(graph, fileGraph, resolveType(graph, fileGraph, type, argMap, guard), type);
+            return walkStaticMember(graph, fileGraph, type, argMap, guard, fallback);
+        case "Function":
+            // Ruling 19: a component's own returns can contain a nested
+            // ReturnTypeOf/MemberOf (`List = ({items}) => items.map(render)`) that
+            // needs wrapper-folding's steps (the opaque-callee / dynamic-map
+            // handling below), not `resolveType`'s plain algebra — `resolveType`'s
+            // own "Function" case recurses via plain `resolveType`, which never
+            // re-enters this walk, so a JSX usage resolving to such a Function
+            // (e.g. `<List/>`) silently produced zero occurrences before this.
+            // Mirrors `resolveType`'s "Function" case, one level up. Ruling 20:
+            // pass THIS Function as the identity fallback for every return — a
+            // Function is never TypeOf/DynamicImport, so `deriveIdentity` on it
+            // is always null, matching the pre-ruling-19 semantics this restores.
+            return type.returns.flatMap((r) => walkWithFolding(graph, fileGraph, r, argMap, guard, type));
+        case "TypeOf":
+            return walkTypeOf(graph, fileGraph, type, argMap, guard, fallback);
+        case "Union":
+            // Structural re-entry (D1/D3): each branch walks through the walker so
+            // a TypeOf branch reaches `walkTypeOf` and decides its own identity
+            // (per-branch attribution, #131) while a bare JSX branch — a lowered
+            // ternary/logical render body — derives from the outer fallback exactly
+            // as the algebra's `source ?? fallback` did.
+            return type.types.flatMap((branch) => walkWithFolding(graph, fileGraph, branch, argMap, guard, fallback));
+        case "ParameterOf":
+        case "DynamicImport":
+        case "Object":
+        case "Array":
+        case "JSX":
+        case "Str":
+        case "Unknown":
+            return foldLeaf(graph, fileGraph, type, argMap, guard, fallback);
+        default:
+            return assertNever(type);
+    }
+}
+/**
+ * The leaf fold: pure algebra, then identity synthesis through the ONE
+ * unreducible-leaf seam (`foldTerminals`). This is the only place the walker
+ * hands a subtree to `resolveType`; every structural kind (TypeOf, Union,
+ * MemberOf, Function, ReturnTypeOf) has its own arm above and re-enters
+ * `walkWithFolding` instead.
+ */
+function foldLeaf(graph, fileGraph, type, argMap, guard, fallback) {
+    return foldTerminals(graph, fileGraph, resolveType(graph, fileGraph, type, argMap, guard), fallback);
+}
+/**
+ * THE seam for "walk a Function in its authoring file" (spec D4). A Function
+ * declared in another module must walk in THAT module's graph, because the
+ * walker's file-scoped lookups inside it — a dynamic map's binding
+ * (`findMapBinding`), an import table — only resolve where the code was
+ * written. Originally `walkDispatcherReturns`' rationale (#136): a
+ * cross-module `function getMapped(k) { return MAP[k]; }` walked in the
+ * caller's fileGraph misses `MAP` entirely and loses the `dynamic-map` hop.
+ * `walkTypeOf` needs the identical switch, so it is one function, not two.
+ * Falls back to the caller's graph when the file is absent or unindexed.
+ */
+function fileGraphForFunction(graph, fileGraph, fn) {
+    return fn.enclosingBinding?.file && fn.enclosingBinding.file !== fileGraph.filePath
+        ? (graph.files.get(fn.enclosingBinding.file) ?? fileGraph)
+        : fileGraph;
+}
+/**
+ * Structural re-entry for a reference (spec D1–D4, D6; #521). Resolves ONE
+ * hop and walks the resolved value through `walkWithFolding`, so every walker
+ * rule — wrapper hops, dynamic maps, Ruling 19's `.map()` bodies — applies
+ * through an alias exactly as at a direct render site. Before this arm the
+ * default fold handed the whole subtree to `resolveType`, which never comes
+ * back, so a map-bodied `List` reached via `MAP[k]` died as Unknown.
+ *
+ * Identity (D2): a terminal that comes back with no identity of its own is
+ * stamped with THIS reference's identity only when the reference names a
+ * component-shaped value — `evalKind === "component"`, the one component-
+ * shape seam, called not re-derived. A reference to a JSX value
+ * (`return priceElement`) or to a parameter binding stays null so the outer
+ * fallback wins: Ruling 20 by construction rather than by special case.
+ *
+ * An import the graph cannot see (`resolved` is Unknown) is NOT re-entered
+ * (D6): it is the identity-bearing leaf `foldLeaf` synthesises from
+ * (#135/#274), and `foldToWrappedArg`'s rescue relies on that shape.
+ *
+ * Cross-file (D4): a Function authored elsewhere walks in ITS file graph
+ * through the `fileGraphForFunction` seam — the same switch
+ * `walkDispatcherReturns` makes — so file-scoped lookups inside it (a dynamic
+ * map's binding) resolve where they were written.
+ *
+ * Cycle guard: mirrors `resolveType`'s node guard. `const A = B; const B = A`
+ * is legal JS and would otherwise re-enter forever.
+ */
+function walkTypeOf(graph, fileGraph, type, argMap, guard, fallback) {
+    if (guard.pushNode(type) === "cycle") {
+        return [{ type: { kind: "Unknown" }, viaTrail: [], identity: null }];
+    }
+    try {
+        const resolved = resolveReference(graph, fileGraph, type.ref, guard);
+        if (resolved.kind === "Unknown") {
+            // Pop before delegating: foldLeaf re-enters `resolveType`, which pushes
+            // this SAME node onto the guard's path again — leaving it pushed here
+            // would self-collide as a spurious cycle (guard tracks by object
+            // identity) on every import-backed leaf, not just real cycles. The
+            // `finally` below still runs (a no-op double pop) once this returns.
+            guard.popNode(type);
+            return foldLeaf(graph, fileGraph, type, argMap, guard, fallback);
+        }
+        const innerGraph = resolved.kind === "Function" ? fileGraphForFunction(graph, fileGraph, resolved) : fileGraph;
+        const inner = walkWithFolding(graph, innerGraph, resolved, argMap, guard, fallback);
+        if (inner.every((t) => t.identity !== null))
+            return inner;
+        const self = resolved.kind !== "ParameterOf" && evalKind(resolved, graph, innerGraph, argMap) === "component"
+            ? deriveIdentity(type, fileGraph, graph)
+            : null;
+        const stamp = self ?? deriveIdentity(fallback, fileGraph, graph);
+        return inner.map((t) => (t.identity === null ? { type: t.type, viaTrail: t.viaTrail, identity: stamp } : t));
+    }
+    finally {
+        guard.popNode(type);
+    }
+}
+/**
+ * Static member access (spec D5; #512). Mirrors `walkDynamicMember` for one
+ * named prop and without the `dynamic-map` hop: resolve the object, take the
+ * member, walk the member's VALUE through `walkWithFolding` — so a wrapper
+ * product stored in a map (`MAP.memo` → `memo(Button)`) reaches
+ * `walkReturnTypeOf` and keeps its `hoc-wrapper` hop. Anything that is not an
+ * in-graph Object (an Array, an import-backed namespace the graph cannot see)
+ * takes the leaf fold exactly as before.
+ *
+ * Cycle guard: mirrors `walkTypeOf`. `const A = { Item: () => B.Item };
+ * const B = { Item: () => A.Item }` is legal, loadable JS and the walk
+ * re-enters this arm forever without it — `resolveType` pops every node it
+ * pushes, so nothing on such a cycle stays on the guard's path otherwise.
+ */
+function walkStaticMember(graph, fileGraph, type, argMap, guard, fallback) {
+    if (guard.pushNode(type) === "cycle") {
+        return [{ type: { kind: "Unknown" }, viaTrail: [], identity: null }];
+    }
+    try {
+        const objects = resolveType(graph, fileGraph, type.obj, argMap, guard)
+            .map((r) => r.type)
+            .filter((t) => t.kind === "Object");
+        if (objects.length === 0) {
+            // Pop before delegating: foldLeaf re-enters `resolveType`, which pushes
+            // this SAME node onto the guard's path again — leaving it pushed here
+            // would self-collide as a spurious cycle (guard tracks by object
+            // identity), not just on real cycles. The `finally` below still runs
+            // (a no-op double pop) once this returns.
+            guard.popNode(type);
+            return foldLeaf(graph, fileGraph, type, argMap, guard, fallback);
         }
+        const out = [];
+        for (const obj of objects) {
+            const value = obj.props[type.member];
+            if (value === undefined)
+                continue;
+            out.push(...walkWithFolding(graph, fileGraph, value, argMap, guard, fallback));
+        }
+        return out.length > 0 ? out : [{ type: { kind: "Unknown" }, viaTrail: [], identity: null }];
+    }
+    finally {
+        guard.popNode(type);
     }
 }
 function walkReturnTypeOf(graph, fileGraph, type, argMap, guard) {
@@ -172,6 +397,23 @@ function walkReturnTypeOf(graph, fileGraph, type, argMap, guard) {
     const dispatcherResult = walkDispatcherReturns(graph, fileGraph, type, argMap, guard);
     if (dispatcherResult)
         return dispatcherResult;
+    // (2b) Structural pass-through (spec D9 arm 1; #328). When every Function
+    // the callee resolves to returns its own parameter (a bare `ParameterOf`, or a `TypeOf` that resolves to one) bound by THIS call,
+    // the wrapper is identity-preserving by construction — `c => c`; React's
+    // memo/forwardRef reach this arm through a library stub table, regardless
+    // of import spelling (named, default, or namespace). Fold straight to that argument and record the wrapper as a
+    // hoc-wrapper hop. Decided from the callee's shape, never from whether the
+    // algebra happened to succeed, so a local wrapped component and an external
+    // one attribute identically. Folding goes through `foldToWrappedArg`, the
+    // same tail step 4 uses, so both arms synthesise identity identically.
+    const passThroughIndex = passThroughParameterIndex(graph, fileGraph, type, argMap, guard);
+    if (passThroughIndex !== null) {
+        const wrapped = type.args[passThroughIndex];
+        if (wrapped !== undefined) {
+            const inner = walkWithFolding(graph, fileGraph, wrapped, argMap, guard);
+            return foldToWrappedArg(inner, buildHocVia(type, wrapped, fileGraph));
+        }
+    }
     // (3) Pure algebra walk. Per-leaf identity uses each terminal's source
     // (the leaf at the innermost fanout fork that produced it) so dynamic-map /
     // Union / Array fanouts attribute each branch to its own binding instead
@@ -209,30 +451,57 @@ function walkReturnTypeOf(graph, fileGraph, type, argMap, guard) {
         return [{ type: { kind: "Unknown" }, viaTrail: [], identity: null }];
     }
     const inner = walkWithFolding(graph, fileGraph, lastArg, argMap, guard);
-    const innerHasNonUnknown = inner.some((t) => t.type.kind !== "Unknown");
-    const via = buildHocVia(type, lastArg, fileGraph);
-    if (innerHasNonUnknown) {
-        // Inner resolved to JSX terminal(s): inherit identity from inner.
-        return inner.map((t) => ({
-            type: t.type,
-            viaTrail: [via, ...t.viaTrail],
-            identity: t.identity,
-        }));
-    }
-    // Wrapped target with a known identity: inner couldn't resolve to JSX
-    // (algebra failed — common for opaque HOCs), but if we have an identity
-    // hint (imported OR local-promoted via #101), synthesize a JSX terminal.
-    // Matches engine/index.ts's sentinel pattern for non-graph external imports
-    // AND covers the in-graph case where #101 promoted the inner identity from
-    // `imported` to `local` (without this, ~128 HOC-wrapped occurrences in
-    // example-web's connect/flow/withTranslators patterns drop silently —
-    // diagnosed via location-set diff on PR #141).
-    const synthesisIdentity = inner.find((t) => t.identity !== null)?.identity ?? null;
-    if (synthesisIdentity) {
-        return [{ type: { kind: "JSX" }, viaTrail: [via], identity: synthesisIdentity }];
+    // Ruling 19: a data-method render call (`items.map(render)`) is not a
+    // wrapper — its result IS the callback's rendered JSX, not a component
+    // received as a prop. Return the callback's terminals AS-IS: no
+    // `hoc-wrapper` hop, and identity stays null so the engine's own fallback
+    // (the declaration being walked, e.g. `List`) wins rather than whatever
+    // the callback itself happened to resolve to. Import-backed MemberOf
+    // callees (`Sentry.withProfiler`) fall through to the existing fold+hop
+    // below — arm 3 (D9) stands for those.
+    if (isDataMethodRenderCall(type, graph, fileGraph, guard)) {
+        const nonUnknown = inner.filter((t) => t.type.kind !== "Unknown");
+        if (nonUnknown.length > 0) {
+            return nonUnknown.map((t) => ({ type: t.type, viaTrail: t.viaTrail, identity: null }));
+        }
+        return [{ type: { kind: "Unknown" }, viaTrail: [], identity: null }];
     }
-    // Truly nothing — preserve the original "no useful identity" behaviour.
-    return [{ type: { kind: "Unknown" }, viaTrail: [], identity: null }];
+    return foldToWrappedArg(inner, buildHocVia(type, lastArg, fileGraph));
+}
+/**
+ * Index of the argument an identity-preserving wrapper returns, or null when
+ * the callee is not structurally pass-through. Pass-through means: every
+ * Function the callee resolves to has ≥1 return, every return reduces (bare, or
+ * a `TypeOf` resolved one hop) to a `ParameterOf` whose `fn` is the ref this
+ * call binds args to (`bindingRef`), and every return names the same index.
+ * Unions, JSX, nested Functions or an unresolvable callee all yield null so the
+ * existing algebra / opaque-HOC paths handle them exactly as before.
+ */
+function passThroughParameterIndex(graph, fileGraph, type, argMap, guard) {
+    const calleeFns = resolveToFunctions(graph, fileGraph, type.callee, argMap, guard);
+    if (calleeFns.length === 0)
+        return null;
+    let index = null;
+    for (const { fn, bindingRef } of calleeFns) {
+        if (fn.kind !== "Function" || bindingRef === null || fn.returns.length === 0)
+            return null;
+        const boundKey = argumentRefKey(bindingRef);
+        for (const ret of fn.returns) {
+            // The parser lowers `(C) => C` to a TypeOf return whose ref names the
+            // parameter binding; the ParameterOf lives on that binding's declaration
+            // in the function's body scope. Resolve one hop so real parser output
+            // reaches this arm, not only hand-built graphs.
+            const leaf = ret.kind === "TypeOf" ? resolveReference(graph, fileGraph, ret.ref, guard) : ret;
+            if (leaf.kind !== "ParameterOf")
+                return null;
+            if (argumentRefKey(leaf.fn) !== boundKey)
+                return null;
+            if (index !== null && index !== leaf.index)
+                return null;
+            index = leaf.index;
+        }
+    }
+    return index;
 }
 /**
  * Cross-module dispatcher walk (#136). When the callee of a ReturnTypeOf
@@ -257,9 +526,7 @@ function walkDispatcherReturns(graph, fileGraph, type, argMap, guard) {
     for (const { fn, bindingRef } of calleeFns) {
         if (fn.kind !== "Function")
             continue;
-        const fnFileGraph = fn.enclosingBinding?.file && fn.enclosingBinding.file !== fileGraph.filePath
-            ? (graph.files.get(fn.enclosingBinding.file) ?? fileGraph)
-            : fileGraph;
+        const fnFileGraph = fileGraphForFunction(graph, fileGraph, fn);
         if (bindingRef)
             argMap.bind(bindingRef, type.args);
         try {
@@ -326,36 +593,49 @@ function findFirstDynamicImport(t, fileGraph, depthBudget) {
     }
     return null;
 }
+/**
+ * Cycle guard: mirrors `walkStaticMember`. A mutually-recursive object map
+ * reached through `MAP[k]` re-enters this arm forever without it. No
+ * `foldLeaf` path here, so no early pop is needed.
+ */
 function walkDynamicMember(graph, fileGraph, type, argMap, guard) {
-    const objResults = resolveType(graph, fileGraph, type.obj, argMap, guard);
-    const out = [];
-    for (const { type: obj } of objResults) {
-        if (obj.kind !== "Object")
-            continue;
-        const mapBinding = findMapBinding(type.obj, fileGraph);
-        const mapName = mapBinding?.symbol ?? "unknown";
-        const mapLoc = {
-            file: fileGraph.filePath,
-            line: mapBinding?.loc.line ?? 0,
-            column: mapBinding?.loc.column ?? 0,
-        };
-        for (const propValue of Object.values(obj.props)) {
-            // Recurse via walkWithFolding so identity is derived from each branch's
-            // leaf TypeOf (Foo/Bar resolve to their respective bindings).
-            const inner = walkWithFolding(graph, fileGraph, propValue, argMap, guard);
-            const via = { kind: "dynamic-map", mapName, mapLoc };
-            for (const t of inner) {
-                if (t.type.kind === "Unknown")
-                    continue;
-                out.push({
-                    type: t.type,
-                    viaTrail: [via, ...t.viaTrail],
-                    identity: t.identity, // per-branch identity, distinct per map value
-                });
+    if (guard.pushNode(type) === "cycle") {
+        return [{ type: { kind: "Unknown" }, viaTrail: [], identity: null }];
+    }
+    try {
+        const objResults = resolveType(graph, fileGraph, type.obj, argMap, guard);
+        const out = [];
+        for (const { type: obj } of objResults) {
+            if (obj.kind !== "Object")
+                continue;
+            const mapBinding = findMapBinding(type.obj, fileGraph);
+            const mapName = mapBinding?.symbol ?? "unknown";
+            const mapLoc = {
+                file: fileGraph.filePath,
+                line: mapBinding?.loc.line ?? 0,
+                column: mapBinding?.loc.column ?? 0,
+            };
+            for (const propValue of Object.values(obj.props)) {
+                // Recurse via walkWithFolding so identity is derived from each branch's
+                // leaf TypeOf (Foo/Bar resolve to their respective bindings).
+                const inner = walkWithFolding(graph, fileGraph, propValue, argMap, guard);
+                const via = { kind: "dynamic-map", mapName, mapLoc };
+                for (const t of inner) {
+                    if (t.type.kind === "Unknown")
+                        continue;
+                    out.push({
+                        type: t.type,
+                        viaTrail: [via, ...t.viaTrail],
+                        identity: t.identity, // per-branch identity, distinct per map value
+                    });
+                }
             }
         }
+        return out;
+    }
+    finally {
+        guard.popNode(type);
     }
-    return out;
 }
 function findMapBinding(obj, fileGraph) {
     if (obj.kind !== "TypeOf")
@@ -577,9 +857,18 @@ function memberLocalIdentity(graph, fileGraph, specifier, imported) {
         return null;
     return { kind: "local", filePath: member.absFile, export: member.exportName };
 }
+/** Append a residual member chain (#518) to a derived identity's export name. */
+function withResidual(identity, residual) {
+    if (identity === null || residual.length === 0)
+        return identity;
+    return identity.kind === "local"
+        ? { ...identity, export: compoundExportName(identity.export, residual) }
+        : { ...identity, imported: compoundExportName(identity.imported, residual) };
+}
 /**
- * Walk the input type to find the leaf TypeOf ref (or DynamicImport), then resolve
- * that ref to either an imported or local identity.
+ * Resolve the input type's leaf TypeOf ref (or DynamicImport) to either an
+ * imported or a local identity. Any other shape — a `ReturnTypeOf` included —
+ * has no identity of its own and yields null.
  *
  * Switches FileGraph context via `ref.originFile` when set, so refs that have
  * travelled across module boundaries (e.g. cross-module function returns) are
@@ -587,11 +876,11 @@ function memberLocalIdentity(graph, fileGraph, specifier, imported) {
  * that match the ref actually live.
  */
 export function deriveIdentity(type, fileGraph, graph) {
-    // Unwrap nested ReturnTypeOf chains to find the wrapped argument (used by
-    // HOC fallback callers passing the last arg here).
-    let cur = type;
-    while (cur.kind === "ReturnTypeOf")
-        cur = cur.callee;
+    // A ReturnTypeOf never derives identity from its callee (spec D9 arm 2):
+    // a resolvable factory call's identity is the declaration holding the call,
+    // which every engine push site already supplies as its fallback. Returning
+    // null here is what makes that fallback win. (#271, #328)
+    const cur = type;
     if (cur.kind === "DynamicImport") {
         const importedName = cur.projection[0] ?? "default";
         const resolvedFile = graph ? resolveImportedFile(graph, fileGraph, cur.specifier, importedName) : null;
@@ -622,33 +911,39 @@ export function deriveIdentity(type, fileGraph, graph) {
         if (imp) {
             // Namespace-import members canonicalise to the member name (#394),
             // matching the direct-import path's `effectiveImported` (engine/index.ts,
-            // #362) so both paths mint the same identity.
+            // #362) so both paths mint the same identity. The residual chain (#518)
+            // is appended AFTER every root lookup, so `Dialog.Popup` on an unparsed
+            // package and `NS.Inline` on a workspace member both mirror the direct
+            // path.
             const imported = effectiveExportName(imp.imported, cur.ref.memberChain);
+            const residual = residualMemberChain(imp.imported, cur.ref.memberChain);
             const resolvedFile = graph ? resolveImportedFile(graph, lookup, imp.specifier, imported) : null;
             const workspaceLocal = workspaceSiblingIdentity(graph, imp.specifier, imported, resolvedFile);
             if (workspaceLocal)
-                return workspaceLocal;
+                return withResidual(workspaceLocal, residual);
             const relativeLocal = relativeChainLocalIdentity(graph, lookup, imp.specifier, imported);
             if (relativeLocal)
-                return relativeLocal;
+                return withResidual(relativeLocal, residual);
             const memberLocal = memberLocalIdentity(graph, lookup, imp.specifier, imported);
             if (memberLocal)
-                return memberLocal;
-            return {
+                return withResidual(memberLocal, residual);
+            return withResidual({
                 kind: "imported",
                 specifier: imp.specifier,
                 imported,
                 resolvedFile,
-            };
+            }, residual);
         }
-        // Check local declarations.
+        // Check local declarations. A same-file symbol is never a namespace
+        // import, so the whole member chain is residual (mirror of
+        // `pushLocalOccurrence`'s fallback, #518) — an empty chain is a no-op.
         for (const [, decl] of lookup.declarations) {
             if (decl && decl.symbol === symbol) {
-                return {
+                return withResidual({
                     kind: "local",
                     filePath: lookup.filePath,
                     export: decl.exportedAs ?? symbol,
-                };
+                }, cur.ref.memberChain);
             }
         }
     }