@enricai/barnacle 1.0.0

package/dist/scripts/recon-generate.js

@@ -0,0 +1,2572 @@
+"use strict";
+/**
+ * Phase 4f: reads recon artifacts and generates a complete plugin skeleton —
+ * contract.ts, flows/browser-flow.ts, index.ts, and fixtures/ — so no manual
+ * coding is required between running recon and registering the plugin.
+ *
+ * Usage:
+ *   pnpm run recon:generate -- --site-id my-site [--force]
+ *
+ * --force overwrites an existing src/sites/<siteId>/ directory.
+ *
+ * Reads from:
+ *   /tmp/recon/graphql/*.json        — Capture[] from recon-browser.ts
+ *   /tmp/recon/replays/*.json        — ReplayResult[] from recon-http.ts
+ *   /tmp/recon/replays/rate-limit.json
+ *   /tmp/recon/aux/*.json            — static fixture files
+ *   src/sites/<siteId>/recon-flow.json — plain-English flow steps
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStepPayloadField = resolveStepPayloadField;
+exports.emitMultiStepExecuteHttp = emitMultiStepExecuteHttp;
+exports.emitContractTs = emitContractTs;
+exports.emitConfigManifest = emitConfigManifest;
+exports.emitBrowserFlowTs = emitBrowserFlowTs;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const errors_1 = require("../lib/errors");
+const logging_1 = require("../lib/logging");
+const plugin_manifest_envelope_1 = require("../plugins/plugin-manifest-envelope");
+const recon_shared_1 = require("../scripts/recon-shared");
+const logger = (0, logging_1.getScriptLogger)("recon-generate");
+// ── helpers ──────────────────────────────────────────────────────────────────
+function toPascalCase(siteId) {
+    return siteId
+        .split(/[-_]/)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join("");
+}
+/**
+ * Instruction labels that name a NON-candidate field — a reference-contact, an
+ * employment-history row, the applicant's signature, etc. When any of these
+ * matches we leave the step literal so the generator never splices the primary
+ * applicant's PII into a field that must hold someone/something else. Matched
+ * against the English label in the instruction, never the recon constant value.
+ */
+const PAYLOAD_FIELD_EXCLUSIONS = [
+    /reference\s*#?\s*\d/i,
+    /employment history/i,
+    /\bcompany (name|phone)\b/i,
+    /\bemployer\b/i,
+    /signature/i,
+    /\bfull name\b/i,
+    /today'?s date/i,
+    /school|institution|degree|major|education/i,
+    // Screening-question shapes: "For '<question>' select '<answer>'" and any
+    // step framed around a 'question'. Here the first quoted string is the
+    // question label, not a candidate value — a label word inside the question
+    // (e.g. "...licensed in this state?") must NOT trigger a splice that would
+    // overwrite the question quote. Candidate-fill steps say "fill in the X
+    // field with '...'" / "Select '...' from the X dropdown" instead.
+    /^\s*for\s+'/i,
+    /\bquestion\b/i,
+];
+/**
+ * Ordered candidate-field label table. Each entry maps an English-label regex
+ * to the PascalCase payload field the generator should splice. Order matters:
+ * the first matching row wins, so more-specific labels precede broader ones.
+ */
+const PAYLOAD_FIELD_TABLE = [
+    [/\bfirst name\b/i, "FirstName"],
+    [/\blast name\b/i, "LastName"],
+    [/\b(e-?mail|email address)\b/i, "Email"],
+    [/\b(mobile phone|primary phone|phone number|mobile)\b/i, "MobilePhone"],
+    [/\b(street address|address line 1)\b/i, "AddressLine1"],
+    [/\bcity\b/i, "City"],
+    [/\b(state|province|state\/region)\b/i, "State"],
+    [/\b(zip|postal)\b/i, "PostalCode"],
+    [/\bcountry\b/i, "Country"],
+];
+/**
+ * Decide whether a flow step should splice a runtime `payload.<field>` value in
+ * place of the frozen recon constant baked into its instruction. Exists so
+ * generated browser-flows use the caller's real applicant identity instead of
+ * recon's captured identity, while operational-default steps (decline self-ID,
+ * legal yes/no answers) stay literal. Matching on the English LABEL — not the
+ * drifting constant value — keeps the decision stable when recon re-captures
+ * with a different identity.
+ *
+ * @param instruction the flow step's plain-English instruction
+ * @param explicit an optional flow-authored `payloadField` override (wins outright)
+ * @param forceNone when true, force a literal step (the `payloadFieldNone` opt-out)
+ * @returns the PascalCase payload field name to splice, or null to keep literal
+ */
+function resolveStepPayloadField(instruction, explicit, forceNone) {
+    if (forceNone)
+        return null;
+    if (explicit)
+        return explicit;
+    // Nothing to splice unless the instruction actually carries a recon constant:
+    // a quoted literal, the ${RECON_EMAIL} token, or a dropdown/select phrasing.
+    const hasSpliceable = /'[^']*'/.test(instruction) ||
+        /\$\{RECON_EMAIL\}/.test(instruction) ||
+        /\bdropdown\b/i.test(instruction) ||
+        /\bselect\b[^.]*\bfrom\b/i.test(instruction);
+    if (!hasSpliceable)
+        return null;
+    if (PAYLOAD_FIELD_EXCLUSIONS.some((rx) => rx.test(instruction)))
+        return null;
+    // "Secondary Phone Number" must not fill the primary MobilePhone field.
+    if (/\bsecondary\b/i.test(instruction) && /\bphone\b/i.test(instruction))
+        return null;
+    for (const [rx, field] of PAYLOAD_FIELD_TABLE) {
+        if (rx.test(instruction))
+            return field;
+    }
+    return null;
+}
+/**
+ * Recursively infers a Zod schema expression string from a JSON value.
+ * Caps recursion at 4 levels to avoid generating unwieldy output for deeply
+ * nested API responses — deeper fields collapse to z.unknown().
+ */
+function inferZodSchema(value, depth = 0, indent = "", opts = {}) {
+    if (depth > 4)
+        return "z.unknown()";
+    if (value === null)
+        return "z.null()";
+    if (typeof value === "string")
+        return "z.string()";
+    if (typeof value === "number")
+        return opts.multipartCoerce ? "z.coerce.number()" : "z.number()";
+    if (typeof value === "boolean") {
+        // multipart/form-data encodes booleans as "true"/"false". The contract
+        // emitter imports the shared multipartBoolean() helper from @/lib/zod-multipart
+        // when any field needs this coercion; we call it here to keep field declarations short.
+        return opts.multipartCoerce ? "multipartBoolean()" : "z.boolean()";
+    }
+    if (Array.isArray(value)) {
+        const item = value.length > 0 ? inferZodSchema(value[0], depth + 1, indent, opts) : "z.unknown()";
+        return `z.array(${item})`;
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value);
+        if (entries.length === 0)
+            return "z.record(z.string(), z.unknown())";
+        const inner = `${indent}  `;
+        // Emit identifier-shaped keys unquoted so Biome's formatter doesn't rewrite
+        // the generated file on first lint:fix.
+        const fields = entries
+            .map(([k, v]) => `${inner}${isValidJsIdentifier(k) ? k : JSON.stringify(k)}: ${inferZodSchema(v, depth + 1, inner, opts)}`)
+            .join(",\n");
+        return `z.object({\n${fields},\n${indent}})`;
+    }
+    return "z.unknown()";
+}
+function deriveMinTime(rateLimits) {
+    const first = rateLimits.find((f) => f.safeRps !== null);
+    return first?.safeRps ? Math.floor(1000 / first.safeRps) : 200;
+}
+function deriveBaseUrl(captures) {
+    for (const c of captures) {
+        try {
+            const u = new URL(c.url);
+            return `${u.protocol}//${u.host}`;
+        }
+        catch {
+            // try next
+        }
+    }
+    return "https://example.com";
+}
+const IGNORE_REQUEST_HEADERS = new Set([
+    "host",
+    "content-length",
+    "connection",
+    "accept-encoding",
+    "cookie",
+    ":method",
+    ":path",
+    ":authority",
+    ":scheme",
+]);
+/**
+ * Derives BASE_HEADERS from the request headers the browser actually sent
+ * during recon, filtered to those present in every capture whose endpoint
+ * replayed successfully. Always includes the standard Content-Type / Accept /
+ * Origin / Referer / User-Agent baseline regardless of presence count.
+ *
+ * Fallback: when no replays succeeded (typical for auth-gated multi-step
+ * flows where every request after `/user/create` requires a token the
+ * stateless replay phase can't thread), derive headers from the meaningful
+ * action POSTs instead — same `extractActionSequence` definition used by
+ * the submission-flow detector. This catches load-bearing site-specific
+ * headers (Workday's `X-CSRF-Token`, Greenhouse's `Job-Boards-API-Token`,
+ * ClearCompany's `API-ShortName`, etc.) without the generator needing to
+ * know about any particular site.
+ */
+function deriveRequestHeaders(captures, replays, baseUrl) {
+    const successfulUrls = new Set(replays
+        .filter((r) => r.success)
+        .map((r) => {
+        try {
+            const u = new URL(r.url);
+            return `${u.origin}${u.pathname}`;
+        }
+        catch {
+            return r.url;
+        }
+    }));
+    // Prefer ACTION captures (non-GET 2xx to baseUrl host, non-telemetry) as
+    // the authoritative header source. Replay-matched static-asset GETs lack
+    // the API-specific headers that REST endpoints require, so falling back
+    // to those produces a degenerate baseline-only header set. When action
+    // captures exist (multi-step submission flows), use them. For sites
+    // where the flow is a single REST call (no detectable action sequence),
+    // fall back to the replay-matched captures.
+    const actionCaptures = extractActionSequence(captures, baseUrl).map((a) => a.capture);
+    const replayMatchedCaptures = captures.filter((c) => {
+        try {
+            const u = new URL(c.url);
+            return successfulUrls.has(`${u.origin}${u.pathname}`);
+        }
+        catch {
+            return false;
+        }
+    });
+    const relevantCaptures = actionCaptures.length > 0 ? actionCaptures : replayMatchedCaptures;
+    const counts = new Map();
+    for (const c of relevantCaptures) {
+        for (const header of Object.keys(c.requestHeaders)) {
+            const lower = header.toLowerCase();
+            if (IGNORE_REQUEST_HEADERS.has(lower))
+                continue;
+            counts.set(lower, (counts.get(lower) ?? 0) + 1);
+        }
+    }
+    const baseline = {
+        "Content-Type": "application/json",
+        Accept: "application/json, */*",
+        Origin: baseUrl,
+        Referer: `${baseUrl}/`,
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    };
+    // Add any request header present in all relevant captures, preserving original casing.
+    for (const [lower, count] of counts) {
+        if (count < relevantCaptures.length)
+            continue;
+        if (Object.keys(baseline).some((k) => k.toLowerCase() === lower))
+            continue;
+        for (const c of relevantCaptures) {
+            const original = Object.keys(c.requestHeaders).find((h) => h.toLowerCase() === lower);
+            if (original) {
+                baseline[original] = c.requestHeaders[original];
+                break;
+            }
+        }
+    }
+    return baseline;
+}
+function isGraphQL(captures) {
+    return captures.some((c) => c.operationName !== null);
+}
+function firstSuccessfulReplayBody(replays) {
+    return replays.find((r) => r.success)?.replayBody ?? null;
+}
+function firstGraphQLQuery(captures) {
+    return captures.find((c) => c.query)?.query ?? null;
+}
+function firstEndpointPath(captures) {
+    for (const c of captures) {
+        try {
+            const u = new URL(c.url);
+            return u.pathname;
+        }
+        catch {
+            // skip
+        }
+    }
+    return "/api/search";
+}
+// ── multi-step "submission flow" detection ────────────────────────────────────
+//
+// For transactional sites (apply forms, multi-step checkout, etc.) the captures
+// form an ordered sequence of POSTs that thread state values through subsequent
+// requests (auth tokens, candidate IDs, application IDs). Single-endpoint
+// sites (job search, pricing APIs) have one action capture and skip this path.
+/** Path elements we always treat as noise (analytics, logging). */
+const TELEMETRY_URL_PATTERNS = [
+    "/util/logging/vweb/message",
+    "/blank/page",
+    "stats.g.doubleclick.net",
+    "google-analytics.com",
+    "click.appcast.io",
+];
+/**
+ * Extracts the ordered sequence of meaningful POSTs that represent the
+ * transactional flow. Filters out GETs, telemetry, asset hits, and non-2xx.
+ */
+function extractActionSequence(captures, baseUrl) {
+    let host;
+    try {
+        host = new URL(baseUrl).host;
+    }
+    catch {
+        host = "";
+    }
+    return captures
+        .map((capture, index) => ({ capture, index }))
+        .filter(({ capture }) => {
+        if (capture.method === "GET")
+            return false;
+        if (capture.status < 200 || capture.status >= 300)
+            return false;
+        let captureHost;
+        try {
+            captureHost = new URL(capture.url).host;
+        }
+        catch {
+            return false;
+        }
+        if (captureHost !== host)
+            return false;
+        if (TELEMETRY_URL_PATTERNS.some((p) => capture.url.includes(p)))
+            return false;
+        return true;
+    });
+}
+/**
+ * Collapses redundant PATCH calls to the same endpoint path, keeping only the
+ * last occurrence. SPA auto-save patterns produce one PATCH per field change,
+ * but the API accepts a single full-state PATCH. Reduces the generated hot
+ * path from dozens of calls to the essential sequence.
+ */
+function collapseRedundantPatches(actions) {
+    const lastPatchByPath = new Map();
+    for (let i = 0; i < actions.length; i++) {
+        const a = actions[i];
+        if (a.capture.method === "PATCH") {
+            const path = a.capture.url.split("?")[0] ?? a.capture.url;
+            lastPatchByPath.set(path, i);
+        }
+    }
+    return actions.filter((a, i) => {
+        if (a.capture.method !== "PATCH")
+            return true;
+        const path = a.capture.url.split("?")[0] ?? a.capture.url;
+        return lastPatchByPath.get(path) === i;
+    });
+}
+/**
+ * Recursively walks a JSON value and yields every string leaf, paired with its
+ * JSON path. Numbers/booleans/nulls are skipped — only string leaves are
+ * candidates for state values (auth tokens, UUIDs, IDs).
+ */
+function* walkStringLeaves(value, path = []) {
+    if (typeof value === "string") {
+        yield { value, path };
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            yield* walkStringLeaves(value[i], [...path, String(i)]);
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            yield* walkStringLeaves(v, [...path, k]);
+        }
+    }
+}
+/**
+ * Yields every primitive leaf (string, number, boolean, null) in the JSON
+ * value with its path. Used by the body-literal substitution pass to find
+ * JSON-keyed values whose key matches a payload field name — for example,
+ * `"FutureConsideration":true` becomes `"FutureConsideration":${payload.FutureConsideration}`.
+ * Unlike walkStringLeaves this includes non-string primitives, so boolean
+ * and number payload fields get parameterized too.
+ */
+function* walkAllPrimitiveLeaves(value, path = []) {
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        value === null) {
+        yield { value, path };
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            yield* walkAllPrimitiveLeaves(value[i], [...path, String(i)]);
+        }
+        return;
+    }
+    if (typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            yield* walkAllPrimitiveLeaves(v, [...path, k]);
+        }
+    }
+}
+/** Minimum length for a string leaf to be indexed as a potential state value.
+ * Shorter strings (1-7 chars) are rarely meaningful auth tokens / IDs and
+ * inflate the index without contributing to state threading. */
+const MIN_STATE_VALUE_LENGTH = 8;
+/**
+ * Documented enum of common HTTP-API error-reporting key names. Closed set
+ * (per the no-regex-open-sets feedback): when an API returns 200 with an
+ * error payload, it almost always uses one of these key names at the top of
+ * the body. Matched case-insensitively so `Message`/`message`/`Error`/`error`
+ * all detect.
+ */
+const KNOWN_TOP_LEVEL_ERROR_KEYS = new Set(["message", "error", "errormessage"]);
+/**
+ * Suffixes that mark a JSON key as carrying validation/data errors when its
+ * value is non-null. Case-sensitive because real APIs use mixed-case in the
+ * exact form they ship (e.g. ClearCompany's `ResponseValidationErrors`).
+ */
+const NESTED_ERROR_KEY_SUFFIXES = ["ValidationErrors", "DataErrors", "ValidationError"];
+/**
+ * Detects which error-reporting key names this site's recon uses. Scans
+ * successful action-step response bodies for the well-known key shapes; only
+ * emits guards for keys that NEVER appear as non-null values in success
+ * responses (so legitimate success-only fields like `Name` aren't false-
+ * flagged as errors).
+ *
+ * Site-agnostic: ClearCompany uses `Message`/`Sections.ResponseValidationErrors`
+ * /`Sections.DataValidationErrors`; a different ATS using `error`/`errors[]`
+ * would emit guards for those instead.
+ */
+function detectErrorSignals(actions) {
+    const candidateTopLevelKeys = new Map();
+    const candidateNestedPaths = new Map();
+    for (const step of actions) {
+        const body = step.capture.responseBody;
+        if (body === null || typeof body !== "object" || Array.isArray(body))
+            continue;
+        for (const [k, v] of Object.entries(body)) {
+            if (KNOWN_TOP_LEVEL_ERROR_KEYS.has(k.toLowerCase())) {
+                const existing = candidateTopLevelKeys.get(k) ?? { presentInSuccess: false };
+                if (typeof v === "string" && v.length > 0)
+                    existing.presentInSuccess = true;
+                candidateTopLevelKeys.set(k, existing);
+            }
+        }
+        walkForNestedErrorKeys(body, [], candidateNestedPaths);
+    }
+    const successKeys = new Set();
+    for (const [k, info] of candidateTopLevelKeys) {
+        if (info.presentInSuccess)
+            successKeys.add(k);
+    }
+    const stringMessageKey = [...candidateTopLevelKeys.keys()].find((k) => !successKeys.has(k)) ?? null;
+    const nestedErrorPaths = [];
+    for (const info of candidateNestedPaths.values()) {
+        if (!info.presentInSuccess) {
+            nestedErrorPaths.push({ parentPath: info.parentPath, errorKey: info.errorKey });
+        }
+    }
+    return { stringMessageKey, nestedErrorPaths };
+}
+function walkForNestedErrorKeys(value, path, candidates) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return;
+    for (const [k, v] of Object.entries(value)) {
+        if (NESTED_ERROR_KEY_SUFFIXES.some((suffix) => k.endsWith(suffix))) {
+            const dedupeKey = `${path.join(".")}::${k}`;
+            const existing = candidates.get(dedupeKey) ?? {
+                parentPath: path,
+                errorKey: k,
+                presentInSuccess: false,
+            };
+            if (v !== null)
+                existing.presentInSuccess = true;
+            candidates.set(dedupeKey, existing);
+        }
+        walkForNestedErrorKeys(v, [...path, k], candidates);
+    }
+}
+/**
+ * Canonical UUID-shape test. Closed-form regex per the no-regex-open-sets
+ * feedback: matches the dash-delimited 8-4-4-4-12 hex format universally used
+ * by Microsoft/RFC4122 UUIDs. Used to distinguish schema identifiers (UUIDs
+ * that the API uses as stable structural keys) from semantic strings.
+ */
+const UUID_REGEX = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+/**
+ * Converts a FieldSourceCode like "contact.first.name" or "address.country.subdivision"
+ * to PascalCase: "ContactFirstName", "AddressCountrySubdivision". Site-agnostic:
+ * operates only on the input string. Returns null for inputs that don't
+ * produce a valid JS identifier.
+ */
+function sourceCodeToPascalCase(sourceCode) {
+    const parts = sourceCode.split(/[.\-_\s]+/).filter((p) => p.length > 0);
+    if (parts.length === 0)
+        return null;
+    const pascal = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase()).join("");
+    return isValidJsIdentifier(pascal) ? pascal : null;
+}
+/**
+ * Converts a free-form FieldName like "Reference #1 First Name" or "Email" to
+ * PascalCase, stripping punctuation in a way that preserves position (so
+ * "Reference #1 First Name" → "Reference1FirstName" via a section-heading
+ * prefix). Site-agnostic: operates only on input strings.
+ */
+/**
+ * Converts an HTTP header name (e.g. `API-ShortName`, `X-CSRF-Token`) into a
+ * PascalCase JS identifier suitable for a payload field name. Preserves
+ * internal casing of each header-name part (so `ShortName` stays `ShortName`)
+ * while normalizing UPPER-only parts (`API` → `Api`). Site-agnostic.
+ */
+function headerNameToPayloadFieldName(headerName) {
+    return headerName
+        .split(/[^a-zA-Z0-9]+/)
+        .filter((p) => p.length > 0)
+        .map((p) => {
+        const isAllUpper = p === p.toUpperCase();
+        return isAllUpper
+            ? p.charAt(0).toUpperCase() + p.slice(1).toLowerCase()
+            : p.charAt(0).toUpperCase() + p.slice(1);
+    })
+        .join("");
+}
+function fieldNameToPascalCase(fieldName, prefix) {
+    const cleaned = fieldName.replace(/[^a-zA-Z0-9\s]/g, " ").trim();
+    if (cleaned === "")
+        return null;
+    const parts = cleaned.split(/\s+/).filter((p) => p.length > 0);
+    if (parts.length === 0)
+        return null;
+    const pascal = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase()).join("");
+    const withPrefix = prefix ? `${prefix}${pascal}` : pascal;
+    return isValidJsIdentifier(withPrefix) ? withPrefix : null;
+}
+/**
+ * Recon-driven detection of form-schema captures. Scans all response bodies
+ * for arrays whose objects look like SectionField (UUID-shaped FieldId plus
+ * FieldName or FieldSourceCode). Builds FieldId → PascalCase name map.
+ *
+ * Site-agnostic: identifies form-schema captures by structural fingerprint,
+ * not by URL or site name. Any ATS exposing a similar schema would match.
+ */
+function detectFormSchemaFieldNames(captures) {
+    const fieldNameMap = new Map();
+    const fieldOptionsMap = new Map();
+    const allSchemaUuids = new Set();
+    for (const capture of captures) {
+        walkForSectionFieldsArrays(capture.responseBody, fieldNameMap, fieldOptionsMap);
+        walkForSchemaUuids(capture.responseBody, allSchemaUuids);
+    }
+    return { fieldNameMap, fieldOptionsMap, allSchemaUuids };
+}
+/**
+ * Walks a response body collecting every UUID-shaped string that appears at
+ * a `FieldId` or `OptionId` (and its lowercase variants) path leaf, OR as the
+ * `Id` of an object that has `OptionSourceCode`/`StringKey`/`FieldOptions`
+ * sibling — i.e. an OptionId in the form schema. These UUIDs are stable
+ * schema anchors that must be shielded from state-threading even when
+ * detectFormSchemaFieldNames doesn't emit a payload-mappable name for the
+ * field (e.g. when the field's FieldName is too long for our naming heuristic).
+ */
+function walkForSchemaUuids(value, out) {
+    if (value === null || typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walkForSchemaUuids(item, out);
+        return;
+    }
+    const obj = value;
+    const fieldIdRaw = obj.FieldId;
+    if (typeof fieldIdRaw === "string" && UUID_REGEX.test(fieldIdRaw)) {
+        out.add(fieldIdRaw);
+    }
+    const optionsRaw = obj.FieldOptions;
+    if (Array.isArray(optionsRaw)) {
+        for (const opt of optionsRaw) {
+            if (opt !== null && typeof opt === "object") {
+                const optId = opt.Id;
+                if (typeof optId === "string" && UUID_REGEX.test(optId))
+                    out.add(optId);
+            }
+        }
+    }
+    // Recurse into nested objects/arrays so nested SectionFields get walked too.
+    for (const v of Object.values(obj))
+        walkForSchemaUuids(v, out);
+}
+/**
+ * Closed enum of well-known cache-buster query parameter names. Stripped
+ * from the schema-fetch URL template so the runtime emit doesn't carry the
+ * recon's stale timestamp. Per the no-regex-open-sets feedback this is a
+ * small enumerated set.
+ */
+const CACHE_BUSTER_QUERY_KEYS = new Set(["_", "cb", "t", "_t", "nocache"]);
+function stripCacheBusterParams(url) {
+    try {
+        const u = new URL(url);
+        for (const key of CACHE_BUSTER_QUERY_KEYS) {
+            u.searchParams.delete(key);
+        }
+        return u.toString();
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Recon-driven detection of the form-schema fetch capture. Returns the first
+ * GET capture (in recon order) whose response body contains a SectionFields-
+ * shaped array. Sites without such a capture get `null` and Phase B/C/D
+ * become no-ops.
+ *
+ * Site-agnostic: identifies the fetch by structural fingerprint of the
+ * response body, not by URL or site name.
+ */
+function detectFormSchemaFetchCapture(captures, baseUrl) {
+    let host;
+    try {
+        host = new URL(baseUrl).host;
+    }
+    catch {
+        host = "";
+    }
+    for (let i = 0; i < captures.length; i++) {
+        const capture = captures[i];
+        if (capture.method !== "GET")
+            continue;
+        if (capture.status < 200 || capture.status >= 300)
+            continue;
+        let captureHost;
+        try {
+            captureHost = new URL(capture.url).host;
+        }
+        catch {
+            continue;
+        }
+        if (captureHost !== host)
+            continue;
+        if (TELEMETRY_URL_PATTERNS.some((p) => capture.url.includes(p)))
+            continue;
+        if (responseContainsSectionFields(capture.responseBody)) {
+            return { capture, index: i };
+        }
+    }
+    return null;
+}
+function responseContainsSectionFields(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Array.isArray(value)) {
+        if (looksLikeSectionFieldsArray(value))
+            return true;
+        for (const item of value) {
+            if (responseContainsSectionFields(item))
+                return true;
+        }
+        return false;
+    }
+    for (const v of Object.values(value)) {
+        if (responseContainsSectionFields(v))
+            return true;
+    }
+    return false;
+}
+function walkForSectionFieldsArrays(value, fieldNameMap, fieldOptionsMap) {
+    if (value === null || typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        if (looksLikeSectionFieldsArray(value)) {
+            assignFieldNamesFromArray(value, fieldNameMap, fieldOptionsMap);
+        }
+        for (const item of value)
+            walkForSectionFieldsArrays(item, fieldNameMap, fieldOptionsMap);
+        return;
+    }
+    for (const v of Object.values(value)) {
+        walkForSectionFieldsArrays(v, fieldNameMap, fieldOptionsMap);
+    }
+}
+/**
+ * Structural fingerprint: array of objects, at least half of which have a
+ * UUID-shaped FieldId AND at least one of FieldName/FieldSourceCode.
+ */
+function looksLikeSectionFieldsArray(arr) {
+    if (arr.length === 0)
+        return false;
+    let matches = 0;
+    for (const item of arr) {
+        if (item === null || typeof item !== "object")
+            continue;
+        const obj = item;
+        const fieldIdRaw = obj.FieldId;
+        if (typeof fieldIdRaw !== "string")
+            continue;
+        if (!UUID_REGEX.test(fieldIdRaw))
+            continue;
+        if (typeof obj.FieldName === "string" || typeof obj.FieldSourceCode === "string") {
+            matches++;
+        }
+    }
+    return matches >= Math.max(1, Math.floor(arr.length * 0.5));
+}
+function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap) {
+    let currentPrefix = null;
+    const usedNames = new Set([...fieldNameMap.values()]);
+    for (const obj of arr) {
+        const fieldId = obj.FieldId;
+        if (typeof fieldId !== "string")
+            continue;
+        const sourceCode = obj.FieldSourceCode;
+        const name = obj.FieldName;
+        let semantic = null;
+        if (typeof sourceCode === "string" && sourceCode.trim().length > 0) {
+            semantic = sourceCodeToPascalCase(sourceCode);
+            currentPrefix = null;
+        }
+        else if (typeof name === "string" && name.trim().length > 0 && name.length < 250) {
+            const hasNoSourceCode = typeof sourceCode !== "string" || sourceCode.trim().length === 0;
+            // Section-heading heuristic: short FieldName, no SourceCode, MOSTLY
+            // uppercase letters (>= 70% of alphabetic chars) OR contains '#'.
+            // Whole-name uppercase ratio avoids false positives like "MM/DD/YYYY"
+            // appearing as a format hint inside a normal field label.
+            const letters = name.replace(/[^a-zA-Z]/g, "");
+            const upperLetters = name.replace(/[^A-Z]/g, "");
+            const isMostlyUppercase = letters.length >= 3 && upperLetters.length / letters.length >= 0.7;
+            const isSectionHeading = hasNoSourceCode && (isMostlyUppercase || name.includes("#"));
+            if (isSectionHeading) {
+                const headingPrefix = fieldNameToPascalCase(name, null);
+                if (headingPrefix !== null) {
+                    currentPrefix = headingPrefix;
+                }
+                continue;
+            }
+            semantic = fieldNameToPascalCase(name, currentPrefix);
+        }
+        if (semantic !== null && !fieldNameMap.has(fieldId)) {
+            let unique = semantic;
+            let suffix = 2;
+            while (usedNames.has(unique)) {
+                unique = `${semantic}${suffix}`;
+                suffix++;
+            }
+            fieldNameMap.set(fieldId, unique);
+            usedNames.add(unique);
+            // Capture FieldOptions when present and ALL options have non-empty
+            // semantic Values (SystemFieldOption-tagged). Custom options with empty
+            // Value are skipped — they have no semantic label, so we can't generate
+            // a meaningful enum and leave the field's OptionId baked.
+            const optionsRaw = obj.FieldOptions;
+            if (Array.isArray(optionsRaw) && optionsRaw.length > 0) {
+                const options = [];
+                let allSemantic = true;
+                for (const optRaw of optionsRaw) {
+                    if (optRaw === null || typeof optRaw !== "object") {
+                        allSemantic = false;
+                        break;
+                    }
+                    const opt = optRaw;
+                    const optId = opt.Id;
+                    const optValue = opt.Value;
+                    if (typeof optId !== "string" ||
+                        typeof optValue !== "string" ||
+                        optValue.trim().length === 0) {
+                        allSemantic = false;
+                        break;
+                    }
+                    options.push({ value: optValue, optionId: optId });
+                }
+                if (allSemantic && options.length > 0 && !fieldOptionsMap.has(fieldId)) {
+                    fieldOptionsMap.set(fieldId, { semanticName: unique, options });
+                }
+            }
+        }
+    }
+}
+/**
+ * Substitutes Responses[].Value literals with payload accessors based on the
+ * field-name map from the form schema. Operates on the body string before
+ * state interpolation so already-substituted state values (e.g. ${firstName})
+ * are preserved.
+ *
+ * Closed-set substring matching: both FieldId and the literal Value come from
+ * the generator's own input (recon).
+ */
+function applyFormSchemaSubstitutions(rawBody, fieldNameMap, outDiscoveredFields) {
+    if (fieldNameMap.size === 0)
+        return rawBody;
+    let result = rawBody;
+    for (const [fieldId, semanticName] of fieldNameMap) {
+        const fieldIdMarker = `"FieldId":"${fieldId}"`;
+        let cursor = 0;
+        while (true) {
+            const idx = result.indexOf(fieldIdMarker, cursor);
+            if (idx === -1)
+                break;
+            const objEnd = result.indexOf("}", idx);
+            if (objEnd === -1)
+                break;
+            const segment = result.slice(idx, objEnd);
+            const valueMarker = `"Value":"`;
+            const valueIdx = segment.indexOf(valueMarker);
+            if (valueIdx === -1) {
+                cursor = objEnd;
+                continue;
+            }
+            const valueStart = idx + valueIdx + valueMarker.length;
+            const valueEnd = result.indexOf(`"`, valueStart);
+            if (valueEnd === -1 || valueEnd > objEnd) {
+                cursor = objEnd;
+                continue;
+            }
+            const currentValue = result.slice(valueStart, valueEnd);
+            if (currentValue.includes("${")) {
+                cursor = objEnd;
+                continue;
+            }
+            const replacement = `\${payload.${semanticName}}`;
+            result = result.slice(0, valueStart) + replacement + result.slice(valueEnd);
+            outDiscoveredFields.add(semanticName);
+            cursor = valueStart + replacement.length;
+        }
+    }
+    return result;
+}
+/**
+ * Substitutes Responses[].OptionId literals with payload-driven enum lookups.
+ * Operates on the body string before state interpolation. For each FieldId
+ * with a captured FieldOptionsMapping, find `"FieldId":"<uuid>"` and rewrite
+ * the matching `"OptionId":"<uuid>"` to `"OptionId":"${OPT_<Name>[payload.<Name>]}"`.
+ *
+ * Order-insensitive: matches `"OptionId":"<uuid>"` anywhere within the same
+ * JSON object as the FieldId (which is between this FieldId marker and the
+ * closing `}`). Closed-set substring matching: both FieldId and OptionId
+ * come from the generator's own input.
+ */
+function applyFormSchemaOptionIdSubstitutions(rawBody, fieldOptionsMap, outDiscoveredOptionFields) {
+    if (fieldOptionsMap.size === 0)
+        return rawBody;
+    let result = rawBody;
+    for (const [fieldId, mapping] of fieldOptionsMap) {
+        const fieldIdMarker = `"FieldId":"${fieldId}"`;
+        let cursor = 0;
+        while (true) {
+            const idx = result.indexOf(fieldIdMarker, cursor);
+            if (idx === -1)
+                break;
+            const objEnd = result.indexOf("}", idx);
+            if (objEnd === -1)
+                break;
+            const segment = result.slice(idx, objEnd);
+            const optionIdMarker = `"OptionId":"`;
+            const optionIdLocal = segment.indexOf(optionIdMarker);
+            if (optionIdLocal === -1) {
+                cursor = objEnd;
+                continue;
+            }
+            const optionStart = idx + optionIdLocal + optionIdMarker.length;
+            const optionEnd = result.indexOf(`"`, optionStart);
+            if (optionEnd === -1 || optionEnd > objEnd) {
+                cursor = objEnd;
+                continue;
+            }
+            const currentOptionId = result.slice(optionStart, optionEnd);
+            if (currentOptionId.includes("${")) {
+                cursor = objEnd;
+                continue;
+            }
+            const replacement = `\${OPT_${mapping.semanticName}[payload.${mapping.semanticName}]}`;
+            result = result.slice(0, optionStart) + replacement + result.slice(optionEnd);
+            outDiscoveredOptionFields.add(mapping.semanticName);
+            cursor = optionStart + replacement.length;
+        }
+    }
+    return result;
+}
+/**
+ * For fields whose FieldOptions have NO semantic values (CustomFieldOption
+ * options where the recon schema's `.Value` is empty), T3's OPT_* enum
+ * mapping can't be emitted. Instead, parameterize the OptionId slot as a
+ * caller-supplied `<FieldName>OptionId` payload field with the recon-observed
+ * UUID documented in a TSDoc comment.
+ *
+ * Operates on the same `"FieldId":"<uuid>"` anchored search as
+ * applyFormSchemaOptionIdSubstitutions, but only fires when the FieldId is
+ * in fieldNameMap (has a semantic name) AND NOT in fieldOptionsMap (the
+ * structured enum substitution didn't fire). Site-agnostic.
+ */
+function applyRawOptionIdPayloadSubstitutions(rawBody, fieldNameMap, fieldOptionsMap, outDiscoveredRawOptionFields) {
+    if (fieldNameMap.size === 0)
+        return rawBody;
+    let result = rawBody;
+    for (const [fieldId, fieldName] of fieldNameMap) {
+        if (fieldOptionsMap.has(fieldId))
+            continue; // T3's OPT_* already handles this.
+        const fieldIdMarker = `"FieldId":"${fieldId}"`;
+        let cursor = 0;
+        while (true) {
+            const idx = result.indexOf(fieldIdMarker, cursor);
+            if (idx === -1)
+                break;
+            const objEnd = result.indexOf("}", idx);
+            if (objEnd === -1)
+                break;
+            const segment = result.slice(idx, objEnd);
+            const optionIdMarker = `"OptionId":"`;
+            const optionIdLocal = segment.indexOf(optionIdMarker);
+            if (optionIdLocal === -1) {
+                cursor = objEnd;
+                continue;
+            }
+            const optionStart = idx + optionIdLocal + optionIdMarker.length;
+            const optionEnd = result.indexOf(`"`, optionStart);
+            if (optionEnd === -1 || optionEnd > objEnd) {
+                cursor = objEnd;
+                continue;
+            }
+            const currentOptionId = result.slice(optionStart, optionEnd);
+            if (currentOptionId.includes("${")) {
+                cursor = objEnd;
+                continue;
+            }
+            const fieldNameOptionId = `${fieldName}OptionId`;
+            const replacement = `\${payload.${fieldNameOptionId}}`;
+            result = result.slice(0, optionStart) + replacement + result.slice(optionEnd);
+            // Record the recon-observed UUID so the contract can document it in
+            // a TSDoc comment as the caller's starting reference value.
+            if (!outDiscoveredRawOptionFields.has(fieldNameOptionId)) {
+                outDiscoveredRawOptionFields.set(fieldNameOptionId, currentOptionId);
+            }
+            cursor = optionStart + replacement.length;
+        }
+    }
+    return result;
+}
+/** Maximum length to guard against indexing massive blobs (HTML fragments,
+ * embedded base64 images, etc.) that aren't candidates for state threading. */
+const MAX_STATE_VALUE_LENGTH = 256;
+/** Canonical "uninitialized" sentinel values that some REST APIs return as
+ * placeholders before a downstream call populates the real identifier.
+ * ClearCompany's `/user/create` returns these for CandidateId/ApplicationId/
+ * ApplyProcessId, then `/user/start` returns the real values. Indexing the
+ * placeholder would lock the generated plugin's `${candidateId}` binding to
+ * the all-zero UUID — every downstream call would then 404 with "candidate
+ * does not exist". Closed set, literal-string match — never expand to
+ * pattern-based detection (would trip the no-regex-on-open-sets rule). */
+const PLACEHOLDER_STATE_VALUES = new Set(["00000000-0000-0000-0000-000000000000"]);
+/**
+ * Walks every capture's response (including GETs — formHistoryId-style values
+ * may originate in a state-load GET, not a POST). Indexes every string leaf
+ * whose length is in [MIN, MAX], recording the EARLIEST capture index that
+ * produced it. Later occurrences of the same value reuse the earliest origin.
+ *
+ * The index is intentionally permissive — it doesn't try to shape-match
+ * "what looks like a token" because token shapes are an open set across the
+ * web. Authoritative filtering happens downstream in `compileActionSteps`,
+ * which only emits produces[] entries for values that ALSO appear in some
+ * downstream URL/headers/body (i.e. real cross-step reuse).
+ *
+ * Exception: values in `PLACEHOLDER_STATE_VALUES` are skipped entirely so
+ * the LATER non-placeholder occurrence at the same JSON path becomes the
+ * canonical binding instead.
+ */
+function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndices = new Set()) {
+    const index = new Map();
+    // First pass: identify the earliest origin among ACTION captures for each
+    // value. Action-only earliest-origin tracking is what compileActionSteps'
+    // produces[] check needs — it ignores non-action captures (telemetry GETs,
+    // static-asset fetches) that may have surfaced the same UUID earlier in
+    // recon order. Without this, a UUID like FormId that appears in some pre-
+    // r0 GET response would never produce[] from r1 because originIndex points
+    // at the non-action GET that nobody emits as a step.
+    const haveActionFilter = actionCaptureIndices.size > 0;
+    for (let i = 0; i < captures.length; i++) {
+        const c = captures[i];
+        if (c.responseBody === undefined || c.responseBody === null)
+            continue;
+        if (haveActionFilter && !actionCaptureIndices.has(i))
+            continue;
+        // For GET captures, only index UUID-shaped strings. GET captures (today,
+        // only the form-schema fetch inserted as an action step) surface stable
+        // structural identifiers — UUIDs that downstream POSTs need to thread.
+        // Short non-UUID strings ("candidate", "unlocked") from GET responses are
+        // noise and create substring-collision bugs in length-descending replace:
+        // e.g. "candidate" as a state value gets substituted INSIDE an already-
+        // emitted ${candidateId} interpolation, producing ${${entityTypeCode}Id}.
+        const isGet = c.method === "GET";
+        for (const { value, path } of walkStringLeaves(c.responseBody)) {
+            if (value.length < MIN_STATE_VALUE_LENGTH)
+                continue;
+            if (value.length > MAX_STATE_VALUE_LENGTH)
+                continue;
+            if (PLACEHOLDER_STATE_VALUES.has(value))
+                continue;
+            // Schema-identifier UUIDs (FieldId, OptionId) are stable anchors that
+            // T2/T3 substitution depends on remaining literal in body templates.
+            // Indexing them would let state-threading rewrite the anchors and
+            // corrupt T2/T3's already-substituted Values.
+            if (shieldedUuids.has(value))
+                continue;
+            if (isGet && !UUID_REGEX.test(value))
+                continue;
+            if (!index.has(value)) {
+                index.set(value, { value, originIndex: i, path });
+            }
+        }
+    }
+    return index;
+}
+/** Matches strings that are valid JavaScript identifiers (start with letter/$/_,
+ * followed by letters/digits/$/_). Used by the code emitter to decide between
+ * dot-access vs bracket-access and quoted vs unquoted object keys. */
+function isValidJsIdentifier(s) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s);
+}
+/** Converts a path like ["Auth","Token"] to a JS access expression ".Auth.Token". */
+function pathToAccessor(path) {
+    return path.map((p) => (isValidJsIdentifier(p) ? `.${p}` : `[${JSON.stringify(p)}]`)).join("");
+}
+/**
+ * Builds a nested TypeScript assertion type matching a JSON path. e.g.
+ *   ["Auth","Token"] -> `{ Auth: { Token: string } }`
+ *   ["Sections","SectionIds","0"] -> `{ Sections: { SectionIds: { "0": string } } }`
+ * The leaf is always `string` because produces[] entries are only emitted for
+ * string leaves (see compileActionSteps + walkStringLeaves). Used to keep
+ * emitted code free of `any` casts while still letting nested-path access
+ * compile against `Record<string, unknown>`-typed response variables.
+ */
+function pathToAssertionType(path) {
+    if (path.length === 0)
+        return "string";
+    const segment = path[0];
+    const key = isValidJsIdentifier(segment) ? segment : JSON.stringify(segment);
+    return `{ ${key}: ${pathToAssertionType(path.slice(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) {
+    for (let i = path.length - 1; i >= 0; i--) {
+        const segment = path[i];
+        if (isValidJsIdentifier(segment)) {
+            return segment.charAt(0).toLowerCase() + segment.slice(1);
+        }
+    }
+    return "value";
+}
+/**
+ * Walks the action sequence and decorates each step with: a unique response
+ * var name, the state values its response produces (used by downstream steps),
+ * and a multipart flag (request body bytes not captured).
+ */
+function compileActionSteps(actions, stateIndex) {
+    const usedValues = new Set();
+    // Pre-scan: collect all state values referenced by ANY action's URL/headers/body
+    // so we only "produce" the values that are actually consumed downstream.
+    for (const { capture } of actions) {
+        const haystacks = [capture.url];
+        for (const v of Object.values(capture.requestHeaders))
+            haystacks.push(v);
+        if (capture.requestPostData)
+            haystacks.push(capture.requestPostData);
+        for (const sv of stateIndex.values()) {
+            if (haystacks.some((h) => h.includes(sv.value)))
+                usedValues.add(sv.value);
+        }
+    }
+    let lastHost = null;
+    return actions.map(({ capture, index }, i) => {
+        const varName = `r${i}`;
+        const produces = [];
+        const seenNames = new Set();
+        if (capture.responseBody !== undefined && capture.responseBody !== null) {
+            for (const { value, path } of walkStringLeaves(capture.responseBody)) {
+                if (!usedValues.has(value))
+                    continue;
+                const sv = stateIndex.get(value);
+                // Only PRODUCE values whose earliest origin is this very capture.
+                if (!sv || sv.originIndex !== index)
+                    continue;
+                let name = pathToVarName(path);
+                let suffix = 1;
+                while (seenNames.has(name)) {
+                    suffix++;
+                    name = `${pathToVarName(path)}${suffix}`;
+                }
+                seenNames.add(name);
+                produces.push({ name, pathExpr: `${varName}${pathToAccessor(path)}`, path });
+            }
+        }
+        const ct = Object.entries(capture.requestHeaders).find(([k]) => k.toLowerCase() === "content-type");
+        const isMultipart = (ct?.[1] ?? "").toLowerCase().includes("multipart/") && capture.requestPostData === null;
+        let currentHost = null;
+        try {
+            currentHost = new URL(capture.url).host;
+        }
+        catch {
+            currentHost = null;
+        }
+        const isCrossDomain = lastHost !== null && currentHost !== null && lastHost !== currentHost;
+        lastHost = currentHost;
+        return { capture, varName, produces, isMultipart, isCrossDomain };
+    });
+}
+/**
+ * Replaces occurrences of state values in `template` with `${varName}`
+ * interpolations. Returns a JS template-literal string fragment (no backticks).
+ *
+ * Algorithm: walk the producing steps' response bodies in order, harvest each
+ * produced value's concrete string, and map it to the produces[].name. Then
+ * scan the template for those strings and replace with ${varName}. Length-
+ * descending order avoids prefix conflicts (e.g. an 8-char prefix of a
+ * 36-char UUID).
+ */
+function interpolateStateValues(template, priorSteps, payloadAccessorByValue = new Map()) {
+    const varNameByValue = new Map();
+    for (const step of priorSteps) {
+        for (const p of step.produces) {
+            let cursor = step.capture.responseBody;
+            for (const segment of p.path) {
+                if (cursor !== null &&
+                    typeof cursor === "object" &&
+                    segment in cursor) {
+                    cursor = cursor[segment];
+                }
+                else {
+                    cursor = null;
+                    break;
+                }
+            }
+            if (typeof cursor === "string")
+                varNameByValue.set(cursor, p.name);
+        }
+    }
+    let result = template;
+    // Pass 1: substitute state values (length-descending to avoid prefix
+    // conflicts). `\$` is a literal dollar sign (NOT an interpolation);
+    // `${varName}` interpolates the binding name at code-generation time so
+    // the resulting string contains a template-literal placeholder like
+    // `${candidateId}`.
+    const sortedState = [...varNameByValue.entries()].sort((a, b) => b[0].length - a[0].length);
+    for (const [value, varName] of sortedState) {
+        result = result.split(value).join(`\${${varName}}`);
+    }
+    // Pass 2: substitute payload values that survived the state pass. Same
+    // length-descending order. The payload pass only fires on remaining
+    // literal occurrences, so state substitutions win on collisions
+    // (e.g., when an Auth.UserName response value contains the user's email).
+    const sortedPayload = [...payloadAccessorByValue.entries()].sort((a, b) => b[0].length - a[0].length);
+    for (const [value, accessor] of sortedPayload) {
+        result = result.split(value).join(`\${${accessor}}`);
+    }
+    return result;
+}
+/**
+ * Substitutes literal JSON key/value pairs in a body template with payload
+ * interpolations. Catches short strings (e.g. Culture: "en"), booleans
+ * (FutureConsideration: true), and numbers that interpolateStateValues skips
+ * because they're below the state-value length threshold or non-string.
+ *
+ * Site-agnostic: only consults the recon's POST body shapes, doesn't
+ * reference any site-specific key names.
+ *
+ * Substitution is **JSON-key-aware** — only fires on `"key":value` patterns
+ * with the exact recon-captured value. Closed-set matching per the
+ * no-regex-open-sets feedback: both the key and the value come from the
+ * generator's own input. No risk of substring false positives because the
+ * key-prefix anchors the match to a JSON object property.
+ *
+ * additionalBodies are merged after inputBody so subsequent POST bodies' new
+ * top-level keys also become caller-supplied payload fields. Used in Phase F
+ * to parameterize fields like SourceCode that appear in r1's body but not
+ * r0's (inputBody).
+ */
+function applyPayloadKeyValueSubstitutions(template, inputBody, additionalBodies = [], outAdditionalKeys = new Map()) {
+    const merged = [];
+    const seenKeys = new Set();
+    // Track keys from inputBody (r0) separately so we know which ones are NEW.
+    // Only NEW keys need to be added to discovered-form-fields (the payload
+    // schema's inferZodSchema(inputBody) already covers inputBody's keys).
+    if (inputBody !== null && typeof inputBody === "object" && !Array.isArray(inputBody)) {
+        for (const { path } of walkAllPrimitiveLeaves(inputBody)) {
+            if (path.length === 1)
+                seenKeys.add(path[0]);
+        }
+    }
+    const inputBodyKeys = new Set(seenKeys);
+    const allBodies = [inputBody, ...additionalBodies];
+    for (const body of allBodies) {
+        if (body === undefined || body === null || typeof body !== "object" || Array.isArray(body)) {
+            continue;
+        }
+        for (const { value, path } of walkAllPrimitiveLeaves(body)) {
+            if (path.length !== 1)
+                continue;
+            const key = path[0];
+            if (!isValidJsIdentifier(key))
+                continue;
+            if (seenKeys.has(key) && body !== inputBody)
+                continue;
+            // For inputBody first pass: don't dedupe (we need all values).
+            if (body === inputBody && !inputBodyKeys.has(key))
+                continue;
+            seenKeys.add(key);
+            if (value === null)
+                continue;
+            merged.push([key, value]);
+            // Record only the NEW keys (not in inputBody) so the contract emitter
+            // can add them to the payload schema. inputBody's keys are already
+            // emitted by inferZodSchema(inputBody).
+            if (!inputBodyKeys.has(key)) {
+                if (typeof value === "string")
+                    outAdditionalKeys.set(key, "string");
+                else if (typeof value === "number")
+                    outAdditionalKeys.set(key, "number");
+                else if (typeof value === "boolean")
+                    outAdditionalKeys.set(key, "boolean");
+            }
+        }
+    }
+    let result = template;
+    for (const [key, value] of merged) {
+        const accessor = `payload.${key}`;
+        if (typeof value === "string") {
+            const target = `"${key}":${JSON.stringify(value)}`;
+            const replacement = `"${key}":"\${${accessor}}"`;
+            result = result.split(target).join(replacement);
+        }
+        else if (typeof value === "boolean" || typeof value === "number") {
+            const target = `"${key}":${JSON.stringify(value)}`;
+            const replacement = `"${key}":\${${accessor}}`;
+            result = result.split(target).join(replacement);
+        }
+    }
+    return result;
+}
+// ── base64 Content parameterization ──────────────────────────────────────────
+/** Keyword map for matching ATS screening question prompts to payload.Answers field names. */
+const QUESTION_PROMPT_KEYWORDS = {
+    RelatedToEmployee: ["related", "employee"],
+    PreviouslyEmployedAtEncompass: ["previously", "worked"],
+    EverSanctionedOrOnProbation: ["sanctions", "probation", "limitations"],
+    EverTerminated: ["terminated", "resign"],
+    EverExcludedFromFederalProgram: ["excluded", "federal", "program"],
+    VisaSponsorship: ["visa", "sponsor"],
+    LegallyEligibleToWorkUS: ["legal", "eligib", "work", "united states"],
+    CanPerformJobFunctions: ["perform", "job functions", "duties"],
+};
+/**
+ * Scans captures for a `recruitingCEQuestions` GET response and builds a
+ * mapping from question prompts to payload.Answers field names using keyword
+ * overlap scoring. Returns null if no questions capture is found.
+ */
+function buildQuestionnaireMapping(captures) {
+    const questionCapture = captures.find((c) => c.method === "GET" && c.url.includes("recruitingCEQuestions"));
+    if (!questionCapture)
+        return null;
+    const resp = typeof questionCapture.responseBody === "string"
+        ? JSON.parse(questionCapture.responseBody)
+        : questionCapture.responseBody;
+    if (!resp || !Array.isArray(resp.items))
+        return null;
+    const mappings = [];
+    for (const item of resp.items) {
+        const prompt = String(item.Prompt ?? "").toLowerCase();
+        const qid = item.AttributeName;
+        const uiType = String(item.UIDisplayType ?? "");
+        if (!qid || uiType === "TextBox")
+            continue;
+        let bestField = null;
+        let bestScore = 0;
+        for (const [field, keywords] of Object.entries(QUESTION_PROMPT_KEYWORDS)) {
+            const score = keywords.filter((kw) => prompt.includes(kw)).length;
+            if (score > bestScore) {
+                bestScore = score;
+                bestField = field;
+            }
+        }
+        if (!bestField || bestScore < 2)
+            continue;
+        if (mappings.some((m) => m.payloadField === bestField))
+            continue;
+        const answers = {};
+        for (const a of (item.answers ?? [])) {
+            const meaning = String(a.Meaning ?? "");
+            const code = a.LookupCode;
+            if (meaning && code)
+                answers[meaning] = code;
+        }
+        mappings.push({ questionId: qid, payloadField: bestField, answers });
+    }
+    return mappings.length > 0 ? mappings : null;
+}
+/**
+ * Builds the TypeScript source for a `buildBase64Content` function that
+ * constructs the base64-encoded Content JSON from payload values and returns
+ * it as a base64 string. The function replaces persona-specific values
+ * with payload references and maps questionnaire answers via a static
+ * lookup table derived from the recon captures.
+ */
+function emitBuildBase64ContentFunction(base64, personaValues, questionMapping, pascal) {
+    const decoded = Buffer.from(base64, "base64").toString("utf8");
+    const content = JSON.parse(decoded);
+    const candidate = content.candidate;
+    const basic = candidate.basicInformation;
+    const phone = basic.phone;
+    const application = content.application;
+    const esig = application.eSignature;
+    basic.firstName = "__PAYLOAD_FirstName__";
+    basic.lastName = "__PAYLOAD_LastName__";
+    basic.email = "__PAYLOAD_Email__";
+    if (esig)
+        esig.fullName = "__PAYLOAD_SignatureFullName__";
+    if (basic.displayName && typeof basic.displayName === "string")
+        basic.displayName = "__PAYLOAD_DisplayName__";
+    if (phone && typeof phone.number === "string" && phone.number)
+        phone.number = "__PAYLOAD_Phone__";
+    for (const [personaVal, _payloadRef] of personaValues) {
+        if (typeof basic.email === "string" && basic.email === personaVal)
+            basic.email = "__PAYLOAD_Email__";
+    }
+    const questionnaires = candidate.questionnaires;
+    if (questionnaires && questionMapping) {
+        for (const q of questionnaires) {
+            q.questionnaireId = -1;
+            for (const question of q.questions) {
+                const mapping = questionMapping.find((m) => m.questionId === question.questionId);
+                if (mapping) {
+                    question.answer = `__QMAP_${mapping.payloadField}__`;
+                }
+            }
+        }
+    }
+    const attachments = candidate.attachments;
+    if (attachments) {
+        for (const att of attachments) {
+            if (att.id && att.id !== "draft-json-undefined") {
+                att.id = "__PAYLOAD_AttachmentId__";
+            }
+        }
+        if (attachments[0]) {
+            attachments[0].appDraftId = "__PAYLOAD_DraftId__";
+        }
+    }
+    const jsonStr = JSON.stringify(content, null, 0);
+    const contentObj = JSON.parse(jsonStr);
+    const questionMapEntries = (questionMapping ?? []).map((m) => `    ${JSON.stringify(m.payloadField)}: { answers: ${JSON.stringify(m.answers)} as Record<string, number>, questionId: ${m.questionId} },`);
+    const questionMapConst2 = questionMapEntries.length > 0
+        ? `\nconst QUESTIONNAIRE_ANSWER_MAP = {\n${questionMapEntries.join("\n")}\n};\n`
+        : "";
+    const contentTemplate = JSON.stringify(contentObj, null, 2);
+    const parameterized = contentTemplate
+        .replace(/"__PAYLOAD_FirstName__"/g, "payload.FirstName")
+        .replace(/"__PAYLOAD_LastName__"/g, "payload.LastName")
+        .replace(/"__PAYLOAD_Email__"/g, "payload.Email")
+        .replace(/"__PAYLOAD_Phone__"/g, "payload.Phone")
+        .replace(/"__PAYLOAD_SignatureFullName__"/g, "payload.Answers.SignatureFullName")
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: emitted as generated template-literal source
+        .replace(/"__PAYLOAD_DisplayName__"/g, "`${payload.FirstName} ${payload.LastName}`")
+        .replace(/"__PAYLOAD_AttachmentId__"/g, "attachmentId")
+        .replace(/"__PAYLOAD_DraftId__"/g, "draftId")
+        .replace(/-1(?=,\n\s*"questions")/g, "questionnaireId");
+    for (const m of questionMapping ?? []) {
+        parameterized.replace(`"__QMAP_${m.payloadField}__"`, `QUESTIONNAIRE_ANSWER_MAP[${JSON.stringify(m.payloadField)}].answers[payload.Answers.${m.payloadField}] ?? "draft-json-undefined"`);
+    }
+    let finalTemplate = parameterized.replace(/"__QMAP_[^"]*__"/g, '"draft-json-undefined"');
+    for (const m of questionMapping ?? []) {
+        finalTemplate = finalTemplate.replace(`"__QMAP_${m.payloadField}__"`, `(QUESTIONNAIRE_ANSWER_MAP[${JSON.stringify(m.payloadField)}].answers[payload.Answers.${m.payloadField}] ?? "draft-json-undefined")`);
+    }
+    return `${questionMapConst2}
+/** Builds the ATS Content payload as a base64-encoded JSON string. */
+function buildBase64Content(
+  payload: ${pascal}Payload,
+  questionnaireId: number,
+  draftId: number,
+  attachmentId: string
+): string {
+  const content = ${finalTemplate};
+  return Buffer.from(JSON.stringify(content)).toString("base64");
+}
+`;
+}
+/** Builds the multi-step `executeHttp` body as a single template-literal string.
+ *
+ * Two-pass design avoids emitting unused bindings (which would trip Biome's
+ * `noUnusedVariables`):
+ *   1. Render URL / headers / body for each step and collect the set of
+ *      `${name}` substrings actually referenced by emitted text.
+ *   2. Emit. Skip per-step response bindings whose response var isn't
+ *      referenced AND isn't the terminal var (needed for `return { data }`).
+ *      Skip produces[] entries whose name isn't referenced anywhere downstream.
+ */
+/**
+ * Emits per-step `throw new Error(...)` lines for each detected error signal.
+ * Returns lines indented to sit inside the `if (typeof X === "object" && X !==
+ * null)` wrapper that `emitMultiStepExecuteHttp` writes.
+ */
+function emitErrorSignalGuards(varName, urlPath, signals) {
+    const out = [];
+    if (signals.stringMessageKey !== null) {
+        const k = signals.stringMessageKey;
+        out.push(`      if (typeof (${varName} as { ${k}?: unknown }).${k} === "string") throw new Error(\`step ${varName} (${urlPath}) returned error: \${(${varName} as { ${k}: string }).${k}}\`);`);
+    }
+    const nestedByParent = new Map();
+    for (const { parentPath, errorKey } of signals.nestedErrorPaths) {
+        const key = parentPath.join(".");
+        const existing = nestedByParent.get(key) ?? [];
+        existing.push({ errorKey });
+        nestedByParent.set(key, existing);
+    }
+    for (const [parentPathStr, errorKeys] of nestedByParent) {
+        if (parentPathStr === "") {
+            for (const { errorKey } of errorKeys) {
+                out.push(`      if ((${varName} as { ${errorKey}?: unknown }).${errorKey} != null) throw new Error(\`step ${varName} ${errorKey.toLowerCase()}: \${JSON.stringify((${varName} as { ${errorKey}: unknown }).${errorKey})}\`);`);
+            }
+            continue;
+        }
+        const parentSegments = parentPathStr.split(".");
+        const parentVar = `${varName}_${parentSegments[parentSegments.length - 1].toLowerCase()}`;
+        const parentAccessor = parentSegments.join("?.");
+        const parentTypeAssertion = errorKeys.map(({ errorKey }) => `${errorKey}?: unknown`).join("; ");
+        const parentObjType = parentSegments
+            .reverse()
+            .reduce((inner, seg) => `${seg}?: { ${inner} }`, parentTypeAssertion);
+        parentSegments.reverse();
+        out.push(`      const ${parentVar} = (${varName} as { ${parentObjType} }).${parentAccessor};`);
+        for (const { errorKey } of errorKeys) {
+            const label = errorKey === "ResponseValidationErrors"
+                ? "validation errors"
+                : errorKey === "DataValidationErrors"
+                    ? "data errors"
+                    : errorKey
+                        .replace(/([A-Z])/g, " $1")
+                        .trim()
+                        .toLowerCase();
+            out.push(`      if (${parentVar} != null && ${parentVar}.${errorKey} != null) throw new Error(\`step ${varName} ${label}: \${JSON.stringify(${parentVar}.${errorKey})}\`);`);
+        }
+    }
+    return out;
+}
+/** 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, base64PatchOverride = new Map()) {
+    // 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
+    // payload references (e.g. ${payload.FirstName}) — so the generated plugin
+    // actually uses the runtime payload instead of the recon's frozen identity.
+    //
+    // Same MIN_STATE_VALUE_LENGTH threshold as state values: short values
+    // (e.g. `"en"` for Culture, `"US"` for country) collide with arbitrary
+    // substrings in URLs/bodies ("token", "entities", "Australia") and would
+    // produce nonsense substitutions. Values below the threshold stay literal
+    // in the emitted template — fine for short enum-like fields that rarely
+    // need to vary at runtime.
+    const payloadAccessorByValue = new Map();
+    if (inputBody !== undefined && inputBody !== null) {
+        for (const { value, path } of walkStringLeaves(inputBody)) {
+            if (value.length < MIN_STATE_VALUE_LENGTH)
+                continue;
+            const accessor = `payload${pathToAccessor(path)}`;
+            payloadAccessorByValue.set(value, accessor);
+            // Phase F: register a lowercase variant for UUID-shaped values so case-
+            // variant URL path segments (e.g. r9 echoes the requisition UUID in
+            // lowercase even though r0's body had it uppercase) still get
+            // substituted. Site-agnostic.
+            if (UUID_REGEX.test(value) && value.toLowerCase() !== value) {
+                payloadAccessorByValue.set(value.toLowerCase(), accessor);
+            }
+        }
+    }
+    // G1: register the recon's baseUrl so the existing payload-substitution pass
+    // rewrites every URL occurrence to `${payload.BaseUrl}/...`. Same plugin
+    // then works for any tenant on the same ATS just by passing a different
+    // BaseUrl. Site-agnostic: just registers the recon's own baseUrl as a payload
+    // accessor; no site-specific URL knowledge.
+    if (baseUrl.length >= MIN_STATE_VALUE_LENGTH) {
+        payloadAccessorByValue.set(baseUrl, "payload.BaseUrl");
+        outDiscoveredFields.add("BaseUrl");
+    }
+    // G2: register any tenant-subdomain header values as payload-supplied fields
+    // (e.g. ClearCompany's `API-ShortName: "addus"` becomes `payload.ApiShortName`).
+    for (const [headerName, _value] of tenantSubdomainHeaders) {
+        outDiscoveredFields.add(headerNameToPayloadFieldName(headerName));
+    }
+    // Phase F: gather all action POST bodies (parsed) so the T1 substitution
+    // can catch top-level keys from EVERY POST, not just the first one. E.g.
+    // r1's body has SourceCode/FormId/LocationIds/ReOpen — these become
+    // caller-supplied payload fields (when non-null).
+    const additionalBodies = [];
+    for (let i = 1; i < actions.length; i++) {
+        const cap = actions[i].capture;
+        if (cap.method !== "POST" || !cap.requestPostData)
+            continue;
+        try {
+            additionalBodies.push(JSON.parse(cap.requestPostData));
+        }
+        catch {
+            // skip non-JSON bodies (e.g. multipart raw bytes)
+        }
+    }
+    // Pass 1: render every step's emitted strings; collect referenced var names.
+    const rendered = [];
+    for (let i = 0; i < actions.length; i++) {
+        const step = actions[i];
+        const cap = step.capture;
+        const prior = actions.slice(0, i);
+        const url = interpolateStateValues(cap.url, prior, payloadAccessorByValue);
+        // Form-schema substitution runs first on the raw recon body so its
+        // FieldId-anchored matches see the original JSON. State-threading and
+        // payload key-value passes then run on top. OptionId substitution runs
+        // here too: same closed-set FieldId anchor; rewrites "OptionId":"<uuid>"
+        // slots to "${OPT_X[payload.X]}" lookups.
+        const rawBodyWithFormSubs = cap.requestPostData
+            ? applyRawOptionIdPayloadSubstitutions(applyFormSchemaOptionIdSubstitutions(applyFormSchemaSubstitutions(cap.requestPostData, fieldNameMap, outDiscoveredFields), fieldOptionsMap, outDiscoveredOptionFields), fieldNameMap, fieldOptionsMap, outDiscoveredRawOptionFields)
+            : "";
+        let bodyTemplate = rawBodyWithFormSubs
+            ? applyPayloadKeyValueSubstitutions(interpolateStateValues(rawBodyWithFormSubs, prior, payloadAccessorByValue), inputBody, additionalBodies, outDiscoveredAdditionalBodyKeys)
+            : "";
+        const contentOverride = base64PatchOverride.get(step.varName);
+        if (contentOverride && bodyTemplate) {
+            bodyTemplate = bodyTemplate.replace(/"Content":"ey[A-Za-z0-9+/=]{100,}"/, contentOverride);
+        }
+        const perCallHeaders = {};
+        for (const [k, v] of Object.entries(cap.requestHeaders)) {
+            const lower = k.toLowerCase();
+            if (lower === "api-token" || lower === "authorization") {
+                perCallHeaders[k] = interpolateStateValues(v, prior, payloadAccessorByValue);
+            }
+        }
+        // G1: emit baseUrl-derived headers (Origin, Referer) per-call from
+        // payload.BaseUrl. interpolateStateValues already substituted the literal
+        // baseUrl with `${payload.BaseUrl}`, so a simple sub of the recon's
+        // observed baseUrl in each header value gives us `${payload.BaseUrl}/`.
+        // Emit "${payload.BaseUrl}" as a template-literal placeholder into the
+        // generated plugin code. Built via concatenation so Biome doesn't mistake
+        // it for a placeholder in THIS file's source.
+        const baseUrlPlaceholder = `$${"{"}payload.BaseUrl${"}"}`;
+        for (const [headerName, observedValue] of baseUrlDerivedHeaders) {
+            perCallHeaders[headerName] = observedValue.split(baseUrl).join(baseUrlPlaceholder);
+        }
+        // G2: emit tenant-subdomain headers per-call from caller payload field
+        // (e.g. API-ShortName → ${payload.ApiShortName}). The discoveredFields
+        // population above ensures the field is in the payload schema.
+        for (const [headerName, _observedValue] of tenantSubdomainHeaders) {
+            const fieldName = headerNameToPayloadFieldName(headerName);
+            perCallHeaders[headerName] = `\${payload.${fieldName}}`;
+        }
+        const headersExpr = Object.keys(perCallHeaders).length
+            ? `headers: { ${Object.entries(perCallHeaders)
+                .map(([k, v]) => `${JSON.stringify(k)}: \`${v}\``)
+                .join(", ")} },`
+            : "";
+        const bodyArg = bodyTemplate ? `body: \`${bodyTemplate}\`,` : "";
+        rendered.push({ url, method: cap.method, headersExpr, bodyArg });
+    }
+    // Identifier scan against the rendered text — captures `${foo}`, `${foo.bar}`,
+    // etc. The first segment (anchored at `${`) is the binding's name. Closed
+    // grammar (template-literal syntax we generated ourselves).
+    // For multipart steps the bodyArg isn't emitted (the body is a FormData
+    // built inline), but the URL and headers ARE in executable code — scan
+    // only those two haystacks for multipart.
+    const referencedNames = new Set();
+    for (let i = 0; i < rendered.length; i++) {
+        const r = rendered[i];
+        const haystacks = actions[i].isMultipart
+            ? [r.url, r.headersExpr]
+            : [r.url, r.headersExpr, r.bodyArg];
+        for (const haystack of haystacks) {
+            for (const match of haystack.matchAll(/\$\{([A-Za-z_$][A-Za-z0-9_$]*)/g)) {
+                referencedNames.add(match[1]);
+            }
+        }
+    }
+    // The last step's var is also referenced by the closing `return { data }`.
+    if (actions.length > 0)
+        referencedNames.add(actions[actions.length - 1].varName);
+    // Base64 Content overrides reference variables inside function calls
+    // (e.g. buildBase64Content(payload, questionnaireId, ...)) that the
+    // ${name} regex above doesn't capture. Add them explicitly.
+    for (const [key, override] of base64PatchOverride.entries()) {
+        if (key === "__EXTRA_VARS__")
+            continue;
+        for (const m of override.matchAll(/\b([A-Za-z_$][A-Za-z0-9_$]*)\b/g)) {
+            const name = m[1];
+            if (/^r\d+$/.test(name))
+                continue;
+            referencedNames.add(name);
+        }
+    }
+    // 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
+    // referenced — the produces line dereferences it.
+    const lines = [];
+    const declaredNames = new Set();
+    for (let i = 0; i < actions.length; i++) {
+        const step = actions[i];
+        const cap = step.capture;
+        const r = rendered[i];
+        const hasReferencedProduce = step.produces.some((p) => referencedNames.has(p.name));
+        const bindResponse = referencedNames.has(step.varName) || hasReferencedProduce;
+        if (base64PatchOverride.has(step.varName) && base64PatchOverride.has("__EXTRA_VARS__")) {
+            lines.push(base64PatchOverride.get("__EXTRA_VARS__"));
+            lines.push("");
+        }
+        if (step.isCrossDomain) {
+            lines.push(`    // TODO: cross-domain redirect detected (${cap.url.split("/")[2]}) — likely needs browser fallback for this step.`);
+        }
+        if (step.isMultipart) {
+            // Bypasses httpClient because its typed string-body interface can't
+            // carry a FormData payload. We splice in BASE_HEADERS (minus
+            // Content-Type, which FormData sets to multipart/form-data with the
+            // boundary it generates) so site-required custom headers like
+            // API-Realm/API-AppType/etc. are carried over. The next call goes
+            // back through httpClient for rate-limit + Zod parsing.
+            //
+            // Binary asset (file Buffer + content-type + filename) is required on
+            // the payload. The plugin route is registered with @fastify/multipart's
+            // `attachFieldsToBody: 'keyValues'` so callers POST these fields as
+            // standard multipart/form-data — no base64-in-JSON, no fixtures.
+            const fdVar = `fd_${step.varName}`;
+            const respVar = `resp_${step.varName}`;
+            const headersVar = `headers_${step.varName}`;
+            // Extract just the per-call header overrides (API-Token etc.) from the
+            // rendered headers expression to merge with BASE_HEADERS.
+            const perCallHeaderEntries = [];
+            for (const [k, v] of Object.entries(cap.requestHeaders)) {
+                const lower = k.toLowerCase();
+                if (lower === "api-token" || lower === "authorization") {
+                    perCallHeaderEntries.push(`${JSON.stringify(k)}: \`${interpolateStateValues(v, actions.slice(0, i), payloadAccessorByValue)}\``);
+                }
+            }
+            // G1+G2: include tenant-derived headers in the multipart fetch too.
+            // Build the placeholder via concatenation so Biome doesn't mistake it
+            // for a template-literal in THIS file's source.
+            const baseUrlPlaceholder = `$${"{"}payload.BaseUrl${"}"}`;
+            for (const [headerName, observedValue] of baseUrlDerivedHeaders) {
+                const v = observedValue.split(baseUrl).join(baseUrlPlaceholder);
+                perCallHeaderEntries.push(`${JSON.stringify(headerName)}: \`${v}\``);
+            }
+            for (const [headerName, _observedValue] of tenantSubdomainHeaders) {
+                const fieldName = headerNameToPayloadFieldName(headerName);
+                perCallHeaderEntries.push(`${JSON.stringify(headerName)}: \`\${payload.${fieldName}}\``);
+            }
+            const perCallHeadersLit = perCallHeaderEntries.length
+                ? `, ${perCallHeaderEntries.join(", ")}`
+                : "";
+            // Buffer-to-Blob coercion in the emitted line below: Node's Buffer is a
+            // Uint8Array subclass, but its TS type lists ArrayBufferLike (which
+            // includes SharedArrayBuffer), so it isn't assignable to BlobPart
+            // directly. Uint8Array.from copies the bytes into a fresh
+            // ArrayBuffer-backed view that satisfies BlobPart.
+            lines.push(`    // Expected response shape: ${JSON.stringify(summariseResponseShape(cap.responseBody))}`, `    const ${fdVar} = new FormData();`, `    const ${fdVar}_bytes = Uint8Array.from(payload.Resume);`, `    ${fdVar}.append("files[]", new Blob([${fdVar}_bytes], { type: payload.ResumeContentType }), payload.ResumeFilename);`, `    const ${headersVar} = { ...omitHeaderCaseInsensitive(BASE_HEADERS, "Content-Type")${perCallHeadersLit} };`, `    const ${respVar} = await fetch(\`${r.url}\`, {`, `      method: "POST",`, `      headers: ${headersVar},`, `      body: ${fdVar},`, `    });`, `    if (!${respVar}.ok) throw new Error(\`step ${step.varName} (multipart upload) failed: HTTP \${${respVar}.status}\`);`);
+            if (bindResponse) {
+                lines.push(`    const ${step.varName} = (await ${respVar}.json()) as Record<string, unknown>;`);
+            }
+            else {
+                lines.push(`    await ${respVar}.json();`);
+            }
+        }
+        else {
+            const urlPath = cap.url.split("/").slice(3).join("/").split("?")[0] ?? "";
+            const guardLines = emitErrorSignalGuards(step.varName, urlPath, errorSignals);
+            const needsBinding = bindResponse || guardLines.length > 0;
+            if (needsBinding) {
+                lines.push(`    const ${step.varName} = (await httpClient(\`${r.url}\`, {`);
+            }
+            else {
+                lines.push(`    await httpClient(\`${r.url}\`, {`);
+            }
+            lines.push(`      method: ${JSON.stringify(r.method)},`);
+            const joined = [r.headersExpr, r.bodyArg].filter((s) => s !== "").join(" ");
+            if (joined !== "") {
+                lines.push(`      ${joined}`);
+            }
+            if (needsBinding) {
+                lines.push(`    })) as Record<string, unknown>;`);
+            }
+            else {
+                lines.push(`    });`);
+            }
+            if (guardLines.length > 0) {
+                lines.push(`    if (typeof ${step.varName} === "object" && ${step.varName} !== null) {`);
+                for (const line of guardLines)
+                    lines.push(line);
+                lines.push(`    }`);
+            }
+        }
+        for (const p of step.produces) {
+            if (declaredNames.has(p.name))
+                continue;
+            if (!referencedNames.has(p.name))
+                continue;
+            declaredNames.add(p.name);
+            const assertion = pathToAssertionType(p.path);
+            lines.push(`    const ${p.name} = (${step.varName} as ${assertion})${pathToAccessor(p.path)};`);
+        }
+        lines.push("");
+    }
+    const lastVar = actions.length > 0 ? actions[actions.length - 1].varName : "undefined";
+    lines.push(`    return { data: ${lastVar} };`);
+    return lines.join("\n");
+}
+function summariseResponseShape(value) {
+    if (value === null || typeof value !== "object")
+        return typeof value;
+    if (Array.isArray(value))
+        return `array(${value.length})`;
+    const obj = {};
+    for (const [k, v] of Object.entries(value)) {
+        obj[k] = v === null ? "null" : typeof v;
+    }
+    return obj;
+}
+// ── code emitters ─────────────────────────────────────────────────────────────
+/** 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, pascal, baseUrl, baseHeaders, minTime, safeRps, responseBody, gql, gqlQuery, endpointPath, auxFiles, multiStepBody, inputBody, hasMultipartStep = false, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, payloadFieldNames, base64ContentHelper = "", } = opts;
+    // Multi-step plugins thread responses through many different shapes that a
+    // single Zod schema can't cover — use z.unknown() so each per-step access
+    // compiles cleanly. Single-endpoint plugins keep the inferred schema.
+    const responseSchemaExpr = multiStepBody ? `z.unknown()` : inferZodSchema(responseBody);
+    // Multi-step flows that include a multipart upload need the binary asset
+    // on the payload. Add Resume/ResumeContentType/ResumeFilename as required
+    // fields so the @fastify/multipart-populated request body has everything
+    // the upload step needs. Site-agnostic: works for any flow with a multipart
+    // step, regardless of which step in the sequence it is. The hasMultipartStep
+    // flag is computed once at the call site from actionSteps.some(s.isMultipart).
+    //
+    // multipart/form-data wire format encodes every text field as a string, so
+    // pass multipartCoerce so inferZodSchema emits multipartBoolean() calls for
+    // booleans and z.coerce.number() for numbers at the source rather than via
+    // brittle post-process string substitution. Site-agnostic: only flips on
+    // when meta.multipart is true.
+    const basePayloadSchemaExpr = inputBody
+        ? inferZodSchema(inputBody, 0, "", { multipartCoerce: hasMultipartStep })
+        : `z.object({\n  query: z.string().min(1),\n})`;
+    // Form-schema-discovered fields (e.g. AddressLine1, UserSsn, Reference1FirstName)
+    // are added to the payload as required strings. Site-agnostic: the set is
+    // populated by applyFormSchemaSubstitutions when the recon includes a
+    // detectable form schema; empty for sites without one.
+    const formFieldsExtension = discoveredFormFields && discoveredFormFields.size > 0
+        ? `.extend({\n${[...discoveredFormFields]
+            .sort()
+            .map((name) => `  ${name}: z.string(),`)
+            .join("\n")}\n})`
+        : "";
+    // Candidate-PII fields the browser flow splices as `payload.<field>`. Emitted
+    // as required strings (z.email() for Email per the repo's z.string().email()→
+    // z.email() migration) so those references typecheck in the generated flow.
+    // Skip any field the form-schema pass already added to avoid a duplicate
+    // `.extend` key.
+    const splicedFieldNames = payloadFieldNames
+        ? [...payloadFieldNames].filter((name) => !discoveredFormFields?.has(name)).sort()
+        : [];
+    const splicedFieldsExtension = splicedFieldNames.length > 0
+        ? `.extend({\n${splicedFieldNames
+            .map((name) => `  ${name}: ${name === "Email" ? "z.email()" : "z.string()"},`)
+            .join("\n")}\n})`
+        : "";
+    // Build per-field OPT_<Name> constant declarations + payload-schema enum
+    // entries from the form schema's FieldOptions. Only fields whose OptionId
+    // slots were actually rewritten in the body (i.e. that appear in
+    // discoveredOptionFields) get emitted; the rest leave their schema entries
+    // unused. Computed BEFORE payloadSchemaExpr so the extension string is
+    // available for the final schema concat.
+    const emittedOptionMappings = [];
+    if (fieldOptionsMap && discoveredOptionFields && discoveredOptionFields.size > 0) {
+        for (const mapping of fieldOptionsMap.values()) {
+            if (discoveredOptionFields.has(mapping.semanticName)) {
+                emittedOptionMappings.push(mapping);
+            }
+        }
+        emittedOptionMappings.sort((a, b) => a.semanticName.localeCompare(b.semanticName));
+    }
+    const optionDecls = emittedOptionMappings
+        .map((mapping) => {
+        const entries = mapping.options
+            .map(({ value, optionId }) => `  ${isValidJsIdentifier(value) ? value : JSON.stringify(value)}: ${JSON.stringify(optionId)},`)
+            .join("\n");
+        return `\nconst OPT_${mapping.semanticName} = {\n${entries}\n} as const;\n`;
+    })
+        .join("");
+    const optionSchemaExtension = emittedOptionMappings.length > 0
+        ? `.extend({\n${emittedOptionMappings
+            .map((m) => `  ${m.semanticName}: z.enum([${m.options.map((o) => JSON.stringify(o.value)).join(", ")}]),`)
+            .join("\n")}\n})`
+        : "";
+    // Phase E raw-option payload fields: FieldOptions whose .Value strings are
+    // empty in the schema (CustomFieldOption) — no semantic enum is possible,
+    // so the caller supplies the OptionId UUID directly. The recon-observed
+    // UUID is documented in a TSDoc comment so callers have a starting point.
+    const sortedRawOptionEntries = discoveredRawOptionFields
+        ? [...discoveredRawOptionFields.entries()].sort(([a], [b]) => a.localeCompare(b))
+        : [];
+    const rawOptionSchemaExtension = sortedRawOptionEntries.length > 0
+        ? `.extend({\n${sortedRawOptionEntries
+            .map(([name, reconUuid]) => `  /** Recon-observed: ${reconUuid}. Caller supplies the OptionId UUID for this field. */\n  ${name}: z.string(),`)
+            .join("\n")}\n})`
+        : "";
+    // Phase F: additional-body keys (from action POSTs beyond r0). Each gets a
+    // payload field of the appropriate Zod type. Site-agnostic.
+    const sortedAdditionalKeys = discoveredAdditionalBodyKeys
+        ? [...discoveredAdditionalBodyKeys.entries()].sort(([a], [b]) => a.localeCompare(b))
+        : [];
+    const additionalBodyKeysExtension = sortedAdditionalKeys.length > 0
+        ? `.extend({\n${sortedAdditionalKeys
+            .map(([name, kind]) => {
+            // 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"
+                    ? hasMultipartStep
+                        ? "z.coerce.number()"
+                        : "z.number()"
+                    : hasMultipartStep
+                        ? "multipartBoolean()"
+                        : "z.boolean()";
+            return `  ${name}: ${zod},`;
+        })
+            .join("\n")}\n})`
+        : "";
+    // optionSchemaExtension is appended LAST so option enums show up at the
+    // end of the payload type — the section ordering (base, multipart fields,
+    // form-schema fields, option enums, raw-option fields) mirrors the body
+    // emit order and keeps the generated payload type readable.
+    const answersExtension = base64ContentHelper ? ".extend({ Answers: AnswersSchema })" : "";
+    const payloadSchemaExpr = hasMultipartStep
+        ? `${basePayloadSchemaExpr}.extend({\n  Resume: z.instanceof(Buffer),\n  ResumeContentType: z.string(),\n  ResumeFilename: z.string(),\n})${formFieldsExtension}${splicedFieldsExtension}${optionSchemaExtension}${rawOptionSchemaExtension}${additionalBodyKeysExtension}${answersExtension}`
+        : `${basePayloadSchemaExpr}${formFieldsExtension}${splicedFieldsExtension}${optionSchemaExtension}${rawOptionSchemaExtension}${additionalBodyKeysExtension}${answersExtension}`;
+    // When the payload schema uses multipartBoolean(), import the shared helper
+    // from @/lib/zod-multipart so the generated file resolves the reference and
+    // doesn't re-inline the preprocess expression per boolean field.
+    const multipartBoolImport = hasMultipartStep
+        ? `import { multipartBoolean } from "../lib/zod-multipart";\n`
+        : "";
+    // Content-Type must be absent from multipart fetch calls so FormData can inject the boundary.
+    const caseInsensitiveHeadersImport = hasMultipartStep
+        ? `import { omitHeaderCaseInsensitive } from "../lib/case-insensitive-headers";\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)
+        .map(([k, v]) => `  ${isValidJsIdentifier(k) ? k : JSON.stringify(k)}: ${JSON.stringify(v)}`)
+        .join(",\n");
+    const fixtureImport = auxFiles.length > 0 ? `// import { loadFixture } from "../scraper/fixtures";\n` : "";
+    const clientImport = gql
+        ? `import { createGraphqlClient } from "../scraper/graphql-client";`
+        : `import { createHttpClient } from "../scraper/http-client";`;
+    const queryConst = gql && gqlQuery
+        ? `\n// Lifted verbatim from recon capture — trim UI-only fields before shipping.\nconst ${pascal.toUpperCase()}_QUERY = \`${gqlQuery.trim()}\`;\n`
+        : "";
+    const gqlCacheBlock = gql
+        ? `
+type GqlFn = (operationName: string, query: string, variables: Record<string, unknown>) => Promise<${pascal}Response>;
+
+const gqlCache = new Map<string, GqlFn>();
+
+function getGql(baseUrl: string): GqlFn {
+  let client = gqlCache.get(baseUrl);
+  if (!client) {
+    client = createGraphqlClient({
+      schema: ${pascal}ResponseSchema,
+      bottleneck: limiter,
+      baseHeaders: BASE_HEADERS,
+      endpoint: \`\${baseUrl}${endpointPath}\`,
+    });
+    gqlCache.set(baseUrl, client);
+  }
+  return client;
+}
+`
+        : `
+const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottleneck: limiter, baseHeaders: BASE_HEADERS });
+`;
+    const executeHttpBody = multiStepBody
+        ? multiStepBody
+        : gql
+            ? `    const data = await getGql(context.baseUrl)(${JSON.stringify(`${pascal}Search`)}, ${pascal.toUpperCase()}_QUERY, { q: payload.query });
+    return { data };`
+            : `    const data = await httpClient(\`\${context.baseUrl}${endpointPath}\`, {
+      method: "POST",
+      body: JSON.stringify({ query: payload.query }),
+    });
+    return { data };`;
+    const fixtureComments = auxFiles.length > 0
+        ? `\n// Fixtures downloaded by recon — commit to src/sites/${siteId}/fixtures/ and uncomment:\n` +
+            auxFiles
+                .map((f) => `// const ${f.replace(".json", "")} = loadFixture(${JSON.stringify(siteId)}, ${JSON.stringify(f)}, z.unknown());`)
+                .join("\n") +
+            "\n"
+        : "";
+    const queryChecklistLine = gql
+        ? `\n *   [ ] Trim UI-only fields from ${pascal.toUpperCase()}_QUERY (keep only fields you need)`
+        : "";
+    return `/**
+ * Generated by recon-generate.ts — review before shipping.
+ *
+ * Checklist:${queryChecklistLine}
+ *   [ ] Narrow ${pascal}ResponseSchema to match the real response shape
+ *   [ ] Adjust ${pascal}PayloadSchema to your actual request parameters
+ *   [ ] Verify BASE_HEADERS — remove any that aren't load-bearing
+ */
+
+import Bottleneck from "bottleneck";
+import { z } from "zod/v4";
+
+${fixtureImport}${caseInsensitiveHeadersImport}${multipartBoolImport}${clientImport}
+import type { BrowserSession } from "../scraper/session";
+import type { SitePlugin, SitePluginContext, SitePluginResult } from "../site-plugin";
+import { run${pascal}BrowserFlow } from "@/sites/${siteId}/flows/browser-flow";
+
+const BASE_HEADERS: Record<string, string> = {
+${headersLiteral},
+};
+
+// Safe ceiling: ${safeRps} rps — from recon rate-limit probe.
+const limiter = new Bottleneck({ minTime: ${minTime} });
+
+const ${pascal}ResponseSchema = ${responseSchemaExpr};
+
+export type ${pascal}Response = z.infer<typeof ${pascal}ResponseSchema>;
+
+export default ${pascal}ResponseSchema;
+${optionDecls}${base64ContentHelper}
+const ${pascal}PayloadSchema = ${payloadSchemaExpr};
+
+export type ${pascal}Payload = z.infer<typeof ${pascal}PayloadSchema>;
+${queryConst}${gqlCacheBlock}${fixtureComments}
+/**
+ * Plugin for ${siteId}. Tries the direct-HTTP hot path first; falls back to
+ * Stagehand automatically on schema drift or bot challenge.
+ */
+export const ${siteId.replace(/-([a-z])/g, (_, c) => c.toUpperCase())}Plugin: SitePlugin<${pascal}Payload, ${pascal}Response> = {
+  meta: {
+    siteId: ${JSON.stringify(siteId)},
+    displayName: ${JSON.stringify(pascal.replace(/([A-Z])/g, " $1").trim())},
+    bodySchema: ${pascal}PayloadSchema,
+    responseSchema: ${pascal}ResponseSchema,
+    defaultBaseUrl: ${JSON.stringify(baseUrl)},${hasMultipartStep ? "\n    multipart: true," : ""}
+  },
+
+  /** Hot path: direct HTTP — no browser, no LLM tokens. */
+  async executeHttp(
+    payload: ${pascal}Payload,
+    ${executeHttpBody.includes("context.") ? "context" : "_context"}: SitePluginContext
+  ): Promise<SitePluginResult<${pascal}Response>> {
+${executeHttpBody}
+  },
+
+  /** Browser fallback: Stagehand + Steel — invoked only when hot path fails. */
+  async execute(
+    payload: ${pascal}Payload,
+    session: BrowserSession,
+    context: SitePluginContext
+  ): Promise<SitePluginResult<${pascal}Response>> {
+    const raw = await run${pascal}BrowserFlow(session.stagehand, context.baseUrl, payload);
+    return { data: raw as ${pascal}Response };
+  },
+};
+`;
+}
+/**
+ * Escape a literal string segment so it is safe INSIDE a JS backtick template
+ * literal — backslashes, backticks, and `${` interpolation starts must all be
+ * neutralized so the only interpolation the emitted flow performs is the
+ * `${payload.X}` splice we insert deliberately.
+ */
+function escapeForTemplateLiteral(segment) {
+    return segment.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+}
+/**
+ * Build the emitted instruction expression for one step: a plain double-quoted
+ * literal when nothing splices, or a backtick template literal with the recon
+ * constant replaced by `${payload.<field>}` when the resolver picks a field.
+ * The first `${RECON_EMAIL}` token (preferred) or the first single-quoted
+ * literal in the instruction is the splice site.
+ */
+function buildStepInstructionExpr(instruction, field) {
+    if (field === null)
+        return JSON.stringify(instruction);
+    // Concatenated so Biome's noTemplateCurlyInString doesn't flag the literal
+    // env-var token — it must stay `${RECON_EMAIL}` to match recon's flow files.
+    const emailToken = `$${"{RECON_EMAIL}"}`;
+    const emailIdx = instruction.indexOf(emailToken);
+    const [before, matched, after] = emailIdx >= 0
+        ? [
+            instruction.slice(0, emailIdx),
+            emailToken,
+            instruction.slice(emailIdx + emailToken.length),
+        ]
+        : (() => {
+            const m = /'[^']*'/.exec(instruction);
+            if (m === null)
+                return [instruction, "", ""];
+            return [
+                instruction.slice(0, m.index),
+                m[0],
+                instruction.slice(m.index + m[0].length),
+            ];
+        })();
+    if (matched === "")
+        return JSON.stringify(instruction);
+    return `\`${escapeForTemplateLiteral(before)}\${payload.${field}}${escapeForTemplateLiteral(after)}\``;
+}
+/**
+ * Rewrites one step instruction into the config-manifest templating form:
+ * the recon splice site (a `${RECON_EMAIL}` token or the first single-quoted
+ * literal) becomes `{{ .request.<field> }}`. Unlike {@link buildStepInstructionExpr}
+ * this yields a plain manifest string, not a TS expression — the runtime
+ * config-plugin resolver, not the code generator, performs the splice.
+ */
+function buildManifestInstruction(instruction, field) {
+    if (field === null)
+        return instruction;
+    const emailToken = `$${"{RECON_EMAIL}"}`;
+    const emailIdx = instruction.indexOf(emailToken);
+    if (emailIdx >= 0) {
+        return (instruction.slice(0, emailIdx) +
+            `{{ .request.${field} }}` +
+            instruction.slice(emailIdx + emailToken.length));
+    }
+    const m = /'[^']*'/.exec(instruction);
+    if (m === null)
+        return instruction;
+    return (instruction.slice(0, m.index) +
+        `{{ .request.${field} }}` +
+        instruction.slice(m.index + m[0].length));
+}
+/**
+ * Emits a config-only plugin manifest (`<siteId>.plugin.json`) from the recon
+ * flow, as an alternative to the `.ts` trio for browser-only sites. Reuses the
+ * SAME `resolveStepPayloadField` splice logic as the browser-flow emitter, so
+ * every `{{ .request.<field> }}` reference also lands in the manifest's request
+ * schema — the two cannot drift. The direct-HTTP hot path is intentionally
+ * omitted; a site that needs it keeps the `.ts` path or wires `spec.httpModule`.
+ */
+function emitConfigManifest(opts) {
+    const { siteId, displayName, baseUrl, flowSteps } = opts;
+    const payloadFieldNames = new Set();
+    const steps = flowSteps.map((step) => {
+        const isObj = typeof step !== "string";
+        const instruction = isObj ? step.step : step;
+        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined);
+        if (field !== null)
+            payloadFieldNames.add(field);
+        const rewritten = buildManifestInstruction(instruction, field);
+        const optional = isObj ? step.optional === true : false;
+        const upload = isObj ? step.upload === true : false;
+        const submitStep = isObj ? step.submitStep === true : false;
+        if (!optional && !upload && !submitStep)
+            return rewritten;
+        return { step: rewritten, optional, upload, submitStep };
+    });
+    const requestProperties = Object.fromEntries([...payloadFieldNames].sort().map((name) => [name, { type: "string" }]));
+    const manifest = {
+        apiVersion: plugin_manifest_envelope_1.CONFIG_PLUGIN_API_VERSION,
+        kind: plugin_manifest_envelope_1.CONFIG_PLUGIN_KIND,
+        metadata: { siteId, displayName },
+        spec: {
+            defaultBaseUrl: baseUrl,
+            request: { type: "object", properties: requestProperties },
+            response: {
+                type: "object",
+                description: "TODO: declare the fields this site returns (recon leaves this empty).",
+                properties: {},
+            },
+            flow: { steps },
+            extract: {
+                instruction: `extract the confirmation id and status for ${siteId}`,
+                schema: {
+                    type: "object",
+                    description: "TODO: declare the fields to extract (empty extracts nothing at runtime).",
+                    properties: {},
+                },
+            },
+        },
+    };
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+/**
+ * Emit the generated browser-flow module and return the accumulated set of
+ * spliced payload-field names. Exported so the anti-drift unit test can assert
+ * every `payload.<field>` the flow references also appears in the contract's
+ * payload schema (both are driven by this same set).
+ */
+function emitBrowserFlowTs(opts) {
+    const { siteId, pascal, flowSteps, isSubmissionFlow, hasMultipartStep = false } = opts;
+    const payloadFieldNames = new Set();
+    const hasUploadStep = flowSteps.some((s) => typeof s !== "string" && s.upload === true);
+    const stepLiterals = flowSteps.map((step) => {
+        const isObj = typeof step !== "string";
+        const instruction = isObj ? step.step : step;
+        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined);
+        if (field !== null)
+            payloadFieldNames.add(field);
+        const instructionExpr = buildStepInstructionExpr(instruction, field);
+        const optional = isObj ? step.optional === true : false;
+        const upload = isObj ? step.upload === true : false;
+        const submitStep = isObj ? step.submitStep === true : false;
+        return `  { instruction: ${instructionExpr}, optional: ${optional}, upload: ${upload}, submitStep: ${submitStep} },`;
+    });
+    const flowStepsBlock = stepLiterals.length > 0
+        ? stepLiterals.join("\n")
+        : `  // TODO: add flow steps from src/sites/${siteId}/recon-flow.json`;
+    // Wire a resumeFixture from the payload's Resume/ResumeFilename/
+    // ResumeContentType fields ONLY when the contract actually carries them
+    // (hasMultipartStep) AND the flow uploads. When a flow has an upload step but
+    // the captures weren't detected as multipart (e.g. a GraphQL site where
+    // multipart detection is dropped), those payload fields don't exist yet — emit
+    // a null + TODO so the generated module still typechecks; the operator adds
+    // the multipart contract fields and wires the fixture during hand-finish.
+    const resumeFixtureExpr = hasUploadStep && hasMultipartStep
+        ? `{
+    buffer: Buffer.from(payload.Resume ?? "", "base64"),
+    name: payload.ResumeFilename ?? "resume.pdf",
+    mimeType: payload.ResumeContentType ?? "application/pdf",
+  }`
+        : hasUploadStep
+            ? `null /* TODO: this flow uploads, but the contract has no Resume multipart\n    fields yet. Add Resume/ResumeFilename/ResumeContentType to the payload\n    schema (set meta.multipart:true) and build the fixture from payload here. */`
+            : "null";
+    const code = `/**
+ * Generated by recon-generate.ts — Stagehand browser fallback for ${siteId}.
+ * Core invokes this automatically when executeHttp throws HttpSchemaError or
+ * HttpBotChallengeError. Update the flow steps and extract schema as needed.
+ *
+ * Steps whose instruction named a candidate PII label have their recon
+ * constant spliced to \`payload.<field>\` so the caller's real applicant reaches
+ * the page; operational-default steps stay literal. The steps run through the
+ * self-heal cascade via runHealingFlow — the same engine the recon CLI uses,
+ * minus its disk-dump/replan layer.
+ */
+
+import type { Stagehand } from "@browserbasehq/stagehand";
+import { z } from "zod/v4";
+
+import { buildAnthropicClient } from "../lib/llm/anthropic-client";
+import { getLogger } from "../lib/logging";
+import { type HealingFlowStep, runHealingFlow, waitForSpaReady } from "../scraper/flow-runner";
+import { guardedExtract } from "../scraper/stagehand-guard";
+import type { ${pascal}Payload, ${pascal}Response } from "@/sites/${siteId}/contract";
+
+const logger = getLogger({ name: "${siteId}-browser-flow" });
+
+const ${pascal}BrowserSchema = z.object({
+  // TODO: define the fields you need — align with ${pascal}Response
+  extraction: z.string(),
+});
+
+/**
+ * Drives ${siteId} through the recon flow and extracts structured data. This is
+ * the browser path; if contract.ts also defines executeHttp, that hot path runs
+ * first and this is the fallback — otherwise this IS the production path.
+ */
+export async function run${pascal}BrowserFlow(
+  stagehand: Stagehand,
+  baseUrl: string,
+  payload: ${pascal}Payload
+): Promise<${pascal}Response> {
+  const page = await stagehand.context.awaitActivePage();
+
+  await page.goto(baseUrl, { waitUntil: "networkidle" });
+  // networkidle can resolve before a Cloudflare-fronted SPA hydrates; wait for
+  // the real DOM so the first steps don't probe an empty shell page and skip.
+  await waitForSpaReady(page, logger);
+
+  const FLOW_STEPS: HealingFlowStep[] = [
+${flowStepsBlock}
+  ];
+
+  // buildAnthropicClient() enables the cascade's attempt-5 rephrase + replan to
+  // recover a stuck step; null on a Bedrock-only deployment, where the cascade
+  // degrades to its deterministic DOM primitives.
+  await runHealingFlow({
+    stagehand,
+    page,
+    steps: FLOW_STEPS,
+    logger,
+    anthropic: buildAnthropicClient(),
+    resumeFixture: ${resumeFixtureExpr},
+  });
+
+  // Schema-enforced extract via guardedExtract: Stagehand 3.4.0 accepts
+  // both Zod v3 and v4 schemas natively (StagehandZodSchema union since
+  // 2.4.3 / PR #944), and the caller-side safeParse defends against SDK
+  // contract drift. Widen ${pascal}BrowserSchema as needed to match the
+  // fields the recon flow actually surfaces.
+  const result = await guardedExtract(
+    stagehand,
+    ${isSubmissionFlow ? `\`drove the ${siteId} submission flow for payload \${JSON.stringify(payload)}\`` : `\`extract results matching query: \${payload.query}\``},
+    ${pascal}BrowserSchema
+  );
+
+  return result as unknown as ${pascal}Response;
+}
+`;
+    return { code, payloadFieldNames };
+}
+function emitIndexTs(opts) {
+    const { siteId } = opts;
+    const camel = siteId.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    return `/**
+ * Generated by recon-generate.ts.
+ * Register this built-in plugin by adding it to \`BUILTIN_SITE_PLUGINS\` in
+ * src/plugins/discover.ts:
+ *
+ *   import { ${camel}Plugin } from "@/sites/${siteId}";
+ *   BUILTIN_SITE_PLUGINS.push(${camel}Plugin as SitePlugin<unknown, unknown>);
+ */
+
+export { ${camel}Plugin } from "@/sites/${siteId}/contract";
+`;
+}
+// ── main ──────────────────────────────────────────────────────────────────────
+async function main() {
+    const args = process.argv.slice(2);
+    let siteId = "";
+    let force = false;
+    let emit = "ts";
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--site-id" && args[i + 1])
+            siteId = args[++i];
+        else if (args[i] === "--force")
+            force = true;
+        else if (args[i] === "--emit" && args[i + 1]) {
+            const value = args[++i];
+            if (value !== "ts" && value !== "config") {
+                logger.error(`--emit must be "ts" or "config", got ${JSON.stringify(value)}`);
+                process.exit(1);
+            }
+            emit = value;
+        }
+    }
+    if (!siteId) {
+        logger.error("--site-id <id> is required");
+        process.exit(1);
+    }
+    const outDir = `src/sites/${siteId}`;
+    const manifestPath = `src/sites/${siteId}/${siteId}.plugin.json`;
+    if (emit === "ts" && (0, node_fs_1.existsSync)(outDir) && !force) {
+        logger.error(`${outDir} already exists — pass --force to overwrite`);
+        process.exit(1);
+    }
+    if (emit === "config" && (0, node_fs_1.existsSync)(manifestPath) && !force) {
+        logger.error(`${manifestPath} already exists — pass --force to overwrite`);
+        process.exit(1);
+    }
+    const captures = (0, recon_shared_1.readJsonDir)(recon_shared_1.CAPTURES_DIR);
+    const replays = (0, recon_shared_1.readJsonDir)(recon_shared_1.REPLAYS_DIR, [
+        "rate-limit.json",
+        "introspection-schema.json",
+    ]);
+    const rateLimits = (() => {
+        try {
+            return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(recon_shared_1.REPLAYS_DIR, "rate-limit.json"), "utf8"));
+        }
+        catch {
+            return [];
+        }
+    })();
+    const auxFiles = (() => {
+        try {
+            return (0, node_fs_1.readdirSync)(recon_shared_1.AUX_DIR)
+                .filter((f) => f.endsWith(".json"))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    })();
+    const flowSteps = (() => {
+        const flowFile = `src/sites/${siteId}/recon-flow.json`;
+        try {
+            const raw = JSON.parse((0, node_fs_1.readFileSync)(flowFile, "utf8"));
+            if (Array.isArray(raw))
+                return raw;
+            if (raw !== null &&
+                typeof raw === "object" &&
+                "steps" in raw &&
+                Array.isArray(raw.steps)) {
+                return raw.steps;
+            }
+            return [];
+        }
+        catch {
+            return [];
+        }
+    })();
+    const pascal = toPascalCase(siteId);
+    const baseUrl = deriveBaseUrl(captures);
+    const baseHeaders = deriveRequestHeaders(captures, replays, baseUrl);
+    const minTime = deriveMinTime(rateLimits);
+    const safeRps = rateLimits.find((f) => f.safeRps !== null)?.safeRps ?? Math.floor(1000 / minTime);
+    const responseBody = firstSuccessfulReplayBody(replays);
+    const gql = isGraphQL(captures);
+    const gqlQuery = firstGraphQLQuery(captures);
+    const endpointPath = firstEndpointPath(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.
+    const rawActionCaptures = gql
+        ? []
+        : collapseRedundantPatches(extractActionSequence(captures, baseUrl));
+    // Form-schema detection runs BEFORE state-indexing so the FieldId/OptionId
+    // UUIDs can be shielded from indexing — those UUIDs are stable schema
+    // anchors that T2/T3 substitution depends on remaining literal in body
+    // templates.
+    const { fieldNameMap, fieldOptionsMap, allSchemaUuids } = detectFormSchemaFieldNames(captures);
+    // Shield ALL FieldId/OptionId UUIDs that appear in any schema response, not
+    // just the ones that detectFormSchemaFieldNames emits a payload name for.
+    // Some fields have FieldNames too long for the naming heuristic (>80 chars)
+    // and would be skipped by fieldNameMap; their FieldIds still need shielding
+    // because they appear as anchors in the T2-substituted body templates.
+    const shieldedUuids = new Set(allSchemaUuids);
+    // T4 — Phase B+C: detect a form-schema GET capture and insert it into the
+    // action sequence at the position observed during recon, so the existing
+    // state-threading machinery can produce its FormHistoryId / section UUIDs /
+    // etc. as state values for downstream POSTs. Strip cache-buster query
+    // params (recon timestamps) from the captured URL so the emitted runtime
+    // fetch uses a clean template. Sites without a schema-fetch capture
+    // (rawSchemaFetch === null) get unchanged behavior.
+    const rawSchemaFetch = gql ? null : detectFormSchemaFetchCapture(captures, baseUrl);
+    const schemaFetchCleaned = rawSchemaFetch
+        ? { ...rawSchemaFetch.capture, url: stripCacheBusterParams(rawSchemaFetch.capture.url) }
+        : null;
+    const actionCaptures = (() => {
+        if (rawActionCaptures.length === 0 || schemaFetchCleaned === null || rawSchemaFetch === null) {
+            return rawActionCaptures;
+        }
+        let insertAt = rawActionCaptures.length;
+        for (let i = 0; i < rawActionCaptures.length; i++) {
+            if (rawActionCaptures[i].index >= rawSchemaFetch.index) {
+                insertAt = i;
+                break;
+            }
+        }
+        return [
+            ...rawActionCaptures.slice(0, insertAt),
+            { capture: schemaFetchCleaned, index: rawSchemaFetch.index },
+            ...rawActionCaptures.slice(insertAt),
+        ];
+    })();
+    const actionCaptureIndices = new Set(actionCaptures.map((a) => a.index));
+    const stateIndex = actionCaptures.length > 1
+        ? indexStateValues(captures, shieldedUuids, actionCaptureIndices)
+        : new Map();
+    const actionSteps = actionCaptures.length > 1 ? compileActionSteps(actionCaptures, stateIndex) : [];
+    const isSubmissionFlow = actionSteps.length > 1;
+    const inputBody = isSubmissionFlow
+        ? (() => {
+            try {
+                return JSON.parse(actionSteps[0].capture.requestPostData ?? "null");
+            }
+            catch {
+                return null;
+            }
+        })()
+        : undefined;
+    const errorSignals = detectErrorSignals(actionSteps);
+    const discoveredFormFields = new Set();
+    const discoveredOptionFields = new Set();
+    // Phase E: maps FieldName-derived raw-option payload field name (e.g.
+    // "AreYouOverTheAgeOf18OptionId") → recon-observed OptionId UUID. Used to
+    // emit `<FieldName>OptionId: z.string()` payload fields with TSDoc docs.
+    const discoveredRawOptionFields = new Map();
+    // Phase F: keys from additional action POST bodies (beyond inputBody/r0)
+    // that get parameterized. Recorded with their value type so the contract
+    // emitter can add them to the payload schema with appropriate Zod types.
+    const discoveredAdditionalBodyKeys = new Map();
+    // G1+G2: partition baseHeaders into three buckets:
+    //   - static: values that don't reference baseUrl or tenant subdomain
+    //   - baseUrl-derived: values containing the recon's baseUrl as substring
+    //     (e.g. Origin, Referer) — emit per-call from payload.BaseUrl
+    //   - tenant-subdomain: values that EXACTLY equal the first subdomain
+    //     (e.g. API-ShortName: "addus") — emit per-call from a payload field
+    const staticBaseHeaders = {};
+    const baseUrlDerivedHeaders = new Map();
+    const tenantSubdomainHeaders = new Map();
+    const firstSubdomain = (() => {
+        try {
+            const host = new URL(baseUrl).hostname;
+            const firstDot = host.indexOf(".");
+            return firstDot === -1 ? host : host.slice(0, firstDot);
+        }
+        catch {
+            return "";
+        }
+    })();
+    for (const [k, v] of Object.entries(baseHeaders)) {
+        if (firstSubdomain.length > 0 && v === firstSubdomain) {
+            tenantSubdomainHeaders.set(k, v);
+        }
+        else if (baseUrl.length > 0 && v.includes(baseUrl)) {
+            baseUrlDerivedHeaders.set(k, v);
+        }
+        else {
+            staticBaseHeaders[k] = v;
+        }
+    }
+    const multiStepBody = isSubmissionFlow
+        ? emitMultiStepExecuteHttp(actionSteps, inputBody, errorSignals, fieldNameMap, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders)
+        : undefined;
+    let base64ContentHelper = "";
+    const base64PatchOverride = new Map();
+    if (isSubmissionFlow && actionSteps.length > 0) {
+        const lastPatchWithContent = [...actionSteps]
+            .reverse()
+            .find((s) => s.capture.method === "PATCH" &&
+            s.capture.requestPostData &&
+            /"Content":"ey[A-Za-z0-9+/=]{100,}"/.test(s.capture.requestPostData));
+        if (lastPatchWithContent) {
+            const b64Match = lastPatchWithContent.capture.requestPostData.match(/"Content":"(ey[A-Za-z0-9+/=]{100,})"/);
+            if (b64Match) {
+                const b64 = b64Match[1];
+                const qMapping = buildQuestionnaireMapping(captures);
+                const personaValues = new Map();
+                const firstPost = captures.find((c) => c.method === "POST" &&
+                    c.url.includes("recruitingCEJobApplicationDrafts") &&
+                    c.requestPostData);
+                if (firstPost?.requestPostData) {
+                    try {
+                        const pb = JSON.parse(firstPost.requestPostData);
+                        if (typeof pb.EmailAddress === "string")
+                            personaValues.set(pb.EmailAddress, "payload.Email");
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+                base64ContentHelper = emitBuildBase64ContentFunction(b64, personaValues, qMapping, pascal);
+                base64PatchOverride.set(lastPatchWithContent.varName, 
+                // biome-ignore lint/suspicious/noTemplateCurlyInString: emitted as generated template-literal source
+                '"Content":"${buildBase64Content(payload, questionnaireId, Number(draftId), String(attachmentId))}"');
+                const draftPostStep = actionSteps.find((s) => s.capture.method === "POST" &&
+                    s.capture.url.includes("recruitingCEJobApplicationDrafts"));
+                if (draftPostStep && !draftPostStep.produces.some((p) => p.name === "draftId")) {
+                    draftPostStep.produces.push({
+                        name: "draftId",
+                        pathExpr: `${draftPostStep.varName}.APPDraftId`,
+                        path: ["APPDraftId"],
+                    });
+                }
+                const attachPostStep = actionSteps.find((s) => s.capture.method === "POST" && s.capture.url.includes("/attachments"));
+                if (attachPostStep && !attachPostStep.produces.some((p) => p.name === "attachmentId")) {
+                    attachPostStep.produces.push({
+                        name: "attachmentId",
+                        pathExpr: `${attachPostStep.varName}.Id`,
+                        path: ["Id"],
+                    });
+                }
+                const questionnaireCapture = captures.find((c) => c.method === "GET" &&
+                    c.url.includes("recruitingCEQuestions") &&
+                    c.url.includes("expand=answers"));
+                let sampleQid;
+                if (questionnaireCapture) {
+                    const qResp = typeof questionnaireCapture.responseBody === "string"
+                        ? JSON.parse(questionnaireCapture.responseBody)
+                        : questionnaireCapture.responseBody;
+                    sampleQid = qResp?.items?.[0]?.QuestionnaireId ?? undefined;
+                }
+                const overrideValue = base64PatchOverride.values().next().value;
+                if (overrideValue) {
+                    const extraVarLines = [];
+                    if (sampleQid) {
+                        extraVarLines.push(`    const questionnaireId = ${sampleQid};`);
+                    }
+                    if (!attachPostStep) {
+                        extraVarLines.push(`    const attachmentId = "";`);
+                    }
+                    if (extraVarLines.length > 0) {
+                        base64PatchOverride.set("__EXTRA_VARS__", extraVarLines.join("\n"));
+                    }
+                }
+                const answersFields = (qMapping ?? []).map((m) => m.payloadField);
+                answersFields.push("SignatureFullName");
+                const answersSchemaFields = answersFields.map((f) => `    ${f}: z.string(),`).join("\n");
+                base64ContentHelper = `\nconst AnswersSchema = z.object({\n${answersSchemaFields}\n});\n${base64ContentHelper}`;
+                const inputKeys = new Set();
+                if (inputBody && typeof inputBody === "object" && !Array.isArray(inputBody)) {
+                    for (const k of Object.keys(inputBody))
+                        inputKeys.add(k);
+                }
+                for (const fld of ["FirstName", "LastName", "Email", "Phone"]) {
+                    if (!inputKeys.has(fld))
+                        discoveredAdditionalBodyKeys.set(fld, "string");
+                }
+            }
+        }
+    }
+    const processedMultiStepBody = isSubmissionFlow
+        ? emitMultiStepExecuteHttp(actionSteps, inputBody, errorSignals, fieldNameMap, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, base64PatchOverride)
+        : multiStepBody;
+    const hasMultipartStep = actionSteps.some((s) => s.isMultipart);
+    // For submission flows the final action's response body is the most useful
+    // shape inference target (it's the terminal success signal). Fall back to
+    // the replay body for single-endpoint sites.
+    const effectiveResponseBody = isSubmissionFlow
+        ? (actionSteps[actionSteps.length - 1].capture.responseBody ?? responseBody)
+        : responseBody;
+    logger.info(`generating plugin for ${siteId} (${gql ? "GraphQL" : 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: pascal,
+            baseUrl,
+            flowSteps,
+        }));
+        logger.info(`wrote ${manifestPath}`);
+        logger.info(`done — review ${manifestPath}, fill in response/extract schemas, then load via BARNACLE_PLUGINS or BARNACLE_PLUGINS_CONFIG_DIR (no compile step)`);
+        return;
+    }
+    (0, node_fs_1.mkdirSync)(`${outDir}/flows`, { recursive: true });
+    // Emit the browser flow first so the SAME payloadFieldNames set that drives
+    // its `payload.<field>` splices also extends the contract's payload schema —
+    // the two artifacts can't drift because one accumulator feeds both.
+    const browserFlow = emitBrowserFlowTs({
+        siteId,
+        pascal,
+        baseUrl,
+        flowSteps,
+        isSubmissionFlow,
+        hasMultipartStep,
+    });
+    (0, node_fs_1.writeFileSync)(`${outDir}/contract.ts`, emitContractTs({
+        siteId,
+        pascal,
+        baseUrl,
+        // G1+G2: only the static headers (no baseUrl/tenant-subdomain references)
+        // get baked into BASE_HEADERS. The rest are emitted per-call from payload.
+        baseHeaders: isSubmissionFlow ? staticBaseHeaders : baseHeaders,
+        minTime,
+        safeRps,
+        responseBody: effectiveResponseBody,
+        gql,
+        gqlQuery,
+        endpointPath,
+        auxFiles,
+        multiStepBody: processedMultiStepBody,
+        base64ContentHelper,
+        inputBody,
+        hasMultipartStep,
+        discoveredFormFields,
+        fieldOptionsMap,
+        discoveredOptionFields,
+        discoveredRawOptionFields,
+        discoveredAdditionalBodyKeys,
+        payloadFieldNames: browserFlow.payloadFieldNames,
+    }));
+    logger.info(`wrote ${outDir}/contract.ts`);
+    (0, node_fs_1.writeFileSync)(`${outDir}/flows/browser-flow.ts`, browserFlow.code);
+    logger.info(`wrote ${outDir}/flows/browser-flow.ts`);
+    (0, node_fs_1.writeFileSync)(`${outDir}/index.ts`, emitIndexTs({ siteId, pascal }));
+    logger.info(`wrote ${outDir}/index.ts`);
+    if (auxFiles.length > 0) {
+        (0, node_fs_1.mkdirSync)(`${outDir}/fixtures`, { recursive: true });
+        for (const f of auxFiles) {
+            (0, node_fs_1.copyFileSync)((0, node_path_1.join)(recon_shared_1.AUX_DIR, f), `${outDir}/fixtures/${f}`);
+        }
+        logger.info(`copied ${auxFiles.length} fixture(s) to ${outDir}/fixtures/`);
+    }
+    logger.info(`done — review ${outDir}/, then register in src/plugins/loader.ts`);
+}
+if (process.argv[1] !== undefined &&
+    (process.argv[1].endsWith("recon-generate.ts") || process.argv[1].endsWith("recon-generate.js"))) {
+    main().catch((err) => {
+        logger.error(`recon-generate failed: ${(0, errors_1.toErrorMessage)(err)}`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=recon-generate.js.map