@enricai/barnacle 1.12.12 → 1.12.13

package/dist/scripts/recon-generate.js

@@ -26,12 +26,14 @@ exports.buildKnownFieldValues = buildKnownFieldValues;
 exports.extractStepPersonaValue = extractStepPersonaValue;
 exports.deriveFillLabelField = deriveFillLabelField;
 exports.harvestPersonaBindings = harvestPersonaBindings;
+exports.resolveCompositePersonaFields = resolveCompositePersonaFields;
 exports.inferZodSchemaFromSamples = inferZodSchemaFromSamples;
 exports.selectPayloadAction = selectPayloadAction;
 exports.selectReturnAction = selectReturnAction;
 exports.selectEffectiveResponseBody = selectEffectiveResponseBody;
 exports.extractEntryUrlParams = extractEntryUrlParams;
 exports.selectPrimaryGraphQLOperation = selectPrimaryGraphQLOperation;
+exports.firstEndpointCapture = firstEndpointCapture;
 exports.firstEndpointPath = firstEndpointPath;
 exports.resolveManifestActionSequence = resolveManifestActionSequence;
 exports.extractActionSequence = extractActionSequence;
@@ -42,16 +44,20 @@ exports.indexLabelValueOptionCodes = indexLabelValueOptionCodes;
 exports.buildSelectOptionResolutions = buildSelectOptionResolutions;
 exports.walkSetCookiePairs = walkSetCookiePairs;
 exports.indexStateValues = indexStateValues;
+exports.sanitizeFixtureIdentifier = sanitizeFixtureIdentifier;
 exports.compileActionSteps = compileActionSteps;
 exports.collectHeaderBindings = collectHeaderBindings;
 exports.deriveProducerBoundaryBindings = deriveProducerBoundaryBindings;
 exports.emitMultiStepExecuteHttp = emitMultiStepExecuteHttp;
+exports.buildContractChecklist = buildContractChecklist;
 exports.emitContractTs = emitContractTs;
+exports.assertRequiredUrlFieldsReferenced = assertRequiredUrlFieldsReferenced;
 exports.emitConfigManifest = emitConfigManifest;
 exports.emitBrowserFlowTs = emitBrowserFlowTs;
 exports.emitIndexTs = emitIndexTs;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const ats_field_vocabulary_1 = require("../lib/ats-field-vocabulary");
 const errors_1 = require("../lib/errors");
 const logging_1 = require("../lib/logging");
 const plugin_api_version_1 = require("../plugins/plugin-api-version");
@@ -348,7 +354,7 @@ function deriveFillLabelField(instruction) {
     const label = /\b(?:fill(?:\s+in)?|enter|type)\s+(?:in\s+)?the\s+(.+?)\s+field\b/i.exec(instruction)?.[1];
     if (label === undefined)
         return null;
-    return fieldNameToPascalCase(label, null);
+    return (0, ats_field_vocabulary_1.resolveCanonicalAtsFieldName)(label) ?? fieldNameToPascalCase(label, null);
 }
 /**
  * Builds the map from a recon persona VALUE (as it appears in the captured
@@ -389,6 +395,71 @@ function harvestPersonaBindings(flowSteps, vocabulary, env) {
     }
     return bindings;
 }
+/**
+ * Detects a flow step whose quoted VALUE is the space-joined concatenation of
+ * two already-known field values (either order), e.g. a signature step whose
+ * label the vocabulary doesn't recognize but whose value is `${FirstName}
+ * ${LastName}`. {@link resolveStepPayloadField} only ever resolves a SINGLE
+ * field per step, so a composite value like this falls through its label
+ * match entirely and the persona literal would otherwise survive emission.
+ *
+ * @returns the two known fields (in the order they appear in the value), or
+ *   null when the step's value is not such a concatenation
+ */
+function resolveCompositePersonaFields(instruction, knownFieldValues) {
+    const spans = findQuoteSpans(instruction);
+    if (spans.length === 0)
+        return null;
+    const value = pickValueSpan(instruction, spans).value;
+    if (value.length === 0)
+        return null;
+    for (const [fieldA, valueA] of knownFieldValues) {
+        for (const [fieldB, valueB] of knownFieldValues) {
+            if (fieldA === fieldB)
+                continue;
+            if (value === `${valueA} ${valueB}`)
+                return { fieldA, fieldB };
+        }
+    }
+    return null;
+}
+/**
+ * Every persona literal a generated flow could leak: each single known field
+ * value, plus both concatenation orders of every distinct pair — the same
+ * composite shape {@link resolveCompositePersonaFields} splices. Feeds
+ * {@link assertNoLeakedPersonaConstant}'s final safety-net scan so a splice
+ * miss (single OR composite) is caught regardless of which matching path
+ * should have handled it.
+ */
+function allPersonaLiterals(knownFieldValues) {
+    const entries = [...knownFieldValues.entries()];
+    const literals = entries.map(([, value]) => value);
+    for (const [fieldA, valueA] of entries) {
+        for (const [fieldB, valueB] of entries) {
+            if (fieldA === fieldB)
+                continue;
+            literals.push(`${valueA} ${valueB}`);
+        }
+    }
+    return literals.filter((value) => value.length > 0);
+}
+/**
+ * Final safety net: throws if any known persona constant — single field or
+ * composite concatenation — still appears verbatim as a quoted literal in the
+ * fully-built flow code. Every splice path above (vocabulary match, derived
+ * label, composite match) is a heuristic; this is the loud failure that
+ * catches whatever heuristic missed rather than shipping the recon identity's
+ * own data as a frozen literal in every caller's submission.
+ *
+ * @throws when a persona literal survives emission
+ */
+function assertNoLeakedPersonaConstant(code, knownFieldValues) {
+    for (const value of allPersonaLiterals(knownFieldValues)) {
+        if (code.includes(`'${value}'`)) {
+            throw new Error(`recon-generate: persona constant '${value}' survived emission — a flow step failed to splice its known field value to payload.<field>`);
+        }
+    }
+}
 /**
  * How deep to infer before collapsing to z.unknown(). Deep enough to reach the
  * fields that carry meaning on real inventory APIs — a listing's price
@@ -703,9 +774,6 @@ function deriveRequestHeaders(captures, replays, baseUrl, submitPatterns = null)
 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;
 }
@@ -789,11 +857,17 @@ function selectPrimaryGraphQLOperation(captures, flowSteps, vocabulary, env = pr
     })();
     return { capture: winner.capture, endpointPath };
 }
-function firstEndpointPath(captures) {
+/**
+ * Resolves the same primary-endpoint capture that {@link firstEndpointPath}
+ * derives a path string from, so non-GraphQL flows can also read that
+ * capture's own `.responseBody` instead of an array-order-first replay.
+ */
+function firstEndpointCapture(captures) {
     const nonGetCaptures = captures.filter((c) => c.method !== "GET");
     for (const c of nonGetCaptures) {
         try {
-            return new URL(c.url).pathname;
+            new URL(c.url);
+            return c;
         }
         catch {
             // skip
@@ -801,13 +875,23 @@ function firstEndpointPath(captures) {
     }
     for (const c of captures) {
         try {
-            return new URL(c.url).pathname;
+            new URL(c.url);
+            return c;
         }
         catch {
             // skip
         }
     }
-    return "/api/search";
+    return null;
+}
+function firstEndpointPath(captures) {
+    try {
+        const capture = firstEndpointCapture(captures);
+        return capture ? new URL(capture.url).pathname : "/api/search";
+    }
+    catch {
+        return "/api/search";
+    }
 }
 /**
  * Builds the compiled submit-pattern predicate. A flow-declared regex that
@@ -1344,6 +1428,12 @@ function looksLikeSectionFieldsArray(arr, formSchema) {
 }
 function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap, formSchema) {
     let currentPrefix = null;
+    // Repeated/indexed headings (e.g. "Reference #1") must keep suppressing
+    // canonicalization to avoid colliding a nested entity's field with the
+    // applicant's own top-level field. Plain grouping headings with no
+    // repetition marker (e.g. "CONTACT INFORMATION") still describe the
+    // applicant, so canonicalization must still apply under them.
+    let currentPrefixIsRepeated = false;
     const usedNames = new Set([...fieldNameMap.values()]);
     // First field-name key is the machine code (preferred, PascalCased directly);
     // any later key is a human label (subject to the section-heading heuristic).
@@ -1358,8 +1448,9 @@ function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap, formSchem
         const name = labelKey !== undefined ? obj[labelKey] : obj[codeKey ?? ""];
         let semantic = null;
         if (typeof sourceCode === "string" && sourceCode.trim().length > 0) {
-            semantic = sourceCodeToPascalCase(sourceCode);
+            semantic = (0, ats_field_vocabulary_1.resolveCanonicalAtsFieldName)(sourceCode) ?? sourceCodeToPascalCase(sourceCode);
             currentPrefix = null;
+            currentPrefixIsRepeated = false;
         }
         else if (typeof name === "string" && name.trim().length > 0 && name.length < 250) {
             const hasNoSourceCode = typeof sourceCode !== "string" || sourceCode.trim().length === 0;
@@ -1375,10 +1466,23 @@ function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap, formSchem
                 const headingPrefix = fieldNameToPascalCase(name, null);
                 if (headingPrefix !== null) {
                     currentPrefix = headingPrefix;
+                    // Only a repeated/indexed heading (e.g. "Reference #1", "Employer 2")
+                    // marks a nested sub-entity whose fields must stay prefixed to avoid
+                    // colliding with the applicant's own top-level field name. A trailing
+                    // 1-2 digit index, standing on its own word boundary, is a repetition
+                    // marker; a longer digit run (e.g. a year in "EMPLOYMENT HISTORY
+                    // 2024") is not, and must still canonicalize underneath it.
+                    currentPrefixIsRepeated = /\b\d{1,2}\s*$/.test(name) || name.includes("#");
                 }
                 continue;
             }
             semantic = fieldNameToPascalCase(name, currentPrefix);
+            if (!currentPrefixIsRepeated) {
+                const canonical = (0, ats_field_vocabulary_1.resolveCanonicalAtsFieldName)(name);
+                if (canonical !== null) {
+                    semantic = canonical;
+                }
+            }
         }
         if (semantic !== null && !fieldNameMap.has(fieldId)) {
             let unique = semantic;
@@ -2124,6 +2228,19 @@ function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndi
 function isValidJsIdentifier(s) {
     return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s);
 }
+/** Derives a valid camelCase identifier from a fixture filename (e.g.
+ * "10219132.json" -> "fixture10219132", "acme-metrics.config.json" ->
+ * "acmeMetricsConfig") for use in generated `loadFixture` const lines. */
+function sanitizeFixtureIdentifier(filename) {
+    const camelCased = filename
+        .replace(/\.json$/, "")
+        .split(/[^A-Za-z0-9_$]+/)
+        .filter(Boolean)
+        .map((part, i) => (i === 0 ? part : `${part.charAt(0).toUpperCase()}${part.slice(1)}`))
+        .join("");
+    const stripped = camelCased.replace(/[^A-Za-z0-9_$]/g, "");
+    return isValidJsIdentifier(stripped) ? stripped : `fixture${stripped}`;
+}
 /**
  * Converts a path like ["Auth","Token"] to a JS access expression ".Auth.Token".
  * Identifier segments use dot access; numeric / non-identifier segments use
@@ -3465,8 +3582,46 @@ function renderGqlVariablesExpr(variables, payloadFieldNames) {
     });
     return entries.length > 0 ? `{ ${entries.join(", ")} }` : "{}";
 }
+/**
+ * Same review-checklist items the pre-move contract.ts header used to embed,
+ * now surfaced on recon-generate's own stdout instead of the shipped file —
+ * call with the exact same opts passed to {@link emitContractTs} so the two
+ * can never drift out of sync.
+ */
+function buildContractChecklist(opts) {
+    const { pascal, gql, omitExecuteHttp, multiStepBody } = opts;
+    const queryChecklistLine = !omitExecuteHttp && gql
+        ? `Trim UI-only fields from ${pascal.toUpperCase()}_QUERY (keep only fields you need)`
+        : "";
+    // Multi-step flows validate each call against its own per-call inferred
+    // schema (emitMultiStepExecuteHttp) — narrowing ResponseSchema only changes
+    // what executeHttp promises ITS OWN caller, never a per-call validator, so
+    // the checklist item must say that explicitly. Single-endpoint plugins have
+    // exactly one call, so the client schema and that call's validator are the
+    // same schema and the shorter wording stays accurate. Browser-flow-only
+    // plugins have no executeHttp at all, so ResponseSchema is only ever the
+    // browser flow's own return-value contract.
+    const narrowSchemaChecklistLine = omitExecuteHttp
+        ? `Narrow ${pascal}ResponseSchema to match what the browser flow should promise ITS CALLER — this flow could not synthesize a trustworthy executeHttp (a required value from the captured sequence never resolved), so it ships browser-only`
+        : multiStepBody
+            ? `Narrow ${pascal}ResponseSchema to match what executeHttp should promise ITS CALLER — this is the plugin's own return-value contract, not a per-call validator (each call in the flow is already checked against its own inferred schema)`
+            : `Narrow ${pascal}ResponseSchema to match the real response shape`;
+    const baseHeadersChecklistLine = omitExecuteHttp
+        ? ""
+        : "Verify BASE_HEADERS — remove any that aren't load-bearing";
+    const outOfTreeChecklistLine = omitExecuteHttp
+        ? "Out-of-tree: `pnpm add zod` — this file imports it directly, and a strict node_modules layout (pnpm) won't resolve it as a transitive dep of @enricai/barnacle alone"
+        : "Out-of-tree: `pnpm add bottleneck zod` — this file imports both directly, and a strict node_modules layout (pnpm) won't resolve them as transitive deps of @enricai/barnacle alone";
+    return [
+        queryChecklistLine,
+        narrowSchemaChecklistLine,
+        `Adjust ${pascal}PayloadSchema to your actual request parameters`,
+        baseHeadersChecklistLine,
+        outOfTreeChecklistLine,
+    ].filter((line) => line !== "");
+}
 function emitContractTs(opts) {
-    const { siteId, pascal, baseUrl, baseHeaders, minTime, safeRps, responseBody, gql, gqlQuery, endpointPath, gqlOperationName, gqlVariables, auxFiles, multiStepBody, omitExecuteHttp = false, inputBody, hasMultipartStep = false, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, discoveredStructuredKeys, payloadFieldNames, headerBindings = [], } = opts;
+    const { siteId, pascal, baseUrl, baseHeaders, minTime, safeRps, hasRateLimitProbeData = false, responseBody, gql, gqlQuery, endpointPath, gqlOperationName, gqlVariables, auxFiles, multiStepBody, omitExecuteHttp = false, isSubmissionFlow = false, inputBody, hasMultipartStep = false, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, discoveredStructuredKeys, payloadFieldNames, headerBindings = [], } = opts;
     // This is the CLIENT-level schema — createHttpClient's default, and the
     // plugin's caller-facing contract (what executeHttp's return value promises
     // its own caller). It does NOT validate any individual call in a multi-step
@@ -3485,8 +3640,16 @@ function emitContractTs(opts) {
     // Single-endpoint plugins keep the same inferred-schema treatment, since
     // there both roles (client default and sole call) coincide.
     // Browser-flow-only plugins have no HTTP call to infer a shape from —
-    // z.unknown() there is the honest gap, not a narrowing shortcut.
-    const responseSchemaExpr = omitExecuteHttp ? `z.unknown()` : inferZodSchema(responseBody);
+    // z.unknown() there is the honest gap, not a narrowing shortcut. A
+    // submission flow is the exception: runHealingFlow's submitStep
+    // verification already throws StepVerificationError on failure, so a
+    // successful return IS a real signal — z.unknown() would be dishonest
+    // in the other direction, hiding a field the flow can actually promise.
+    const responseSchemaExpr = omitExecuteHttp && isSubmissionFlow
+        ? `z.object({ verified: z.boolean() })`
+        : omitExecuteHttp
+            ? `z.unknown()`
+            : inferZodSchema(responseBody);
     // Multi-step flows that include a multipart upload need the binary asset
     // on the payload. ApplicantContactSchema (via ApplicantResumeSchema) already
     // declares Resume/ResumeContentType/ResumeFilename, so submission flows
@@ -3632,6 +3795,7 @@ function emitContractTs(opts) {
     const sortedAdditionalKeys = discoveredAdditionalBodyKeys
         ? [...discoveredAdditionalBodyKeys.entries()].sort(([a], [b]) => a.localeCompare(b))
         : [];
+    let usesMultipartBoolean = false;
     for (const [name, kind] of sortedAdditionalKeys) {
         if (isReservedByApplicantContactSchema(name))
             continue;
@@ -3647,6 +3811,8 @@ function emitContractTs(opts) {
                 : payloadNeedsMultipart
                     ? "multipartBoolean()"
                     : "z.boolean()";
+        if (zod === "multipartBoolean()")
+            usesMultipartBoolean = true;
         addExtendField(name, `  ${name}: ${zod},`);
     }
     // Mechanism B: nested caller structures become payload fields carrying their
@@ -3675,6 +3841,9 @@ function emitContractTs(opts) {
     const internalRequestReferenceExpr = inputBody
         ? inferZodSchema(inputBody, 0, "", { multipartCoerce: hasMultipartStep })
         : null;
+    if (internalRequestReferenceExpr?.includes("multipartBoolean(")) {
+        usesMultipartBoolean = true;
+    }
     // All field sources above are merged into a SINGLE `.extend({...})` object
     // literal, keyed by field name — a name that recurs across sources (or
     // that collides with the base extend's own Email/ClickUrl/Answers) collapses
@@ -3684,12 +3853,12 @@ function emitContractTs(opts) {
     const payloadSchemaExpr = `${basePayloadSchemaExpr}${mergedExtension}`;
     // basePayloadSchemaExpr's own Answers field always wraps in
     // multipartJsonObject() for submission flows (inputBody set);
-    // multipartBoolean() and the structured-keys wrapping above are needed
-    // whenever payloadNeedsMultipart is true (an upload step OR a non-scalar
-    // discoveredStructuredKeys field).
+    // multipartBoolean() is only imported when a boolean field was actually
+    // wrapped in it above (an additional-body-key or an inputBody field under
+    // multipartCoerce) — payloadNeedsMultipart alone doesn't imply that.
     // Named imports from the same module are combined into one import statement.
     const zodMultipartNamedImports = [
-        ...(payloadNeedsMultipart ? ["multipartBoolean"] : []),
+        ...(usesMultipartBoolean ? ["multipartBoolean"] : []),
         ...(inputBody || (payloadNeedsMultipart && sortedStructuredEntries.length > 0)
             ? ["multipartJsonObject"]
             : []),
@@ -3703,7 +3872,7 @@ function emitContractTs(opts) {
         ? `import { ApplicantContactSchema } from "${ENGINE_PKG}/lib/applicant-payload";\n`
         : "";
     // Content-Type must be absent from multipart fetch calls so FormData can inject the boundary.
-    const caseInsensitiveHeadersImport = hasMultipartStep
+    const caseInsensitiveHeadersImport = hasMultipartStep && !omitExecuteHttp
         ? `import { omitHeaderCaseInsensitive } from "${ENGINE_PKG}/lib/case-insensitive-headers";\n`
         : "";
     // Emit identifier-shaped keys unquoted so Biome's formatter doesn't rewrite
@@ -3768,7 +3937,7 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
     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());`)
+                .map((f) => `// const ${sanitizeFixtureIdentifier(f)} = loadFixture(${JSON.stringify(siteId)}, ${JSON.stringify(f)}, z.unknown());`)
                 .join("\n") +
             "\n"
         : "";
@@ -3791,22 +3960,6 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
 export const ${pascal}InternalRequestReference = ${internalRequestReferenceExpr};
 `
         : "";
-    const queryChecklistLine = !omitExecuteHttp && gql
-        ? `\n *   [ ] Trim UI-only fields from ${pascal.toUpperCase()}_QUERY (keep only fields you need)`
-        : "";
-    // Multi-step flows validate each call against its own per-call inferred
-    // schema (emitMultiStepExecuteHttp) — narrowing ResponseSchema only changes
-    // what executeHttp promises ITS OWN caller, never a per-call validator, so
-    // the checklist item must say that explicitly. Single-endpoint plugins have
-    // exactly one call, so the client schema and that call's validator are the
-    // same schema and the shorter wording stays accurate. Browser-flow-only
-    // plugins have no executeHttp at all, so ResponseSchema is only ever the
-    // browser flow's own return-value contract.
-    const narrowSchemaChecklistLine = omitExecuteHttp
-        ? `\n *   [ ] Narrow ${pascal}ResponseSchema to match what the browser flow should promise ITS CALLER — this flow could not synthesize a trustworthy executeHttp (a required value from the captured sequence never resolved), so it ships browser-only`
-        : multiStepBody
-            ? `\n *   [ ] Narrow ${pascal}ResponseSchema to match what executeHttp should promise ITS CALLER — this is the plugin's own return-value contract, not a per-call validator (each call in the flow is already checked against its own inferred schema)`
-            : `\n *   [ ] Narrow ${pascal}ResponseSchema to match the real response shape`;
     const camel = siteId.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
     // Browser-flow-only plugins need neither Bottleneck (no rate-limited HTTP
     // client) nor BASE_HEADERS (no per-call headers to bake in) — both would
@@ -3819,10 +3972,13 @@ const BASE_HEADERS: Record<string, string> = {
 ${headersLiteral},
 };
 `;
+    const rateLimitComment = hasRateLimitProbeData
+        ? `// Safe ceiling: ${safeRps} rps — from recon rate-limit probe.`
+        : `// Safe ceiling: ${safeRps} rps — DEFAULT (no rate-limit probe data; run recon:http).`;
     const limiterBlock = omitExecuteHttp
         ? ""
         : `
-// Safe ceiling: ${safeRps} rps — from recon rate-limit probe.
+${rateLimitComment}
 const limiter = new Bottleneck({ minTime: ${minTime} });
 `;
     const executeHttpMethodBlock = omitExecuteHttp
@@ -3840,23 +3996,15 @@ ${executeHttpBody}
         ? `/**
  * Plugin for ${siteId}. Browser-flow-only: the captured multi-step submission
  * sequence could not be synthesized into a trustworthy direct-HTTP hot path
- * (see the checklist above), so this always runs via Stagehand.
+ * (see recon-generate's review checklist, logged to stdout at generation
+ * time), so this always runs via Stagehand.
  */`
         : `/**
  * Plugin for ${siteId}. Tries the direct-HTTP hot path first; falls back to
  * Stagehand automatically on schema drift or bot challenge.
  */`;
-    const baseHeadersChecklistLine = omitExecuteHttp
-        ? ""
-        : `\n *   [ ] Verify BASE_HEADERS — remove any that aren't load-bearing`;
-    const outOfTreeChecklistLine = omitExecuteHttp
-        ? `\n *   [ ] Out-of-tree: \`pnpm add zod\` — this file imports it directly, and a\n *       strict node_modules layout (pnpm) won't resolve it as a transitive\n *       dep of @enricai/barnacle alone`
-        : `\n *   [ ] Out-of-tree: \`pnpm add bottleneck zod\` — this file imports both\n *       directly, and a strict node_modules layout (pnpm) won't resolve\n *       them as transitive deps of @enricai/barnacle alone`;
     return `/**
  * Generated by recon-generate.ts — review before shipping.
- *
- * Checklist:${queryChecklistLine}${narrowSchemaChecklistLine}
- *   [ ] Adjust ${pascal}PayloadSchema to your actual request parameters${baseHeadersChecklistLine}${outOfTreeChecklistLine}
  */
 
 ${bottleneckImport}import { z } from "zod/v4";
@@ -3880,11 +4028,11 @@ ${pluginDocComment}
 export const ${camel}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)},
-    // multipart is required whenever the flow itself uploads a file
+    ${payloadNeedsMultipart || inputBody
+        ? `// multipart is required whenever the flow itself uploads a file
     // (hasMultipartStep), OR this is a submission flow (inputBody set) since
     // basePayloadSchemaExpr always requires a real Resume Buffer via
     // ApplicantContactSchema regardless of whether the recorded browser flow
@@ -3892,7 +4040,8 @@ export const ${camel}Plugin: SitePlugin<${pascal}Payload, ${pascal}Response> = {
     // discoveredStructuredKeys field (payloadNeedsMultipart), since the
     // multipart wire format is what makes that field's JSON-stringified
     // encoding parseable.
-    apiVersion: ${JSON.stringify(plugin_api_version_1.PLUGIN_API_VERSION)},${payloadNeedsMultipart || inputBody ? "\n    multipart: true," : ""}
+    `
+        : ""}apiVersion: ${JSON.stringify(plugin_api_version_1.PLUGIN_API_VERSION)},${payloadNeedsMultipart || inputBody ? "\n    multipart: true," : ""}
   },
 ${executeHttpMethodBlock}
   /** Browser fallback: Stagehand + Steel — invoked only when hot path fails. */
@@ -3901,7 +4050,7 @@ ${executeHttpMethodBlock}
     session: BrowserSession,
     context: SitePluginContext
   ): Promise<SitePluginResult<${pascal}Response>> {
-    const raw = await run${pascal}BrowserFlow(session.stagehand, context.baseUrl, payload);
+    const raw = await run${pascal}BrowserFlow(session.stagehand, ${inputBody ? "payload.ClickUrl" : "context.baseUrl"}, payload);
     return { data: raw as ${pascal}Response };
   },
 };
@@ -3912,6 +4061,29 @@ ${executeHttpMethodBlock}
 export { ${camel}Plugin as plugin };
 `;
 }
+/**
+ * Fails generation loudly when the payload schema `emitContractTs` just wrote
+ * declares a required `*Url` field (e.g. `ClickUrl`) that neither the
+ * contract's own `execute()` call site nor the emitted browser flow ever
+ * reads as `payload.<Field>`. A required URL field nothing dereferences means
+ * the flow enters on the wrong page (see
+ * docs/recon-generate-browser-flow-entry-url-pii-and-unverified-submit.md
+ * defect 1) — this generalizes the check past ClickUrl so any future
+ * required URL field regresses loudly instead of silently.
+ */
+function assertRequiredUrlFieldsReferenced(contractCode, browserFlowCode) {
+    const urlFieldLinePattern = /^\s*(\w*Url\w*):\s*z\.\w+\(.*$/gm;
+    const emittedCode = `${contractCode}\n${browserFlowCode}`;
+    const unreferenced = [...contractCode.matchAll(urlFieldLinePattern)]
+        .filter((match) => !match[0].includes(".optional("))
+        .map((match) => match[1])
+        .filter((name) => name !== undefined)
+        .filter((name) => !emittedCode.includes(`payload.${name}`));
+    if (unreferenced.length === 0)
+        return;
+    throw new Error(`recon-generate: required URL field(s) ${unreferenced.join(", ")} declared on the payload schema ` +
+        `but never referenced by the emitted contract or browser flow — the flow would enter on the wrong page`);
+}
 /**
  * Escape a literal string segment so it is safe INSIDE a JS backtick template
  * literal — backslashes, backticks, and `${` interpolation starts must all be
@@ -3939,6 +4111,19 @@ function buildStepInstructionExpr(instruction, field) {
         return JSON.stringify(instruction);
     return `\`${escapeForTemplateLiteral(site.before)}\${payload.${field}}${escapeForTemplateLiteral(site.after)}\``;
 }
+/**
+ * Build the emitted instruction expression for a step whose value is the
+ * concatenation of two known fields ({@link resolveCompositePersonaFields}):
+ * a backtick template literal with the whole quoted value replaced by
+ * `${payload.<fieldA>} ${payload.<fieldB>}`, preserving the single space the
+ * concatenation was built with.
+ */
+function buildCompositeStepInstructionExpr(instruction, fieldA, fieldB) {
+    const site = locateSpliceSite(instruction);
+    if (site === null)
+        return JSON.stringify(instruction);
+    return `\`${escapeForTemplateLiteral(site.before)}\${payload.${fieldA}} \${payload.${fieldB}}${escapeForTemplateLiteral(site.after)}\``;
+}
 /**
  * Build the emitted instruction expression for a step whose splice site is the
  * reserved `${RECON_PASSWORD}` token: a backtick template literal with the
@@ -4010,7 +4195,7 @@ function jsonSchemaTypeOf(value) {
  * browser `flow` is the only execution path, and the field is omitted.
  */
 function emitConfigManifest(opts) {
-    const { siteId, displayName, baseUrl, flowSteps, vocabulary, inputBody, recoveredFields, httpModulePath, env = process.env, } = opts;
+    const { siteId, displayName, baseUrl, flowSteps, vocabulary, inputBody, recoveredFields, httpModulePath, isSubmissionFlow = false, env = process.env, } = opts;
     const payloadFieldNames = new Set();
     const knownFieldValues = buildKnownFieldValues(flowSteps, vocabulary ?? vocabulary_1.EMPTY_VOCABULARY, env);
     const steps = flowSteps.map((step) => {
@@ -4042,6 +4227,23 @@ function emitConfigManifest(opts) {
             return rewritten;
         return { step: rewritten, optional, upload, submitStep };
     });
+    // The last step of a submission flow is structurally the submit — force
+    // submitStep:true even when the source recon-flow.json step never declared
+    // it, mirroring emitBrowserFlowTs's forcing (see there) so a config-plugin
+    // load of this manifest also gates on runHealingFlow's submitStep verification.
+    const lastStepIndex = steps.length - 1;
+    const lastStep = steps[lastStepIndex];
+    if (isSubmissionFlow && lastStep !== undefined) {
+        steps[lastStepIndex] =
+            typeof lastStep === "string"
+                ? { step: lastStep, optional: false, upload: false, submitStep: true }
+                : {
+                    step: lastStep.step,
+                    optional: lastStep.optional,
+                    upload: lastStep.upload,
+                    submitStep: true,
+                };
+    }
     // The request surface, widest wins: a flow splice, a recovered form field, or
     // a key from the first POST body all name something a caller controls. Splices
     // and recovered fields are strings (the browser flow fills them as text); a
@@ -4062,7 +4264,7 @@ function emitConfigManifest(opts) {
     const manifest = {
         apiVersion: plugin_manifest_envelope_1.CONFIG_PLUGIN_API_VERSION,
         kind: plugin_manifest_envelope_1.CONFIG_PLUGIN_KIND,
-        metadata: { siteId, displayName },
+        metadata: { siteId, ...(displayName !== undefined && { displayName }) },
         spec: {
             defaultBaseUrl: baseUrl,
             ...(httpModulePath ? { httpModule: httpModulePath } : {}),
@@ -4114,14 +4316,30 @@ function emitBrowserFlowTs(opts) {
             return `  { instruction: ${instructionExpr}, optional: ${optional}, upload: ${upload}, submitStep: ${submitStep} },`;
         }
         const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary, knownFieldValues);
+        const composite = field === null && !(isObj && step.payloadFieldNone)
+            ? resolveCompositePersonaFields(instruction, knownFieldValues)
+            : null;
         if (field !== null)
             payloadFieldNames.add(field);
-        const instructionExpr = buildStepInstructionExpr(instruction, field);
+        if (composite !== null) {
+            payloadFieldNames.add(composite.fieldA);
+            payloadFieldNames.add(composite.fieldB);
+        }
+        const instructionExpr = composite !== null
+            ? buildCompositeStepInstructionExpr(instruction, composite.fieldA, composite.fieldB)
+            : 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} },`;
     });
+    // The last step of a submission flow is structurally the submit — force
+    // submitStep:true even when the source recon-flow.json step never declared
+    // it, so the engine's pre-submit probe/StepVerificationError actually gates it.
+    const lastStepLiteral = stepLiterals.at(-1);
+    if (isSubmissionFlow && lastStepLiteral !== undefined) {
+        stepLiterals[stepLiterals.length - 1] = lastStepLiteral.replace(/submitStep: (true|false)(?= \},)/, "submitStep: true");
+    }
     const flowStepsBlock = stepLiterals.length > 0
         ? stepLiterals.join("\n")
         : "  // TODO: no flow steps were parsed. Re-run recon-browser with a --flow\n" +
@@ -4148,8 +4366,8 @@ function emitBrowserFlowTs(opts) {
  * 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
+ * Steps whose instruction named a labeled payload field have their recon
+ * constant spliced to \`payload.<field>\` so the caller's real value 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.
@@ -4166,9 +4384,13 @@ import type { ${pascal}Payload, ${pascal}Response } from "@/sites/${siteId}/cont
 
 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(),
+const ${pascal}BrowserSchema = z.object({${isSubmissionFlow
+        ? `
+  // runHealingFlow throws StepVerificationError on a failed submitStep, so
+  // reaching this point already proves the submission verified.
+  verified: z.boolean(),`
+        : `
+  extraction: z.string(),`}
 });
 
 /**
@@ -4178,13 +4400,13 @@ const ${pascal}BrowserSchema = z.object({
  */
 export async function run${pascal}BrowserFlow(
   stagehand: Stagehand,
-  baseUrl: string,
+  ${isSubmissionFlow ? "entryUrl" : "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
+  await page.goto(${isSubmissionFlow ? "entryUrl" : "baseUrl"}, { waitUntil: "networkidle" });
+  // networkidle can resolve before a bot-managed/CDN-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);
 ${usesThrowawayPassword ? "\n  // Minted once per run — the flow needs a credential to authenticate, but\n  // there is no caller-supplied Password field on the payload to splice.\n  const throwawayPassword = generateThrowawayPassword();\n" : ""}
@@ -4210,16 +4432,37 @@ ${flowStepsBlock}
   // 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.
+  // fields the recon flow actually surfaces.${isSubmissionFlow
+        ? `
+  // runHealingFlow above already verified the submit (submitStep:true), so the
+  // application is already committed at the ATS. A schema-validation or
+  // watchdog-timeout throw from this trailing confirmation extract must not
+  // propagate and trigger a duplicate re-dispatch — catch it, log it, and
+  // degrade to a not-confirmed result instead.
+  try {
+    const result = await guardedExtract(
+      stagehand,
+      "is a submission confirmation shown, and what is its reference number?",
+      ${pascal}BrowserSchema
+    );
+    return { ...result, verified: true } as unknown as ${pascal}Response;
+  } catch (error) {
+    logger.error(\`GuardedExtractError: post-submit confirmation extract failed on an already-verified submit, degrading to not-confirmed: \${error}\`);
+    return { verified: false } as unknown as ${pascal}Response;
+  }
+}
+`
+        : `
   const result = await guardedExtract(
     stagehand,
-    ${isSubmissionFlow ? `\`drove the ${siteId} submission flow for payload \${JSON.stringify(payload)}\`` : `\`extract results matching query: \${payload.query}\``},
+    \`extract results matching query: \${payload.query}\`,
     ${pascal}BrowserSchema
   );
 
   return result as unknown as ${pascal}Response;
 }
-`;
+`}`;
+    assertNoLeakedPersonaConstant(code, knownFieldValues);
     return { code, payloadFieldNames };
 }
 /** Generates the site's index.ts barrel — exported so the out-of-tree e2e
@@ -4335,6 +4578,9 @@ async function main() {
         "rate-limit.json",
         "introspection-schema.json",
     ]);
+    if (replays.length === 0) {
+        logger.warn(`recon-generate: run dir ${runRoot} has an empty replays/ directory — recon:http (rate-limit probe) and replay validation were skipped, so this contract's timing and shape are unvalidated`);
+    }
     const rateLimits = (() => {
         try {
             return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(replaysDir, "rate-limit.json"), "utf8"));
@@ -4410,8 +4656,8 @@ async function main() {
     const baseUrl = deriveBaseUrl(captures);
     const baseHeaders = deriveRequestHeaders(captures, replays, baseUrl, submitPatterns);
     const minTime = deriveMinTime(rateLimits);
+    const hasRateLimitProbeData = rateLimits.some((f) => f.safeRps !== null);
     const safeRps = rateLimits.find((f) => f.safeRps !== null)?.safeRps ?? Math.floor(1000 / minTime);
-    const responseBody = firstSuccessfulReplayBody(replays);
     const gql = isGraphQL(captures);
     // Hoisted so both the primary-operation gate below and rawActionCaptures
     // (further down) read the same computed sequence instead of calling the
@@ -4423,6 +4669,11 @@ async function main() {
         : null;
     const gqlQuery = primaryGraphQLOperation?.capture.query ?? firstGraphQLQuery(captures);
     const endpointPath = primaryGraphQLOperation?.endpointPath ?? firstEndpointPath(captures);
+    // Derived from the primary operation's own Phase-1 capture, never from
+    // replay array order -- a replay's body reflects whichever endpoint fired
+    // first, not necessarily the primary operation, and only exists once
+    // recon:http has run.
+    const responseBody = (primaryGraphQLOperation?.capture ?? firstEndpointCapture(captures))?.responseBody ?? null;
     // 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.
@@ -4656,12 +4907,12 @@ async function main() {
         (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
         (0, node_fs_1.writeFileSync)(manifestPath, emitConfigManifest({
             siteId,
-            displayName: pascal,
             baseUrl,
             flowSteps,
             vocabulary,
             inputBody,
             recoveredFields: [...discoveredFormFields, ...discoveredOptionFields],
+            isSubmissionFlow,
             // A submission flow is the case where the `.ts` emit carries an
             // executeHttp hot path; point the manifest at where the operator drops
             // the compiled module rather than silently dropping the direct path.
@@ -4687,7 +4938,7 @@ async function main() {
         vocabulary,
         frameSelector,
     });
-    (0, node_fs_1.writeFileSync)(`${outDir}/contract.ts`, emitContractTs({
+    const contractOpts = {
         siteId,
         pascal,
         baseUrl,
@@ -4696,6 +4947,7 @@ async function main() {
         baseHeaders: isSubmissionFlow ? staticBaseHeaders : baseHeaders,
         minTime,
         safeRps,
+        hasRateLimitProbeData,
         responseBody: effectiveResponseBody,
         gql,
         gqlQuery,
@@ -4705,6 +4957,7 @@ async function main() {
         auxFiles,
         multiStepBody,
         omitExecuteHttp: browserFlowOnly,
+        isSubmissionFlow,
         inputBody,
         hasMultipartStep,
         discoveredFormFields,
@@ -4715,8 +4968,17 @@ async function main() {
         discoveredStructuredKeys,
         payloadFieldNames: browserFlow.payloadFieldNames,
         headerBindings,
-    }));
+    };
+    const contractCode = emitContractTs(contractOpts);
+    // Fails loudly rather than shipping a flow that requires a URL field it
+    // never reads (see assertRequiredUrlFieldsReferenced doc comment).
+    assertRequiredUrlFieldsReferenced(contractCode, browserFlow.code);
+    (0, node_fs_1.writeFileSync)(`${outDir}/contract.ts`, contractCode);
     logger.info(`wrote ${outDir}/contract.ts`);
+    // Same opts fed to emitContractTs above, so this can never drift from what
+    // the header used to embed.
+    const checklist = buildContractChecklist(contractOpts);
+    logger.info(`review checklist for ${outDir}/contract.ts:\n${checklist.map((item) => `  [ ] ${item}`).join("\n")}`);
     (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 }));