@enricai/barnacle 1.12.18 → 1.12.20

package/dist/scripts/recon-generate.js

@@ -29,10 +29,12 @@ exports.harvestPersonaBindings = harvestPersonaBindings;
 exports.resolveCompositePersonaFields = resolveCompositePersonaFields;
 exports.collectConditionalGraphQLFieldNames = collectConditionalGraphQLFieldNames;
 exports.inferZodSchemaFromSamples = inferZodSchemaFromSamples;
+exports.detectAggregateUnitBasisFindings = detectAggregateUnitBasisFindings;
 exports.selectPayloadAction = selectPayloadAction;
 exports.selectReturnAction = selectReturnAction;
 exports.selectEffectiveResponseBody = selectEffectiveResponseBody;
 exports.extractEntryUrlParams = extractEntryUrlParams;
+exports.gatherResponseBodySamples = gatherResponseBodySamples;
 exports.selectPrimaryGraphQLOperation = selectPrimaryGraphQLOperation;
 exports.firstEndpointCapture = firstEndpointCapture;
 exports.firstEndpointPath = firstEndpointPath;
@@ -50,6 +52,9 @@ exports.compileActionSteps = compileActionSteps;
 exports.collectHeaderBindings = collectHeaderBindings;
 exports.deriveProducerBoundaryBindings = deriveProducerBoundaryBindings;
 exports.emitMultiStepExecuteHttp = emitMultiStepExecuteHttp;
+exports.detectDrillDownFoldPlan = detectDrillDownFoldPlan;
+exports.parseFoldReturnSpec = parseFoldReturnSpec;
+exports.resolveFoldPlan = resolveFoldPlan;
 exports.buildContractChecklist = buildContractChecklist;
 exports.emitContractTs = emitContractTs;
 exports.assertRequiredUrlFieldsReferenced = assertRequiredUrlFieldsReferenced;
@@ -61,6 +66,7 @@ const node_path_1 = require("node:path");
 const ats_field_vocabulary_1 = require("../lib/ats-field-vocabulary");
 const errors_1 = require("../lib/errors");
 const logging_1 = require("../lib/logging");
+const merge_folded_primary_bodies_1 = require("../lib/merge-folded-primary-bodies");
 const plugin_api_version_1 = require("../plugins/plugin-api-version");
 const plugin_manifest_envelope_1 = require("../plugins/plugin-manifest-envelope");
 const capture_filters_1 = require("../recon/capture-filters");
@@ -508,7 +514,7 @@ function collectConditionalGraphQLFieldNames(query) {
  * what the endpoint actually returns rather than what one capture happened to
  * show.
  */
-function inferZodSchemaFromSamples(samples, depth = 0, indent = "", opts = {}) {
+function inferZodSchemaFromSamples(samples, depth = 0, indent = "", opts = {}, path = []) {
     const maxDepth = opts.maxDepth ?? DEFAULT_MAX_INFER_DEPTH;
     if (depth > maxDepth)
         return "z.unknown()";
@@ -546,11 +552,11 @@ function inferZodSchemaFromSamples(samples, depth = 0, indent = "", opts = {}) {
         const items = nonNull.flat();
         if (items.length === 0)
             return wrap("z.array(z.unknown())");
-        return wrap(`z.array(${inferZodSchemaFromSamples(items, depth + 1, indent, opts)})`);
+        return wrap(`z.array(${inferZodSchemaFromSamples(items, depth + 1, indent, opts, path)})`);
     }
     if (kind === "object") {
         const objects = nonNull;
-        const keys = [...new Set(objects.flatMap((o) => Object.keys(o)))];
+        const keys = [...new Set(objects.flatMap((o) => Object.keys(o)))].filter((k) => !(opts.looseServerResponse && k === "__typename"));
         if (keys.length === 0)
             return wrap("z.record(z.string(), z.unknown())");
         const inner = `${indent}  `;
@@ -558,18 +564,26 @@ function inferZodSchemaFromSamples(samples, depth = 0, indent = "", opts = {}) {
         // the generated file on first lint:fix.
         const fields = keys
             .map((k) => {
+            const fieldPath = [...path, k];
             const valuesForKey = objects.filter((o) => k in o).map((o) => o[k]);
-            const expr = inferZodSchemaFromSamples(valuesForKey, depth + 1, inner, opts);
+            const expr = inferZodSchemaFromSamples(valuesForKey, depth + 1, inner, opts, fieldPath);
             // Seen on some samples but not others (the endpoint omits it sometimes)
             // OR the query marks it @include/@skip-conditional (the server can
             // legally omit it regardless of what this sample happened to show):
             // either signal alone is enough to require callers to guard the field.
             const isOptional = valuesForKey.length < objects.length || (opts.conditionalFieldNames?.has(k) ?? false);
             const optional = isOptional ? `${expr}.optional()` : expr;
-            return `${inner}${isValidJsIdentifier(k) ? k : JSON.stringify(k)}: ${optional}`;
+            const findings = opts.aggregateUnitBasisFindingsByPath?.get(fieldPath.join("."));
+            const described = findings?.length
+                ? `${optional}.describe(${JSON.stringify(`Derived: ${findings
+                    .map((finding) => `equals the sum of "${finding.unitFieldName}" across every entry of "${finding.breakdownPath.join(".")}"`)
+                    .join("; also ")}.`)})`
+                : optional;
+            return `${inner}${isValidJsIdentifier(k) ? k : JSON.stringify(k)}: ${described}`;
         })
             .join(",\n");
-        return wrap(`z.object({\n${fields},\n${indent}})`);
+        const objectExpr = `z.object({\n${fields},\n${indent}})${opts.looseServerResponse ? ".loose()" : ""}`;
+        return wrap(objectExpr);
     }
     return wrap("z.unknown()");
 }
@@ -579,6 +593,198 @@ function inferZodSchemaFromSamples(samples, depth = 0, indent = "", opts = {}) {
 function inferZodSchema(value, depth = 0, indent = "", opts = {}) {
     return inferZodSchemaFromSamples([value], depth, indent, opts);
 }
+/** Bound on how far {@link detectAggregateUnitBasisFindings} descends into a
+ * response tree, matching {@link DEFAULT_MAX_INFER_DEPTH} so detection never
+ * outruns the schema inference it feeds. */
+const MAX_AGGREGATE_UNIT_BASIS_DEPTH = DEFAULT_MAX_INFER_DEPTH;
+/** Relative tolerance for aggregate-vs-sum comparison, wide enough to absorb
+ * float rounding in tax/currency math but tight enough that two merely
+ * similar-magnitude fields won't pass by coincidence. */
+const AGGREGATE_UNIT_BASIS_RELATIVE_EPSILON = 1e-6;
+const AGGREGATE_UNIT_BASIS_ABSOLUTE_EPSILON = 1e-6;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A "map of objects" is a dynamically-keyed collection (guest index, room id,
+ * line-item id, ...) where every value is itself a record — the per-unit
+ * breakdown shape, as opposed to a plain nested object or a scalar map. */
+function isMapOfObjects(value) {
+    if (!isPlainObject(value))
+        return false;
+    const values = Object.values(value);
+    if (values.length === 0)
+        return false;
+    return values.every(isPlainObject);
+}
+/**
+ * Collects, for one merged object node, every numeric field that could be an
+ * aggregate: fields directly on the node, and fields one level deeper inside
+ * a plain (non-map) nested object — the shape the report evidences
+ * (`price.summary.total`, where `summary` is a single object, not a
+ * dynamically-keyed map).
+ */
+function collectAggregateCandidates(instances, path, keys) {
+    const candidates = [];
+    for (const key of keys) {
+        if (instances.some((instance) => typeof instance[key] === "number")) {
+            candidates.push({
+                fieldName: key,
+                path: [...path, key],
+                getValue: (instance) => typeof instance[key] === "number" ? instance[key] : undefined,
+            });
+        }
+        const nestedObjects = instances.map((instance) => instance[key]).filter(isPlainObject);
+        if (nestedObjects.length === 0 || nestedObjects.some(isMapOfObjects))
+            continue;
+        const innerKeys = new Set(nestedObjects.flatMap((o) => Object.keys(o)));
+        for (const innerKey of innerKeys) {
+            if (!nestedObjects.some((o) => typeof o[innerKey] === "number"))
+                continue;
+            candidates.push({
+                fieldName: innerKey,
+                path: [...path, key, innerKey],
+                getValue: (instance) => {
+                    const nested = instance[key];
+                    return isPlainObject(nested) && typeof nested[innerKey] === "number"
+                        ? nested[innerKey]
+                        : undefined;
+                },
+            });
+        }
+    }
+    return candidates;
+}
+function collectBreakdownCandidates(instances, keys) {
+    const candidates = [];
+    for (const key of keys) {
+        if (!instances.some((instance) => isMapOfObjects(instance[key])))
+            continue;
+        candidates.push({
+            key,
+            getEntries: (instance) => {
+                const value = instance[key];
+                return isMapOfObjects(value) ? Object.values(value) : undefined;
+            },
+        });
+    }
+    return candidates;
+}
+/**
+ * Checks one aggregate/breakdown candidate pair against every instance at
+ * this node and records a finding only when the sum relation holds in ALL
+ * evidence. A single sample that violates the relation, or a breakdown entry
+ * missing the shared field, disqualifies the pair entirely -- proving the
+ * relation from a subset of samples is exactly the false-positive pattern
+ * this detector exists to avoid (a field that merely happens to share
+ * magnitude with a sum on some responses).
+ */
+function evaluateAggregateUnitBasisPair(instances, breakdownPath, aggregate, breakdown, findings) {
+    let confirmedSamples = 0;
+    let maxEntries = 0;
+    let sawEvidence = false;
+    for (const instance of instances) {
+        const aggregateValue = aggregate.getValue(instance);
+        const entries = breakdown.getEntries(instance);
+        if (aggregateValue === undefined || entries === undefined || entries.length === 0)
+            continue;
+        sawEvidence = true;
+        maxEntries = Math.max(maxEntries, entries.length);
+        const unitValues = entries.map((entry) => entry[aggregate.fieldName]);
+        if (!unitValues.every((v) => typeof v === "number"))
+            return;
+        const sum = unitValues.reduce((total, v) => total + v, 0);
+        const tolerance = Math.max(Math.abs(aggregateValue) * AGGREGATE_UNIT_BASIS_RELATIVE_EPSILON, AGGREGATE_UNIT_BASIS_ABSOLUTE_EPSILON);
+        if (Math.abs(sum - aggregateValue) > tolerance)
+            return;
+        confirmedSamples++;
+    }
+    if (!sawEvidence || confirmedSamples === 0)
+        return;
+    // A single-entry breakdown makes aggregate == unit trivially true and
+    // proves nothing about summation -- at least one sample must carry a real
+    // multi-entry breakdown for the relation to be evidence of aggregation.
+    if (maxEntries < 2)
+        return;
+    findings.push({
+        aggregatePath: aggregate.path,
+        breakdownPath,
+        unitFieldName: aggregate.fieldName,
+        sampleCount: confirmedSamples,
+        maxBreakdownEntries: maxEntries,
+    });
+}
+function detectAggregateUnitBasisAtNode(instances, path, findings) {
+    const keys = new Set(instances.flatMap((instance) => Object.keys(instance)));
+    const aggregateCandidates = collectAggregateCandidates(instances, path, keys);
+    const breakdownCandidates = collectBreakdownCandidates(instances, keys);
+    for (const aggregate of aggregateCandidates) {
+        // The immediate child key the aggregate was found under -- either the
+        // aggregate's own key (direct case) or the plain-object container it was
+        // found nested inside (one-level-deeper case).
+        const aggregateContainerKey = aggregate.path[path.length];
+        for (const breakdown of breakdownCandidates) {
+            if (aggregateContainerKey === breakdown.key)
+                continue;
+            evaluateAggregateUnitBasisPair(instances, [...path, breakdown.key], aggregate, breakdown, findings);
+        }
+    }
+}
+function walkAggregateUnitBasis(values, path, depth, findings) {
+    if (depth > MAX_AGGREGATE_UNIT_BASIS_DEPTH)
+        return;
+    const instances = values.filter(isPlainObject);
+    if (instances.length > 0) {
+        detectAggregateUnitBasisAtNode(instances, path, findings);
+        const keys = new Set(instances.flatMap((instance) => Object.keys(instance)));
+        for (const key of keys) {
+            const childValues = instances
+                .map((instance) => instance[key])
+                .filter((v) => v !== undefined && v !== null);
+            if (childValues.length === 0)
+                continue;
+            walkAggregateUnitBasis(childValues, [...path, key], depth + 1, findings);
+        }
+    }
+    const arrayItems = values.filter((v) => Array.isArray(v)).flat();
+    if (arrayItems.length > 0) {
+        walkAggregateUnitBasis(arrayItems, path, depth + 1, findings);
+    }
+}
+/**
+ * Finds every object path where a numeric field's value observably equals
+ * the sum of a same-named numeric field carried by every entry of a sibling
+ * map-of-objects field -- the party-total/per-guest-breakdown shape
+ * generalized to any aggregate/per-unit pair, regardless of field or site
+ * naming, so recon-generate can annotate the price basis instead of leaving
+ * every plugin author and consumer to re-derive it independently and
+ * diverge. See docs/architecture.md, "Why the generator annotates
+ * aggregate/per-unit basis instead of deriving it".
+ *
+ * Pure and read-only: walks the merged sample set the same way
+ * {@link inferZodSchemaFromSamples} does, but only ever compares numbers
+ * already present in the samples -- it emits no schema and mutates nothing.
+ */
+function detectAggregateUnitBasisFindings(samples) {
+    const findings = [];
+    walkAggregateUnitBasis(samples.filter((s) => s !== undefined && s !== null), [], 0, findings);
+    return findings;
+}
+/** Groups {@link detectAggregateUnitBasisFindings} output by aggregate path so
+ * {@link inferZodSchemaFromSamples} can look findings up per-field in O(1). */
+function groupAggregateUnitBasisFindingsByPath(samples) {
+    const byPath = new Map();
+    for (const finding of detectAggregateUnitBasisFindings(samples)) {
+        const key = finding.aggregatePath.join(".");
+        const existing = byPath.get(key);
+        if (existing) {
+            existing.push(finding);
+        }
+        else {
+            byPath.set(key, [finding]);
+        }
+    }
+    return byPath;
+}
 function deriveMinTime(rateLimits) {
     const first = rateLimits.find((f) => f.safeRps !== null);
     return first?.safeRps ? Math.floor(1000 / first.safeRps) : 200;
@@ -681,11 +887,50 @@ function selectReturnAction(steps) {
  * submission flow's `executeHttp` and its inferred type/schema have to agree
  * on which call they describe, or the emitted type disagrees with the value
  * actually returned. Falls back to the replay body for single-endpoint sites.
+ *
+ * A resolved drill-down fold plan (see {@link resolveFoldPlan}) bypasses
+ * `selectReturnAction` entirely, exactly as `emitMultiStepExecuteHttp` does
+ * when it emits the per-item loop-and-merge — so the shape this infers has to
+ * be the FOLDED primary body, not the plain one, or the schema would omit
+ * every field the fold adds. Both resolve through `resolveFoldPlan` with the
+ * same `foldReturnSpec` so they can never disagree on whether a fold applies.
+ * When multiple plans resolve, each plan's own folded body is merged via
+ * `mergeFoldedPrimaryBodies` into one combined object — the same merge
+ * `emitMultiStepExecuteHttp` performs for `return { data }` — so the inferred
+ * shape and the runtime return value always describe the same call, and two
+ * plans that share a top-level array key (e.g. the same paginated primary
+ * endpoint drilled into twice) both contribute their items instead of one
+ * 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.
  */
-function selectEffectiveResponseBody(isSubmissionFlow, actionSteps, replayResponseBody) {
+function selectEffectiveResponseBody(isSubmissionFlow, actionSteps, replayResponseBody, foldReturnSpec = null) {
     if (!isSubmissionFlow)
         return replayResponseBody;
-    return selectReturnAction(actionSteps)?.capture.responseBody ?? replayResponseBody;
+    const foldPlans = resolveFoldPlan(actionSteps, foldReturnSpec);
+    const lastFoldPlan = foldPlans[foldPlans.length - 1] ?? null;
+    if (foldPlans.length <= 1) {
+        if (lastFoldPlan)
+            return foldResponseBodyForShapeInference(actionSteps, lastFoldPlan);
+        return selectReturnAction(actionSteps)?.capture.responseBody ?? replayResponseBody;
+    }
+    // Plans sharing a primaryStepIndex (independent arrays on one primary
+    // response) MUST fold onto the SAME accumulating body, not independent
+    // copies of the original — folding each in isolation and then merging via
+    // mergeFoldedPrimaryBodies would array-concat one plan's folded items with
+    // the other's still-unfolded ones, duplicating every item.
+    const plansByPrimaryStep = new Map();
+    for (const plan of foldPlans) {
+        plansByPrimaryStep.set(plan.primaryStepIndex, [
+            ...(plansByPrimaryStep.get(plan.primaryStepIndex) ?? []),
+            plan,
+        ]);
+    }
+    const foldedBodies = [...plansByPrimaryStep.values()].map((plans) => plans.reduce((body, plan) => foldResponseBodyForShapeInference(actionSteps, plan, body), actionSteps[plans[0].primaryStepIndex].capture.responseBody));
+    if (foldedBodies.every(isPlainObject)) {
+        return (0, merge_folded_primary_bodies_1.mergeFoldedPrimaryBodies)(...foldedBodies);
+    }
+    return foldResponseBodyForShapeInference(actionSteps, lastFoldPlan);
 }
 /**
  * A capture's own URL is not guaranteed parseable (see the try/catch in
@@ -854,7 +1099,7 @@ function stripLeadingGraphQLComments(query) {
 }
 /**
  * Parses `$name:` declarations out of a GraphQL operation signature, e.g.
- * `query cruiseSearch_Cruises($filters: String, $qualifiers: String)` yields
+ * `query catalogSearch_Catalog($filters: String, $qualifiers: String)` yields
  * `["filters", "qualifiers"]`.
  */
 function declaredOperationVariableNames(query) {
@@ -891,6 +1136,35 @@ function operationGroupKey(capture) {
     const name = capture.operationName ?? parsedOperationName(capture.query ?? "") ?? "anonymous";
     return `${endpointPath}::${name}`;
 }
+/**
+ * Every 2xx capture in the run sharing `winningCapture`'s operation identity
+ * (its `operationGroupKey` for a GraphQL winner, `endpointKey` for a
+ * plain-REST one), deduplicated by response body. A single recon run can
+ * capture the same read operation multiple times (pagination, re-filtering),
+ * and each occurrence is evidence for `inferZodSchemaFromSamples` about
+ * which fields the operation actually returns every time versus only
+ * sometimes -- evidence the winning capture alone can't provide.
+ */
+function gatherResponseBodySamples(winningCapture, isGraphQLWinner, captures) {
+    if (!winningCapture)
+        return [null];
+    const identityOf = (c) => isGraphQLWinner ? operationGroupKey(c) : endpointKey(c.url);
+    const winningIdentity = identityOf(winningCapture);
+    const seen = new Set();
+    const samples = [];
+    for (const c of captures) {
+        if (c.status < 200 || c.status >= 300)
+            continue;
+        if (identityOf(c) !== winningIdentity)
+            continue;
+        const serialized = JSON.stringify(c.responseBody);
+        if (seen.has(serialized))
+            continue;
+        seen.add(serialized);
+        samples.push(c.responseBody);
+    }
+    return samples.length > 0 ? samples : [winningCapture.responseBody];
+}
 /**
  * A declared variable is "populated" only by a non-null, non-empty-string
  * value — an operation can declare a filter input that every capture leaves
@@ -2191,9 +2465,25 @@ function locateFormEnvelopePath(parsedBody) {
  * whole blob is caller-supplied; the generator can't reach inside a value it
  * has delegated wholesale.
  *
+ * A candidate whose leaves include a value already threaded from elsewhere in
+ * the fold — either a PRIOR step's response (e.g. a per-item join token
+ * wrapped in a bulk-lookup array like `{"tokens":["<prior-response-value>"]}`)
+ * OR the fold's own PRIMARY ITEM field feeding the immediate drill step's
+ * request (e.g. `{"orderIds":["<primary-item-value>"]}`) — is never swallowed
+ * here, no matter how array/object-shaped it looks: both are threaded
+ * dependent-drill-down coordinates, not caller-supplied history data. The
+ * prior-step-response case must stay reachable for `interpolateStateValues`
+ * (Pass 1, which runs AFTER this pass); the primary-item case must stay
+ * reachable as literal text for the fold-loop's own `parameterize` pass
+ * (which runs even later, once rendering enters the per-item loop) to find
+ * and swap for `${item.<field>}`. Freezing either into an opaque
+ * `${JSON.stringify(payload.tokens)}` blob here would silently drop the
+ * value the request depends on, breaking the fold at exactly the case an
+ * ARRAY/OBJECT-wrapped join field represents.
+ *
  * Site-agnostic: operates only on the recon body's own shape.
  */
-function applyStructuredValuePayloadSubstitutions(template, parsedBody, outStructuredKeys) {
+function applyStructuredValuePayloadSubstitutions(template, parsedBody, outStructuredKeys, priorStepStateValues = new Set()) {
     if (parsedBody === null || typeof parsedBody !== "object" || Array.isArray(parsedBody)) {
         return template;
     }
@@ -2217,6 +2507,11 @@ function applyStructuredValuePayloadSubstitutions(template, parsedBody, outStruc
             Object.keys(value).length > 0;
         if (!isNonEmptyArray && !isNestedObject)
             continue;
+        if (priorStepStateValues.size > 0) {
+            const carriesThreadedValue = [...walkAllPrimitiveLeaves(value)].some(({ value: leaf }) => leaf !== null && priorStepStateValues.has(String(leaf)));
+            if (carriesThreadedValue)
+                continue;
+        }
         const keyMarker = `"${key}":`;
         const markerIdx = result.indexOf(keyMarker);
         if (markerIdx === -1)
@@ -2454,6 +2749,44 @@ function pathToAssertionType(path) {
     const key = isValidJsIdentifier(segment) ? segment : JSON.stringify(segment);
     return `{ ${key}: ${pathToAssertionType(path.slice(1))} }`;
 }
+/**
+ * Same nesting as {@link pathToAssertionType} but the leaf types as
+ * `Record<string, unknown>[]` instead of `string` — used to cast a step's
+ * response down to the object-array field a {@link FoldPlan} located
+ * (the primary results array, or the drill-down's per-item match array). An
+ * {@link ARRAY_WILDCARD_SEGMENT} segment types as an array of whatever the
+ * rest of the path resolves to, matching the `.flatMap` accessor
+ * {@link pathToFoldAccessorExpr} emits for the same segment.
+ */
+function foldArrayAssertionType(path) {
+    if (path.length === 0)
+        return "Record<string, unknown>[]";
+    const segment = path[0];
+    if (segment === ARRAY_WILDCARD_SEGMENT) {
+        return `(${foldArrayAssertionType(path.slice(1))})[]`;
+    }
+    const key = isValidJsIdentifier(segment) ? segment : JSON.stringify(segment);
+    return `{ ${key}: ${foldArrayAssertionType(path.slice(1))} }`;
+}
+/**
+ * Builds a JS access expression reading `path` off of `expr`, generalizing
+ * across every {@link ARRAY_WILDCARD_SEGMENT} in `path` via `.flatMap` so the
+ * emitted accessor visits every element of that outer array instead of
+ * freezing the single index that happened to contain the matched item during
+ * detection (see {@link ARRAY_WILDCARD_SEGMENT}'s docstring). A path with no
+ * wildcard segment degrades to the plain {@link pathToAccessor} chain.
+ */
+function pathToFoldAccessorExpr(expr, path, depth = 0) {
+    const wildcardIndex = path.indexOf(ARRAY_WILDCARD_SEGMENT);
+    if (wildcardIndex === -1) {
+        return `${expr}${pathToAccessor(path, { assertNonNull: false })}`;
+    }
+    const before = path.slice(0, wildcardIndex);
+    const after = path.slice(wildcardIndex + 1);
+    const groupVar = `g${depth}`;
+    const outerExpr = `${expr}${pathToAccessor(before, { assertNonNull: false })}`;
+    return `${outerExpr}.flatMap((${groupVar}) => ${pathToFoldAccessorExpr(groupVar, after, depth + 1)})`;
+}
 /** Suggests a JS-camelCase variable name for a state value path. Falls back
  * up the path if the tail is numeric or not a valid JS identifier. */
 function pathToVarName(path) {
@@ -3193,7 +3526,7 @@ function emitErrorSignalGuards(varName, urlPath, signals) {
 }
 /** 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()) {
+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) {
     // Walk the first action's request body to map each leaf string value to its
     // `payload.<accessor>` expression. The emit's second interpolation pass uses
     // this to substitute literal occurrences (e.g. "Reginald") with their
@@ -3366,6 +3699,65 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
     const boundValues = new Set(payloadAccessorByValue.keys());
     // Captured literals that survived every pass — surfaced as a review TODO.
     const unboundLiteralKeys = new Set();
+    // A fold target's join value can be threaded through a request HEADER
+    // rather than the URL/body (see collectRequestValuesIncludingHeaders) —
+    // the structural heuristic can't see those, but a flow-declared foldReturn
+    // spec resolves the target anyway, and the drill step's per-item re-issue
+    // below must still carry that header or every iteration replays the SAME
+    // captured header value instead of re-keying it. Resolved once, up front
+    // (fold plans depend only on `actions`/`foldReturnSpec`, not on Pass 1's
+    // render), so Pass 1's header collection below knows which non-auth header
+    // names are actually load-bearing for a resolved fold.
+    const earlyFoldPlans = resolveFoldPlan(actions, foldReturnSpec);
+    const joinCarryingHeaderNamesByStep = new Map();
+    // A fold target's join value is the PRIMARY ITEM's own field, threaded into
+    // the drill step's request text-literally by the fold-loop's own
+    // `parameterize` pass (later, once rendering enters the per-item loop) — it
+    // is never a prior STEP's produced state var, so `deriveStateVarByValue`
+    // (built from `produces[]`) never sees it. Mechanism B
+    // (`applyStructuredValuePayloadSubstitutions`) runs BEFORE that loop-aware
+    // pass and only knows to spare a candidate carrying a prior step's state
+    // value; without this, it freezes an array/object-wrapped join field (e.g.
+    // `{"orderIds":["<item.orderId>"]}`) into an opaque
+    // `${JSON.stringify(payload.orderIds)}` blob, destroying the literal text
+    // `parameterize` needs to find and swap for `${item.orderId}` — every
+    // iteration then replays one caller-supplied value instead of the item's
+    // own. Collected once here (fold plans depend only on `actions`/
+    // `foldReturnSpec`, not on Pass 1's render) so Pass 1 knows which values to
+    // spare per step, mirroring the header-name collection above.
+    const joinFieldValuesByStep = new Map();
+    for (const plan of earlyFoldPlans) {
+        const primaryItems = objectItemsAtPath(actions[plan.primaryStepIndex].capture.responseBody, plan.primaryArrayPath);
+        for (const target of plan.targets) {
+            const firstItem = primaryItems?.[target.primaryMatchedItemIndex];
+            if (!firstItem)
+                continue;
+            for (const stepIndex of [target.drillStepIndex, ...target.chain]) {
+                const headerNames = joinCarryingHeaderNamesByStep.get(stepIndex) ?? new Set();
+                for (const [headerName, headerValue] of Object.entries(actions[stepIndex].capture.requestHeaders)) {
+                    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));
+                    });
+                    if (matchesJoinField)
+                        headerNames.add(headerName);
+                }
+                if (headerNames.size > 0)
+                    joinCarryingHeaderNamesByStep.set(stepIndex, headerNames);
+                const joinValues = joinFieldValuesByStep.get(stepIndex) ?? new Set();
+                for (const field of target.joinFields) {
+                    const value = readValueAtPath(firstItem, field.split("."));
+                    if (typeof value === "string" && value.length > 0)
+                        joinValues.add(value);
+                    else if (typeof value === "number")
+                        joinValues.add(String(value));
+                }
+                if (joinValues.size > 0)
+                    joinFieldValuesByStep.set(stepIndex, joinValues);
+            }
+        }
+    }
     // Pass 1: render every step's emitted strings; collect referenced var names.
     const rendered = [];
     for (let i = 0; i < actions.length; i++) {
@@ -3401,9 +3793,16 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
         // (experienceData/educationData history, opaque eventData) BEFORE value
         // substitution reaches inside them: swallowing the entire array/object first
         // keeps interpolateStateValues from binding a code buried in the history
-        // sample (e.g. a work entry's state code) to an unrelated field.
+        // sample (e.g. a work entry's state code) to an unrelated field. Excludes
+        // any candidate that itself carries a PRIOR step's produced value (see
+        // applyStructuredValuePayloadSubstitutions' docstring) — an array-wrapped
+        // dependent-drill-down join field (e.g. a bulk `{"tokens":[...]}` lookup)
+        // must stay reachable for state threading, not get frozen as caller data.
         const rawBodyWithStructuredSubs = parsedBody !== null
-            ? applyStructuredValuePayloadSubstitutions(rawBodyWithFormSubs, parsedBody, outStructuredKeys)
+            ? applyStructuredValuePayloadSubstitutions(rawBodyWithFormSubs, parsedBody, outStructuredKeys, new Set([
+                ...deriveStateVarByValue(prior).keys(),
+                ...(joinFieldValuesByStep.get(i) ?? []),
+            ]))
             : rawBodyWithFormSubs;
         // Whole-value caller coordinates bind here — after structured subs, BEFORE
         // state threading — so a composite coordinate (a jobLocation or jobSeqNo
@@ -3459,10 +3858,11 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
                 unboundLiteralKeys.add(key);
             }
         }
+        const joinCarryingHeaderNames = joinCarryingHeaderNamesByStep.get(i);
         const perCallHeaders = {};
         for (const [k, v] of Object.entries(cap.requestHeaders)) {
             const lower = k.toLowerCase();
-            if (lower === "api-token" || lower === "authorization") {
+            if (lower === "api-token" || lower === "authorization" || joinCarryingHeaderNames?.has(k)) {
                 perCallHeaders[k] = interpolateStateValues(v, prior, payloadAccessorByValue);
             }
         }
@@ -3496,7 +3896,10 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
         // validates any individual call. Without this override, HttpRequestInit.schema
         // would default to the client's z.unknown() and narrowing the caller-facing
         // contract would enforce that narrowed shape on every call in the chain.
-        const schemaExpr = inferZodSchema(cap.responseBody);
+        const schemaExpr = inferZodSchema(cap.responseBody, 0, "", {
+            looseServerResponse: true,
+            aggregateUnitBasisFindingsByPath: groupAggregateUnitBasisFindingsByPath([cap.responseBody]),
+        });
         rendered.push({ url, method: cap.method, headersExpr, bodyArg, schemaExpr });
     }
     // Identifier scan against the rendered text — captures `${foo}`, `${foo.bar}`,
@@ -3520,11 +3923,17 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
             }
         }
     }
-    // The relevance-selected step's var is also referenced by the closing
-    // `return { data }` — see selectReturnAction.
-    const returnAction = selectReturnAction(actions);
+    // Every resolved drill-down fold plan bypasses selectReturnAction entirely:
+    // each plan's primary step's array is folded in place (see the loop-and-merge
+    // emitted below, one such loop per plan), so a primary step's var — not
+    // whichever call selectReturnAction would otherwise pick — is what
+    // `return { data }` must reference when any plan resolves.
+    const foldPlans = earlyFoldPlans;
+    const returnAction = foldPlans.length > 0 ? null : selectReturnAction(actions);
     if (returnAction)
         referencedNames.add(returnAction.varName);
+    for (const plan of foldPlans)
+        referencedNames.add(actions[plan.primaryStepIndex].varName);
     // Pass 2: emit. Skip response bindings that aren't referenced; skip
     // produces[] entries whose name isn't referenced. A step's response var
     // is still needed when at least one of its produces[] entries IS
@@ -3544,10 +3953,195 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
         lines.push(`    // TODO: unbound captured literal(s) — verify these carry caller data, not the recon capture's: ${[...unboundLiteralKeys].join(", ")}`);
     }
     const declaredNames = new Set();
+    // Every non-terminal chain step past the drill step is folded into the SAME
+    // per-item loop the drill step itself emits (see below) — it must not also
+    // get the normal single-call treatment this pass gives every other step, or
+    // its request would be issued a second time, unconditionally, outside the
+    // loop.
+    // Every step in a fold target's chain (the drill step and every further
+    // step transitively dependent on it — see FoldTarget.chain) is emitted
+    // together as a single per-item loop below, not by this pass's normal
+    // per-step produce/response declarations: their responses and produces are
+    // block-scoped to that loop and never escape to the rest of the function,
+    // so none of them may run through the outer `declaredNames`/produceLines
+    // bookkeeping below (that bookkeeping assumes function-scope declarations).
+    const foldChainIndices = new Set(foldPlans.flatMap((plan) => plan.targets.flatMap((target) => target.chain)));
     for (let i = 0; i < actions.length; i++) {
         const step = actions[i];
         const cap = step.capture;
         const r = rendered[i];
+        // Every independent fold target within a given plan — regardless of which
+        // drill step starts it — is folded into ONE shared per-item loop over
+        // that plan's primary array, emitted once, at the plan's FIRST target's
+        // drillStepIndex: each target's chain calls and Object.assign both run
+        // inside that same `for (const item of foldItems)` body, so a primary
+        // item ends up with fields folded in from every independent dependent
+        // drill-down of that plan, not just the first. When more than one
+        // independent plan resolves (distinct primary arrays), each plan gets its
+        // OWN loop block, anchored at that plan's own first target's
+        // drillStepIndex, so each primary array is folded with only its own
+        // drill-downs' matched fields.
+        // Each chain step re-issues the SAME url/headers/bodyArg/schemaExpr this
+        // pass already rendered for it, only with the captured join value(s)
+        // swapped for the loop item's own field accessor (the drill step) or its
+        // own produced response values (later chain steps, which already render
+        // with `${producedName}` templates — see deriveStateVarByValue).
+        const matchingPlanIndex = foldPlans.findIndex((plan) => plan.targets.length > 0 && plan.targets[0].drillStepIndex === i);
+        if (matchingPlanIndex !== -1) {
+            const foldPlan = foldPlans[matchingPlanIndex];
+            const primaryStep = actions[foldPlan.primaryStepIndex];
+            // Read at the plan's OWN path rather than re-running the DFS: a
+            // flow-declared `resultsPath` (see FoldReturnSpec) can name a different
+            // array than findObjectArrayField's first match.
+            const primaryItems = objectItemsAtPath(primaryStep.capture.responseBody, foldPlan.primaryArrayPath);
+            const primaryArrType = foldArrayAssertionType(foldPlan.primaryArrayPath);
+            // Plan-level suffix mirrors the target-level suffix below: multiple
+            // loop blocks now sharing the same function scope can't declare
+            // unsuffixed `foldItems`/`item` locals without colliding. The
+            // overwhelmingly common single-plan case keeps the original
+            // unsuffixed names.
+            const planSuffix = foldPlans.length > 1 ? String(matchingPlanIndex) : "";
+            const foldItemsVar = `foldItems${planSuffix}`;
+            const foldItemsExpr = pathToFoldAccessorExpr(`(${primaryStep.varName} 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()) {
+                // `firstItem` decides which captured literal `parameterize` rewrites
+                // — it must be the item at `primaryMatchedItemIndex`, the one THIS
+                // target's drill request was actually built from, not always index
+                // 0, and can differ per target even though every target now shares
+                // the same runtime loop item.
+                const firstItem = primaryItems?.[target.primaryMatchedItemIndex];
+                if (!firstItem) {
+                    throw new Error(`emitMultiStepExecuteHttp: fold plan primary step ${primaryStep.varName} no longer resolves an object array at ${foldPlan.primaryArrayPath.join(".")} — the fold plan and this emitter have drifted out of sync`);
+                }
+                // Each target's chain variables and merge result get their own
+                // suffixed local names so multiple independent targets sharing the
+                // same loop body can each declare their own locals without
+                // colliding on `foldMatches`/`foldMatch`. The overwhelmingly common
+                // single-target case keeps the original unsuffixed names.
+                const suffix = foldPlan.targets.length > 1 ? `${planSuffix}${targetIndex}` : planSuffix;
+                const joinAccessor = (field) => `${itemVar}${pathToAccessor(field.split("."), { assertNonNull: false })}`;
+                // A join field can reach the render either as the raw captured literal
+                // (URL query params) or as an already-generic `${payload.<field>}`
+                // reference (top-level JSON body keys — see
+                // applyPayloadKeyValueSubstitutions, which payload-ifies every scalar
+                // body key regardless of length, running BEFORE this fold branch ever
+                // sees the value). Both must resolve to the loop item's own field, not
+                // a caller-supplied payload value shared across every iteration.
+                // Word-boundary anchored: a plain `.split(value).join(...)` would also
+                // rewrite unrelated substrings that happen to contain the join value
+                // (e.g. a "p1" product id colliding with a "/v1/" path segment or a
+                // "p10" sibling id), corrupting parts of the request the join field
+                // never touched.
+                const replaceWholeValue = (haystack, value, replacement) => haystack.replace(new RegExp(`\\b${value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "g"), replacement);
+                const parameterize = (text) => target.joinFields.reduce((acc, field) => {
+                    const replacement = `\${${joinAccessor(field)}}`;
+                    // applyPayloadKeyValueSubstitutions only ever names a payload
+                    // accessor after the DRILL REQUEST's own top-level JSON key
+                    // (`${payload.sku}`), never after `field`'s dot path into the
+                    // PRIMARY ITEM — those are unrelated structures that only
+                    // happen to share a leaf name for a top-level join field. A
+                    // nested join field (e.g. `identifiers.sku`) must therefore
+                    // also match on its bare last segment, or the accessor swap
+                    // silently no-ops and leaves an undefined `payload.sku`
+                    // reference behind once the literal value itself has already
+                    // been replaced by the payload-key-value pass.
+                    const lastSegment = field.split(".").pop();
+                    const withAccessorSwapped = acc
+                        .split(`\${payload.${field}}`)
+                        .join(replacement)
+                        .split(`\${payload.${lastSegment}}`)
+                        .join(replacement);
+                    const value = readValueAtPath(firstItem, field.split("."));
+                    const stringValue = typeof value === "string" && value.length > 0
+                        ? value
+                        : typeof value === "number"
+                            ? String(value)
+                            : null;
+                    return stringValue !== null
+                        ? replaceWholeValue(withAccessorSwapped, stringValue, replacement)
+                        : withAccessorSwapped;
+                }, text);
+                // Every chain step's response and produces are block-scoped to this
+                // `for` — they never escape to the rest of the function. That is
+                // exactly the constraint the previous (now-removed) throw enforced by
+                // refusing to run at all: instead of failing, each chain step's
+                // produces are re-declared here as loop-scoped locals, so a later
+                // chain step's own request (already rendered with `${producedName}`
+                // templates by the pass above, same as it would be for any two
+                // sequential non-fold steps) resolves them from this narrower scope.
+                const chainDeclared = new Set();
+                for (const chainIndex of target.chain) {
+                    const chainStep = actions[chainIndex];
+                    const chainRendered = rendered[chainIndex];
+                    lines.push(`      const ${chainStep.varName} = (await httpClient(\`${parameterize(chainRendered.url)}\`, {`, `        method: ${JSON.stringify(chainRendered.method)},`);
+                    const joined = [
+                        parameterize(chainRendered.headersExpr),
+                        parameterize(chainRendered.bodyArg),
+                    ]
+                        .filter((s) => s !== "")
+                        .join(" ");
+                    if (joined !== "")
+                        lines.push(`        ${joined}`);
+                    lines.push(`        schema: ${chainRendered.schemaExpr},`, `      })) as Record<string, unknown>;`);
+                    for (const p of chainStep.produces) {
+                        if (p.kind === "header")
+                            continue;
+                        if (chainDeclared.has(p.name))
+                            continue;
+                        if (!referencedNames.has(p.name))
+                            continue;
+                        chainDeclared.add(p.name);
+                        const assertion = pathToAssertionType(p.path);
+                        lines.push(`      const ${p.name} = (${chainStep.varName} as ${assertion})${pathToAccessor(p.path, { assertNonNull: false })};`);
+                    }
+                }
+                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(`    }`, "");
+            continue;
+        }
+        // Every other chain step (already fully emitted, inline, by the fold
+        // block above) must not also get the normal single-call treatment this
+        // pass gives every step, or its request would be issued a second time,
+        // unconditionally, outside the loop.
+        if (foldChainIndices.has(i))
+            continue;
         // Build the produce-extraction lines FIRST so the binding decision reflects
         // what is actually emitted, not a pre-scan predicate. A produce whose name
         // was already declared by an earlier step is de-dup-skipped here — and must
@@ -3659,8 +4253,38 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
             lines.push(line);
         lines.push("");
     }
-    const returnVar = returnAction ? returnAction.varName : "undefined";
-    lines.push(`    return { data: ${returnVar} };`);
+    // When multiple plans resolve, every plan's own primary var is deep-merged
+    // together into one combined result via mergeFoldedPrimaryBodies —
+    // mirroring selectEffectiveResponseBody's merge — so the runtime return
+    // value and the inferred shape always describe the same call. A plain
+    // object-spread would silently drop one plan's array whenever two plans'
+    // primary bodies share a top-level array key (e.g. the same paginated
+    // primary endpoint drilled into twice). A primary whose OWN top-level body
+    // isn't a plain object can't be merged meaningfully, so in that case this
+    // falls back to the LAST plan's primary var alone, same as before this
+    // merge was introduced.
+    //
+    // Deduped by var name (not one entry per plan): two plans anchored on the
+    // SAME primary step (e.g. a structural plan and a spec-only plan each
+    // resolving a different array on one shared response — see
+    // mergeSpecPlanOntoSamePrimary) both mutate that ONE response object's own
+    // arrays in place per their own loop above. Passing that same var into
+    // mergeFoldedPrimaryBodies once per plan would concatenate every one of its
+    // arrays with itself, duplicating every already-folded item.
+    const lastFoldPlan = foldPlans[foldPlans.length - 1] ?? null;
+    const uniquePrimaryVarNames = [
+        ...new Set(foldPlans.map((plan) => actions[plan.primaryStepIndex].varName)),
+    ];
+    const everyPrimaryIsPlainObject = foldPlans.every((plan) => isPlainObject(actions[plan.primaryStepIndex].capture.responseBody));
+    if (uniquePrimaryVarNames.length > 1 && everyPrimaryIsPlainObject) {
+        lines.push(`    return { data: mergeFoldedPrimaryBodies(${uniquePrimaryVarNames.join(", ")}) };`);
+    }
+    else {
+        const returnVar = lastFoldPlan
+            ? actions[lastFoldPlan.primaryStepIndex].varName
+            : (returnAction?.varName ?? "undefined");
+        lines.push(`    return { data: ${returnVar} };`);
+    }
     return lines.join("\n");
 }
 function summariseResponseShape(value) {
@@ -3812,22 +4436,843 @@ function findNumericFieldByName(value, pattern, path = []) {
     }
     return null;
 }
-/** Depth-first search for the first array whose elements are (non-array)
+/** Filter predicate isolating an array's (non-array) object elements — the
+ * shape both {@link findAllObjectArrayFields} and {@link objectItemsAtPath}
+ * treat as a "results array" candidate. */
+function isObjectArrayItem(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** Sentinel path segment marking "every element of the array reached so
+ * far", emitted by {@link findAllObjectArrayFields} in place of a literal
+ * numeric index whenever it descends through an array to keep searching —
+ * the array itself is a container of candidate groups, not a single fixed
+ * one. Freezing the literal index of whichever group happened to contain
+ * the matched item (the bug this sentinel fixes) meant a multi-element
+ * outer array — e.g. a paginated/grouped response wrapping several
+ * sub-collections — only ever resolved/iterated the ONE group seen during
+ * detection. {@link objectItemsAtPath} and the fold-emission accessor
+ * builders below both flatten across every element at this position instead
+ * of indexing into one. */
+const ARRAY_WILDCARD_SEGMENT = "*";
+/** Depth-first search for every array whose elements are (non-array)
  * objects — the same "per-item response array" shape schema inference
- * already resolves to when it emits `z.array(z.object({...}))`. */
-function findObjectArrayField(value, path = []) {
+ * already resolves to when it emits `z.array(z.object({...}))`. Ordered by
+ * DFS/key order, so `[0]` is {@link findObjectArrayField}'s first match.
+ * 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 = []) {
     if (value === null || typeof value !== "object")
-        return null;
+        return [];
     if (Array.isArray(value)) {
-        const objectItems = value.filter((v) => v !== null && typeof v === "object" && !Array.isArray(v));
-        return objectItems.length > 0 ? { path, items: objectItems } : null;
+        const objectItems = value.filter(isObjectArrayItem);
+        const nestedCandidates = objectItems.flatMap((item) => findAllObjectArrayFields(item, [...path, ARRAY_WILDCARD_SEGMENT]));
+        return objectItems.length > 0
+            ? [{ path, items: objectItems }, ...nestedCandidates]
+            : nestedCandidates;
     }
-    for (const [key, v] of Object.entries(value)) {
-        const found = findObjectArrayField(v, [...path, key]);
-        if (found)
-            return found;
+    return Object.entries(value).flatMap(([key, v]) => findAllObjectArrayFields(v, [...path, key]));
+}
+/** The first object-array field by DFS/key order — see
+ * {@link findAllObjectArrayFields}. Every call site that must disambiguate
+ * between several candidate arrays (e.g. a decoy array positioned earlier in
+ * key order than the real one) uses {@link findAllObjectArrayFields}
+ * directly instead of this first-match shortcut. */
+function findObjectArrayField(value, path = []) {
+    return findAllObjectArrayFields(value, path)[0] ?? null;
+}
+/** {@link findAllObjectArrayFields}, widened to ALSO offer the flat
+ * (non-array) whole object itself as a candidate — a detail-by-id
+ * drill/chain response (e.g. `GET /widgets/{id}` returning the widget
+ * object directly, not `{ widget: {...} }`) is exactly as foldable as a
+ * one-element array would be. The flat entry's path is `[]` (the whole
+ * body); {@link objectItemsAtPath} recognizes a flat object at a resolved
+ * path the same way, so a {@link FoldTarget} built from this fallback
+ * resolves correctly end to end. The flat candidate is appended AFTER every
+ * real object-array candidate (never in place of one) so a caller that
+ * needs to compare candidates by richness — see {@link
+ * chainTerminalItemRichness} — can prefer the flat shape when it carries
+ * 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. */
+function findAllObjectArrayFieldsOrWholeObject(value, path = []) {
+    const found = findAllObjectArrayFields(value, path);
+    return isObjectArrayItem(value) ? [...found, { path, items: [value] }] : found;
+}
+/** The first candidate from {@link findAllObjectArrayFieldsOrWholeObject} —
+ * the flat-object-aware counterpart of {@link findObjectArrayField}. */
+function findObjectArrayFieldOrWholeObject(value, path = []) {
+    return findAllObjectArrayFieldsOrWholeObject(value, path)[0] ?? null;
+}
+/** Every string and numeric value present in a capture's outbound request —
+ * its URL path segments and query parameters (always strings) and its JSON
+ * body's string and numeric leaves (numeric leaves stringified) — the set a
+ * drill-down request's threaded join value must appear in. Path segments are
+ * included because REST-style APIs commonly thread a primary item's id as a
+ * path segment (e.g. `/orders/{id}`) rather than a query param or body
+ * field. Numeric leaves are included because a join key is just as often a
+ * numeric id (threaded as a query param string or a JSON body number
+ * literal) as a string one. */
+function collectRequestStringValues(capture) {
+    const values = new Set();
+    try {
+        const url = new URL(capture.url);
+        for (const v of url.searchParams.values())
+            values.add(v);
+        for (const segment of url.pathname.split("/").filter(Boolean))
+            values.add(segment);
     }
-    return null;
+    catch {
+        // Relative or malformed URL — no query params or path segments to contribute.
+    }
+    for (const v of jsonBodyLeafValues(capture.requestPostData) ?? [])
+        values.add(v);
+    const parsedBody = (() => {
+        try {
+            return typeof capture.requestPostData === "string" && capture.requestPostData.length > 0
+                ? JSON.parse(capture.requestPostData)
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (parsedBody !== undefined) {
+        for (const { value } of walkAllPrimitiveLeaves(parsedBody)) {
+            if (typeof value === "number")
+                values.add(String(value));
+        }
+    }
+    return values;
+}
+/**
+ * Yields every string/numeric 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
+ * field yields a single-segment path (e.g. `["sku"]`), matching every
+ * existing joinFields entry's shape unchanged; a field nested inside an
+ * object (e.g. `{ identifiers: { sku } }`) yields `["identifiers", "sku"]`.
+ */
+function* walkItemFieldPaths(item, path = []) {
+    for (const [k, v] of Object.entries(item)) {
+        const childPath = [...path, k];
+        if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+            yield* walkItemFieldPaths(v, childPath);
+            continue;
+        }
+        yield { path: childPath, value: v };
+    }
+}
+/**
+ * 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
+ * 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
+ * inside an object becomes e.g. `"identifiers.sku"`. Field order follows the
+ * item's own key order (nested objects walked depth-first as encountered),
+ * so a composite join (e.g. `accountId` + `region`) comes out in the same
+ * order the primary response declares them, not sorted. Returns `[]` when no
+ * field of the item threads into the request at all.
+ */
+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))))
+        .map(({ path }) => path.join("."));
+}
+/** Every string and numeric leaf value present anywhere in a response body —
+ * 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) {
+    const values = new Set();
+    for (const { value } of walkAllPrimitiveLeaves(responseBody)) {
+        if (typeof value === "string" && value.length > 0)
+            values.add(value);
+        if (typeof value === "number")
+            values.add(String(value));
+    }
+    return values;
+}
+/**
+ * Walks forward from `drillStepIndex`, following the transitive per-item
+ * dependency chain: each subsequent step whose request threads a value out
+ * of ANY step already in the chain is itself added to the chain, since its
+ * own request — and therefore its response — only makes sense once per
+ * matched primary item. Reuses {@link collectRequestValuesIncludingHeaders}
+ * (URL, body, AND headers) so a chained step threading its join value
+ * through a header, exactly like {@link buildFoldPlanFromSpec}'s own
+ * threading, is still picked up. Returns the ordered step indices (starting
+ * at `drillStepIndex`) plus the object-array path AND owning step index found
+ * on the LAST chain step whose response actually has an object-array field,
+ * OR — failing that — the last chain step whose response is a flat object
+ * carrying MORE of its own per-item data than the chain's best terminal
+ * found so far (see {@link chainTerminalItemRichness}). Either way this is
+ * NOT necessarily `chain`'s last entry, since a step can be chained purely
+ * because it threads a value onward (e.g. a status-check response with no
+ * array of its own and no richer data than what came before) without itself
+ * holding the foldable data. Falls back to `drillArrayPath`/`drillStepIndex`
+ * (the immediate drill step's own array or flat object) when nothing
+ * threads further, so `chain` degrades to `[drillStepIndex]` for the common
+ * single-step case.
+ */
+/** Disambiguates among every object-array (or flat-object) candidate on
+ * `responseBody`, preferring the one whose items thread `capture`'s own
+ * request/header values (see {@link findThreadedJoinFields}), falling back
+ * to the richest candidate by {@link chainTerminalItemRichness} when none
+ * thread. Both the immediate drill step ({@link scanPrimaryCandidateGroups})
+ * and every later chained step ({@link computeFoldChain}) must disambiguate
+ * identically — a decoy candidate positioned earlier in key order than the
+ * real per-item array is exactly as invalid a pick on a chain hop as it is
+ * on the immediate drill call — so this is the single implementation both
+ * reuse instead of each doing its own first-DFS-match shortcut. */
+function selectDisambiguatedCandidate(responseBody, capture) {
+    const candidates = findAllObjectArrayFieldsOrWholeObject(responseBody);
+    if (candidates.length === 0)
+        return null;
+    const requestValues = collectRequestValuesIncludingHeaders(capture);
+    const threaded = candidates.find((candidate) => candidate.items.some((item) => findThreadedJoinFields(item, capture).length > 0));
+    if (threaded)
+        return threaded;
+    return candidates.reduce((richest, candidate) => {
+        const candidateRichness = chainTerminalItemRichness(responseBody, candidate.path, requestValues);
+        const richestSoFar = chainTerminalItemRichness(responseBody, richest.path, requestValues);
+        return candidateRichness > richestSoFar ? candidate : richest;
+    });
+}
+function computeFoldChain(actions, drillStepIndex, drillArrayPath) {
+    const chain = [drillStepIndex];
+    let chainArrayPath = drillArrayPath;
+    let chainTerminalIndex = drillStepIndex;
+    let chainTerminalRichness = chainTerminalItemRichness(actions[drillStepIndex].capture.responseBody, drillArrayPath, collectRequestValuesIncludingHeaders(actions[drillStepIndex].capture));
+    for (let i = drillStepIndex + 1; i < actions.length; i++) {
+        const candidate = actions[i];
+        const requestValues = collectRequestValuesIncludingHeaders(candidate.capture);
+        const dependsOnChain = chain.some((chainIndex) => {
+            const chainStepCapture = actions[chainIndex].capture;
+            const responseValues = collectResponseLeafValues(chainStepCapture.responseBody);
+            const echoedValues = collectRequestValuesIncludingHeaders(chainStepCapture);
+            return [...responseValues].some((v) => !echoedValues.has(v) && requestValues.has(v));
+        });
+        if (!dependsOnChain)
+            continue;
+        chain.push(i);
+        // Disambiguated identically to the immediate drill step (see
+        // selectDisambiguatedCandidate): a decoy object-array field positioned
+        // earlier in key order than the real per-item array must not win just
+        // for being found first on THIS chain step's own response, any more
+        // than it would on the immediate drill call. The winning candidate
+        // still only displaces the terminal when it's STRICTLY richer than the
+        // chain's best terminal so far, OR ties it with a genuine object-ARRAY
+        // candidate (isGenuineArrayCandidate: candidateArray.path is non-empty).
+        // A flat single-object candidate never wins a tie — otherwise a step
+        // chained purely for threading a value onward (e.g. a `{ held: true }`
+        // confirmation, never richer than the real per-item shape it merely
+        // threads from) would always qualify as an implicit one-item collection
+        // and collapse this into "always advance the terminal to the newest
+        // chain member" regardless of whether that member actually holds
+        // foldable data. But a later hop that DOES resolve to a real per-item
+        // array, tied only because a same-shaped flat confirmation hop sits
+        // earlier in the chain, is the genuine terminal and must still win —
+        // see buildMulticallSingleShotSearchDrillDownRichnessTiedConfirmationHopChainedDependentActionSteps.
+        const candidateArray = selectDisambiguatedCandidate(candidate.capture.responseBody, candidate.capture);
+        if (!candidateArray)
+            continue;
+        const candidateRichness = chainTerminalItemRichness(candidate.capture.responseBody, candidateArray.path, requestValues);
+        const isGenuineArrayCandidate = candidateArray.path.length > 0;
+        const advancesOnTie = candidateRichness === chainTerminalRichness &&
+            candidateRichness > 0 &&
+            isGenuineArrayCandidate;
+        if (candidateRichness > chainTerminalRichness || advancesOnTie) {
+            chainArrayPath = candidateArray.path;
+            chainTerminalIndex = i;
+            chainTerminalRichness = candidateRichness;
+        }
+    }
+    return { chain, chainArrayPath, chainTerminalIndex };
+}
+/** The per-item primitive-field richness of a chain terminal candidate at
+ * `path` — {@link directPrimitiveChildCountExcludingEchoed} of the first item
+ * {@link objectItemsAtPath} resolves there (an object-array item when `path`
+ * names a real array, or the whole flat object when `path` is `[]`), or 0
+ * when `path` resolves to nothing. `requestValues` excludes fields the
+ * candidate's own response merely echoes back from its request (join keys,
+ * threaded ids), so an echo can never be mistaken for genuine per-item data.
+ * The single metric every {@link computeFoldChain} comparison — baseline,
+ * array-branch, and flat-branch alike — uses, so a later step only ever
+ * displaces the terminal by actually contributing more of its own data. */
+function chainTerminalItemRichness(responseBody, path, requestValues) {
+    const items = objectItemsAtPath(responseBody, path);
+    return items && items.length > 0
+        ? directPrimitiveChildCountExcludingEchoed(items[0], requestValues)
+        : 0;
+}
+/** Like {@link directPrimitiveChildCount}, but skips a field whose value was
+ * itself already threaded INTO this response's own request (present in
+ * `requestValues`) — a confirmation step routinely echoes the id/token it
+ * was called with alongside a status flag, and that echo must not count as
+ * genuine per-item data or a side-effect-only response (e.g. `{ token:
+ * "t1", held: true }` echoing a threaded `token`) would out-rank the real
+ * terminal on field count alone. */
+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 (requestValues.has(String(v)))
+                    continue;
+            }
+            n++;
+        }
+    }
+    return n;
+}
+/**
+ * Scans every candidate object-array field of `actions[primaryIndex]`'s
+ * response independently, each yielding its own {@link PrimaryScanGroup} of
+ * targets when at least one later step threads a join field out of it — a
+ * single primary response holding two genuinely unrelated per-item
+ * collections (e.g. a search response with both a `results[]` and a
+ * `facets[]` that are each independently drilled by their own later call)
+ * must fold BOTH, not just whichever array the first qualifying drill-down
+ * happens to thread from. `consumedIndices` is shared across every
+ * candidate's scan (not reset per candidate) so a step already folded into
+ * 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) {
+    const primary = actions[primaryIndex];
+    const primaryCandidates = findAllObjectArrayFields(primary.capture.responseBody);
+    if (primaryCandidates.length === 0)
+        return [];
+    const groups = [];
+    // A step already consumed as a later member of an earlier target's
+    // chain — from THIS primary array or an independent one on the same
+    // primary response — threads its request from that target's own
+    // response, not straight off the primary array, so it must not also be
+    // picked up as a second, independent target of any candidate array.
+    const consumedIndices = new Set();
+    for (const primaryArray of primaryCandidates) {
+        const targets = [];
+        for (let drillIndex = primaryIndex + 1; drillIndex < actions.length; drillIndex++) {
+            const drill = actions[drillIndex];
+            if (drill === primary)
+                continue;
+            if (consumedIndices.has(drillIndex))
+                continue;
+            if (globallyConsumedIndices.has(drillIndex))
+                continue;
+            // Every item in THIS candidate array is searched, not just items[0]
+            // — a flow that only ever drilled into a later item (never the
+            // first) must still resolve.
+            const primaryMatchedItemIndex = primaryArray.items.findIndex((item) => findThreadedJoinFields(item, drill.capture).length > 0);
+            if (primaryMatchedItemIndex === -1)
+                continue;
+            const joinFields = findThreadedJoinFields(primaryArray.items[primaryMatchedItemIndex], drill.capture);
+            // Widened to a flat (non-array) object response when the drill step has
+            // no object-array field of its own — see
+            // findAllObjectArrayFieldsOrWholeObject. A detail-by-id response (e.g.
+            // `GET /widgets/{id}` returning the widget directly) is just as valid a
+            // fold target as a one-element array would be; only skipping it, rather
+            // than treating it as an implicit one-item collection, was the actual
+            // root cause of dependent drill-downs never folding onto primary
+            // results. Disambiguated via selectDisambiguatedCandidate — a per-item
+            // drill array commonly echoes the join value(s) it was looked up by
+            // (e.g. a `sku` search parameter mirrored back on each result), which
+            // distinguishes it from a decoy array (e.g. an `errors[]` collection)
+            // that never does. Not every real drill array echoes the join value,
+            // though (e.g. a `productId`-keyed lookup returning `units[]` with no
+            // `productId` field of its own), so when no candidate threads, the
+            // richest candidate by per-item primitive-field count wins — the same
+            // selection computeFoldChain applies to every later chained step, so a
+            // decoy is never disambiguated differently on the immediate drill call
+            // than it is one hop further down the chain.
+            // An immediate hop with no object-array/flat-object candidate at all
+            // (a bare token/id array, a scalar, an empty body) must not abandon
+            // the whole candidate here — a LATER hop in the chain may still
+            // thread forward to the real per-item data (e.g. an id array whose
+            // values are looked up individually on a following step). Feed
+            // computeFoldChain the empty-path baseline FoldTarget already
+            // documents as its fallback contract, and only bail once the
+            // resolved chain terminal itself has no real items to fold onto.
+            const drillArray = selectDisambiguatedCandidate(drill.capture.responseBody, drill.capture);
+            const drillArrayPath = drillArray?.path ?? [];
+            const { chain, chainArrayPath, chainTerminalIndex } = computeFoldChain(actions, drillIndex, drillArrayPath);
+            const chainTerminalItems = objectItemsAtPath(actions[chainTerminalIndex].capture.responseBody, chainArrayPath);
+            if (!chainTerminalItems || chainTerminalItems.length === 0)
+                continue;
+            // `primaryArray.path` can carry an ARRAY_WILDCARD_SEGMENT (a matched
+            // item nested inside a multi-element outer array — e.g. a
+            // paginated/grouped response wrapping several sub-collections), in
+            // which case `primaryMatchedItemIndex` above is only the LOCAL index
+            // within the one group `primaryArray.items` happens to be. Re-resolve
+            // it against the FLATTENED items every group at that path contributes,
+            // by object identity (findAllObjectArrayFields and objectItemsAtPath
+            // both read the same references, never cloning), so downstream
+            // consumers reading through `objectItemsAtPath` — the emitter's
+            // `firstItem` lookup and the shape-inference fold — land on the exact
+            // same item regardless of which group it came from.
+            const flattenedPrimaryItems = objectItemsAtPath(primary.capture.responseBody, primaryArray.path) ?? [];
+            const globalMatchedItemIndex = flattenedPrimaryItems.indexOf(primaryArray.items[primaryMatchedItemIndex]);
+            targets.push({
+                joinFields,
+                drillStepIndex: drillIndex,
+                drillArrayPath,
+                primaryMatchedItemIndex: globalMatchedItemIndex === -1 ? primaryMatchedItemIndex : globalMatchedItemIndex,
+                chain,
+                chainArrayPath,
+                chainTerminalIndex,
+            });
+            // Everything past drillIndex already folded into this target's own
+            // chain is per-item dependent on THIS drill-down, not independently
+            // threaded off the primary array, so it must be skipped rather than
+            // re-considered as a new target — by this candidate array's own
+            // further scanning or any other candidate array's scan.
+            for (const chainIndex of chain)
+                consumedIndices.add(chainIndex);
+        }
+        if (targets.length > 0)
+            groups.push({ primaryArrayPath: primaryArray.path, targets });
+    }
+    return groups;
+}
+function detectDrillDownFoldPlan(actions) {
+    const plans = [];
+    // Spans every primary candidate, not just the current one's own drill
+    // scan: a step already folded into an earlier plan's chain — as either
+    // its drill step or a later chained step — depended on that earlier
+    // 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();
+    for (let primaryIndex = 0; primaryIndex < actions.length; primaryIndex++) {
+        if (globallyConsumedIndices.has(primaryIndex))
+            continue;
+        const primary = actions[primaryIndex];
+        const groups = scanPrimaryCandidateGroups(actions, primaryIndex, globallyConsumedIndices);
+        if (groups.length === 0)
+            continue;
+        const primaryEndpointKey = endpointKey(primary.capture.url);
+        // Each independent array group on this primary is resolved (and
+        // freshest-wins-checked) on its own — a re-queried primary can have one
+        // array whose freshest occurrence is a later re-query while a second,
+        // unrelated array on the SAME step is only ever threaded from the
+        // first occurrence, so the two groups must not be forced to share one
+        // anchor index.
+        for (const group of groups) {
+            // A re-queried primary (same endpoint hit more than once, per
+            // findRequeriedActions) can have MULTIPLE occurrences that each
+            // independently thread a join key into the SAME later drill-down —
+            // e.g. two "available-products" calls that both happen to contain the
+            // item the drill-down looks up. selectReturnAction/selectPayloadAction
+            // already establish freshest-wins for this exact re-queried-primary
+            // case, so the plan must anchor on the LAST such occurrence, not the
+            // first one the forward scan happens to reach.
+            let freshestIndex = primaryIndex;
+            let freshestGroup = group;
+            for (let laterIndex = primaryIndex + 1; laterIndex < actions.length; laterIndex++) {
+                if (globallyConsumedIndices.has(laterIndex))
+                    continue;
+                const laterAction = actions[laterIndex];
+                if (endpointKey(laterAction.capture.url) !== primaryEndpointKey)
+                    continue;
+                const laterGroups = scanPrimaryCandidateGroups(actions, laterIndex, globallyConsumedIndices);
+                const laterGroup = laterGroups.find((g) => JSON.stringify(g.primaryArrayPath) === JSON.stringify(freshestGroup.primaryArrayPath));
+                if (laterGroup === undefined)
+                    continue;
+                const threadsSameDrill = laterGroup.targets.some((laterTarget) => freshestGroup.targets.some((currentTarget) => currentTarget.drillStepIndex === laterTarget.drillStepIndex));
+                if (!threadsSameDrill)
+                    continue;
+                // A primary occurrence's targets all read from THAT occurrence's own
+                // response array, so switching the anchor to a later occurrence can
+                // only be done wholesale, not merged field-by-field. Doing so is only
+                // safe when the later occurrence re-threads EVERY drill-down the
+                // current anchor already covers — otherwise a drill-down target
+                // unique to the earlier occurrence (one it threads independently of
+                // the re-queried join key) would be silently dropped instead of
+                // folded at all.
+                const laterCoversEveryCurrentTarget = freshestGroup.targets.every((currentTarget) => laterGroup.targets.some((laterTarget) => laterTarget.drillStepIndex === currentTarget.drillStepIndex));
+                if (!laterCoversEveryCurrentTarget)
+                    continue;
+                freshestIndex = laterIndex;
+                freshestGroup = laterGroup;
+            }
+            // Defer to the later occurrence: it will be picked up on its own turn
+            // through the outer loop, once it is reached as `primaryIndex`.
+            if (freshestIndex !== primaryIndex)
+                continue;
+            plans.push({
+                primaryStepIndex: freshestIndex,
+                primaryArrayPath: freshestGroup.primaryArrayPath,
+                targets: freshestGroup.targets,
+            });
+            // A step already folded into this plan's chains — the drill step(s)
+            // and everything threaded onward from them — was already merged
+            // into this primary's own array; it must not be re-picked up as a
+            // fresh PRIMARY (its response was already consumed here) nor as a
+            // drill target for a later, independent primary. The primary index
+            // 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);
+            for (const target of freshestGroup.targets) {
+                for (const chainIndex of target.chain)
+                    globallyConsumedIndices.add(chainIndex);
+            }
+        }
+    }
+    return plans;
+}
+/**
+ * Parses an object-form recon-flow.json's optional `foldReturn` declaration
+ * into a typed {@link FoldReturnSpec}, or `null` when the flow is array-form,
+ * doesn't declare `foldReturn`, or declares it with a non-string field —
+ * mirroring the same null-safe pattern the flow loader already applies to
+ * `submitEndpointPattern`/`submitBodyPattern`.
+ */
+function parseFoldReturnSpec(flowFileContents) {
+    try {
+        const raw = JSON.parse(flowFileContents);
+        if (Array.isArray(raw))
+            return null;
+        if (raw === null ||
+            typeof raw !== "object" ||
+            !("steps" in raw) ||
+            !Array.isArray(raw.steps)) {
+            return null;
+        }
+        const foldReturn = raw.foldReturn;
+        if (foldReturn === undefined || foldReturn === null || typeof foldReturn !== "object") {
+            return null;
+        }
+        const { endpointPattern, resultsPath, drillResultsPath, joinFields } = foldReturn;
+        if (typeof endpointPattern !== "string" ||
+            typeof resultsPath !== "string" ||
+            (drillResultsPath !== undefined &&
+                (typeof drillResultsPath !== "string" || drillResultsPath.length === 0)) ||
+            !Array.isArray(joinFields) ||
+            joinFields.length === 0 ||
+            !joinFields.every((f) => typeof f === "string" && f.length > 0)) {
+            return null;
+        }
+        return {
+            endpointPattern,
+            resultsPath,
+            ...(drillResultsPath !== undefined ? { drillResultsPath } : {}),
+            joinFields,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Reads the value at an exact JSON path out of a response body, or
+ * `undefined` when any segment doesn't resolve. The exactness is the point:
+ * {@link findObjectArrayField} is a DFS FIRST-match, so it would silently
+ * override a flow-declared `resultsPath` that names a later array. */
+function readValueAtPath(body, path) {
+    return path.reduce((node, segment) => {
+        if (node === null || typeof node !== "object")
+            return undefined;
+        return node[segment];
+    }, body);
+}
+/** The object items of the array at `path` — the same subset
+ * {@link findObjectArrayField} exposes as `items`, but anchored to a
+ * caller-supplied path instead of discovered by DFS. `null` when `path`
+ * doesn't resolve to an array holding at least one non-array object, UNLESS
+ * `path` resolves to a flat (non-array) object itself, in which case that
+ * object is treated as an implicit one-item collection — see {@link
+ * findAllObjectArrayFieldsOrWholeObject}, which resolves a {@link
+ * FoldTarget}'s `chainArrayPath` to exactly this whole-body shape for a
+ * detail-by-id drill/chain response. An {@link ARRAY_WILDCARD_SEGMENT}
+ * segment in `path` flattens across every element of the array reached at
+ * that point — in DFS/outer-array order — instead of indexing into one,
+ * mirroring the `.flatMap` accessor {@link pathToFoldAccessorExpr} emits for
+ * the same segment, so plan resolution and codegen always agree on which
+ * items a fold covers. */
+function objectItemsAtPath(body, path) {
+    const wildcardIndex = path.indexOf(ARRAY_WILDCARD_SEGMENT);
+    if (wildcardIndex === -1) {
+        const value = readValueAtPath(body, path);
+        if (Array.isArray(value)) {
+            const items = value.filter(isObjectArrayItem);
+            return items.length > 0 ? items : null;
+        }
+        return isObjectArrayItem(value) ? [value] : null;
+    }
+    const outer = readValueAtPath(body, path.slice(0, wildcardIndex));
+    if (!Array.isArray(outer))
+        return null;
+    const after = path.slice(wildcardIndex + 1);
+    const items = outer.flatMap((element) => objectItemsAtPath(element, after) ?? []);
+    return items.length > 0 ? items : null;
+}
+/**
+ * Builds a {@link FoldPlan} from a flow-declared {@link FoldReturnSpec}, so a
+ * site author can express a fold the structural heuristic misses.
+ *
+ * Returns `null` — the same null-safe contract as
+ * {@link detectDrillDownFoldPlan} — when `endpointPattern` is not a valid
+ * regex, when `resultsPath` resolves to no object array on any action, when
+ * no strictly-later action's URL matches `endpointPattern`, or when neither
+ * the matched drill-down's own response nor any later chained hop off of it
+ * holds an object array or flat object (the emitter folds `foldMatches[0]`
+ * out of that collection, so a plan without one has nothing to merge).
+ */
+/** Same value set as {@link collectRequestStringValues}, plus every request
+ * header value — a flow-declared `foldReturn` exists specifically to cover
+ * joins the structural heuristic can't see (most notably a value threaded
+ * 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). */
+function collectRequestValuesIncludingHeaders(capture) {
+    const values = collectRequestStringValues(capture);
+    for (const v of Object.values(capture.requestHeaders))
+        values.add(v);
+    return values;
+}
+/** Finds which of `primaryItems` the drill call actually captured, by
+ * checking every field named in `joinFields` against the drill request's
+ * full value set (URL, body, and headers) — the item matches only when ALL
+ * join fields resolve, since a composite join (e.g. `accountId` + `region`)
+ * is only a real match when every field lines up together. Returns `null`
+ * (never a guessed index) when no item fully matches. */
+function resolveSpecMatchedPrimaryItemIndex(primaryItems, joinFields, drillCapture) {
+    const requestValues = collectRequestValuesIncludingHeaders(drillCapture);
+    if (requestValues.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 && requestValues.has(value)) ||
+            (typeof value === "number" && requestValues.has(String(value))));
+    }));
+    return matchedIndex === -1 ? null : matchedIndex;
+}
+function buildFoldPlanFromSpec(actions, spec) {
+    const primaryArrayPath = spec.resultsPath.split(".");
+    const endpointRx = (() => {
+        try {
+            return new RegExp(spec.endpointPattern);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (endpointRx === null)
+        return null;
+    let freshestPlan = null;
+    for (let primaryStepIndex = 0; primaryStepIndex < actions.length; primaryStepIndex++) {
+        const primaryItems = objectItemsAtPath(actions[primaryStepIndex].capture.responseBody, primaryArrayPath);
+        if (!primaryItems)
+            continue;
+        for (let drillStepIndex = primaryStepIndex + 1; drillStepIndex < actions.length; drillStepIndex++) {
+            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
+            // detail-by-id drill response exactly like the case the heuristic
+            // detects on its own, not just an array field.
+            // Falls through with an empty `[]` path baseline — rather than
+            // bailing here — when the matched drill step's own response holds no
+            // object-array/flat-object candidate, so an intermediate hop that
+            // merely threads a value onward (holding no foldable data itself)
+            // still lets computeFoldChain walk to a later chained step that DOES
+            // hold the real per-item data, exactly as the structural heuristic
+            // 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 drillArrayPath = (() => {
+                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 ?? []);
+            // 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
+            // is skipped exactly as the pre-chain null check used to skip it.
+            if (!objectItemsAtPath(actions[chainTerminalIndex].capture.responseBody, chainArrayPath)) {
+                continue;
+            }
+            freshestPlan = {
+                primaryStepIndex,
+                primaryArrayPath,
+                targets: [
+                    {
+                        joinFields: spec.joinFields,
+                        drillStepIndex,
+                        drillArrayPath: drillArrayPath ?? [],
+                        primaryMatchedItemIndex,
+                        chain,
+                        chainArrayPath,
+                        chainTerminalIndex,
+                    },
+                ],
+            };
+        }
+    }
+    return freshestPlan;
+}
+/**
+ * Unions a flow-declared `foldReturn` spec's drill-down target into the
+ * structurally-detected plan for the SAME primary array (matched by
+ * `primaryStepIndex` and `primaryArrayPath`), so a spec declaring an
+ * independent target the heuristic missed is not silently discarded just
+ * because the heuristic already resolved something for that primary. A spec
+ * whose own primary/drill pair is entirely independent of every structural
+ * plan — its `primaryStepIndex` and its target chains touch no index any
+ * structural plan already consumes — is appended as a brand-new plan
+ * instead. Only a spec whose primary step is itself already consumed by an
+ * unrelated structural plan's own chain (not its own primary) is left alone,
+ * to avoid folding onto a step that plan already depends on. A spec
+ * re-declaring a `drillStepIndex` the heuristic already found (for the SAME
+ * primary) is skipped, not duplicated.
+ */
+function mergeSpecPlanOntoSamePrimary(structuralPlans, actions, foldReturnSpec) {
+    if (foldReturnSpec === null)
+        return [...structuralPlans];
+    const specPlan = buildFoldPlanFromSpec(actions, foldReturnSpec);
+    if (specPlan === null)
+        return [...structuralPlans];
+    const samePrimaryPlan = structuralPlans.find((plan) => plan.primaryStepIndex === specPlan.primaryStepIndex &&
+        JSON.stringify(plan.primaryArrayPath) === JSON.stringify(specPlan.primaryArrayPath));
+    if (samePrimaryPlan !== undefined) {
+        return structuralPlans.map((plan) => {
+            if (plan !== samePrimaryPlan)
+                return plan;
+            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] };
+        });
+    }
+    // Keyed by the (primaryStepIndex, primaryArrayPath) pair, not
+    // primaryStepIndex alone — a structural plan only ever consumed ITS OWN
+    // array on that step, not the whole step. A spec whose resultsPath names
+    // a second, structurally-undetected array on that exact same primary step
+    // has already been proven independent by the samePrimaryPlan lookup above
+    // (its primaryArrayPath differs from every structural plan's), so keying
+    // solely on the step index would wrongly treat it as already consumed and
+    // silently drop it.
+    const consumedIndices = new Set();
+    const consumedPrimarySteps = new Set();
+    for (const plan of structuralPlans) {
+        consumedPrimarySteps.add(`${plan.primaryStepIndex}:${JSON.stringify(plan.primaryArrayPath)}`);
+        for (const target of plan.targets) {
+            for (const chainIndex of target.chain)
+                consumedIndices.add(chainIndex);
+        }
+    }
+    const specConsumesOnlyItsOwnIndices = !consumedIndices.has(specPlan.primaryStepIndex) &&
+        !consumedPrimarySteps.has(`${specPlan.primaryStepIndex}:${JSON.stringify(specPlan.primaryArrayPath)}`) &&
+        specPlan.targets.every((target) => target.chain.every((chainIndex) => !consumedIndices.has(chainIndex)));
+    return specConsumesOnlyItsOwnIndices ? [...structuralPlans, specPlan] : [...structuralPlans];
+}
+/**
+ * The single fold-plan entry point: {@link detectDrillDownFoldPlan}'s
+ * structural heuristic first, falling back to a flow-declared `foldReturn`
+ * spec when the heuristic finds nothing. `emitMultiStepExecuteHttp` and
+ * `selectEffectiveResponseBody` MUST both resolve through this rather than
+ * calling the detector directly, or the emitted `executeHttp` and its
+ * inferred schema would describe different calls (see
+ * {@link selectEffectiveResponseBody}'s own docstring).
+ *
+ * A multipart step anywhere in a target's fold chain disqualifies only that
+ * target: the fold loop re-issues EVERY chain step's request per item by
+ * re-keying its rendered JSON request template (not just the immediate drill
+ * step's), and a raw `FormData` upload has no such template to re-key — so
+ * that target falls back to ordinary single-call emission instead of
+ * emitting a broken loop, while any other target on the same primary that
+ * has no multipart step in its chain still folds normally. A plan is dropped
+ * from the returned array only when EVERY target for its primary is
+ * multipart-disqualified, leaving nothing left to fold.
+ *
+ * {@link detectDrillDownFoldPlan} can find more than one independent
+ * primary/drill-down pair in a single action sequence, so this returns every
+ * plan that survives multipart disqualification, letting every downstream
+ * emitter/shape-inference caller fold each of them.
+ */
+function resolveFoldPlan(actions, foldReturnSpec = null) {
+    const structuralPlans = detectDrillDownFoldPlan(actions);
+    const plans = structuralPlans.length > 0
+        ? mergeSpecPlanOntoSamePrimary(structuralPlans, actions, foldReturnSpec)
+        : (() => {
+            if (foldReturnSpec === null)
+                return [];
+            const specPlan = buildFoldPlanFromSpec(actions, foldReturnSpec);
+            return specPlan === null ? [] : [specPlan];
+        })();
+    return plans.flatMap((plan) => {
+        const targets = plan.targets.filter((target) => !target.chain.some((chainIndex) => actions[chainIndex].isMultipart));
+        return targets.length === 0 ? [] : [{ ...plan, targets }];
+    });
+}
+/** 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
+ * unchanged. Identity, not a path, is what locates the splice point: a
+ * {@link FoldPlan.primaryArrayPath} carrying an {@link ARRAY_WILDCARD_SEGMENT}
+ * names a whole family of per-group arrays, not one splice-able location, so
+ * only the matched item's own object reference (never cloned by
+ * {@link findAllObjectArrayFields}/{@link objectItemsAtPath}, both of which
+ * only filter) pins down where the fold actually lands, regardless of which
+ * group it came from. */
+function replaceByReference(value, target, replacement) {
+    if (value === target)
+        return replacement;
+    if (Array.isArray(value))
+        return value.map((v) => replaceByReference(v, target, replacement));
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [
+            k,
+            replaceByReference(v, target, replacement),
+        ]));
+    }
+    return value;
+}
+/**
+ * The value-level counterpart of the per-item loop-and-merge
+ * `emitMultiStepExecuteHttp` emits for a detected {@link FoldPlan}: merges
+ * the captured drill-down item whose `joinFields` match the single captured
+ * primary sample's matched array item — at `primaryMatchedItemIndex`, the
+ * same item `detectDrillDownFoldPlan` built the join key from, not
+ * necessarily index 0 — falling back to the drill array's first item only
+ * when no drill item matches, so schema inference walks the SAME shape the
+ * folded `executeHttp` actually returns at runtime. Reads both arrays at
+ * the plan's OWN paths rather than re-running `findObjectArrayField`, so a
+ * flow-declared `resultsPath` stays authoritative here exactly as it is in
+ * the emitter. Falls back to the unmerged primary body if either capture no
+ * longer resolves an object array — same drift guard as the emitter's own
+ * `throw` at the analogous point, minus the throw, since shape inference
+ * degrading gracefully is preferable to failing a generate run over it.
+ */
+function foldResponseBodyForShapeInference(actionSteps, foldPlan, initialBody = actionSteps[foldPlan.primaryStepIndex].capture.responseBody) {
+    return foldPlan.targets.reduce((body, target) => {
+        const drillBody = actionSteps[target.chainTerminalIndex].capture.responseBody;
+        const primaryItems = objectItemsAtPath(body, foldPlan.primaryArrayPath);
+        const drillItems = objectItemsAtPath(drillBody, target.chainArrayPath);
+        const matchedItem = primaryItems?.[target.primaryMatchedItemIndex];
+        const drillMatch = drillItems?.find((d) => target.joinFields.every((f) => String(readValueAtPath(d, f.split("."))) ===
+            String(readValueAtPath(matchedItem, f.split("."))))) ?? drillItems?.[0];
+        if (!primaryItems || !matchedItem || !drillMatch)
+            return body;
+        return replaceByReference(body, matchedItem, { ...matchedItem, ...drillMatch });
+    }, initialBody);
 }
 /**
  * Detects whether a read-only GraphQL primary operation exposes a bounded
@@ -3914,7 +5359,7 @@ function buildPaginatedGqlExecuteHttpBody(opts) {
     return `    const baseVariables = ${gqlVariablesExpr};
     const PAGE_SIZE = ${pageSize};
     // Bounded so a paging bug (a total that never converges) can't loop forever.
-    const MAX_PAGES = 50;
+    const MAX_PAGES = payload.maxPages ?? 50;
     const itemsById = new Map<string, unknown>();
     let skip = 0;
     const page = await getGql(context.baseUrl)(${gqlOperationNameExpr}, ${queryConstName}, ${variablesForCall});
@@ -3977,7 +5422,7 @@ function buildContractChecklist(opts) {
     ].filter((line) => line !== "");
 }
 function emitContractTs(opts) {
-    const { siteId, pascal, baseUrl, baseHeaders, minTime, safeRps, hasRateLimitProbeData = false, responseBody, gql, gqlQuery, endpointPath, gqlOperationName, gqlVariables, auxFiles, multiStepBody, omitExecuteHttp = false, isSubmissionFlow = false, inputBody, hasMultipartStep = false, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, discoveredStructuredKeys, payloadFieldNames, headerBindings = [], } = 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;
     // 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
@@ -4002,11 +5447,16 @@ function emitContractTs(opts) {
     // successful return IS a real signal — z.unknown() would be dishonest
     // in the other direction, hiding a field the flow can actually promise.
     const conditionalFieldNames = gql && gqlQuery ? collectConditionalGraphQLFieldNames(gqlQuery) : undefined;
+    const aggregateUnitBasisFindingsByPath = groupAggregateUnitBasisFindingsByPath(responseBodySamples);
     const responseSchemaExpr = omitExecuteHttp && isSubmissionFlow
         ? `z.object({ verified: z.boolean() })`
         : omitExecuteHttp
             ? `z.unknown()`
-            : inferZodSchema(responseBody, 0, "", { conditionalFieldNames });
+            : inferZodSchemaFromSamples(responseBodySamples, 0, "", {
+                conditionalFieldNames,
+                looseServerResponse: true,
+                aggregateUnitBasisFindingsByPath,
+            });
     // Multi-step flows that include a multipart upload need the binary asset
     // on the payload. ApplicantContactSchema (via ApplicantResumeSchema) already
     // declares Resume/ResumeContentType/ResumeFilename, so submission flows
@@ -4034,6 +5484,12 @@ function emitContractTs(opts) {
     const basePayloadSchemaExpr = inputBody
         ? `ApplicantContactSchema`
         : `z.object({\n  query: z.string().min(1),\n})`;
+    // Only the single-endpoint GraphQL read path (a real primary operation, no
+    // multi-step flow) is a candidate for a paging signal — multiStepBody
+    // already owns its own per-call semantics.
+    const paginationSignal = !multiStepBody && gql && gqlOperationName
+        ? detectPaginationSignal(responseBody, gqlVariables)
+        : null;
     // 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({...})`
@@ -4046,6 +5502,13 @@ function emitContractTs(opts) {
     const addExtendField = (name, line) => {
         extendFields.set(name, line);
     };
+    // A detected bounded-paging signal means buildPaginatedGqlExecuteHttpBody
+    // will emit a loop bounded by MAX_PAGES — expose that bound as a caller-
+    // overridable payload field, mirroring how PAGE_SIZE is already sourced
+    // from the detected signal.
+    if (paginationSignal) {
+        addExtendField("maxPages", "  maxPages: z.number().int().positive().optional(),");
+    }
     // The base extend's own keys — submission flows only.
     if (inputBody) {
         addExtendField("Email", "  Email: z.email(),");
@@ -4206,6 +5669,25 @@ function emitContractTs(opts) {
     // that collides with the base extend's own Email/ClickUrl/Answers) collapses
     // to its last-declared line, rather than becoming a second, dupe-prone
     // `.extend()` call chained onto the schema.
+    // A field whose name matches (case-insensitively, the same convention
+    // renderGqlVariablesExpr uses) a declared GraphQL variable that no capture
+    // ever populated has no wiring target in executeHttp — it would replay the
+    // captured frozen value regardless of what the caller sends. Downgrading it
+    // to `.optional()` here, at the single merge point every source funnels
+    // through, keeps the schema honest without special-casing any one source.
+    // Email/ClickUrl/Answers are the public contract every submission-flow
+    // plugin must declare unconditionally (see the basePayloadSchemaExpr
+    // comment above) — a GraphQL mutation that happens to declare an
+    // unpopulated variable with a matching name (e.g. `$email`) must not
+    // downgrade that required base field.
+    const baseContractFieldNames = new Set(["Email", "ClickUrl", "Answers"]);
+    for (const [fieldName, line] of extendFields) {
+        if (inputBody && baseContractFieldNames.has(fieldName))
+            continue;
+        if (unpopulatedDeclaredVariables.some((name) => name.toLowerCase() === fieldName.toLowerCase())) {
+            extendFields.set(fieldName, line.replace(/,\s*$/, ".optional(),"));
+        }
+    }
     const mergedExtension = extendFields.size > 0 ? `.extend({\n${[...extendFields.values()].join("\n")}\n})` : "";
     const payloadSchemaExpr = `${basePayloadSchemaExpr}${mergedExtension}`;
     // basePayloadSchemaExpr's own Answers field always wraps in
@@ -4232,6 +5714,12 @@ function emitContractTs(opts) {
     const caseInsensitiveHeadersImport = hasMultipartStep && !omitExecuteHttp
         ? `import { omitHeaderCaseInsensitive } from "${ENGINE_PKG}/lib/case-insensitive-headers";\n`
         : "";
+    // emitMultiStepExecuteHttp emits a call to this helper whenever more than
+    // one fold plan resolves — the generated plugin package can't reach into
+    // recon-generate.ts's own module scope, so it must import it separately.
+    const mergeFoldedPrimaryBodiesImport = multiStepBody?.includes("mergeFoldedPrimaryBodies(") === true
+        ? `import { mergeFoldedPrimaryBodies } from "${ENGINE_PKG}/lib/merge-folded-primary-bodies";\n`
+        : "";
     // Emit identifier-shaped keys unquoted so Biome's formatter doesn't rewrite
     // the generated file on first lint:fix.
     const headersLiteral = Object.entries(baseHeaders)
@@ -4248,7 +5736,7 @@ function emitContractTs(opts) {
             ? `import { createGraphqlClient } from "${ENGINE_PKG}/scraper/graphql-client";`
             : `import { createHttpClient } from "${ENGINE_PKG}/scraper/http-client";`;
     const queryConst = !omitExecuteHttp && gql && gqlQuery
-        ? `\n// Lifted verbatim from recon capture — trim UI-only fields before shipping.\nconst ${pascal.toUpperCase()}_QUERY = \`${gqlQuery.trim()}\`;\n`
+        ? `\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`
         : "";
     const gqlCacheBlock = omitExecuteHttp
         ? ""
@@ -4281,12 +5769,6 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
     const gqlVariablesExpr = gqlOperationName
         ? renderGqlVariablesExpr(gqlVariables, payloadFieldNames)
         : "{ q: payload.query }";
-    // Only the single-endpoint GraphQL read path (a real primary operation, no
-    // multi-step flow) is a candidate for a paging signal — multiStepBody
-    // already owns its own per-call semantics.
-    const paginationSignal = !multiStepBody && gql && gqlOperationName
-        ? detectPaginationSignal(responseBody, gqlVariables)
-        : null;
     const executeHttpBody = multiStepBody
         ? multiStepBody
         : paginationSignal
@@ -4380,7 +5862,7 @@ ${executeHttpBody}
 
 ${bottleneckImport}import { z } from "zod/v4";
 
-${fixtureImport}${applicantContactImport}${caseInsensitiveHeadersImport}${multipartBoolImport}${clientImport}
+${fixtureImport}${applicantContactImport}${caseInsensitiveHeadersImport}${mergeFoldedPrimaryBodiesImport}${multipartBoolImport}${clientImport}
 import type { BrowserSession } from "${ENGINE_PKG}/scraper/session";
 import type { SitePlugin, SitePluginContext, SitePluginResult } from "${ENGINE_PKG}/site-plugin";
 import { run${pascal}BrowserFlow } from "@/sites/${siteId}/flows/browser-flow";
@@ -4398,7 +5880,7 @@ ${internalRequestReferenceBlock}${queryConst}${gqlCacheBlock}${fixtureComments}
 ${pluginDocComment}
 export const ${camel}Plugin: SitePlugin<${pascal}Payload, ${pascal}Response> = {
   meta: {
-    siteId: ${JSON.stringify(siteId)},
+    siteId: ${JSON.stringify(siteId)},${displayName !== undefined ? `\n    displayName: ${JSON.stringify(displayName)},` : ""}
     bodySchema: ${pascal}PayloadSchema,
     responseSchema: ${pascal}ResponseSchema,
     defaultBaseUrl: ${JSON.stringify(baseUrl)},
@@ -4968,15 +6450,29 @@ async function main() {
             return [];
         }
     })();
-    const { flowSteps, frameSelector, submitEndpointPattern, submitBodyPattern } = (() => {
+    const { flowSteps, frameSelector, submitEndpointPattern, submitBodyPattern, displayName, foldReturnSpec, } = (() => {
+        const flowFileContents = (() => {
+            try {
+                return (0, node_fs_1.readFileSync)(flowFile, "utf8");
+            }
+            catch {
+                return null;
+            }
+        })();
+        // Parsed off the raw bytes, independently of the steps shape below, so a
+        // valid `foldReturn` still resolves when the rest of the flow file is
+        // degenerate — the two declarations fail independently.
+        const foldReturnSpec = flowFileContents === null ? null : parseFoldReturnSpec(flowFileContents);
         try {
-            const raw = JSON.parse((0, node_fs_1.readFileSync)(flowFile, "utf8"));
+            const raw = flowFileContents === null ? null : JSON.parse(flowFileContents);
             if (Array.isArray(raw))
                 return {
                     flowSteps: raw,
                     frameSelector: undefined,
                     submitEndpointPattern: null,
                     submitBodyPattern: null,
+                    displayName: undefined,
+                    foldReturnSpec,
                 };
             if (raw !== null &&
                 typeof raw === "object" &&
@@ -4988,6 +6484,8 @@ async function main() {
                     frameSelector: obj.frameSelector,
                     submitEndpointPattern: obj.submitEndpointPattern ?? null,
                     submitBodyPattern: obj.submitBodyPattern ?? null,
+                    displayName: obj.displayName,
+                    foldReturnSpec,
                 };
             }
             return {
@@ -4995,6 +6493,8 @@ async function main() {
                 frameSelector: undefined,
                 submitEndpointPattern: null,
                 submitBodyPattern: null,
+                displayName: undefined,
+                foldReturnSpec,
             };
         }
         catch {
@@ -5003,6 +6503,8 @@ async function main() {
                 frameSelector: undefined,
                 submitEndpointPattern: null,
                 submitBodyPattern: null,
+                displayName: undefined,
+                foldReturnSpec,
             };
         }
     })();
@@ -5097,9 +6599,17 @@ async function main() {
     // replay array order -- a replay's body reflects whichever endpoint fired
     // first, not necessarily the primary operation, and only exists once
     // recon:http has run.
-    const responseBody = (primaryGraphQLOperation?.capture ??
+    const winningCapture = primaryGraphQLOperation?.capture ??
         fallbackGraphQLCapture ??
-        firstEndpointCapture(captures, ownBackendHostnames, fallbackDomain))?.responseBody ?? null;
+        firstEndpointCapture(captures, ownBackendHostnames, fallbackDomain);
+    const responseBody = winningCapture?.responseBody ?? null;
+    // Every 2xx capture sharing the winning capture's operation identity, not
+    // just the one that happened to win selection -- a paginated/re-filtered
+    // re-fire of the same operation can omit a field the winning capture
+    // happened to have (or vice versa), and inferZodSchemaFromSamples needs
+    // that presence evidence across occurrences to mark the field .optional()
+    // instead of required from a single observation.
+    const responseBodySamples = gatherResponseBodySamples(winningCapture, primaryGraphQLOperation !== null || fallbackGraphQLCapture !== null, captures);
     // Detect a multi-step submission flow (transactional sites like apply forms,
     // checkout, etc.). When the action sequence has 2+ POSTs, switch the
     // contract template to emit a state-threaded executeHttp.
@@ -5321,18 +6831,25 @@ async function main() {
     const multiStepBody = browserFlowOnly
         ? undefined
         : isSubmissionFlow
-            ? emitMultiStepExecuteHttp(actionSteps, inputBody, errorSignals, fieldNameMap, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, formSchema, personaBindings, entryUrlParams, shieldedUuids, selectResolutions, discoveredStructuredKeys, rawCodeFields)
+            ? emitMultiStepExecuteHttp(actionSteps, inputBody, errorSignals, fieldNameMap, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, formSchema, personaBindings, entryUrlParams, shieldedUuids, selectResolutions, discoveredStructuredKeys, rawCodeFields, foldReturnSpec)
             : undefined;
     const hasMultipartStep = actionSteps.some((s) => s.isMultipart);
     const headerBindings = collectHeaderBindings(actionSteps);
     // Shape inference targets the SAME call executeHttp returns — see
     // selectEffectiveResponseBody — so the two surfaces can't describe different calls.
-    const effectiveResponseBody = selectEffectiveResponseBody(isSubmissionFlow, actionSteps, responseBody);
+    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) {
+        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})`);
     if (emit === "config") {
         (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
         (0, node_fs_1.writeFileSync)(manifestPath, emitConfigManifest({
             siteId,
+            displayName,
             baseUrl,
             flowSteps,
             vocabulary,
@@ -5366,6 +6883,7 @@ async function main() {
     });
     const contractOpts = {
         siteId,
+        displayName,
         pascal,
         baseUrl,
         // G1+G2: only the static headers (no baseUrl/tenant-subdomain references)
@@ -5375,6 +6893,11 @@ async function main() {
         safeRps,
         hasRateLimitProbeData,
         responseBody: effectiveResponseBody,
+        // selectEffectiveResponseBody already resolves a submission flow's own
+        // single terminal capture -- the multi-sample evidence gathered above
+        // describes the (possibly different) read-flow winning capture and
+        // doesn't apply once a submission flow has picked its own return call.
+        responseBodySamples: isSubmissionFlow ? [effectiveResponseBody] : responseBodySamples,
         gql,
         gqlQuery,
         endpointPath,
@@ -5398,6 +6921,7 @@ async function main() {
         discoveredStructuredKeys,
         payloadFieldNames: browserFlow.payloadFieldNames,
         headerBindings,
+        unpopulatedDeclaredVariables: primaryGraphQLOperation?.unpopulatedDeclaredVariables ?? [],
     };
     const contractCode = emitContractTs(contractOpts);
     // Fails loudly rather than shipping a flow that requires a URL field it