@enricai/barnacle 1.12.22 → 1.12.24

package/dist/scripts/recon-generate.js

@@ -63,6 +63,7 @@ exports.collectRequestValuesIncludingHeaders = collectRequestValuesIncludingHead
 exports.getFoldPlanResolutionCallCountForTests = getFoldPlanResolutionCallCountForTests;
 exports.resetFoldPlanResolutionCallCountForTests = resetFoldPlanResolutionCallCountForTests;
 exports.resolveFoldPlan = resolveFoldPlan;
+exports.resolveApplicableFoldPlans = resolveApplicableFoldPlans;
 exports.buildContractChecklist = buildContractChecklist;
 exports.emitContractTs = emitContractTs;
 exports.assertRequiredUrlFieldsReferenced = assertRequiredUrlFieldsReferenced;
@@ -911,15 +912,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
@@ -3661,6 +3669,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) {
@@ -4236,40 +4293,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;
@@ -5369,6 +5393,29 @@ function resolveSpecMatchedPrimaryItemIndex(primaryItems, joinFields, drillCaptu
     }));
     return matchedIndex === -1 ? null : matchedIndex;
 }
+/** Like {@link resolveSpecMatchedPrimaryItemIndex}, but matches against the
+ * drill capture's own RESPONSE instead of its request — a `foldReturn`
+ * spec's `joinFields` names the field the AUTHOR knows the drill-down
+ * response carries (so `emitFoldMatchAndMergeLines` can match it back onto a
+ * primary item at runtime); it names nothing about what the drill's REQUEST
+ * carries, which is very often a completely different per-item field (e.g. a
+ * REST drill-down keyed by an item's `packageCode` whose response happens to
+ * echo back that item's `id`). Tried only as a fallback, after the
+ * request-based match, since a request-carried join value disambiguates a
+ * drill occurrence unambiguously while a response-only match can in
+ * principle collide across primary items with the same response shape. */
+function resolveSpecMatchedPrimaryItemIndexFromResponse(primaryItems, joinFields, drillCapture) {
+    const responseValues = collectResponseLeafValues(drillCapture);
+    if (responseValues.size === 0)
+        return null;
+    const matchedIndex = primaryItems.findIndex((item) => joinFields.every((field) => {
+        const value = readValueAtPath(item, field.split("."));
+        return ((typeof value === "string" && value.length > 0 && responseValues.has(value)) ||
+            (typeof value === "number" && responseValues.has(String(value))) ||
+            (typeof value === "boolean" && responseValues.has(String(value))));
+    }));
+    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
@@ -5555,12 +5602,6 @@ function buildFoldPlanFromSpec(actions, spec) {
             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)
@@ -5569,12 +5610,24 @@ function buildFoldPlanFromSpec(actions, spec) {
         // 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.
+        //
+        // Computed even when `candidateEntryIndicesDescending` is empty (unlike
+        // the request-based path below, which bails immediately in that case):
+        // an endpointPattern match is a single regex test per action, O(actions)
+        // regardless — not the O(actions)-per-candidate backward walk the
+        // request-based prune exists to avoid — so it stays cheap even when no
+        // request anywhere carries this primary's join values, which is exactly
+        // the case {@link resolveSpecMatchedPrimaryItemIndexFromResponse}'s
+        // response-only fallback below exists to resolve.
         const matchingDrillStepIndices = [];
         for (let drillStepIndex = primaryStepIndex + 1; drillStepIndex < actions.length; drillStepIndex++) {
             if (matchesFoldReturnEndpoint(actions[drillStepIndex].capture)) {
                 matchingDrillStepIndices.push(drillStepIndex);
             }
         }
+        if (candidateEntryIndicesDescending.length === 0 && matchingDrillStepIndices.length === 0) {
+            continue;
+        }
         // 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)
@@ -5598,7 +5651,18 @@ 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);
+            const chainMatchResult = resolveSpecMatchedPrimaryItemIndexAlongChain(actions, primaryItems, spec.joinFields, drillStepIndex, matchedItemIndexCache, candidateEntryIndicesDescending);
+            // A request-carried join value (checked above, across this whole
+            // primary/drill chain) disambiguates unambiguously; only fall back to
+            // matching the drill's own RESPONSE — which never disambiguates an
+            // upstream entry hop, only the drill step itself — when that fails.
+            const matchResult = chainMatchResult ??
+                (() => {
+                    const primaryMatchedItemIndex = resolveSpecMatchedPrimaryItemIndexFromResponse(primaryItems, spec.joinFields, drill.capture);
+                    return primaryMatchedItemIndex === null
+                        ? null
+                        : { entryIndex: drillStepIndex, primaryMatchedItemIndex };
+                })();
             if (matchResult === null)
                 continue;
             const { entryIndex, primaryMatchedItemIndex } = matchResult;
@@ -5674,14 +5738,26 @@ function mergeSpecPlanOntoSamePrimary(structuralPlans, actions, foldReturnSpec)
     const samePrimaryPlan = structuralPlans.find((plan) => plan.primaryStepIndex === specPlan.primaryStepIndex &&
         JSON.stringify(plan.primaryArrayPath) === JSON.stringify(specPlan.primaryArrayPath));
     if (samePrimaryPlan !== undefined) {
+        // A drillStepIndex the structural heuristic ALSO resolved keeps its
+        // structurally-resolved chain/drillArrayPath (already proven to reach
+        // real per-item data), but its `joinFields` is overridden to the spec's
+        // declared value — the heuristic's own joinFields only prove a field
+        // threads INTO the drill's REQUEST, which says nothing about whether
+        // that same field can be found on the drill's RESPONSE to match it back
+        // onto a primary item (see emitFoldMatchAndMergeLines). A flow author
+        // declaring `joinFields` on a foldReturn is asserting exactly that: this
+        // is the field their drill-down's RESPONSE actually carries.
+        const specTargetsByDrillStepIndex = new Map(specPlan.targets.map((target) => [target.drillStepIndex, target]));
         return structuralPlans.map((plan) => {
             if (plan !== samePrimaryPlan)
                 return plan;
+            const mergedTargets = plan.targets.map((target) => {
+                const specTarget = specTargetsByDrillStepIndex.get(target.drillStepIndex);
+                return specTarget === undefined ? target : { ...target, joinFields: specTarget.joinFields };
+            });
             const existingDrillStepIndexes = new Set(plan.targets.map((target) => target.drillStepIndex));
             const newTargets = specPlan.targets.filter((target) => !existingDrillStepIndexes.has(target.drillStepIndex));
-            return newTargets.length === 0
-                ? plan
-                : { ...plan, targets: [...plan.targets, ...newTargets] };
+            return { ...plan, targets: [...mergedTargets, ...newTargets] };
         });
     }
     // Keyed by the (primaryStepIndex, primaryArrayPath) pair, not
@@ -5801,6 +5877,19 @@ function resolveFoldPlan(actions, foldReturnSpec = null) {
         return targets.length === 0 ? [] : [{ ...plan, targets }];
     });
 }
+/**
+ * The fold plans `emitContractTs` actually threads into its single-primary
+ * hot path — a multi-step flow owns its own per-item fold loop (via
+ * `emitMultiStepExecuteHttp`) instead, so this resolves to none there.
+ * Exported and shared verbatim by `emitContractTs` and the "no fold plan
+ * resolved" diagnostic in `main()` so the two can never independently decide
+ * whether a declared foldReturn actually made it into the emitted output —
+ * any future exclusion added to the single-primary hot path must be added
+ * here too, and both call sites pick it up automatically.
+ */
+function resolveApplicableFoldPlans(actions, foldReturnSpec, multiStepBody) {
+    return multiStepBody ? [] : resolveFoldPlan(actions, foldReturnSpec);
+}
 /** Rebuilds `value` with every occurrence of `target` (compared by object
  * identity) replaced by `replacement`, spreading every ancestor
  * array/object level so sibling fields and sibling array elements survive
@@ -5915,9 +6004,17 @@ function buildNestedSpreadOverride(base, path, leafExpr) {
  * the observed page size on each call, stops once the response's own
  * reported total is reached or `MAX_PAGES` caps it, and merges pages by the
  * detected identity field rather than concatenating blindly.
+ *
+ * `foldMergeLines`, when non-empty, threads a resolved single-primary fold
+ * plan (see `emitContractTs`'s `singlePrimaryFoldPlans`) additively into the
+ * loop: it runs once, after every page has been fetched and de-duplicated
+ * into `itemsById`, so the drill-down call/merge sees the final assembled
+ * item set rather than only the first page's captured sample. Each merge
+ * mutates its item in place (`Object.assign`), which is visible through
+ * `itemsById`'s own stored references — no re-`set` needed.
  */
 function buildPaginatedGqlExecuteHttpBody(opts) {
-    const { pascal, gqlOperationNameExpr, queryConstName, gqlVariablesExpr, signal } = opts;
+    const { pascal, gqlOperationNameExpr, queryConstName, gqlVariablesExpr, signal, foldMergeLines } = opts;
     const { totalPath, arrayPath, containerPath, countKey, skipKey, pageSize, identityField } = signal;
     const countKeyExpr = isValidJsIdentifier(countKey) ? countKey : JSON.stringify(countKey);
     const skipKeyExpr = isValidJsIdentifier(skipKey) ? skipKey : JSON.stringify(skipKey);
@@ -5957,7 +6054,7 @@ function buildPaginatedGqlExecuteHttpBody(opts) {
       }
       skip += PAGE_SIZE;
     }
-    const truncated = itemsById.size < total;
+${foldMergeLines.length > 0 ? `${foldMergeLines.join("\n")}\n` : ""}    const truncated = itemsById.size < total;
     const withItems = ${withItemsOverrideExpr};
     const data = ${withTotalOverrideExpr} as ${pascal}Response;
     return { data };`;
@@ -6001,7 +6098,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
@@ -6069,6 +6166,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).
+    // Also threaded additively into `paginationSignal`'s fetch loop below (see
+    // buildPaginatedGqlExecuteHttpBody) — the fold runs against the final
+    // assembled/de-duplicated page items, not just the first page's captured
+    // sample, so a paginated primary is no longer excluded from folding.
+    const singlePrimaryFoldPlans = resolveApplicableFoldPlans(actionSteps, foldReturnSpec, multiStepBody);
+    // 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({...})`
@@ -6312,7 +6425,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`
@@ -6338,7 +6451,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)} });
 `;
@@ -6348,6 +6469,107 @@ 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.
+     *
+     * `itemsExprOverride`, when given, replaces the `dataVarName`+`primaryArrayPath`
+     * accessor with a caller-supplied items expression — used by the paginated
+     * GraphQL fetch loop, whose merged/de-duplicated page items already sit in
+     * a flat runtime collection (`itemsById.values()`) rather than nested at
+     * `primaryArrayPath` inside a single response object. */
+    const buildFoldMergeLines = (dataVarName, itemsExprOverride) => {
+        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 = itemsExprOverride ??
+                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.
+                //
+                // Parameterizes off EVERY per-item field this specific chain hop's
+                // own captured request actually varies on (via findThreadedJoinFields),
+                // not just `target.joinFields` — `target.joinFields` names the field
+                // used to MATCH the drill's RESPONSE back onto the primary item (see
+                // emitFoldMatchAndMergeLines), which for a spec-declared foldReturn
+                // can legitimately be a field the request never carries at all (e.g.
+                // an `id` echoed only in the response, while the request is keyed by
+                // an unrelated field like a package code). Building the URL from only
+                // `target.joinFields` in that case would leave it unparameterized —
+                // every item would fetch the SAME first-captured URL.
+                const parameterizeUrl = (rawUrl, chainCapture) => {
+                    const withBase = baseUrl.length > 0 && rawUrl.startsWith(baseUrl)
+                        ? `\${context.baseUrl}${rawUrl.slice(baseUrl.length)}`
+                        : rawUrl;
+                    const threadedFields = new Set([
+                        ...target.joinFields,
+                        ...findThreadedJoinFields(firstItem, chainCapture),
+                    ]);
+                    return [...threadedFields].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, chainStep.capture);
+                    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` : "";
+    // The paginated fetch loop assembles its final page items into
+    // `itemsById` — fold onto THAT flat, de-duplicated collection (once, after
+    // the loop) rather than `data`/`primaryArrayPath`, so every item folded
+    // is the final merged item across all fetched pages, not just page one's.
+    const paginatedFoldMergeLines = paginationSignal
+        ? buildFoldMergeLines("data", "[...itemsById.values()]")
+        : [];
     const executeHttpBody = multiStepBody
         ? multiStepBody
         : paginationSignal
@@ -6357,15 +6579,16 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
                 queryConstName: `${pascal.toUpperCase()}_QUERY`,
                 gqlVariablesExpr,
                 signal: paginationSignal,
+                foldMergeLines: paginatedFoldMergeLines,
             })
             : 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
@@ -7155,7 +7378,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) {
@@ -7311,7 +7541,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
@@ -7429,8 +7659,18 @@ async function main() {
     const effectiveResponseBody = selectEffectiveResponseBody(isSubmissionFlow, actionSteps, responseBody, foldReturnSpec);
     // A declared foldReturn that resolves to no plan is a silent no-op otherwise
     // — the flow author gets the discarding selectReturnAction path with nothing
-    // in the output saying their declaration never applied.
-    if (foldReturnSpec !== null && resolveFoldPlan(actionSteps, foldReturnSpec).length === 0) {
+    // in the output saying their declaration never applied. A multi-step
+    // (submission) flow applies its fold via emitMultiStepExecuteHttp's own
+    // resolveFoldPlan call, entirely independent of resolveApplicableFoldPlans
+    // (which exists only to gate emitContractTs's single-primary hot path, and
+    // unconditionally reports zero plans once multiStepBody is set) — so this
+    // diagnostic must consult the SAME resolution each path actually applies,
+    // or it falsely reports "no fold plan resolved" for every multi-step flow
+    // with a working foldReturn.
+    const effectiveFoldPlanCount = multiStepBody
+        ? resolveFoldPlan(actionSteps, foldReturnSpec).length
+        : resolveApplicableFoldPlans(actionSteps, foldReturnSpec, multiStepBody).length;
+    if (foldReturnSpec !== null && effectiveFoldPlanCount === 0) {
         logger.warn(`flow declares foldReturn (endpointPattern: ${foldReturnSpec.endpointPattern}, resultsPath: ${foldReturnSpec.resultsPath}, joinFields: ${foldReturnSpec.joinFields.join(", ")}) but no fold plan resolved — no later capture matched the endpoint pattern, resultsPath resolved to no object array, or the matched drill-down is multipart; the drill-down's response will not be folded`);
     }
     logger.info(`generating plugin for ${siteId} (${gql ? "GraphQL" : browserFlowOnly ? `submission flow, ${actionSteps.length} steps, browser-flow-only (cross-domain hop detected)` : isSubmissionFlow ? `submission flow, ${actionSteps.length} steps` : "single-endpoint REST"}, baseUrl: ${baseUrl})`);
@@ -7502,6 +7742,8 @@ async function main() {
         isSubmissionFlow,
         inputBody,
         hasMultipartStep,
+        actionSteps,
+        foldReturnSpec,
         discoveredFormFields,
         fieldOptionsMap,
         discoveredOptionFields,