@enricai/barnacle 1.12.21 → 1.12.23

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;
@@ -903,15 +911,22 @@ function selectReturnAction(steps) {
  * clobbering the other. A plan whose folded body isn't a plain object can't
  * be merged meaningfully, so in that case this falls back to the LAST plan's
  * folded body alone, exactly as before this merge was introduced.
+ *
+ * The `!isSubmissionFlow` short-circuit only applies once no fold plan
+ * resolves: a single-primary read flow (isSubmissionFlow false) with a
+ * declared `foldReturn` still needs its primary body folded here, or the
+ * inferred response shape would omit every field the single-primary
+ * getGql/httpClient emission's own fold-merge loop (see `emitContractTs`)
+ * adds at runtime.
  */
 function selectEffectiveResponseBody(isSubmissionFlow, actionSteps, replayResponseBody, foldReturnSpec = null) {
-    if (!isSubmissionFlow)
-        return replayResponseBody;
     const foldPlans = resolveFoldPlan(actionSteps, foldReturnSpec);
     const lastFoldPlan = foldPlans[foldPlans.length - 1] ?? null;
     if (foldPlans.length <= 1) {
         if (lastFoldPlan)
             return foldResponseBodyForShapeInference(actionSteps, lastFoldPlan);
+        if (!isSubmissionFlow)
+            return replayResponseBody;
         return selectReturnAction(actionSteps)?.capture.responseBody ?? replayResponseBody;
     }
     // Plans sharing a primaryStepIndex (independent arrays on one primary
@@ -3653,6 +3668,55 @@ function emitErrorSignalGuards(varName, urlPath, signals) {
     }
     return out;
 }
+/**
+ * Emits the lines that match a fold target's drill-down chain response
+ * against the loop item and merge the match onto it — the last leg of a
+ * fold, shared by {@link emitMultiStepExecuteHttp}'s per-item loop and
+ * `emitContractTs`'s single-primary getGql/httpClient fold-merge loop, so
+ * both emitters describe the exact same match/merge semantics rather than
+ * two copies that could drift apart.
+ */
+function emitFoldMatchAndMergeLines(terminalStep, target, itemVar, suffix, joinAccessor) {
+    // An empty chainArrayPath means the terminal step's response IS the
+    // implicit one-item collection (see findAllObjectArrayFieldsOrWholeObject
+    // / objectItemsAtPath's flat-object branch): the response is a flat
+    // object at runtime, not an array. There is exactly one candidate, so
+    // no join-field match is needed (or even possible against an array
+    // API) — emit a direct object reference instead of the array
+    // `.find()` machinery the multi-item branch below needs.
+    if (target.chainArrayPath.length === 0) {
+        return [
+            `      const foldMatch${suffix} = ${terminalStep.varName} as Record<string, unknown>;`,
+            `      Object.assign(${itemVar}, foldMatch${suffix} ?? {});`,
+        ];
+    }
+    const foldMatchesExpr = pathToFoldAccessorExpr(`(${terminalStep.varName} as ${foldArrayAssertionType(target.chainArrayPath)})`, target.chainArrayPath);
+    return [
+        `      const foldMatches${suffix} = ${foldMatchesExpr};`,
+        `      const foldMatch${suffix} = foldMatches${suffix}.find((m) => ${target.joinFields
+            .map((f) => {
+            const segments = f.split(".");
+            // The drill-down response is a DIFFERENT payload than the
+            // primary item, so it has no obligation to mirror the
+            // primary item's own nesting for the join key (e.g. a
+            // primary item's `identifiers.sku` is typically echoed
+            // back flat, as `sku`, on the drill response). Try the
+            // full nested path first (optional-chained, since an
+            // intermediate segment may not exist on a flat response),
+            // then fall back to the bare last segment.
+            const lastSegment = segments[segments.length - 1];
+            const optionalBracketAccessor = segments
+                .map((segment) => `?.[${JSON.stringify(segment)}]`)
+                .join("");
+            const matchAccessor = segments.length > 1
+                ? `(m${optionalBracketAccessor} ?? m[${JSON.stringify(lastSegment)}])`
+                : `m[${JSON.stringify(lastSegment)}]`;
+            return `String(${matchAccessor}) === String(${joinAccessor(f)})`;
+        })
+            .join(" && ")}) ?? foldMatches${suffix}[0];`,
+        `      Object.assign(${itemVar}, foldMatch${suffix} ?? {});`,
+    ];
+}
 /** Exported for unit testing — lets tests drive the multipart-upload code path directly
  * without going through the full emitContractTs pipeline. */
 function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap, outDiscoveredFields, fieldOptionsMap, outDiscoveredOptionFields, outDiscoveredRawOptionFields, outDiscoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, formSchema = null, personaBindings = new Map(), entryUrlParams = new Map(), shieldedUuids = new Set(), selectResolutions = [], outStructuredKeys = new Map(), rawCodeFields = new Map(), foldReturnSpec = null) {
@@ -4228,40 +4292,7 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
                     }
                 }
                 const terminalStep = actions[target.chainTerminalIndex];
-                // An empty chainArrayPath means the terminal step's response IS the
-                // implicit one-item collection (see findAllObjectArrayFieldsOrWholeObject
-                // / objectItemsAtPath's flat-object branch): the response is a flat
-                // object at runtime, not an array. There is exactly one candidate, so
-                // no join-field match is needed (or even possible against an array
-                // API) — emit a direct object reference instead of the array
-                // `.find()` machinery the multi-item branch below needs.
-                if (target.chainArrayPath.length === 0) {
-                    lines.push(`      const foldMatch${suffix} = ${terminalStep.varName} as Record<string, unknown>;`, `      Object.assign(${itemVar}, foldMatch${suffix} ?? {});`);
-                }
-                else {
-                    const foldMatchesExpr = pathToFoldAccessorExpr(`(${terminalStep.varName} as ${foldArrayAssertionType(target.chainArrayPath)})`, target.chainArrayPath);
-                    lines.push(`      const foldMatches${suffix} = ${foldMatchesExpr};`, `      const foldMatch${suffix} = foldMatches${suffix}.find((m) => ${target.joinFields
-                        .map((f) => {
-                        const segments = f.split(".");
-                        // The drill-down response is a DIFFERENT payload than the
-                        // primary item, so it has no obligation to mirror the
-                        // primary item's own nesting for the join key (e.g. a
-                        // primary item's `identifiers.sku` is typically echoed
-                        // back flat, as `sku`, on the drill response). Try the
-                        // full nested path first (optional-chained, since an
-                        // intermediate segment may not exist on a flat response),
-                        // then fall back to the bare last segment.
-                        const lastSegment = segments[segments.length - 1];
-                        const optionalBracketAccessor = segments
-                            .map((segment) => `?.[${JSON.stringify(segment)}]`)
-                            .join("");
-                        const matchAccessor = segments.length > 1
-                            ? `(m${optionalBracketAccessor} ?? m[${JSON.stringify(lastSegment)}])`
-                            : `m[${JSON.stringify(lastSegment)}]`;
-                        return `String(${matchAccessor}) === String(${joinAccessor(f)})`;
-                    })
-                        .join(" && ")}) ?? foldMatches${suffix}[0];`, `      Object.assign(${itemVar}, foldMatch${suffix} ?? {});`);
-                }
+                lines.push(...emitFoldMatchAndMergeLines(terminalStep, target, itemVar, suffix, joinAccessor));
             }
             lines.push(`    }`, "");
             continue;
@@ -4591,17 +4622,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
@@ -4625,9 +4681,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}. */
@@ -4706,6 +4777,62 @@ 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)
@@ -4724,8 +4851,22 @@ function findThreadedJoinFields(item, drillCapture) {
  * 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. */
+ * (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(capture.responseBody)) {
         if (typeof value === "string" && value.length > 0)
@@ -4885,7 +5026,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)
@@ -4899,7 +5053,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;
@@ -4989,11 +5148,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);
@@ -5020,7 +5208,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;
@@ -5058,10 +5246,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);
             }
         }
     }
@@ -5170,10 +5358,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
@@ -5194,6 +5392,64 @@ function resolveSpecMatchedPrimaryItemIndex(primaryItems, joinFields, drillCaptu
     }));
     return matchedIndex === -1 ? null : matchedIndex;
 }
+/**
+ * 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
@@ -5210,9 +5466,49 @@ function resolveSpecMatchedPrimaryItemIndex(primaryItems, joinFields, drillCaptu
  * `drillStepIndex` alone would never include this upstream entry hop, so it
  * would never be re-executed (header-parameterized) per primary item at
  * runtime. */
-function resolveSpecMatchedPrimaryItemIndexAlongChain(actions, primaryItems, joinFields, primaryStepIndex, drillStepIndex) {
-    for (let entryIndex = drillStepIndex; entryIndex > primaryStepIndex; entryIndex--) {
-        const matched = resolveSpecMatchedPrimaryItemIndex(primaryItems, joinFields, actions[entryIndex].capture);
+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)
@@ -5269,15 +5565,48 @@ function compileFoldReturnResultsMatcher(spec) {
 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 (!matchesFoldReturnEndpoint(drill.capture))
-                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
@@ -5292,7 +5621,7 @@ 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, primaryStepIndex, drillStepIndex);
+            const matchResult = resolveSpecMatchedPrimaryItemIndexAlongChain(actions, primaryItems, spec.joinFields, drillStepIndex, matchedItemIndexCache, candidateEntryIndicesDescending);
             if (matchResult === null)
                 continue;
             const { entryIndex, primaryMatchedItemIndex } = matchResult;
@@ -5339,6 +5668,7 @@ function buildFoldPlanFromSpec(actions, spec) {
                     },
                 ],
             };
+            break;
         }
     }
     return freshestPlan;
@@ -5694,7 +6024,7 @@ function buildContractChecklist(opts) {
     ].filter((line) => line !== "");
 }
 function emitContractTs(opts) {
-    const { siteId, displayName, pascal, baseUrl, baseHeaders, minTime, safeRps, hasRateLimitProbeData = false, responseBody, responseBodySamples = [responseBody], gql, gqlQuery, endpointPath, gqlOperationName, gqlVariables, auxFiles, multiStepBody, omitExecuteHttp = false, isSubmissionFlow = false, inputBody, hasMultipartStep = false, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, discoveredStructuredKeys, payloadFieldNames, headerBindings = [], unpopulatedDeclaredVariables = [], } = opts;
+    const { siteId, displayName, pascal, baseUrl, baseHeaders, minTime, safeRps, hasRateLimitProbeData = false, responseBody, responseBodySamples = [responseBody], gql, gqlQuery, endpointPath, gqlOperationName, gqlVariables, auxFiles, multiStepBody, omitExecuteHttp = false, isSubmissionFlow = false, inputBody, hasMultipartStep = false, actionSteps = [], foldReturnSpec = null, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, discoveredStructuredKeys, payloadFieldNames, headerBindings = [], unpopulatedDeclaredVariables = [], } = opts;
     // This is the CLIENT-level schema — createHttpClient's default, and the
     // plugin's caller-facing contract (what executeHttp's return value promises
     // its own caller). It does NOT validate any individual call in a multi-step
@@ -5762,6 +6092,22 @@ function emitContractTs(opts) {
     const paginationSignal = !multiStepBody && gql && gqlOperationName
         ? detectPaginationSignal(responseBody, gqlVariables)
         : null;
+    // A resolved drill-down fold plan on the single-primary getGql/httpClient
+    // hot path (`multiStepBody` unset — see emitMultiStepExecuteHttp for the
+    // multi-step equivalent) folds onto `data` in place, exactly as the
+    // multi-step loop folds onto its own primary var: without this, a
+    // single-primary read flow with a declared `foldReturn` would silently
+    // drop the fold feature the flow author declared (see
+    // recon-generate-foldreturn-regresses-primary-op-and-payload-to-ats-submission-shape.md).
+    // Not attempted alongside `paginationSignal` — a paginated primary's items
+    // span multiple page fetches this branch never issues, so a fold plan
+    // resolving against only the FIRST page's captured sample would be
+    // incomplete; that combination is out of scope here.
+    const singlePrimaryFoldPlans = multiStepBody || paginationSignal ? [] : resolveFoldPlan(actionSteps, foldReturnSpec);
+    // A GraphQL primary with a resolved drill-down fold has no other REST
+    // client to issue the drill request(s) with — getGql only ever speaks
+    // GraphQL to the primary endpoint.
+    const needsFoldHttpClient = gql && singlePrimaryFoldPlans.length > 0;
     // Every field source below (the base extend's own keys, form-schema
     // discovery, browser-flow splicing, option/raw-option enums, additional
     // body keys, and structured keys) is merged into a SINGLE `.extend({...})`
@@ -6005,7 +6351,7 @@ function emitContractTs(opts) {
     const clientImport = omitExecuteHttp
         ? ""
         : gql
-            ? `import { createGraphqlClient } from "${ENGINE_PKG}/scraper/graphql-client";`
+            ? `import { createGraphqlClient } from "${ENGINE_PKG}/scraper/graphql-client";${needsFoldHttpClient ? `\nimport { createHttpClient } from "${ENGINE_PKG}/scraper/http-client";` : ""}`
             : `import { createHttpClient } from "${ENGINE_PKG}/scraper/http-client";`;
     const queryConst = !omitExecuteHttp && gql && gqlQuery
         ? `\n// Lifted verbatim from recon capture. The adjacent response schema is drift-tolerant by construction (dropped __typename, .loose() objects), so this query text is not hand-trimmed.\nconst ${pascal.toUpperCase()}_QUERY = \`${gqlQuery.trim()}\`;\n`
@@ -6031,7 +6377,15 @@ function getGql(baseUrl: string): GqlFn {
   }
   return client;
 }
+${
+            // A GraphQL primary with a resolved drill-down fold has no other REST
+            // client to issue the drill request(s) with — getGql only ever speaks
+            // GraphQL to the primary endpoint.
+            needsFoldHttpClient
+                ? `
+const httpClient = createHttpClient({ schema: z.unknown(), bottleneck: limiter, baseHeaders: BASE_HEADERS${bindOptionLiteral(headerBindings)} });
 `
+                : ""}`
             : `
 const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottleneck: limiter, baseHeaders: BASE_HEADERS${bindOptionLiteral(headerBindings)} });
 `;
@@ -6041,6 +6395,78 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
     const gqlVariablesExpr = gqlOperationName
         ? renderGqlVariablesExpr(gqlVariables, payloadFieldNames)
         : "{ q: payload.query }";
+    /** Builds the `for (const item of foldItems) { ... }` block(s) that fold
+     * every resolved plan's drill-down data onto `dataVarName`'s primary array
+     * — the single-primary counterpart of emitMultiStepExecuteHttp's own
+     * per-item loop, sharing its match/merge tail via
+     * {@link emitFoldMatchAndMergeLines} so the two can't describe different
+     * merge semantics. Chain hops beyond the drill step itself are rendered
+     * directly off each hop's own captured request (no state-threading
+     * pipeline) since a single-primary read flow carries no submitted payload
+     * for those calls to reference. */
+    const buildFoldMergeLines = (dataVarName) => {
+        const lines = [];
+        for (const [planIndex, foldPlan] of singlePrimaryFoldPlans.entries()) {
+            const primaryStep = actionSteps[foldPlan.primaryStepIndex];
+            if (!primaryStep)
+                continue;
+            const primaryItems = objectItemsAtPath(primaryStep.capture.responseBody, foldPlan.primaryArrayPath);
+            const primaryArrType = foldArrayAssertionType(foldPlan.primaryArrayPath);
+            const planSuffix = singlePrimaryFoldPlans.length > 1 ? String(planIndex) : "";
+            const foldItemsVar = `foldItems${planSuffix}`;
+            const foldItemsExpr = pathToFoldAccessorExpr(`(${dataVarName} as ${primaryArrType})`, foldPlan.primaryArrayPath);
+            const itemVar = `item${planSuffix}`;
+            lines.push(`    const ${foldItemsVar} = ${foldItemsExpr};`, `    for (const ${itemVar} of ${foldItemsVar}) {`);
+            for (const [targetIndex, target] of foldPlan.targets.entries()) {
+                const firstItem = primaryItems?.[target.primaryMatchedItemIndex];
+                if (!firstItem) {
+                    throw new Error(`emitContractTs: fold plan primary step ${foldPlan.primaryStepIndex} no longer resolves an object array at ${foldPlan.primaryArrayPath.join(".")} — the fold plan and this emitter have drifted out of sync`);
+                }
+                const suffix = foldPlan.targets.length > 1 ? `${planSuffix}${targetIndex}` : planSuffix;
+                const joinAccessor = (field) => `${itemVar}${pathToAccessor(field.split("."), { assertNonNull: false })}`;
+                // Same word-boundary-anchored swap emitMultiStepExecuteHttp's own
+                // `parameterize` performs — a plain split/join would also rewrite
+                // unrelated substrings that happen to contain the join value.
+                const parameterizeUrl = (rawUrl) => {
+                    const withBase = baseUrl.length > 0 && rawUrl.startsWith(baseUrl)
+                        ? `\${context.baseUrl}${rawUrl.slice(baseUrl.length)}`
+                        : rawUrl;
+                    return target.joinFields.reduce((acc, field) => {
+                        const value = readValueAtPath(firstItem, field.split("."));
+                        const stringValue = typeof value === "string" && value.length > 0
+                            ? value
+                            : typeof value === "number" || typeof value === "boolean"
+                                ? String(value)
+                                : null;
+                        if (stringValue === null)
+                            return acc;
+                        return acc.replace(new RegExp(`\\b${stringValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "g"), `\${${joinAccessor(field)}}`);
+                    }, withBase);
+                };
+                for (const chainIndex of target.chain) {
+                    const chainStep = actionSteps[chainIndex];
+                    if (!chainStep)
+                        continue;
+                    const url = parameterizeUrl(chainStep.capture.url);
+                    const schemaExpr = inferZodSchema(chainStep.capture.responseBody, 0, "", {
+                        looseServerResponse: true,
+                        aggregateUnitBasisFindingsByPath: groupAggregateUnitBasisFindingsByPath([
+                            chainStep.capture.responseBody,
+                        ]),
+                    });
+                    lines.push(`      const ${chainStep.varName} = (await httpClient(\`${url}\`, {`, `        method: ${JSON.stringify(chainStep.capture.method)},`, `        schema: ${schemaExpr},`, `      })) as Record<string, unknown>;`);
+                }
+                const terminalStep = actionSteps[target.chainTerminalIndex];
+                if (!terminalStep)
+                    continue;
+                lines.push(...emitFoldMatchAndMergeLines(terminalStep, target, itemVar, suffix, joinAccessor));
+            }
+            lines.push(`    }`, "");
+        }
+        return lines;
+    };
+    const dataFoldMergeLines = buildFoldMergeLines("data");
+    const dataFoldMergeBlock = dataFoldMergeLines.length > 0 ? `${dataFoldMergeLines.join("\n")}\n` : "";
     const executeHttpBody = multiStepBody
         ? multiStepBody
         : paginationSignal
@@ -6053,12 +6479,12 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
             })
             : gql
                 ? `    const data = await getGql(context.baseUrl)(${gqlOperationNameExpr}, ${pascal.toUpperCase()}_QUERY, ${gqlVariablesExpr});
-    return { data };`
+${dataFoldMergeBlock}    return { data };`
                 : `    const data = await httpClient(\`\${context.baseUrl}${endpointPath}\`, {
       method: "POST",
       body: JSON.stringify({ query: payload.query }),
     });
-    return { data };`;
+${dataFoldMergeBlock}    return { data };`;
     const fixtureComments = auxFiles.length > 0
         ? `\n// Fixtures downloaded by recon — commit to src/sites/${siteId}/fixtures/ and uncomment:\n` +
             auxFiles
@@ -6848,7 +7274,14 @@ async function main() {
     const graphqlActionSequence = gql
         ? extractGraphQLActionSequence(captures, submitPatterns, foldReturnSpec)
         : [];
-    const primaryGraphQLOperation = gql && graphqlActionSequence.length === 0
+    // A foldReturn-admitted read/drill capture (see extractGraphQLActionSequence's
+    // doc comment) can put 2+ entries in graphqlActionSequence with none of them
+    // an actual `mutation` — a GraphQL-primary query plus its drill-down, not a
+    // transactional multi-step submission. Only a real mutation makes this a
+    // submission flow; an admitted read/drill capture must not, on its own, null
+    // out primaryGraphQLOperation below or flip isSubmissionFlow further down.
+    const graphqlActionSequenceHasMutation = graphqlActionSequence.some((a) => a.capture.query !== null && /^\s*mutation\b/.test(a.capture.query));
+    const primaryGraphQLOperation = gql && !graphqlActionSequenceHasMutation
         ? selectPrimaryGraphQLOperation(captures, flowSteps, vocabulary, process.env, ownBackendHostnames, fallbackDomain)
         : null;
     if (primaryGraphQLOperation && primaryGraphQLOperation.unpopulatedDeclaredVariables.length > 0) {
@@ -7004,7 +7437,7 @@ async function main() {
         ? indexStateValues(captures, shieldedUuids, actionCaptureIndices, dependentDrillDownChainValues)
         : new Map();
     const actionSteps = actionCaptures.length > 1 ? compileActionSteps(actionCaptures, stateIndex) : [];
-    const isSubmissionFlow = actionSteps.length > 1;
+    const isSubmissionFlow = actionSteps.length > 1 && (!gql || graphqlActionSequenceHasMutation);
     // Loud failure for a submitEndpointPattern that under-matches the raw traffic badly
     // enough to collapse the flow to the single-endpoint fallback: heuristicActionCaptures
     // is the pattern-filtered sequence (used both directly and as rawActionCaptures' floor
@@ -7195,6 +7628,8 @@ async function main() {
         isSubmissionFlow,
         inputBody,
         hasMultipartStep,
+        actionSteps,
+        foldReturnSpec,
         discoveredFormFields,
         fieldOptionsMap,
         discoveredOptionFields,