@enricai/barnacle 1.12.20 → 1.12.22

package/dist/scripts/recon-generate.js

@@ -52,8 +52,16 @@ exports.compileActionSteps = compileActionSteps;
 exports.collectHeaderBindings = collectHeaderBindings;
 exports.deriveProducerBoundaryBindings = deriveProducerBoundaryBindings;
 exports.emitMultiStepExecuteHttp = emitMultiStepExecuteHttp;
+exports.findAllObjectArrayFields = findAllObjectArrayFields;
+exports.findAllObjectArrayFieldsOrWholeObject = findAllObjectArrayFieldsOrWholeObject;
+exports.collectResponseLeafValues = collectResponseLeafValues;
+exports.getScanPrimaryCandidateGroupsCallCountForTest = getScanPrimaryCandidateGroupsCallCountForTest;
+exports.resetScanPrimaryCandidateGroupsCallCountForTest = resetScanPrimaryCandidateGroupsCallCountForTest;
 exports.detectDrillDownFoldPlan = detectDrillDownFoldPlan;
 exports.parseFoldReturnSpec = parseFoldReturnSpec;
+exports.collectRequestValuesIncludingHeaders = collectRequestValuesIncludingHeaders;
+exports.getFoldPlanResolutionCallCountForTests = getFoldPlanResolutionCallCountForTests;
+exports.resetFoldPlanResolutionCallCountForTests = resetFoldPlanResolutionCallCountForTests;
 exports.resolveFoldPlan = resolveFoldPlan;
 exports.buildContractChecklist = buildContractChecklist;
 exports.emitContractTs = emitContractTs;
@@ -1414,16 +1422,24 @@ function resolveManifestActionSequence(runRoot, captures) {
  * JWT refresh, reference-lookup) that a browser fires incidentally. Absent
  * patterns preserve the noise heuristic exactly.
  *
+ * When the flow declares a `foldReturnSpec`, a GET whose URL matches its
+ * `endpointPattern` is admitted despite the GET drop above — the same scoped
+ * rule `buildFoldPlanFromSpec` later uses to resolve the fold plan, so a
+ * spec-declared GET drill-down survives to reach it instead of being
+ * dropped before the fold pipeline ever sees it. Every other GET is still
+ * dropped.
+ *
  * Exported for tests: this predicate decides what a generated plugin will POST
  * at a live site, and it is the only gate between a browser's incidental
  * chatter and the emitted hot path.
  */
-function extractActionSequence(captures, submitPatterns = null) {
+function extractActionSequence(captures, submitPatterns = null, foldReturnSpec = null) {
     const matchesSubmit = compileSubmitMatcher(submitPatterns);
+    const matchesFoldReturn = compileFoldReturnEndpointMatcher(foldReturnSpec);
     return captures
         .map((capture, index) => ({ capture, index }))
         .filter(({ capture }) => {
-        if (capture.method === "GET")
+        if (capture.method === "GET" && !matchesFoldReturn(capture))
             return false;
         if (capture.status < 200 || capture.status >= 300)
             return false;
@@ -1445,11 +1461,23 @@ function extractActionSequence(captures, submitPatterns = null) {
  * what let a chronologically-first fallback pick an unrelated query. Host is
  * NOT a filter criterion, matching {@link extractActionSequence}.
  *
+ * When the flow declares a `foldReturnSpec`, a non-mutation capture whose
+ * URL matches its `endpointPattern` is admitted despite the query drop
+ * above, mirroring {@link extractActionSequence}'s GET admission. So is a
+ * non-mutation capture whose response resolves the spec's own `resultsPath`
+ * — the GraphQL-primary read op the drill-down folds onto, which
+ * `endpointPattern` (naming the drill, not the primary) never matches on its
+ * own; without this a declared spec would admit the drill-down but leave
+ * `resolveFoldPlan` with no primary capture to resolve `resultsPath`
+ * against. Every other non-mutation capture is still dropped.
+ *
  * Exported for tests: this predicate decides what a generated GraphQL plugin
  * will send at a live site.
  */
-function extractGraphQLActionSequence(captures, submitPatterns = null) {
+function extractGraphQLActionSequence(captures, submitPatterns = null, foldReturnSpec = null) {
     const matchesSubmit = compileSubmitMatcher(submitPatterns);
+    const matchesFoldReturn = compileFoldReturnEndpointMatcher(foldReturnSpec);
+    const matchesFoldReturnResults = compileFoldReturnResultsMatcher(foldReturnSpec);
     return captures
         .map((capture, index) => ({ capture, index }))
         .filter(({ capture }) => {
@@ -1459,7 +1487,9 @@ function extractGraphQLActionSequence(captures, submitPatterns = null) {
             return false;
         if (!matchesSubmit(capture))
             return false;
-        return capture.query !== null && /^\s*mutation\b/.test(capture.query);
+        if (capture.query !== null && /^\s*mutation\b/.test(capture.query))
+            return true;
+        return matchesFoldReturn(capture) || matchesFoldReturnResults(capture);
     });
 }
 /**
@@ -1530,8 +1560,10 @@ function jsonBodyLeafValues(requestPostData) {
     if (parsed === undefined)
         return null;
     const values = [];
-    for (const { value } of walkStringLeaves(parsed))
-        values.push(value);
+    for (const { value } of walkAllPrimitiveLeaves(parsed)) {
+        if (value !== null)
+            values.push(String(value));
+    }
     return values;
 }
 /**
@@ -2622,11 +2654,29 @@ function* walkSetCookiePairs(rawSetCookie) {
  * Exception: values in `PLACEHOLDER_STATE_VALUES` are skipped entirely so
  * the LATER non-placeholder occurrence at the same JSON path becomes the
  * canonical binding instead.
+ *
+ * `forceIncludeValues` (see {@link collectDependentDrillDownChainValues})
+ * bypasses `MIN_STATE_VALUE_LENGTH` for the specific values it names — a
+ * value already confirmed, by the fold-chain detector itself, to be threaded
+ * from one dependent-drill-down chain hop's response into the next hop's
+ * request is exactly as legitimate a produced state value as a long one; a
+ * length floor exists to keep an UNRELATED short value (an enum code, a page
+ * number) from being mistaken for reused state by blind substring/value
+ * matching, and a value the chain detector already confirmed is threaded
+ * carries no such ambiguity. Every other filter (MAX length, placeholder,
+ * shielded UUID, GET-non-UUID) still applies.
  */
 /** Exported for unit testing — lets tests exercise the produces[] walk (body
  * AND header/cookie origins) directly against synthetic Capture sequences. */
-function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndices = new Set()) {
+function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndices = new Set(), forceIncludeValues = new Set()) {
     const index = new Map();
+    // Computed structurally off the SAME captures being indexed (no
+    // foldReturnSpec available at this layer) — a spec-declared fold's own
+    // chain values reach here via the caller-supplied `forceIncludeValues`
+    // (see recon-generate's top-level `collectDependentDrillDownChainValues`
+    // call), so this indexes a chain-produced value regardless of whether the
+    // fold plan that confirmed it is structural or spec-declared.
+    const chainForceIncludeValues = collectDependentDrillDownChainValues(captures.map((capture) => ({ capture })), null);
     // First pass: identify the earliest origin among ACTION captures for each
     // value. Action-only earliest-origin tracking is what compileActionSteps'
     // produces[] check needs — it ignores non-action captures (telemetry GETs,
@@ -2645,7 +2695,13 @@ function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndi
         const rawSetCookie = Object.entries(c.responseHeaders).find(([k]) => k.toLowerCase() === "set-cookie")?.[1];
         if (rawSetCookie !== undefined) {
             for (const { name, value } of walkSetCookiePairs(rawSetCookie)) {
-                if (value.length < MIN_STATE_VALUE_LENGTH)
+                // Same chain/force exemption as the body-value MIN_STATE_VALUE_LENGTH
+                // floor below: a cookie-sourced value the fold-chain detector already
+                // confirmed is threaded into a later hop's request is exactly as
+                // legitimate as a long one, so it must not be dropped for being short.
+                if (value.length < MIN_STATE_VALUE_LENGTH &&
+                    !chainForceIncludeValues.has(value) &&
+                    !forceIncludeValues.has(value))
                     continue;
                 if (value.length > MAX_COOKIE_STATE_VALUE_LENGTH)
                     continue;
@@ -2661,6 +2717,31 @@ function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndi
                 }
             }
         }
+        // Non-cookie response headers are only indexed for values the fold-chain
+        // detector already confirmed are threaded from this hop's response into a
+        // later hop's request (`chainForceIncludeValues`) — unlike Set-Cookie,
+        // which is always a plausible token mint, an arbitrary header (e.g.
+        // `X-Conversation-Id`) is indexed as producible state only when chain
+        // detection itself has already established that reuse, so this never
+        // sweeps every header value as noise.
+        for (const [headerName, headerValue] of Object.entries(c.responseHeaders)) {
+            if (headerName.toLowerCase() === "set-cookie")
+                continue;
+            if (!chainForceIncludeValues.has(headerValue))
+                continue;
+            if (headerValue.length > MAX_COOKIE_STATE_VALUE_LENGTH)
+                continue;
+            if (PLACEHOLDER_STATE_VALUES.has(headerValue))
+                continue;
+            if (!index.has(headerValue)) {
+                index.set(headerValue, {
+                    value: headerValue,
+                    originIndex: i,
+                    path: [],
+                    headerOrigin: { sourceHeader: headerName },
+                });
+            }
+        }
         if (c.responseBody === undefined || c.responseBody === null)
             continue;
         // For GET captures, only index UUID-shaped strings. GET captures (today,
@@ -2671,8 +2752,13 @@ function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndi
         // e.g. "candidate" as a state value gets substituted INSIDE an already-
         // emitted ${candidateId} interpolation, producing ${${entityTypeCode}Id}.
         const isGet = c.method === "GET";
-        for (const { value, path } of walkStringLeaves(c.responseBody)) {
-            if (value.length < MIN_STATE_VALUE_LENGTH)
+        for (const { value: rawValue, path } of walkAllPrimitiveLeaves(c.responseBody)) {
+            if (rawValue === null)
+                continue;
+            const value = String(rawValue);
+            if (value.length < MIN_STATE_VALUE_LENGTH &&
+                !chainForceIncludeValues.has(value) &&
+                !forceIncludeValues.has(value))
                 continue;
             if (value.length > MAX_STATE_VALUE_LENGTH)
                 continue;
@@ -2685,7 +2771,16 @@ function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndi
             // corrupt T2/T3's already-substituted Values.
             if (shieldedUuids.has(value))
                 continue;
-            if (isGet && !UUID_REGEX.test(value))
+            // Same chain/force exemption as the MIN_STATE_VALUE_LENGTH floor above:
+            // a value the fold-chain detector already confirmed is threaded from
+            // this GET hop's response into a later hop's request is exactly as
+            // legitimate as a UUID anchor, so it must not be dropped just because
+            // this hop happens to be a GET rather than every existing fixture's
+            // POST.
+            if (isGet &&
+                !UUID_REGEX.test(value) &&
+                !chainForceIncludeValues.has(value) &&
+                !forceIncludeValues.has(value))
                 continue;
             if (!index.has(value)) {
                 index.set(value, { value, originIndex: i, path });
@@ -2891,8 +2986,48 @@ function compileActionSteps(actions, stateIndex) {
                 });
             }
         }
+        // Non-cookie response-header-origin produces — mirrors the Set-Cookie
+        // block above but for a plain header (e.g. `X-Price-Token`) whose value
+        // `indexStateValues` indexed with `headerOrigin.sourceHeader` set to the
+        // real header name. Only emitted when the value is actually consumed as
+        // a REQUEST HEADER downstream (`usedValueTargetHeader`) — `createHttpClient`'s
+        // `bind` option (see http-client.ts) is the only mechanism that can
+        // thread a header-origin value forward, since the emitted response
+        // variable never exposes response headers to the rest of the generated
+        // code the way it exposes the parsed body.
+        for (const [headerName, headerValue] of Object.entries(capture.responseHeaders)) {
+            if (headerName.toLowerCase() === "set-cookie")
+                continue;
+            if (!usedValues.has(headerValue))
+                continue;
+            const sv = stateIndex.get(headerValue);
+            if (!sv || sv.originIndex !== index || !sv.headerOrigin)
+                continue;
+            const targetHeader = usedValueTargetHeader.get(headerValue);
+            if (!targetHeader)
+                continue;
+            let name = `${headerName.replace(/[^A-Za-z0-9]/g, "")}Header`;
+            if (!/^[A-Za-z_$]/.test(name))
+                name = `_${name}`;
+            let suffix = 1;
+            while (seenNames.has(name)) {
+                suffix++;
+                name = `${headerName.replace(/[^A-Za-z0-9]/g, "")}Header${suffix}`;
+            }
+            seenNames.add(name);
+            produces.push({
+                kind: "header",
+                name,
+                sourceHeader: sv.headerOrigin.sourceHeader,
+                cookieName: sv.headerOrigin.cookieName,
+                targetHeader,
+            });
+        }
         if (capture.responseBody !== undefined && capture.responseBody !== null) {
-            for (const { value, path } of walkStringLeaves(capture.responseBody)) {
+            for (const { value: rawValue, path } of walkAllPrimitiveLeaves(capture.responseBody)) {
+                if (rawValue === null)
+                    continue;
+                const value = String(rawValue);
                 if (!usedValues.has(value))
                     continue;
                 const sv = stateIndex.get(value);
@@ -2977,7 +3112,9 @@ function resolveResponsePathValue(responseBody, path) {
             return null;
         }
     }
-    return typeof cursor === "string" ? cursor : null;
+    return typeof cursor === "string" || typeof cursor === "number" || typeof cursor === "boolean"
+        ? String(cursor)
+        : null;
 }
 /**
  * Replaces occurrences of state values in `template` with `${varName}`
@@ -3738,7 +3875,8 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
                     const matchesJoinField = target.joinFields.some((field) => {
                         const value = readValueAtPath(firstItem, field.split("."));
                         return ((typeof value === "string" && value.length > 0 && value === headerValue) ||
-                            (typeof value === "number" && String(value) === headerValue));
+                            ((typeof value === "number" || typeof value === "boolean") &&
+                                String(value) === headerValue));
                     });
                     if (matchesJoinField)
                         headerNames.add(headerName);
@@ -3750,7 +3888,7 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
                     const value = readValueAtPath(firstItem, field.split("."));
                     if (typeof value === "string" && value.length > 0)
                         joinValues.add(value);
-                    else if (typeof value === "number")
+                    else if (typeof value === "number" || typeof value === "boolean")
                         joinValues.add(String(value));
                 }
                 if (joinValues.size > 0)
@@ -4056,7 +4194,7 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
                     const value = readValueAtPath(firstItem, field.split("."));
                     const stringValue = typeof value === "string" && value.length > 0
                         ? value
-                        : typeof value === "number"
+                        : typeof value === "number" || typeof value === "boolean"
                             ? String(value)
                             : null;
                     return stringValue !== null
@@ -4461,17 +4599,42 @@ const ARRAY_WILDCARD_SEGMENT = "*";
  * A path segment for an array index the search descended through (to keep
  * looking for a nested candidate array) is the {@link ARRAY_WILDCARD_SEGMENT}
  * sentinel, never a literal index — see its docstring. */
-function findAllObjectArrayFields(value, path = []) {
+function findAllObjectArrayFieldsUncached(value, path = []) {
     if (value === null || typeof value !== "object")
         return [];
     if (Array.isArray(value)) {
         const objectItems = value.filter(isObjectArrayItem);
-        const nestedCandidates = objectItems.flatMap((item) => findAllObjectArrayFields(item, [...path, ARRAY_WILDCARD_SEGMENT]));
+        const nestedCandidates = objectItems.flatMap((item) => findAllObjectArrayFieldsUncached(item, [...path, ARRAY_WILDCARD_SEGMENT]));
         return objectItems.length > 0
             ? [{ path, items: objectItems }, ...nestedCandidates]
             : nestedCandidates;
     }
-    return Object.entries(value).flatMap(([key, v]) => findAllObjectArrayFields(v, [...path, key]));
+    return Object.entries(value).flatMap(([key, v]) => findAllObjectArrayFieldsUncached(v, [...path, key]));
+}
+/** Every distinct top-level `value` object {@link findAllObjectArrayFields}
+ * is invoked on is scanned repeatedly — once per fold-chain candidate/join
+ * disambiguation that re-derives the same response body — so a per-run,
+ * identity-keyed cache lets a given body's whole-tree scan run at most once
+ * regardless of how many callers re-derive it. Keyed on object identity
+ * (never a serialized path/value pair) because captures/response bodies are
+ * never mutated once produced (see this module's fold-plan investigation
+ * notes), so identity alone is a safe, unconditionally correct cache key. */
+const objectArrayFieldsCache = new WeakMap();
+/** Memoized entry point for {@link findAllObjectArrayFieldsUncached} — see
+ * {@link objectArrayFieldsCache}. Only the default top-level `path` is
+ * cached (every real call site invokes with the default); a caller passing
+ * an explicit `path` — recursion within the uncached walk itself — bypasses
+ * the cache and hits the underlying scan directly. */
+function findAllObjectArrayFields(value, path = []) {
+    if (path.length > 0 || value === null || typeof value !== "object") {
+        return findAllObjectArrayFieldsUncached(value, path);
+    }
+    const cached = objectArrayFieldsCache.get(value);
+    if (cached)
+        return cached;
+    const computed = findAllObjectArrayFieldsUncached(value, path);
+    objectArrayFieldsCache.set(value, computed);
+    return computed;
 }
 /** The first object-array field by DFS/key order — see
  * {@link findAllObjectArrayFields}. Every call site that must disambiguate
@@ -4495,9 +4658,24 @@ function findObjectArrayField(value, path = []) {
  * more genuine per-item data than a small real nested object-array; a
  * caller that just wants the first real array (the common case) is
  * unaffected since it still comes first. */
+const objectArrayFieldsOrWholeObjectCache = new WeakMap();
+/** Memoized the same way as {@link findAllObjectArrayFields} (see
+ * {@link objectArrayFieldsCache}) — this is the candidate list
+ * {@link selectDisambiguatedCandidate} and {@link buildFoldPlanFromSpec}
+ * re-derive off the SAME responseBody on every chain hop/disambiguation, so
+ * it is exactly as hot a redundant-recompute site as the underlying scan. */
 function findAllObjectArrayFieldsOrWholeObject(value, path = []) {
+    if (path.length > 0 || value === null || typeof value !== "object") {
+        const found = findAllObjectArrayFields(value, path);
+        return isObjectArrayItem(value) ? [...found, { path, items: [value] }] : found;
+    }
+    const cached = objectArrayFieldsOrWholeObjectCache.get(value);
+    if (cached)
+        return cached;
     const found = findAllObjectArrayFields(value, path);
-    return isObjectArrayItem(value) ? [...found, { path, items: [value] }] : found;
+    const computed = isObjectArrayItem(value) ? [...found, { path, items: [value] }] : found;
+    objectArrayFieldsOrWholeObjectCache.set(value, computed);
+    return computed;
 }
 /** The first candidate from {@link findAllObjectArrayFieldsOrWholeObject} —
  * the flat-object-aware counterpart of {@link findObjectArrayField}. */
@@ -4539,14 +4717,14 @@ function collectRequestStringValues(capture) {
     })();
     if (parsedBody !== undefined) {
         for (const { value } of walkAllPrimitiveLeaves(parsedBody)) {
-            if (typeof value === "number")
+            if (typeof value === "number" || typeof value === "boolean")
                 values.add(String(value));
         }
     }
     return values;
 }
 /**
- * Yields every string/numeric leaf reachable from `item` by walking nested
+ * Yields every string/numeric/boolean leaf reachable from `item` by walking nested
  * plain objects only (not arrays — a join key is a scalar field of the item
  * or one of its nested objects, never an element drawn from a nested array),
  * paired with its dot-separated path from `item`'s root. A bare top-level
@@ -4565,8 +4743,8 @@ function* walkItemFieldPaths(item, path = []) {
     }
 }
 /**
- * Finds the ordered list of an array item's string/numeric field paths whose
- * values are threaded into `drillCapture`'s outbound request — the join key a
+ * Finds the ordered list of an array item's string/numeric/boolean field
+ * paths whose values are threaded into `drillCapture`'s outbound request — the join key a
  * dependent drill-down call was built from. Each entry is a dot-separated
  * path (see {@link readValueAtPath} / {@link pathToAccessor}), so a bare
  * top-level field stays a single segment (e.g. `"sku"`) and a field nested
@@ -4576,29 +4754,107 @@ function* walkItemFieldPaths(item, path = []) {
  * order the primary response declares them, not sorted. Returns `[]` when no
  * field of the item threads into the request at all.
  */
+/**
+ * Maps every string/numeric/boolean value seen in any action's request URL
+ * or body (see {@link collectRequestStringValues} — deliberately headers-
+ * excluded, unlike {@link buildRequestValueIndex}, matching the structural
+ * heuristic's own header-blind scan) to the ascending list of action indices
+ * whose request carries it. Built once per {@link detectDrillDownFoldPlan}
+ * call and shared across every primary candidate's scan, so
+ * {@link scanPrimaryCandidateGroups} can jump straight to the indices that
+ * could possibly thread one of a primary array's own item values instead of
+ * walking every later action — the O(actions)-per-primary forward scan that
+ * makes the structural heuristic itself O(actions^2) on a large capture set
+ * dominated by same-shaped primary candidates.
+ */
+function buildRequestStringValueIndex(actions) {
+    const index = new Map();
+    for (let i = 0; i < actions.length; i++) {
+        for (const value of collectRequestStringValues(actions[i].capture)) {
+            const indices = index.get(value);
+            if (indices)
+                indices.push(i);
+            else
+                index.set(value, [i]);
+        }
+    }
+    return index;
+}
+/** Every string/numeric/boolean field value present anywhere across `items`
+ * — the set of values whose {@link buildRequestStringValueIndex} entries can
+ * possibly thread out of this primary array, used to prune the candidate
+ * drill indices {@link scanPrimaryCandidateGroups} walks instead of
+ * considering every later action index. */
+function collectItemsFieldValues(items) {
+    const values = new Set();
+    for (const item of items) {
+        for (const { value } of walkItemFieldPaths(item)) {
+            if (typeof value === "string" && value.length > 0)
+                values.add(value);
+            else if (typeof value === "number" || typeof value === "boolean")
+                values.add(String(value));
+        }
+    }
+    return values;
+}
+/** Ascending, deduped action indices strictly greater than `afterIndex`
+ * whose request carries at least one of `values` — see
+ * {@link collectItemsFieldValues} / {@link buildRequestStringValueIndex}. */
+function collectCandidateIndicesAscending(requestStringValueIndex, values, afterIndex) {
+    const candidates = new Set();
+    for (const value of values) {
+        for (const index of requestStringValueIndex.get(value) ?? []) {
+            if (index > afterIndex)
+                candidates.add(index);
+        }
+    }
+    return [...candidates].sort((a, b) => a - b);
+}
 function findThreadedJoinFields(item, drillCapture) {
     const requestValues = collectRequestStringValues(drillCapture);
     if (requestValues.size === 0)
         return [];
     return [...walkItemFieldPaths(item)]
         .filter(({ value: v }) => (typeof v === "string" && v.length > 0 && requestValues.has(v)) ||
-        (typeof v === "number" && requestValues.has(String(v))))
+        (typeof v === "number" && requestValues.has(String(v))) ||
+        (typeof v === "boolean" && requestValues.has(String(v))))
         .map(({ path }) => path.join("."));
 }
-/** Every string and numeric leaf value present anywhere in a response body —
+/** Every string, numeric, and boolean leaf value present anywhere in a response —
  * the set a chained drill-down step's request must overlap with for that
  * step to count as depending on this response. Deliberately walks the WHOLE
  * body (not just object-array items, unlike {@link findThreadedJoinFields})
  * since a chained step can thread any response value, not only a per-item
- * join field. */
-function collectResponseLeafValues(responseBody) {
+ * join field. Also walks every response HEADER value, mirroring
+ * {@link collectRequestValuesIncludingHeaders} on the request side, since a
+ * chain hop can just as easily mint its join token in a response header
+ * (e.g. a `Location` or custom correlation header) as in the body.
+ * Memoized like {@link objectArrayFieldsCache} — {@link computeFoldChain}'s
+ * inner `dependsOnChain` check re-derives this for every chain member on
+ * every outer loop iteration, making it the single hottest redundant-
+ * recompute site in fold-chain resolution (see this module's fold-plan
+ * investigation notes). */
+const responseLeafValuesCache = new WeakMap();
+function collectResponseLeafValues(capture) {
+    const cached = responseLeafValuesCache.get(capture);
+    if (cached)
+        return cached;
+    const computed = collectResponseLeafValuesUncached(capture);
+    responseLeafValuesCache.set(capture, computed);
+    return computed;
+}
+function collectResponseLeafValuesUncached(capture) {
     const values = new Set();
-    for (const { value } of walkAllPrimitiveLeaves(responseBody)) {
+    for (const { value } of walkAllPrimitiveLeaves(capture.responseBody)) {
         if (typeof value === "string" && value.length > 0)
             values.add(value);
         if (typeof value === "number")
             values.add(String(value));
+        if (typeof value === "boolean")
+            values.add(String(value));
     }
+    for (const v of Object.values(capture.responseHeaders))
+        values.add(v);
     return values;
 }
 /**
@@ -4657,7 +4913,7 @@ function computeFoldChain(actions, drillStepIndex, drillArrayPath) {
         const requestValues = collectRequestValuesIncludingHeaders(candidate.capture);
         const dependsOnChain = chain.some((chainIndex) => {
             const chainStepCapture = actions[chainIndex].capture;
-            const responseValues = collectResponseLeafValues(chainStepCapture.responseBody);
+            const responseValues = collectResponseLeafValues(chainStepCapture);
             const echoedValues = collectRequestValuesIncludingHeaders(chainStepCapture);
             return [...responseValues].some((v) => !echoedValues.has(v) && requestValues.has(v));
         });
@@ -4725,7 +4981,7 @@ function directPrimitiveChildCountExcludingEchoed(obj, requestValues) {
     let n = 0;
     for (const v of Object.values(obj)) {
         if (v === null || (typeof v !== "object" && typeof v !== "function")) {
-            if (typeof v === "string" || typeof v === "number") {
+            if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
                 if (requestValues.has(String(v)))
                     continue;
             }
@@ -4747,7 +5003,20 @@ function directPrimitiveChildCountExcludingEchoed(obj, requestValues) {
  * one array's target chain is never re-claimed as a fresh target thread of
  * a different, independent array on the same primary response.
  */
-function scanPrimaryCandidateGroups(actions, primaryIndex, globallyConsumedIndices) {
+let scanPrimaryCandidateGroupsCallCount = 0;
+/** Test-only instrumentation for asserting `scanPrimaryCandidateGroups`'s
+ * O(actions.length) scan is reused across repeat queries of the same index
+ * (via `detectDrillDownFoldPlan`'s per-index cache) rather than re-run.
+ * Not read by any production path. */
+function getScanPrimaryCandidateGroupsCallCountForTest() {
+    return scanPrimaryCandidateGroupsCallCount;
+}
+/** Test-only counterpart to {@link getScanPrimaryCandidateGroupsCallCountForTest}. */
+function resetScanPrimaryCandidateGroupsCallCountForTest() {
+    scanPrimaryCandidateGroupsCallCount = 0;
+}
+function scanPrimaryCandidateGroups(actions, primaryIndex, globallyConsumedIndices, requestStringValueIndex) {
+    scanPrimaryCandidateGroupsCallCount++;
     const primary = actions[primaryIndex];
     const primaryCandidates = findAllObjectArrayFields(primary.capture.responseBody);
     if (primaryCandidates.length === 0)
@@ -4761,7 +5030,12 @@ function scanPrimaryCandidateGroups(actions, primaryIndex, globallyConsumedIndic
     const consumedIndices = new Set();
     for (const primaryArray of primaryCandidates) {
         const targets = [];
-        for (let drillIndex = primaryIndex + 1; drillIndex < actions.length; drillIndex++) {
+        // Pruned to the (typically tiny) set of later action indices whose
+        // request could possibly thread one of this array's own item values —
+        // see buildRequestStringValueIndex's docstring — instead of every
+        // index from primaryIndex+1 to the end of actions.
+        const candidateDrillIndices = collectCandidateIndicesAscending(requestStringValueIndex, collectItemsFieldValues(primaryArray.items), primaryIndex);
+        for (const drillIndex of candidateDrillIndices) {
             const drill = actions[drillIndex];
             if (drill === primary)
                 continue;
@@ -4851,11 +5125,40 @@ function detectDrillDownFoldPlan(actions) {
     // primary's response, not on this later primary's array, so it must
     // never be re-claimed as a fresh drill target for a subsequent primary.
     const globallyConsumedIndices = new Set();
+    // scanPrimaryCandidateGroups's result for a given index only depends on
+    // `actions` (fixed) and the current contents of `globallyConsumedIndices`,
+    // so it is safe to reuse across repeat queries of the SAME index as long
+    // as the consumed set hasn't grown since it was computed. The freshest-wins
+    // loop below re-queries the same laterIndex once per sibling group on a
+    // re-queried primary, and the outer loop often reaches that very index as
+    // its own primaryIndex shortly after — both hit this cache instead of
+    // repeating the O(actions.length) scan.
+    let consumedVersion = 0;
+    const scanCache = new Map();
+    const scanCacheVersion = new Map();
+    // Built once for the whole detectDrillDownFoldPlan call — see
+    // buildRequestStringValueIndex's docstring.
+    const requestStringValueIndex = buildRequestStringValueIndex(actions);
+    const scanCached = (index) => {
+        const cachedVersion = scanCacheVersion.get(index);
+        if (cachedVersion === consumedVersion)
+            return scanCache.get(index);
+        const result = scanPrimaryCandidateGroups(actions, index, globallyConsumedIndices, requestStringValueIndex);
+        scanCache.set(index, result);
+        scanCacheVersion.set(index, consumedVersion);
+        return result;
+    };
+    const addConsumed = (index) => {
+        if (globallyConsumedIndices.has(index))
+            return;
+        globallyConsumedIndices.add(index);
+        consumedVersion++;
+    };
     for (let primaryIndex = 0; primaryIndex < actions.length; primaryIndex++) {
         if (globallyConsumedIndices.has(primaryIndex))
             continue;
         const primary = actions[primaryIndex];
-        const groups = scanPrimaryCandidateGroups(actions, primaryIndex, globallyConsumedIndices);
+        const groups = scanCached(primaryIndex);
         if (groups.length === 0)
             continue;
         const primaryEndpointKey = endpointKey(primary.capture.url);
@@ -4882,7 +5185,7 @@ function detectDrillDownFoldPlan(actions) {
                 const laterAction = actions[laterIndex];
                 if (endpointKey(laterAction.capture.url) !== primaryEndpointKey)
                     continue;
-                const laterGroups = scanPrimaryCandidateGroups(actions, laterIndex, globallyConsumedIndices);
+                const laterGroups = scanCached(laterIndex);
                 const laterGroup = laterGroups.find((g) => JSON.stringify(g.primaryArrayPath) === JSON.stringify(freshestGroup.primaryArrayPath));
                 if (laterGroup === undefined)
                     continue;
@@ -4920,10 +5223,10 @@ function detectDrillDownFoldPlan(actions) {
             // itself is marked consumed once per group pushed (idempotent via
             // Set.add), since the step itself is only visited once regardless of
             // how many independent array groups it yields.
-            globallyConsumedIndices.add(freshestIndex);
+            addConsumed(freshestIndex);
             for (const target of freshestGroup.targets) {
                 for (const chainIndex of target.chain)
-                    globallyConsumedIndices.add(chainIndex);
+                    addConsumed(chainIndex);
             }
         }
     }
@@ -5032,10 +5335,20 @@ function objectItemsAtPath(body, path) {
  * through a request HEADER), so matching a spec's `joinFields` against the
  * drill capture must search headers even though the structural heuristic
  * deliberately doesn't (see {@link collectRequestStringValues}'s docstring). */
+const requestValuesCache = new WeakMap();
+/** Memoized like {@link objectArrayFieldsCache} — the same capture's
+ * request/header values are re-derived on every fold-chain candidate that
+ * threads through it. Keyed on `Capture` identity rather than
+ * `responseBody`, since this walks the capture's request side (URL, body,
+ * headers), not its response. */
 function collectRequestValuesIncludingHeaders(capture) {
+    const cached = requestValuesCache.get(capture);
+    if (cached)
+        return cached;
     const values = collectRequestStringValues(capture);
     for (const v of Object.values(capture.requestHeaders))
         values.add(v);
+    requestValuesCache.set(capture, values);
     return values;
 }
 /** Finds which of `primaryItems` the drill call actually captured, by
@@ -5051,12 +5364,150 @@ function resolveSpecMatchedPrimaryItemIndex(primaryItems, joinFields, drillCaptu
     const matchedIndex = primaryItems.findIndex((item) => joinFields.every((field) => {
         const value = readValueAtPath(item, field.split("."));
         return ((typeof value === "string" && value.length > 0 && requestValues.has(value)) ||
-            (typeof value === "number" && requestValues.has(String(value))));
+            (typeof value === "number" && requestValues.has(String(value))) ||
+            (typeof value === "boolean" && requestValues.has(String(value))));
     }));
     return matchedIndex === -1 ? null : matchedIndex;
 }
-function buildFoldPlanFromSpec(actions, spec) {
-    const primaryArrayPath = spec.resultsPath.split(".");
+/**
+ * Maps every string/numeric/boolean value seen in any action's request (URL,
+ * body, or headers — see {@link collectRequestValuesIncludingHeaders}) to the
+ * ascending list of action indices whose request carries it. Built once per
+ * {@link buildFoldPlanFromSpec} call and shared across every primary/drill
+ * candidate pair, so {@link resolveSpecMatchedPrimaryItemIndexAlongChain}'s
+ * upstream search can jump straight to the (typically tiny) set of indices
+ * that could possibly carry a given primary item's join value instead of
+ * scanning every index between the primary and the drill — the O(actions)-
+ * per-candidate backward walk the reported large-capture-set hang traced to.
+ */
+function buildRequestValueIndex(actions) {
+    const index = new Map();
+    for (let i = 0; i < actions.length; i++) {
+        for (const value of collectRequestValuesIncludingHeaders(actions[i].capture)) {
+            const indices = index.get(value);
+            if (indices)
+                indices.push(i);
+            else
+                index.set(value, [i]);
+        }
+    }
+    return index;
+}
+/** Every string/numeric/boolean {@link FoldReturnSpec.joinFields} value
+ * present on any of `primaryItems`, stringified exactly as
+ * {@link resolveSpecMatchedPrimaryItemIndex} compares them — the set of
+ * values whose {@link buildRequestValueIndex} entries can possibly resolve
+ * this primary's join, used to prune the candidate entry indices
+ * {@link resolveSpecMatchedPrimaryItemIndexAlongChain} walks instead of
+ * considering every action index in range. */
+function collectPrimaryJoinValues(primaryItems, joinFields) {
+    const values = new Set();
+    for (const item of primaryItems) {
+        for (const field of joinFields) {
+            const value = readValueAtPath(item, field.split("."));
+            if (typeof value === "string" && value.length > 0)
+                values.add(value);
+            else if (typeof value === "number" || typeof value === "boolean")
+                values.add(String(value));
+        }
+    }
+    return values;
+}
+/** Descending, deduped action indices strictly greater than
+ * `primaryStepIndex` whose request carries at least one of `joinValues` —
+ * the pruned candidate set {@link resolveSpecMatchedPrimaryItemIndexAlongChain}
+ * walks instead of every index in `(primaryStepIndex, actions.length)`. */
+function collectCandidateEntryIndicesDescending(requestValueIndex, joinValues, primaryStepIndex) {
+    const candidates = new Set();
+    for (const value of joinValues) {
+        for (const index of requestValueIndex.get(value) ?? []) {
+            if (index > primaryStepIndex)
+                candidates.add(index);
+        }
+    }
+    return [...candidates].sort((a, b) => b - a);
+}
+/** Like {@link resolveSpecMatchedPrimaryItemIndex}, but also looks upstream of
+ * `drillStepIndex` for the join key when `drillStepIndex`'s own request
+ * doesn't carry it — a `foldReturn` spec's `endpointPattern` naturally names
+ * the chain TERMINAL (the response actually holding the data an author wants
+ * folded), not the opaque entry hop that carries the join key onward (e.g.
+ * as a header-threaded token). Walks every earlier step back to
+ * `primaryStepIndex`, in reverse so the closest (least ambiguous) candidate
+ * wins first, and accepts one only once {@link computeFoldChain} confirms it
+ * actually chains FORWARD to `drillStepIndex` — otherwise an unrelated
+ * earlier step matching the join key by coincidence could hijack the fold.
+ * Returns the resolved `entryIndex` alongside the matched item index so the
+ * caller can build the fold's `chain` starting from the step that ACTUALLY
+ * carries the join key, not from `drillStepIndex` — a chain built from
+ * `drillStepIndex` alone would never include this upstream entry hop, so it
+ * would never be re-executed (header-parameterized) per primary item at
+ * runtime. */
+let resolveSpecMatchedPrimaryItemIndexAlongChainCallCount = 0;
+/** Test-only instrumentation: how many times
+ * {@link resolveSpecMatchedPrimaryItemIndexAlongChain} — the expensive
+ * backward-walk + {@link computeFoldChain} resolution — has actually run
+ * since the last {@link resetFoldPlanResolutionCallCountForTests} call, so a
+ * test can assert `buildFoldPlanFromSpec` pays for it only once per primary
+ * rather than once per matching drill occurrence. */
+function getFoldPlanResolutionCallCountForTests() {
+    return resolveSpecMatchedPrimaryItemIndexAlongChainCallCount;
+}
+function resetFoldPlanResolutionCallCountForTests() {
+    resolveSpecMatchedPrimaryItemIndexAlongChainCallCount = 0;
+}
+function resolveSpecMatchedPrimaryItemIndexAlongChain(actions, primaryItems, joinFields, drillStepIndex, 
+// Keyed by entryIndex alone: valid for every call sharing the same
+// primaryStepIndex/primaryItems/joinFields, since resolveSpecMatchedPrimaryItemIndex's
+// result for a given entryIndex depends on nothing else. Without this,
+// buildFoldPlanFromSpec's per-primary candidate loop re-walks the SAME
+// overlapping entryIndex range from scratch for every matching drill
+// occurrence it tries — O(candidates * chain length) per primary instead
+// of O(chain length) total, the combinatorial blowup the reported hang
+// traced to at large capture-set sizes.
+matchedItemIndexCache, 
+// Descending, deduped, computed once per primaryStepIndex by
+// {@link collectCandidateEntryIndicesDescending} — every index whose
+// request carries at least one of this primary's join values, i.e. a
+// strict superset of the indices `resolveSpecMatchedPrimaryItemIndex`
+// could ever match. Walking this instead of every index down to
+// `primaryStepIndex` is what collapses the backward search from
+// O(actions) to O(occurrences of the actual join value) per candidate.
+candidateEntryIndicesDescending) {
+    resolveSpecMatchedPrimaryItemIndexAlongChainCallCount++;
+    for (const entryIndex of candidateEntryIndicesDescending) {
+        if (entryIndex > drillStepIndex)
+            continue;
+        const cached = matchedItemIndexCache.get(entryIndex);
+        const matched = cached !== undefined
+            ? cached
+            : (() => {
+                const resolved = resolveSpecMatchedPrimaryItemIndex(primaryItems, joinFields, actions[entryIndex].capture);
+                matchedItemIndexCache.set(entryIndex, resolved);
+                return resolved;
+            })();
+        if (matched === null)
+            continue;
+        if (entryIndex === drillStepIndex)
+            return { entryIndex, primaryMatchedItemIndex: matched };
+        const { chain } = computeFoldChain(actions, entryIndex, []);
+        if (chain.includes(drillStepIndex))
+            return { entryIndex, primaryMatchedItemIndex: matched };
+    }
+    return null;
+}
+/**
+ * Compiles a flow-declared {@link FoldReturnSpec.endpointPattern} into a
+ * capture predicate, or a predicate that always returns `false` when `spec`
+ * is `null` or its pattern isn't a valid regex — the same null-safe
+ * try/catch shape {@link buildFoldPlanFromSpec} already applied inline,
+ * shared here so the action-sequence extractors can admit a spec-matched
+ * drill-down capture under the identical rule that later resolves its fold
+ * plan, instead of dropping it before the fold pipeline ever sees it.
+ */
+function compileFoldReturnEndpointMatcher(spec) {
+    if (spec === null)
+        return () => false;
     const endpointRx = (() => {
         try {
             return new RegExp(spec.endpointPattern);
@@ -5066,16 +5517,73 @@ function buildFoldPlanFromSpec(actions, spec) {
         }
     })();
     if (endpointRx === null)
-        return null;
+        return () => false;
+    return (capture) => endpointRx.test(capture.url);
+}
+/**
+ * A capture predicate matching whichever capture actually holds
+ * {@link FoldReturnSpec.resultsPath}'s object array — the flow's own PRIMARY
+ * results source, as opposed to {@link compileFoldReturnEndpointMatcher}'s
+ * `endpointPattern` match (the drill-down). REST's `extractActionSequence`
+ * never needs this: a REST primary is a POST/non-GET and is admitted
+ * unconditionally regardless of `foldReturnSpec`. GraphQL's primary is
+ * always a `query`, and `extractGraphQLActionSequence` drops every
+ * non-mutation capture by default, so without this predicate a declared
+ * `foldReturnSpec` would admit only the drill-down capture and never the
+ * read op whose response the drill-down folds onto — leaving
+ * `buildFoldPlanFromSpec` with no `primaryStepIndex` to resolve against.
+ */
+function compileFoldReturnResultsMatcher(spec) {
+    if (spec === null)
+        return () => false;
+    const resultsPath = spec.resultsPath.split(".");
+    return (capture) => objectItemsAtPath(capture.responseBody, resultsPath) !== null;
+}
+function buildFoldPlanFromSpec(actions, spec) {
+    const primaryArrayPath = spec.resultsPath.split(".");
+    const matchesFoldReturnEndpoint = compileFoldReturnEndpointMatcher(spec);
+    // Built once and shared across every primaryStepIndex — see
+    // buildRequestValueIndex's docstring. Lets each primary immediately tell
+    // whether ANY action anywhere carries one of its own join values before
+    // paying for anything else, instead of scanning its own drill candidates
+    // one by one only to discover none of them can ever match.
+    const requestValueIndex = buildRequestValueIndex(actions);
     let freshestPlan = null;
     for (let primaryStepIndex = 0; primaryStepIndex < actions.length; primaryStepIndex++) {
         const primaryItems = objectItemsAtPath(actions[primaryStepIndex].capture.responseBody, primaryArrayPath);
         if (!primaryItems)
             continue;
+        const joinValues = collectPrimaryJoinValues(primaryItems, spec.joinFields);
+        const candidateEntryIndicesDescending = collectCandidateEntryIndicesDescending(requestValueIndex, joinValues, primaryStepIndex);
+        // No action anywhere carries any of this primary's join values, so no
+        // drillStepIndex candidate could ever resolve — skip straight to the
+        // next primary instead of scanning this one's drill candidates (each of
+        // which would only rediscover the same dead end).
+        if (candidateEntryIndicesDescending.length === 0)
+            continue;
+        // Cheap regex-only pass first: collects every endpointPattern-matching
+        // drillStepIndex without paying for the expensive backward-walk +
+        // computeFoldChain resolution below. Scanned from the freshest (highest)
+        // index down so the expensive resolution — tried only on the entries
+        // this loop actually visits — runs on the candidate that would win
+        // ties in the original last-write-wins scan first, falling through to
+        // the next-freshest only when a candidate fails to resolve, instead of
+        // resolving every earlier occurrence just to have it overwritten.
+        const matchingDrillStepIndices = [];
         for (let drillStepIndex = primaryStepIndex + 1; drillStepIndex < actions.length; drillStepIndex++) {
+            if (matchesFoldReturnEndpoint(actions[drillStepIndex].capture)) {
+                matchingDrillStepIndices.push(drillStepIndex);
+            }
+        }
+        // Shared across every matching-drill candidate tried below for THIS
+        // primaryStepIndex — see resolveSpecMatchedPrimaryItemIndexAlongChain's
+        // docstring on why a fresh cache per primary (not per drill candidate)
+        // is what collapses the backward-walk from O(candidates * chain length)
+        // to O(chain length).
+        const matchedItemIndexCache = new Map();
+        for (let i = matchingDrillStepIndices.length - 1; i >= 0; i--) {
+            const drillStepIndex = matchingDrillStepIndices[i];
             const drill = actions[drillStepIndex];
-            if (!endpointRx.test(drill.capture.url))
-                continue;
             // Widened to a flat (non-array) object response the same way the
             // structural heuristic is (see findAllObjectArrayFieldsOrWholeObject):
             // an explicit foldReturn declaration must be able to express a
@@ -5090,17 +5598,31 @@ function buildFoldPlanFromSpec(actions, spec) {
             // now does (see detectDrillDownFoldPlan). Validated after the chain
             // resolves, below, since `[]` is a valid empty baseline for
             // computeFoldChain but not a valid final drillArrayPath on its own.
+            const matchResult = resolveSpecMatchedPrimaryItemIndexAlongChain(actions, primaryItems, spec.joinFields, drillStepIndex, matchedItemIndexCache, candidateEntryIndicesDescending);
+            if (matchResult === null)
+                continue;
+            const { entryIndex, primaryMatchedItemIndex } = matchResult;
+            // Rooted at `entryIndex` — the step whose request ACTUALLY carries the
+            // join key — not `drillStepIndex`, so an upstream entry hop the join
+            // key was only resolvable through (e.g. a header-threaded token) is
+            // itself part of `chain` and gets re-executed (join-parameterized) per
+            // primary item at runtime, same as every structurally-detected chain.
+            // `drillResultsPath`, when given, still targets `drillStepIndex`'s own
+            // response specifically (the endpoint the spec names); it is otherwise
+            // left for computeFoldChain's own forward richness walk to resolve,
+            // exactly as it does for every step beyond the chain's entry.
             const drillArrayPath = (() => {
+                if (entryIndex !== drillStepIndex) {
+                    return (findObjectArrayFieldOrWholeObject(actions[entryIndex].capture.responseBody)?.path ??
+                        null);
+                }
                 if (spec.drillResultsPath === undefined) {
                     return findObjectArrayFieldOrWholeObject(drill.capture.responseBody)?.path ?? null;
                 }
                 const path = spec.drillResultsPath.split(".");
                 return objectItemsAtPath(drill.capture.responseBody, path) ? path : null;
             })();
-            const primaryMatchedItemIndex = resolveSpecMatchedPrimaryItemIndex(primaryItems, spec.joinFields, drill.capture);
-            if (primaryMatchedItemIndex === null)
-                continue;
-            const { chain, chainArrayPath, chainTerminalIndex } = computeFoldChain(actions, drillStepIndex, drillArrayPath ?? []);
+            const { chain, chainArrayPath, chainTerminalIndex } = computeFoldChain(actions, entryIndex, drillArrayPath ?? []);
             // The chain's resolved terminal must actually hold foldable data —
             // an intermediate drill step with neither its own candidate NOR a
             // later chained step that resolves one has nothing to merge, so it
@@ -5114,7 +5636,7 @@ function buildFoldPlanFromSpec(actions, spec) {
                 targets: [
                     {
                         joinFields: spec.joinFields,
-                        drillStepIndex,
+                        drillStepIndex: entryIndex,
                         drillArrayPath: drillArrayPath ?? [],
                         primaryMatchedItemIndex,
                         chain,
@@ -5123,6 +5645,7 @@ function buildFoldPlanFromSpec(actions, spec) {
                     },
                 ],
             };
+            break;
         }
     }
     return freshestPlan;
@@ -5207,6 +5730,62 @@ function mergeSpecPlanOntoSamePrimary(structuralPlans, actions, foldReturnSpec)
  * plan that survives multipart disqualification, letting every downstream
  * emitter/shape-inference caller fold each of them.
  */
+/**
+ * Every value ACTUALLY threaded from one dependent-drill-down chain hop's
+ * response into a LATER chain hop's own request/headers — the same overlap
+ * `computeFoldChain`'s `dependsOnChain` check already computes to decide a
+ * step belongs in the chain at all — across every fold target
+ * `detectDrillDownFoldPlan` / `buildFoldPlanFromSpec` resolve. These are the
+ * values `indexStateValues` must index as producible state regardless of
+ * `MIN_STATE_VALUE_LENGTH`, so `compileActionSteps` can thread a
+ * chain-produced join value into the next hop's request even when that
+ * value is a short one (e.g. a bare numeric status token).
+ *
+ * Deliberately NOT "every leaf value on a chain hop's response" — a chain
+ * terminal's response commonly ECHOES the primary item's own join field
+ * back (e.g. `sku` on the folded record), and that echoed value is a
+ * PRIMARY-ITEM field the fold loop's own per-item render already threads
+ * literally (see {@link findThreadedJoinFields}'s docstring); sweeping it
+ * into state-threading's single-earliest-origin index would collapse every
+ * item's distinct value onto whichever item's capture was indexed first.
+ * Restricting to values that themselves reappear in a STRICTLY LATER chain
+ * hop's own request — real cross-call threading, not an echo sitting still
+ * in one response — keeps this exact to the shape state-threading is
+ * actually needed for.
+ *
+ * Runs directly off raw actions (not `resolveFoldPlan`, which needs
+ * `isMultipart` — unavailable before `compileActionSteps` has run) since
+ * fold-plan DETECTION depends only on each action's `capture`.
+ */
+function collectDependentDrillDownChainValues(actions, foldReturnSpec) {
+    const structuralPlans = detectDrillDownFoldPlan(actions);
+    const specPlan = foldReturnSpec === null ? null : buildFoldPlanFromSpec(actions, foldReturnSpec);
+    const plans = structuralPlans.length > 0 ? structuralPlans : specPlan === null ? [] : [specPlan];
+    const values = new Set();
+    for (const plan of plans) {
+        for (const target of plan.targets) {
+            for (let j = 0; j < target.chain.length; j++) {
+                const priorIndex = target.chain[j];
+                const priorCapture = actions[priorIndex]?.capture;
+                if (!priorCapture)
+                    continue;
+                const responseValues = collectResponseLeafValues(priorCapture);
+                const echoedValues = collectRequestValuesIncludingHeaders(priorCapture);
+                for (let k = j + 1; k < target.chain.length; k++) {
+                    const laterCapture = actions[target.chain[k]]?.capture;
+                    if (!laterCapture)
+                        continue;
+                    const laterRequestValues = collectRequestValuesIncludingHeaders(laterCapture);
+                    for (const v of responseValues) {
+                        if (!echoedValues.has(v) && laterRequestValues.has(v))
+                            values.add(v);
+                    }
+                }
+            }
+        }
+    }
+    return values;
+}
 function resolveFoldPlan(actions, foldReturnSpec = null) {
     const structuralPlans = detectDrillDownFoldPlan(actions);
     const plans = structuralPlans.length > 0
@@ -6573,7 +7152,9 @@ async function main() {
     // Hoisted so both the primary-operation gate below and rawActionCaptures
     // (further down) read the same computed sequence instead of calling the
     // extractor twice.
-    const graphqlActionSequence = gql ? extractGraphQLActionSequence(captures, submitPatterns) : [];
+    const graphqlActionSequence = gql
+        ? extractGraphQLActionSequence(captures, submitPatterns, foldReturnSpec)
+        : [];
     const primaryGraphQLOperation = gql && graphqlActionSequence.length === 0
         ? selectPrimaryGraphQLOperation(captures, flowSteps, vocabulary, process.env, ownBackendHostnames, fallbackDomain)
         : null;
@@ -6624,7 +7205,7 @@ async function main() {
     // heuristic extraction finds.
     const patternedHeuristicActionCaptures = gql
         ? graphqlActionSequence
-        : collapseRedundantPatches(extractActionSequence(captures, submitPatterns));
+        : collapseRedundantPatches(extractActionSequence(captures, submitPatterns, foldReturnSpec));
     // The same undercount hazard applies one layer below the manifest: a
     // flow-declared submitEndpointPattern that matches only one section's URL
     // (the natural way to describe "the button that finishes the wizard")
@@ -6637,8 +7218,8 @@ async function main() {
     const unfilteredHeuristicActionCaptures = submitPatterns.endpoint === null && submitPatterns.body === null
         ? patternedHeuristicActionCaptures
         : gql
-            ? extractGraphQLActionSequence(captures, null)
-            : collapseRedundantPatches(extractActionSequence(captures, null));
+            ? extractGraphQLActionSequence(captures, null, foldReturnSpec)
+            : collapseRedundantPatches(extractActionSequence(captures, null, foldReturnSpec));
     const patternUndercounts = patternedHeuristicActionCaptures.length < unfilteredHeuristicActionCaptures.length;
     if (patternUndercounts) {
         logger.info(`submission selection: ignoring submitEndpointPattern/submitBodyPattern (${patternedHeuristicActionCaptures.length} capture(s)) as an undercount of the unfiltered heuristic action sequence (${unfilteredHeuristicActionCaptures.length} capture(s))`);
@@ -6669,8 +7250,8 @@ async function main() {
     const rawUnfilteredActionCaptures = submitEndpointPattern === null
         ? null
         : gql
-            ? extractGraphQLActionSequence(captures, null)
-            : collapseRedundantPatches(extractActionSequence(captures, null));
+            ? extractGraphQLActionSequence(captures, null, foldReturnSpec)
+            : collapseRedundantPatches(extractActionSequence(captures, null, foldReturnSpec));
     // Form-schema detection runs BEFORE state-indexing so the field-id/option-id
     // UUIDs can be shielded from indexing — those UUIDs are stable schema
     // anchors that T2/T3 substitution depends on remaining literal in body
@@ -6718,8 +7299,16 @@ async function main() {
         ];
     })();
     const actionCaptureIndices = new Set(actionCaptures.map((a) => a.index));
+    // Resolved off raw actionCaptures — fold-plan DETECTION depends only on
+    // each action's capture, so this runs before compileActionSteps/
+    // indexStateValues even exist — so a short numeric join value threaded
+    // through a dependent-drill-down chain hop still gets indexed as
+    // producible state (see collectDependentDrillDownChainValues).
+    const dependentDrillDownChainValues = actionCaptures.length > 1
+        ? collectDependentDrillDownChainValues(actionCaptures, foldReturnSpec)
+        : new Set();
     const stateIndex = actionCaptures.length > 1
-        ? indexStateValues(captures, shieldedUuids, actionCaptureIndices)
+        ? indexStateValues(captures, shieldedUuids, actionCaptureIndices, dependentDrillDownChainValues)
         : new Map();
     const actionSteps = actionCaptures.length > 1 ? compileActionSteps(actionCaptures, stateIndex) : [];
     const isSubmissionFlow = actionSteps.length > 1;