@enricai/barnacle 1.12.54 → 1.12.55

package/dist/scripts/recon-generate.js

@@ -66,6 +66,7 @@ exports.getScanPrimaryCandidateGroupsCallCountForTest = getScanPrimaryCandidateG
 exports.resetScanPrimaryCandidateGroupsCallCountForTest = resetScanPrimaryCandidateGroupsCallCountForTest;
 exports.detectDrillDownFoldPlan = detectDrillDownFoldPlan;
 exports.parseFoldReturnSpec = parseFoldReturnSpec;
+exports.parseFallbackGateSpec = parseFallbackGateSpec;
 exports.collectRequestValuesIncludingHeaders = collectRequestValuesIncludingHeaders;
 exports.getFoldPlanResolutionCallCountForTests = getFoldPlanResolutionCallCountForTests;
 exports.resetFoldPlanResolutionCallCountForTests = resetFoldPlanResolutionCallCountForTests;
@@ -89,7 +90,9 @@ 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");
 const load_form_schema_1 = require("../recon/load-form-schema");
+const load_value_constraints_1 = require("../recon/load-value-constraints");
 const load_vocabulary_1 = require("../recon/load-vocabulary");
+const value_constraints_1 = require("../recon/value-constraints");
 const vocabulary_1 = require("../recon/vocabulary");
 const recon_shared_1 = require("./recon-shared");
 const logger = (0, logging_1.getScriptLogger)("recon-generate");
@@ -1798,6 +1801,17 @@ function collapseRedundantPatches(actions) {
  * counter, unpaired with an explicit page-size key) since that is the common
  * REST shape, unlike GraphQL's paired variables convention. */
 const PAGINATION_FIELD_NAME_PATTERN = /^(page|pagenum|pagenumber|pageindex|pageno|offset|skip|start|cursor)$/i;
+/** Response leaf-key shapes that name a discoverable ceiling on some other
+ * numeric quantity (a capacity, a maximum, a limit) -- structural, like
+ * {@link PAGINATION_FIELD_NAME_PATTERN}, not tied to any domain's field
+ * vocabulary. Used to bound a request-side numeric field whose observed
+ * values never exceed a same-run response's declared ceiling. */
+const CAPACITY_FIELD_NAME_PATTERN = /(max|capacity|limit)/i;
+/** Upper bound on how many distinct string values a request field may show
+ * across a run's captures before it stops looking like a closed-set facet
+ * vocabulary and starts looking like free text -- past this, emitting
+ * z.enum(...) would lock callers out of values recon simply never sampled. */
+const VOCABULARY_ENUM_MAX_DISTINCT_VALUES = 8;
 /** Request-field key names that name known client-generated scaffolding
  * (a monotonic sequence counter, a correlation/trace id, an idempotency
  * nonce) rather than genuine payload data. Gates {@link
@@ -3928,6 +3942,41 @@ function pathToFoldLoopLines(expr, path, itemVar, indent, varSuffix = "", depth
         ancestorCloseLines,
     };
 }
+/**
+ * Splices a fold's per-item body between `itemOpenLines`/`itemCloseLines`
+ * (see {@link pathToFoldLoopLines}) — either as the original sequential
+ * `for` loop, when the body never issues its own per-item drill fetch (so
+ * existing byte-identical fold output is preserved for every fold that has
+ * nothing to parallelize), or rewritten into a `Promise.allSettled`-based
+ * parallel form when it does: `for (const item of X) {` becomes `await
+ * Promise.allSettled((X).map(async (item) => { ... }));`. Every item's
+ * fetch then fires concurrently instead of one at a time, and a rejected
+ * item's promise can't abort a sibling's — `allSettled` never short-
+ * circuits on a rejection, and the sibling's `Object.assign` onto its own
+ * item already only runs once ITS OWN fetch resolves, so a failed item
+ * simply keeps its original (unmerged) fields instead of taking every other
+ * item's already-fetched data down with it.
+ */
+function emitItemLoopLines(itemOpenLines, itemScopedLines, itemCloseLines, itemVar, hasItemScopedFetch) {
+    if (!hasItemScopedFetch) {
+        return [...itemOpenLines, ...itemScopedLines, ...itemCloseLines];
+    }
+    const forLineIndex = itemOpenLines.length - 1;
+    const forLine = itemOpenLines[forLineIndex];
+    const forLineMatch = forLine.match(/^(\s*)for \(const \w+ of (.+)\) \{$/);
+    if (!forLineMatch) {
+        throw new Error(`emitItemLoopLines: unrecognized fold item-loop shape: ${forLine}`);
+    }
+    const [, indent, iterableExpr] = forLineMatch;
+    return [
+        ...itemOpenLines.slice(0, forLineIndex),
+        `${indent}await Promise.allSettled(`,
+        `${indent}  (${iterableExpr}).map(async (${itemVar}) => {`,
+        ...itemScopedLines,
+        `${indent}  })`,
+        `${indent});`,
+    ];
+}
 /** 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) {
@@ -4817,10 +4866,15 @@ function applyUrlParamPayloadSubstitutions(template, parsedBody, bindings) {
  * even though the field genuinely IS one this step's own request sends as
  * caller-supplied data.
  */
-function applyPayloadKeyValueSubstitutions(template, inputBody, additionalBodies = [], outAdditionalKeys = new Map()) {
+function applyPayloadKeyValueSubstitutions(template, inputBody, additionalBodies = [], outAdditionalKeys = new Map(), 
+/** Every capture's response body from the same run, scanned only for
+ * {@link CAPACITY_FIELD_NAME_PATTERN}-shaped numeric leaves — the
+ * evidence source for a discovered "number" key's `capacityMax`. */
+responseBodiesForCapacitySignal = []) {
     const merged = [];
     const seenPairs = new Set();
     const seenValueByKey = new Map();
+    const distinctValuesByKey = new Map();
     const allBodies = [inputBody, ...additionalBodies];
     for (const body of allBodies) {
         if (body === undefined || body === null || typeof body !== "object" || Array.isArray(body)) {
@@ -4854,6 +4908,17 @@ function applyPayloadKeyValueSubstitutions(template, inputBody, additionalBodies
                 continue;
             }
             seenValueByKey.set(key, value);
+            // Tracked independently of the (key, value) dedupe below — a facet's
+            // vocabulary or a capacity ceiling needs every distinct value it took,
+            // not just the deduped substitution list, and pagination cursors are
+            // excluded from both (their values grow monotonically and are never a
+            // closed set).
+            if ((typeof value === "string" || typeof value === "number") &&
+                !PAGINATION_FIELD_NAME_PATTERN.test(key)) {
+                const distinct = distinctValuesByKey.get(key) ?? new Set();
+                distinct.add(value);
+                distinctValuesByKey.set(key, distinct);
+            }
             const pairKey = `${key} ${typeof value} ${value}`;
             if (seenPairs.has(pairKey))
                 continue;
@@ -4866,11 +4931,54 @@ function applyPayloadKeyValueSubstitutions(template, inputBody, additionalBodies
             // isReservedByApplicantContactSchema — this function has no visibility
             // into that flag, so it must not special-case inputBody's own keys.
             if (typeof value === "string")
-                outAdditionalKeys.set(key, "string");
+                outAdditionalKeys.set(key, { kind: "string" });
             else if (typeof value === "number")
-                outAdditionalKeys.set(key, "number");
+                outAdditionalKeys.set(key, { kind: "number" });
             else if (typeof value === "boolean")
-                outAdditionalKeys.set(key, "boolean");
+                outAdditionalKeys.set(key, { kind: "boolean" });
+        }
+    }
+    // Vocabulary-derived enum: a "string" key whose distinct observed values
+    // form a small closed set is a facet field, not free text — emit the set
+    // so the generated schema rejects a caller value recon never sampled.
+    // Capacity-bounded number: a "number" key gets a ceiling only when some
+    // same-run response carries a max/capacity/limit-shaped numeric leaf that
+    // is >= every value this key was observed to carry; the tightest such
+    // ceiling wins so the bound is never looser than the evidence supports.
+    const capacityCandidatesByMinBound = () => {
+        const candidates = [];
+        for (const body of responseBodiesForCapacitySignal) {
+            if (body === undefined || body === null || typeof body !== "object")
+                continue;
+            for (const { value, path } of walkAllPrimitiveLeaves(body)) {
+                const leafName = path[path.length - 1] ?? "";
+                if (typeof value !== "number")
+                    continue;
+                if (!CAPACITY_FIELD_NAME_PATTERN.test(leafName))
+                    continue;
+                candidates.push(value);
+            }
+        }
+        return candidates;
+    };
+    const capacitySignals = capacityCandidatesByMinBound();
+    for (const [key, info] of outAdditionalKeys) {
+        const distinct = distinctValuesByKey.get(key);
+        if (!distinct)
+            continue;
+        if (info.kind === "string") {
+            if (distinct.size >= 2 && distinct.size <= VOCABULARY_ENUM_MAX_DISTINCT_VALUES) {
+                info.enumValues = [...distinct].map(String).sort();
+            }
+            continue;
+        }
+        if (info.kind === "number") {
+            const maxObserved = Math.max(...[...distinct].map(Number));
+            const tightestCeiling = capacitySignals
+                .filter((v) => v >= maxObserved)
+                .sort((a, b) => a - b)[0];
+            if (tightestCeiling !== undefined)
+                info.capacityMax = tightestCeiling;
         }
     }
     let result = template;
@@ -5254,6 +5362,12 @@ pascalName = null) {
             // skip non-JSON bodies (e.g. multipart raw bytes)
         }
     }
+    // Every action's response body, gathered once for the whole flow so a
+    // capacity/max ceiling discovered on ANY capture (not just the one that
+    // carries the request field itself) is available to bound a request-side
+    // numeric field — the ceiling and the field it bounds are frequently
+    // declared on different calls (an availability check, then a booking).
+    const allResponseBodies = actions.map((a) => a.capture.responseBody);
     // Every value `applyPayloadKeyValueSubstitutions` will unconditionally
     // payload-ify from the ENTRY payload's own top-level key/value pairs,
     // gathered here so {@link interpolateStateValues} can give it payload
@@ -5457,7 +5571,7 @@ pascalName = null) {
             ? applyUrlParamPayloadSubstitutions(rawBodyWithProducerBoundary, parsedBody, urlParamBindings)
             : rawBodyWithProducerBoundary;
         const bodyAfterStateAndKv = rawBodyWithUrlParams
-            ? applyPayloadKeyValueSubstitutions(interpolateStateValues(rawBodyWithUrlParams, prior, cap, payloadAccessorByValue, true, producerBoundaryBindings, i, topLevelPayloadKvValues), inputBody, additionalBodies, outDiscoveredAdditionalBodyKeys)
+            ? applyPayloadKeyValueSubstitutions(interpolateStateValues(rawBodyWithUrlParams, prior, cap, payloadAccessorByValue, true, producerBoundaryBindings, i, topLevelPayloadKvValues), inputBody, additionalBodies, outDiscoveredAdditionalBodyKeys, allResponseBodies)
             : "";
         // Mechanism A — generic (plain-JSON, wire-key-anchored) dropdown label→code
         // rewrite. Runs AFTER interpolateStateValues + the payload-KV pass, not
@@ -5662,6 +5776,15 @@ pascalName = null) {
             // Every target's join/merge — plus any non-hoistable target's own
             // chain fetch — goes here, spliced inside the item loop.
             const itemScopedLines = [];
+            // True once any target's own chain fetch ends up item-scoped (not
+            // hoisted above the item loop) — only then does the item loop have
+            // anything to parallelize; see emitItemLoopLines.
+            let hasItemScopedFetch = false;
+            // True once any item-scoped target's chain threads a response header
+            // through createHttpClient's shared `bind` store — see
+            // chainUsesHeaderThreading below for why that disqualifies
+            // parallelizing the item loop.
+            let hasItemScopedHeaderThreading = false;
             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
@@ -5896,6 +6019,16 @@ pascalName = null) {
                 // `itemVar` is never declared.
                 const itemVarRefPattern = new RegExp(`\\b${itemVar}\\b`);
                 let referencesItemVar = ancestorVars.length === 0;
+                // A chain step that produces a response HEADER threads it through
+                // `createHttpClient`'s single shared `bind` store (see
+                // HttpClientOptions.bind), not a local variable — that store is
+                // mutated in call order and read by whichever call happens to run
+                // next, regardless of which item minted it. Running items
+                // concurrently would let one item's header overwrite another's
+                // in-flight header before its own later chain hop reads it back, so
+                // any target relying on header threading keeps the item loop
+                // sequential rather than risk cross-item header contamination.
+                let chainUsesHeaderThreading = false;
                 for (const chainIndex of target.chain) {
                     const chainStep = actions[chainIndex];
                     const chainRendered = rendered[chainIndex];
@@ -5916,8 +6049,10 @@ pascalName = null) {
                         chainLines.push(`        ${joined}`);
                     chainLines.push(`        schema: ${chainRendered.schemaExpr},`, `      })) as Record<string, unknown>;`);
                     for (const p of chainStep.produces) {
-                        if (p.kind === "header")
+                        if (p.kind === "header") {
+                            chainUsesHeaderThreading = true;
                             continue;
+                        }
                         if (chainDeclared.has(p.name))
                             continue;
                         if (!referencedNames.has(p.name))
@@ -5931,13 +6066,17 @@ pascalName = null) {
                 const matchLines = emitFoldMatchAndMergeLines(terminalStep, target, itemVar, suffix, joinAccessor);
                 if (referencesItemVar) {
                     itemScopedLines.push(...chainLines, ...matchLines);
+                    if (chainLines.length > 0)
+                        hasItemScopedFetch = true;
+                    if (chainUsesHeaderThreading)
+                        hasItemScopedHeaderThreading = true;
                 }
                 else {
                     hoistedChainLines.push(...chainLines);
                     itemScopedLines.push(...matchLines);
                 }
             }
-            lines.push(...hoistedChainLines, ...itemOpenLines, ...itemScopedLines, ...itemCloseLines, ...ancestorCloseLines, "");
+            lines.push(...hoistedChainLines, ...emitItemLoopLines(itemOpenLines, itemScopedLines, itemCloseLines, itemVar, hasItemScopedFetch && !hasItemScopedHeaderThreading), ...ancestorCloseLines, "");
             continue;
         }
         // Every other chain step (already fully emitted, inline, by the fold
@@ -7616,6 +7755,41 @@ function parseFoldReturnSpec(flowFileContents) {
         return null;
     }
 }
+/**
+ * Parses `browserFallbackGate`/`httpTimeoutMs` out of an object-form
+ * recon-flow.json, mirroring {@link parseFoldReturnSpec}'s null-safe pattern:
+ * a missing file, a legacy bare-array flow, or a malformed declaration all
+ * resolve to an empty spec (today's behavior) rather than aborting
+ * generation over a field that only tightens an opt-in guard.
+ */
+function parseFallbackGateSpec(flowFileContents) {
+    try {
+        const raw = JSON.parse(flowFileContents);
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            return {};
+        const { browserFallbackGate, httpTimeoutMs } = raw;
+        const resolvedGate = (() => {
+            if (browserFallbackGate === false)
+                return false;
+            if (Array.isArray(browserFallbackGate) &&
+                browserFallbackGate.length > 0 &&
+                browserFallbackGate.every((n) => typeof n === "string" && n.length > 0)) {
+                return browserFallbackGate;
+            }
+            return undefined;
+        })();
+        const resolvedTimeout = typeof httpTimeoutMs === "number" && Number.isFinite(httpTimeoutMs) && httpTimeoutMs > 0
+            ? httpTimeoutMs
+            : undefined;
+        return {
+            ...(resolvedGate !== undefined ? { browserFallbackGate: resolvedGate } : {}),
+            ...(resolvedTimeout !== undefined ? { httpTimeoutMs: resolvedTimeout } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 /** The JS `typeof` a `drillParamBindings` entry's `default` must match for
  * its declared `type` — the same "assert the type, then check the default
  * agrees" pattern the rest of {@link parseFoldReturnSpec} uses for its other
@@ -8724,11 +8898,17 @@ function buildNestedSpreadOverride(base, path, leafExpr) {
     return `{ ...${base}, ${keyExpr}: ${nested} }`;
 }
 /**
- * Emits a bounded paging loop for a read-only GraphQL primary operation
- * exposing {@link PaginationSignal}: advances the skip/offset variable by
- * the observed page size on each call, stops once the response's own
- * reported total is reached or `MAX_PAGES` caps it, and merges pages by the
- * detected identity field rather than concatenating blindly.
+ * Emits a bounded paging loop for a read-only primary operation exposing
+ * {@link PaginationSignal}: advances the skip/offset variable by the
+ * observed page size on each call, stops once the response's own reported
+ * total is reached or `MAX_PAGES` caps it, and merges pages by the detected
+ * identity field rather than concatenating blindly.
+ *
+ * The primary operation may be GraphQL (each page issued via `getGql`) or a
+ * plain REST endpoint (each page issued via `httpClient`) — `fetchCall`
+ * selects which, and is the only call-shape-specific piece of the loop; the
+ * skip/PAGE_SIZE/MAX_PAGES bookkeeping, de-dup, and halt guards below are
+ * shared verbatim between both.
  *
  * `foldMergeLines`, when non-empty, threads a resolved single-primary fold
  * plan (see `emitContractTs`'s `singlePrimaryFoldPlans`) additively into the
@@ -8738,9 +8918,14 @@ function buildNestedSpreadOverride(base, path, leafExpr) {
  * mutates its item in place (`Object.assign`), which is visible through
  * `itemsById`'s own stored references — no re-`set` needed.
  */
-function buildPaginatedGqlExecuteHttpBody(opts) {
-    const { pascal, gqlOperationNameExpr, queryConstName, gqlVariablesExpr, signal, foldMergeLines } = opts;
+function buildPaginatedFetchLoopExecuteHttpBody(opts) {
+    const { pascal, gqlVariablesExpr, signal, foldMergeLines, fetchCall, valueConstraints } = opts;
     const { totalPath, arrayPath, containerPath, countKey, skipKey, pageSize, identityField } = signal;
+    const declaredMax = valueConstraints?.[countKey]?.max;
+    const pageSizeDefault = declaredMax ?? pageSize;
+    const pageFetchExpr = (variablesExpr) => fetchCall.kind === "gql"
+        ? `getGql(context.baseUrl)(${fetchCall.gqlOperationNameExpr}, ${fetchCall.queryConstName}, ${variablesExpr})`
+        : `httpClient(\`\${context.baseUrl}${fetchCall.endpointPath}\`, { method: "POST", body: JSON.stringify(${variablesExpr}) })`;
     const countKeyExpr = isValidJsIdentifier(countKey) ? countKey : JSON.stringify(countKey);
     const skipKeyExpr = isValidJsIdentifier(skipKey) ? skipKey : JSON.stringify(skipKey);
     const paginationBase = pathAccessExpr("baseVariables", containerPath);
@@ -8753,32 +8938,55 @@ function buildPaginatedGqlExecuteHttpBody(opts) {
     // `lastPage` is typed as ${pascal}Response (never null): the first page is
     // fetched before the loop starts, so there's nothing left to narrow.
     const withItemsOverrideExpr = buildNestedSpreadOverride("lastPage", arrayPath, "[...itemsById.values()]");
-    // When MAX_PAGES caps the loop before `total` converges, the merged
-    // envelope's own total must say so instead of repeating the API's
-    // original (larger) reported total — otherwise a truncated payload still
-    // claims to be complete.
-    const withTotalOverrideExpr = buildNestedSpreadOverride("withItems", totalPath, `truncated ? itemsById.size : ${pathAccessExpr("withItems", totalPath)}`);
+    // The server's own reported total is left untouched — overwriting it with
+    // the delivered count would make a MAX_PAGES-capped fetch indistinguishable
+    // from a genuinely complete one. `deliveredCount`/`truncated` are added as
+    // siblings on the response so a caller can tell "total=5000, delivered=100,
+    // truncated=true" apart from "total=436, delivered=436, truncated=false".
+    const withTotalOverrideExpr = `{ ...withItems, deliveredCount: itemsById.size, truncated }`;
     return `    const baseVariables = ${gqlVariablesExpr};
-    const PAGE_SIZE = ${pageSize};
+    const PAGE_SIZE = payload.pageSize ?? ${pageSizeDefault};
     // Bounded so a paging bug (a total that never converges) can't loop forever.
     const MAX_PAGES = payload.maxPages ?? 50;
     const itemsById = new Map<string, ${itemTypeExpr}>();
     let skip = 0;
-    const page = await getGql(context.baseUrl)(${gqlOperationNameExpr}, ${queryConstName}, ${variablesForCall});
+    const page = await ${pageFetchExpr(variablesForCall)};
     let lastPage: ${pascal}Response = page;
     let total = ${totalAccessExpr};
-    for (const item of ${arrayAccessExpr}) {
+    const firstPageItems = ${arrayAccessExpr};
+    for (const item of firstPageItems) {
       itemsById.set(String(${identityAccessExpr}), item);
     }
     skip += PAGE_SIZE;
-    for (let pageIndex = 1; pageIndex < MAX_PAGES && itemsById.size < total; pageIndex++) {
-      const page = await getGql(context.baseUrl)(${gqlOperationNameExpr}, ${queryConstName}, ${variablesForCall});
+    // A first page shorter than what was asked for is the same "nothing left"
+    // signal as a short subsequent page — stop before ever entering the loop
+    // instead of issuing a request the server already told us would come
+    // back empty.
+    const firstPageWasShort = firstPageItems.length < PAGE_SIZE;
+    for (
+      let pageIndex = 1;
+      !firstPageWasShort && pageIndex < MAX_PAGES && itemsById.size < total;
+      pageIndex++
+    ) {
+      const page = await ${pageFetchExpr(variablesForCall)};
       lastPage = page;
       total = ${totalAccessExpr};
-      for (const item of ${arrayAccessExpr}) {
+      const sizeBeforePage = itemsById.size;
+      const pageItems = ${arrayAccessExpr};
+      for (const item of pageItems) {
         itemsById.set(String(${identityAccessExpr}), item);
       }
+      // A server-reported total that doesn't exactly match the count of
+      // distinct items actually returned would otherwise drive the loop to
+      // MAX_PAGES worth of wasted empty requests; stop as soon as a page
+      // contributes nothing new.
+      if (itemsById.size === sizeBeforePage) break;
       skip += PAGE_SIZE;
+      // A page shorter than what was asked for is the server's own signal
+      // that nothing is left, whether or not its reported total agrees —
+      // stop here instead of issuing a request the server already told us
+      // would come back empty.
+      if (pageItems.length < PAGE_SIZE) break;
     }
 ${foldMergeLines.length > 0 ? `${foldMergeLines.join("\n")}\n` : ""}    const truncated = itemsById.size < total;
     const withItems = ${withItemsOverrideExpr};
@@ -8826,7 +9034,21 @@ function buildContractChecklist(opts) {
 /** Generates a complete contract.ts source string for a plugin — exported so
  * unit tests can drive the emitter directly without spawning the CLI. */
 function emitContractTs(opts) {
-    const { siteId, displayName, pascal, baseUrl, baseHeaders, minTime, safeRps, hasRateLimitProbeData = false, responseBody, responseBodySamples = [responseBody], gql, gqlQuery, endpointPath, gqlOperationName, gqlVariables, allCaptures = [], auxFiles, multiStepBody, omitExecuteHttp = false, isSubmissionFlow = false, inputBody, hasMultipartStep = false, actionSteps = [], foldReturnSpec = null, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, discoveredStructuredKeys, payloadFieldNames, optionalPayloadFieldNames = new Set(), headerBindings = [], unpopulatedDeclaredVariables = [], } = opts;
+    const { siteId, displayName, pascal, baseUrl, baseHeaders, minTime, safeRps, hasRateLimitProbeData = false, responseBody, responseBodySamples = [responseBody], gql, gqlQuery, endpointPath, gqlOperationName, gqlVariables, allCaptures = [], auxFiles, multiStepBody, omitExecuteHttp = false, isSubmissionFlow = false, inputBody, hasMultipartStep = false, actionSteps = [], foldReturnSpec = null, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, discoveredStructuredKeys, valueConstraints = value_constraints_1.EMPTY_VALUE_CONSTRAINTS, payloadFieldNames, optionalPayloadFieldNames = new Set(), headerBindings = [], unpopulatedDeclaredVariables = [], fallbackGateSpec = {}, } = opts;
+    const { browserFallbackGate, httpTimeoutMs } = fallbackGateSpec;
+    /** Rendered `meta.browserFallbackGate` literal: `false` verbatim, a
+     * list-derived arrow-function predicate matching against `error.name`, or
+     * "" (omitted) when the flow declared no gate — preserving byte-identical
+     * output for every flow that doesn't opt in. */
+    const browserFallbackGateLiteral = browserFallbackGate === false
+        ? "\n    browserFallbackGate: false,"
+        : browserFallbackGate !== undefined
+            ? `\n    browserFallbackGate: (error) => ${JSON.stringify(browserFallbackGate)}.includes(error.name),`
+            : "";
+    /** Rendered `createHttpClient({ ..., defaultTimeoutMs })` fragment — "" when
+     * the flow declared no `httpTimeoutMs`, so the call is byte-identical to
+     * today's when the key is absent. */
+    const defaultTimeoutMsOption = httpTimeoutMs !== undefined ? `, defaultTimeoutMs: ${httpTimeoutMs}` : "";
     // 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
@@ -8915,11 +9137,20 @@ function emitContractTs(opts) {
         : inputBody
             ? `z.object({})`
             : `z.object({\n  query: z.string().min(1),\n})`;
-    // Only the single-endpoint GraphQL read path (a real primary operation, no
+    // Only the single-endpoint 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, `${endpointPath}::${gqlOperationName}`, allCaptures)
+    // already owns its own per-call semantics. A REST primary has no
+    // operationName/query, so it already collapses to the same identity
+    // operationGroupKey falls back to for such a capture
+    // (`${endpointPath}::anonymous`) — this is the same identity
+    // detectPaginationSignal uses to match sibling captures below.
+    const paginationOperationIdentity = gql
+        ? gqlOperationName
+            ? `${endpointPath}::${gqlOperationName}`
+            : null
+        : `${endpointPath}::anonymous`;
+    const paginationSignal = !multiStepBody && paginationOperationIdentity
+        ? detectPaginationSignal(responseBody, gqlVariables, paginationOperationIdentity, allCaptures)
         : null;
     // A resolved drill-down fold plan on the single-primary getGql/httpClient
     // hot path (`multiStepBody` unset — see emitMultiStepExecuteHttp for the
@@ -8929,7 +9160,7 @@ function emitContractTs(opts) {
     // drop the fold feature the flow author declared (see
     // recon-generate-foldreturn-regresses-primary-op-and-payload-to-ats-submission-shape.md).
     // Also threaded additively into `paginationSignal`'s fetch loop below (see
-    // buildPaginatedGqlExecuteHttpBody) — the fold runs against the final
+    // buildPaginatedFetchLoopExecuteHttpBody) — the fold runs against the final
     // assembled/de-duplicated page items, not just the first page's captured
     // sample, so a paginated primary is no longer excluded from folding.
     const singlePrimaryFoldPlans = resolveApplicableFoldPlans(actionSteps, foldReturnSpec, multiStepBody);
@@ -8970,12 +9201,13 @@ function emitContractTs(opts) {
     const addExtendField = (name, line) => {
         extendFields.set(name, line);
     };
-    // A detected bounded-paging signal means buildPaginatedGqlExecuteHttpBody
+    // A detected bounded-paging signal means buildPaginatedFetchLoopExecuteHttpBody
     // 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(),");
+        addExtendField("pageSize", "  pageSize: z.number().int().positive().optional(),");
     }
     // The base extend's own keys — job-application submission flows only.
     if (usesApplicantContactSchema) {
@@ -9084,18 +9316,27 @@ function emitContractTs(opts) {
         ? [...discoveredAdditionalBodyKeys.entries()].sort(([a], [b]) => a.localeCompare(b))
         : [];
     let usesMultipartBoolean = false;
-    for (const [name, kind] of sortedAdditionalKeys) {
+    for (const [name, info] of sortedAdditionalKeys) {
         if (isReservedByApplicantContactSchema(name))
             continue;
         // Use multipartBoolean() for booleans when multipart is in play, so
         // multipart string-encoded "true"/"false" round-trip to native booleans
         // (matches the inputBody boolean handling for parity).
-        const zod = kind === "string"
-            ? "z.string()"
-            : kind === "number"
-                ? payloadNeedsMultipart
-                    ? "z.coerce.number()"
-                    : "z.number()"
+        // A closed-set vocabulary (string) or a discovered capacity ceiling
+        // (number) narrows the caller-facing schema instead of falling through
+        // to the unconstrained default — see {@link AdditionalBodyKeyInfo}.
+        const zod = info.kind === "string"
+            ? info.enumValues
+                ? `z.enum([${info.enumValues.map((v) => JSON.stringify(v)).join(", ")}])`
+                : "z.string()"
+            : info.kind === "number"
+                ? info.capacityMax !== undefined
+                    ? payloadNeedsMultipart
+                        ? `z.coerce.number().max(${info.capacityMax})`
+                        : `z.number().max(${info.capacityMax})`
+                    : payloadNeedsMultipart
+                        ? "z.coerce.number()"
+                        : "z.number()"
                 : payloadNeedsMultipart
                     ? "multipartBoolean()"
                     : "z.boolean()";
@@ -9182,6 +9423,32 @@ function emitContractTs(opts) {
             extendFields.set(fieldName, line.replace(/,\s*$/, ".optional(),"));
         }
     }
+    // A consumer-declared value constraint overrides its matching field's
+    // emitted Zod expression here, at the single merge point every discovery
+    // source above funnels through — see {@link ReconValueConstraints}. A
+    // declared field name with no entry in extendFields never appeared in any
+    // capture this run and is a no-op, not an error: there is no schema line
+    // for it to attach to.
+    for (const [fieldName, constraint] of Object.entries(valueConstraints)) {
+        const line = extendFields.get(fieldName);
+        if (line === null || line === undefined)
+            continue;
+        if (constraint.enumValues === undefined &&
+            constraint.min === undefined &&
+            constraint.max === undefined) {
+            continue;
+        }
+        const key = isValidJsIdentifier(fieldName) ? fieldName : JSON.stringify(fieldName);
+        const zod = constraint.enumValues
+            ? `z.enum([${constraint.enumValues.map((v) => JSON.stringify(v)).join(", ")}])`
+            : [
+                "z.number()",
+                ...(constraint.min !== undefined ? [`.min(${constraint.min})`] : []),
+                ...(constraint.max !== undefined ? [`.max(${constraint.max})`] : []),
+            ].join("");
+        const optional = line.trimEnd().endsWith(".optional(),");
+        extendFields.set(fieldName, `  ${key}: ${zod}${optional ? ".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
@@ -9261,18 +9528,24 @@ ${
             // GraphQL to the primary endpoint.
             needsFoldHttpClient
                 ? `
-const httpClient = createHttpClient({ schema: z.unknown(), bottleneck: limiter, baseHeaders: BASE_HEADERS${bindOptionLiteral(headerBindings)} });
+const httpClient = createHttpClient({ schema: z.unknown(), bottleneck: limiter, baseHeaders: BASE_HEADERS${bindOptionLiteral(headerBindings)}${defaultTimeoutMsOption} });
 `
                 : ""}`
             : `
-const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottleneck: limiter, baseHeaders: BASE_HEADERS${bindOptionLiteral(headerBindings)} });
+const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottleneck: limiter, baseHeaders: BASE_HEADERS${bindOptionLiteral(headerBindings)}${defaultTimeoutMsOption} });
 `;
     const gqlOperationNameExpr = gqlOperationName
         ? JSON.stringify(gqlOperationName)
         : JSON.stringify(`${pascal}Search`);
+    // A REST primary with a detected paging signal renders `baseVariables` from
+    // the same captured request-variables object the signal was itself
+    // detected from (see paginationOperationIdentity above) — the default
+    // `{ q: payload.query }` REST body has no skip/count container to advance.
     const gqlVariablesExpr = gqlOperationName
         ? renderGqlVariablesExpr(gqlVariables, payloadFieldNames, optionalPayloadFieldNames)
-        : "{ q: payload.query }";
+        : paginationSignal
+            ? renderGqlVariablesExpr(gqlVariables, payloadFieldNames, optionalPayloadFieldNames)
+            : "{ q: payload.query }";
     /** Builds the nested `for` loop block(s) — see {@link pathToFoldLoopLines}
      * — that fold every resolved plan's drill-down data onto `dataVarName`'s
      * primary array — the single-primary counterpart of
@@ -9338,6 +9611,14 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
             // Every target's join/merge — plus any non-hoistable target's own
             // chain fetch — goes here, spliced inside the item loop.
             const itemScopedLines = [];
+            // True once any target's own chain fetch ends up item-scoped — see
+            // emitMultiStepExecuteHttp's identical flag and emitItemLoopLines.
+            let hasItemScopedFetch = false;
+            // True once any item-scoped target's chain threads a response header
+            // through createHttpClient's shared `bind` store — see
+            // emitMultiStepExecuteHttp's identical flag for why that disqualifies
+            // parallelizing the item loop.
+            let hasItemScopedHeaderThreading = false;
             // Word-boundary match — see emitMultiStepExecuteHttp's identical
             // `itemVarRefPattern` for why an anchored `${itemVar` pattern misses a
             // nested field path's `${(itemVar.field as Record<string,
@@ -9485,10 +9766,20 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
                 // treated as item-scoped too — flat folds must keep emitting
                 // byte-identical code.
                 let referencesItemVar = ancestorVars.length === 0;
+                // See emitMultiStepExecuteHttp's identical `chainUsesHeaderThreading`
+                // for why any header-kind produce disqualifies parallelizing the
+                // item loop — httpClient's shared `bind` store applies to every call
+                // this function's own chainLines make too, even though (unlike
+                // emitMultiStepExecuteHttp) this codegen path never renders a local
+                // variable for the produced header itself.
+                let chainUsesHeaderThreading = false;
                 for (const chainIndex of target.chain) {
                     const chainStep = actionSteps[chainIndex];
                     if (!chainStep)
                         continue;
+                    if (chainStep.produces.some((p) => p.kind === "header")) {
+                        chainUsesHeaderThreading = true;
+                    }
                     // The zero-variance guard lives inside `parameterizeUrl` itself
                     // (see above) so it can skip only the threaded-value splice while
                     // still letting a spec-declared drillParamBindings substitution
@@ -9510,13 +9801,17 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
                 const matchLines = emitFoldMatchAndMergeLines(terminalStep, target, itemVar, suffix, joinAccessor);
                 if (referencesItemVar) {
                     itemScopedLines.push(...chainLines, ...matchLines);
+                    if (chainLines.length > 0)
+                        hasItemScopedFetch = true;
+                    if (chainUsesHeaderThreading)
+                        hasItemScopedHeaderThreading = true;
                 }
                 else {
                     hoistedChainLines.push(...chainLines);
                     itemScopedLines.push(...matchLines);
                 }
             }
-            lines.push(...hoistedChainLines, ...itemOpenLines, ...itemScopedLines, ...itemCloseLines, ...ancestorCloseLines, "");
+            lines.push(...hoistedChainLines, ...emitItemLoopLines(itemOpenLines, itemScopedLines, itemCloseLines, itemVar, hasItemScopedFetch && !hasItemScopedHeaderThreading), ...ancestorCloseLines, "");
         }
         return lines;
     };
@@ -9535,13 +9830,19 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
     const executeHttpBody = multiStepBody
         ? multiStepBody
         : paginationSignal
-            ? buildPaginatedGqlExecuteHttpBody({
+            ? buildPaginatedFetchLoopExecuteHttpBody({
                 pascal,
-                gqlOperationNameExpr,
-                queryConstName: `${pascal.toUpperCase()}_QUERY`,
                 gqlVariablesExpr,
                 signal: paginationSignal,
                 foldMergeLines: paginatedFoldMergeLines,
+                valueConstraints,
+                fetchCall: gql
+                    ? {
+                        kind: "gql",
+                        gqlOperationNameExpr,
+                        queryConstName: `${pascal.toUpperCase()}_QUERY`,
+                    }
+                    : { kind: "rest", endpointPath },
             })
             : gql
                 ? `    const data = await getGql(context.baseUrl)(${gqlOperationNameExpr}, ${pascal.toUpperCase()}_QUERY, ${gqlVariablesExpr});
@@ -9658,7 +9959,7 @@ export const ${camel}Plugin: SitePlugin<${pascal}Payload, ${pascal}Response> = {
     // since the multipart wire format is what makes that field's
     // JSON-stringified encoding parseable.
     `
-        : ""}apiVersion: ${JSON.stringify(plugin_api_version_1.PLUGIN_API_VERSION)},${payloadNeedsMultipart || usesApplicantContactSchema || hasMultipartStep ? "\n    multipart: true," : ""}
+        : ""}apiVersion: ${JSON.stringify(plugin_api_version_1.PLUGIN_API_VERSION)},${payloadNeedsMultipart || usesApplicantContactSchema || hasMultipartStep ? "\n    multipart: true," : ""}${browserFallbackGateLiteral}
   },
 ${executeHttpMethodBlock}
   /** Browser fallback: Stagehand + Steel — invoked only when hot path fails. */
@@ -10198,6 +10499,21 @@ async function resolveFormSchema(specifier) {
     logger.info(`form-schema: ${specifier === load_form_schema_1.FORM_SCHEMA_NONE ? "none (no ATS form recovery)" : `custom keys from ${specifier}`}`);
     return formSchema;
 }
+/**
+ * Resolves the consumer-declared value constraints for this run.
+ *
+ * Absent `--value-constraints`, no override happens: every field's emitted
+ * Zod expression stays whatever its discovery mechanism (Phase E/F options,
+ * form-schema fields, structured keys) already inferred — the same "absence
+ * means none" discipline `--vocabulary`/`--form-schema` use.
+ */
+async function resolveValueConstraints(specifier) {
+    if (!specifier)
+        return value_constraints_1.EMPTY_VALUE_CONSTRAINTS;
+    const valueConstraints = await (0, load_value_constraints_1.loadReconValueConstraints)(specifier, process.cwd());
+    logger.info(`value-constraints: ${specifier === load_value_constraints_1.VALUE_CONSTRAINTS_NONE ? "none (no field overrides)" : `custom constraints from ${specifier}`}`);
+    return valueConstraints;
+}
 /**
  * The capture whose own response `assertRequiredUrlFieldsReferenced`'s
  * scan actually describes: a submission flow returns
@@ -10362,6 +10678,7 @@ async function main() {
     let emit = "ts";
     let vocabularySpecifier = "";
     let formSchemaSpecifier = "";
+    let valueConstraintsSpecifier = "";
     let runDir;
     let allowEmptyCapture = false;
     for (let i = 0; i < args.length; i++) {
@@ -10371,6 +10688,8 @@ async function main() {
             vocabularySpecifier = args[++i];
         else if (args[i] === "--form-schema" && args[i + 1])
             formSchemaSpecifier = args[++i];
+        else if (args[i] === "--value-constraints" && args[i + 1])
+            valueConstraintsSpecifier = args[++i];
         else if (args[i] === "--run-dir" && args[i + 1])
             runDir = args[++i];
         else if (args[i] === "--force")
@@ -10440,7 +10759,7 @@ async function main() {
             return [];
         }
     })();
-    const { flowSteps, frameSelector, submitEndpointPattern, submitBodyPattern, requireSubmitEndpointMatch, displayName, foldReturnSpec, } = (() => {
+    const { flowSteps, frameSelector, submitEndpointPattern, submitBodyPattern, requireSubmitEndpointMatch, displayName, foldReturnSpec, fallbackGateSpec, } = (() => {
         const flowFileContents = (() => {
             try {
                 return (0, node_fs_1.readFileSync)(flowFile, "utf8");
@@ -10453,6 +10772,10 @@ async function main() {
         // 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);
+        // Same independence rule as `foldReturnSpec` above: an empty spec
+        // (missing/malformed declaration) is indistinguishable from "not
+        // declared" and preserves today's byte-identical output.
+        const fallbackGateSpec = flowFileContents === null ? {} : parseFallbackGateSpec(flowFileContents);
         try {
             const raw = flowFileContents === null ? null : JSON.parse(flowFileContents);
             if (Array.isArray(raw))
@@ -10464,6 +10787,7 @@ async function main() {
                     requireSubmitEndpointMatch: false,
                     displayName: undefined,
                     foldReturnSpec,
+                    fallbackGateSpec,
                 };
             if (raw !== null &&
                 typeof raw === "object" &&
@@ -10478,6 +10802,7 @@ async function main() {
                     requireSubmitEndpointMatch: obj.requireSubmitEndpointMatch ?? false,
                     displayName: obj.displayName,
                     foldReturnSpec,
+                    fallbackGateSpec,
                 };
             }
             return {
@@ -10488,6 +10813,7 @@ async function main() {
                 requireSubmitEndpointMatch: false,
                 displayName: undefined,
                 foldReturnSpec,
+                fallbackGateSpec,
             };
         }
         catch {
@@ -10499,6 +10825,7 @@ async function main() {
                 requireSubmitEndpointMatch: false,
                 displayName: undefined,
                 foldReturnSpec,
+                fallbackGateSpec,
             };
         }
     })();
@@ -10516,6 +10843,10 @@ async function main() {
     // Consumer-supplied wire keys for ATS form-schema recovery, or null. When
     // null the recovery functions no-op — the engine hardcodes no vendor format.
     const formSchema = await resolveFormSchema(formSchemaSpecifier);
+    // Consumer-declared domain facts (enum/min/max) that no captured response
+    // leaf exposes a shape for, or EMPTY_VALUE_CONSTRAINTS when absent — see
+    // {@link ReconValueConstraints}.
+    const valueConstraints = await resolveValueConstraints(valueConstraintsSpecifier);
     const pascal = toPascalCase(siteId);
     // Read the flow's declared own-backend hosts BEFORE deriving baseUrl, so
     // deriveBaseUrl itself can gate on them: a third-party host that happens
@@ -10937,7 +11268,12 @@ async function main() {
                     parsedOperationName(primaryGraphQLOperation.capture.query ?? ""))
                 : (fallbackGraphQLCapture?.operationName ??
                     parsedOperationName(fallbackGraphQLCapture?.query ?? "")),
-            gqlVariables: primaryGraphQLOperation?.capture.variables ?? null,
+            // For a REST primary (no primaryGraphQLOperation), the winning
+            // capture's own `variables`/`decodedParams` is the REST equivalent of
+            // a GraphQL operation's captured variables — the object
+            // detectPaginationSignal walks to find a skip/count container.
+            gqlVariables: primaryGraphQLOperation?.capture.variables ??
+                (!gql ? (winningCapture?.variables ?? winningCapture?.decodedParams ?? null) : null),
             allCaptures: activeCaptures,
             auxFiles,
             multiStepBody,
@@ -10953,10 +11289,12 @@ async function main() {
             discoveredRawOptionFields,
             discoveredAdditionalBodyKeys,
             discoveredStructuredKeys,
+            valueConstraints,
             payloadFieldNames: browserFlow.payloadFieldNames,
             optionalPayloadFieldNames: browserFlow.optionalPayloadFieldNames,
             headerBindings,
             unpopulatedDeclaredVariables: primaryGraphQLOperation?.unpopulatedDeclaredVariables ?? [],
+            fallbackGateSpec,
         };
         const contractCode = emitContractTs(contractOpts);
         return {