@enricai/barnacle 1.12.10 → 1.12.12

package/dist/scripts/recon-generate.js

@@ -22,6 +22,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveStepPayloadField = resolveStepPayloadField;
+exports.buildKnownFieldValues = buildKnownFieldValues;
 exports.extractStepPersonaValue = extractStepPersonaValue;
 exports.deriveFillLabelField = deriveFillLabelField;
 exports.harvestPersonaBindings = harvestPersonaBindings;
@@ -75,6 +76,109 @@ const logger = (0, logging_1.getScriptLogger)("recon-generate");
  */
 const ENGINE_PKG = "@enricai/barnacle";
 // ── helpers ──────────────────────────────────────────────────────────────────
+/**
+ * A reserved recon env token, e.g. `${RECON_EMAIL}` or `${RECON_PHONE}` — the
+ * `RECON_` prefix is what marks a `${UPPER_SNAKE}` token as a recon-owned
+ * splice site rather than an unrelated caller-authored env reference.
+ */
+const RESERVED_ENV_TOKEN = /\$\{RECON_[A-Z0-9_]*\}/;
+/**
+ * The reserved `${RECON_PASSWORD}` token. Unlike every other `RESERVED_ENV_TOKEN`
+ * (RECON_EMAIL, RECON_PHONE, ...), which name a piece of the caller's real
+ * applicant identity and so splice to a `payload.<field>` accessor, this one
+ * names a credential the recon capture needed to authenticate but that has no
+ * caller-supplied counterpart on the applicant payload — there is no "Password"
+ * field to route it through. It gets its own reserved-tooling handling ahead of
+ * (never through) vocabulary/payload-field resolution.
+ */
+const RECON_PASSWORD_TOKEN = `$${"{RECON_PASSWORD}"}`;
+/**
+ * Masks the apostrophe in a possessive `'s` (e.g. "the candidate's name") with
+ * a non-quote placeholder of the same length, so a naive `'...'` quote scan
+ * doesn't mistake the possessive apostrophe for an opening quote delimiter.
+ * Length-preserving so callers that need positions in the ORIGINAL instruction
+ * can reuse the indices matched against the masked string unchanged.
+ */
+function maskPossessiveApostrophes(instruction) {
+    return instruction.replace(/(\w)'(s\b)/g, "$1 $2");
+}
+function findQuoteSpans(instruction) {
+    const masked = maskPossessiveApostrophes(instruction);
+    return [...masked.matchAll(/'([^']*)'/g)].map((m) => ({
+        index: m.index,
+        length: m[0].length,
+        value: instruction.slice(m.index + 1, m.index + m[0].length - 1),
+    }));
+}
+/**
+ * Picks which quoted span in an instruction is the persona VALUE, per the
+ * grammar recon-flow steps use: a `Select`/`Choose`/`Pick` step names the
+ * ANSWER first, then the question, so the value is the FIRST quoted span; a
+ * `Fill`/`Enter`/`Type` step names the field label first and the value last,
+ * so it is the LAST quoted span.
+ */
+function pickValueSpan(instruction, spans) {
+    return /^\s*(select|choose|pick)\b/i.test(instruction) ? spans[0] : spans[spans.length - 1];
+}
+/**
+ * Locates the splice site in a flow-step instruction as `{ before, matched,
+ * after }` slices of the ORIGINAL instruction — a reserved `${RECON_*}` env
+ * token when present (preferred, since it names its own site unambiguously),
+ * otherwise the quoted VALUE span per {@link pickValueSpan}'s verb-class rule.
+ * This is the position-aware counterpart to {@link extractStepPersonaValue}:
+ * that function only needs the extracted string, this one needs the actual
+ * before/after slices so a template literal can be rebuilt around the site.
+ *
+ * @returns null when the instruction carries no spliceable site
+ */
+function locateSpliceSite(instruction) {
+    const envToken = RESERVED_ENV_TOKEN.exec(instruction);
+    if (envToken) {
+        return {
+            before: instruction.slice(0, envToken.index),
+            matched: envToken[0],
+            after: instruction.slice(envToken.index + envToken[0].length),
+        };
+    }
+    const spans = findQuoteSpans(instruction);
+    if (spans.length === 0)
+        return null;
+    const span = pickValueSpan(instruction, spans);
+    return {
+        before: instruction.slice(0, span.index),
+        matched: instruction.slice(span.index, span.index + span.length),
+        after: instruction.slice(span.index + span.length),
+    };
+}
+/**
+ * A quoted span immediately followed by "button"/"link"/"tab" NAMES a control,
+ * not a fill/select VALUE — `click the 'Sign in with email' button` carries no
+ * applicant datum even though the quoted text happens to contain a field-label
+ * word ("email"). Checked ahead of vocabulary matching so a control's own name
+ * can never be mistaken for the data it merely mentions.
+ */
+function namesAControl(instruction) {
+    return findQuoteSpans(instruction).some((span) => /^\s*(button|link|tab)\b/i.test(instruction.slice(span.index + span.length)));
+}
+/** The quoted VALUE a Select/Choose/Fill step carries, per {@link pickValueSpan}'s
+ * grammar rule — used to validate a vocabulary match's ANSWER, not just its label. */
+function pickedQuotedValue(instruction) {
+    const spans = findQuoteSpans(instruction);
+    if (spans.length === 0)
+        return null;
+    const value = pickValueSpan(instruction, spans).value;
+    return value.length > 0 ? value : null;
+}
+/**
+ * Closed-enum answers (Yes/No, decline-to-answer, ...) a Select/Choose step
+ * commonly carries. None of these is ever an applicant's own datum — they are
+ * the RESPONSE to a screening question, not the fact a name/state/phone field
+ * asks for — so a vocabulary label match must never bind one to a payload field.
+ * Generic English grammar, not a domain vocabulary concern, so it belongs here
+ * rather than in any consumer's `--vocabulary`.
+ */
+const OPERATIONAL_ANSWER = /^(yes|no|true|false|n\/a|none|decline(?:\s+to\s+(?:answer|self-identify))?|prefer not to (?:answer|say))$/i;
+const EMPTY_KNOWN_FIELD_VALUES = new Map();
 function toPascalCase(siteId) {
     return siteId
         .split(/[-_]/)
@@ -95,16 +199,26 @@ function toPascalCase(siteId) {
  * @param forceNone when true, force a literal step (the `payloadFieldNone` opt-out)
  * @param vocabulary the consumer's domain vocabulary; defaults to {@link EMPTY_VOCABULARY}
  *   (no splicing) when the caller passes none
+ * @param knownFieldValues field→value pairs the flow already established
+ *   unambiguously via a Fill/Enter/Type step ({@link buildKnownFieldValues}). A
+ *   Select/Choose step's ANSWER must equal the known value for the field a
+ *   label match names, or it is not that field's datum (e.g. a device-type
+ *   dropdown's `'Mobile'` looks like a phone-number field by label alone, but
+ *   is nothing like the number the Fill step already bound).
  * @returns the PascalCase payload field name to splice, or null to keep literal
  */
-function resolveStepPayloadField(instruction, explicit, forceNone, vocabulary = vocabulary_1.EMPTY_VOCABULARY) {
+function resolveStepPayloadField(instruction, explicit, forceNone, vocabulary = vocabulary_1.EMPTY_VOCABULARY, knownFieldValues = EMPTY_KNOWN_FIELD_VALUES) {
     if (forceNone)
         return null;
     if (explicit)
         return explicit;
-    // A quoted literal or ${RECON_EMAIL} IS the recon constant this step would
-    // replace, so it is spliceable on its own.
-    const hasQuotedConstant = /'[^']*'/.test(instruction) || /\$\{RECON_EMAIL\}/.test(instruction);
+    // A control's own name (a button/link/tab label) is never a fill/select VALUE,
+    // even when it happens to contain a word a vocabulary row also matches.
+    if (namesAControl(instruction))
+        return null;
+    // A quoted literal or a reserved ${RECON_*} env token IS the recon constant
+    // this step would replace, so it is spliceable on its own.
+    const hasQuotedConstant = /'[^']*'/.test(instruction) || RESERVED_ENV_TOKEN.test(instruction);
     // A dropdown step carries no constant to replace, so a label match alone can't
     // tell "select the test candidate's state" (the caller's data) from "select the
     // neighborhood from the Country dropdown" (a facet that merely says Country).
@@ -115,12 +229,53 @@ function resolveStepPayloadField(instruction, explicit, forceNone, vocabulary =
         return null;
     if (vocabulary.exclusions.some((rx) => rx.test(instruction)))
         return null;
+    // A Select/Choose/Pick step names an ANSWER, not a Fill step's self-evident
+    // value — a label match alone can't tell the applicant's own datum from an
+    // operational choice the widget merely offers, so the answer itself is
+    // validated below.
+    const isSelectStep = /\b(select|choose|pick)\b/i.test(instruction);
     for (const [rx, field] of vocabulary.table) {
-        if (rx.test(instruction))
+        if (!rx.test(instruction))
+            continue;
+        if (!isSelectStep)
             return field;
+        const answer = pickedQuotedValue(instruction);
+        if (answer !== null && OPERATIONAL_ANSWER.test(answer.trim()))
+            return null;
+        const known = knownFieldValues.get(field);
+        if (known !== undefined && answer !== known)
+            return null;
+        return field;
     }
     return null;
 }
+/**
+ * Field→value pairs the flow establishes unambiguously via a Fill/Enter/Type
+ * step — the applicant's own datum, per {@link deriveFillLabelField}'s same
+ * self-describing grammar. {@link resolveStepPayloadField} uses this to verify
+ * a Select/Choose step's ANSWER is that SAME datum before binding it to the
+ * field a label match names, catching the mismatch a label alone cannot see
+ * (a field whose label mentions "phone" but whose select answer is a device
+ * type, not a number).
+ */
+function buildKnownFieldValues(flowSteps, vocabulary, env) {
+    const known = new Map();
+    for (const step of flowSteps) {
+        const isObj = typeof step !== "string";
+        const instruction = isObj ? step.step : step;
+        if (!/^\s*(?:fill(?:\s+in)?|enter|type)\b/i.test(instruction))
+            continue;
+        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary) ?? deriveFillLabelField(instruction);
+        if (field === null)
+            continue;
+        const value = extractStepPersonaValue(instruction, env);
+        if (value === null)
+            continue;
+        if (!known.has(field))
+            known.set(field, value);
+    }
+    return known;
+}
 /**
  * Extracts the concrete persona VALUE a flow step fills — the recon-supplied
  * constant that appears verbatim in the captured request body — so the body
@@ -159,14 +314,10 @@ function extractStepPersonaValue(instruction, env) {
         if (resolved)
             return resolved;
     }
-    // Neutralize the possessive apostrophe so it isn't read as a quote delimiter.
-    const cleaned = instruction.replace(/(\w)'s\b/g, "$1s");
-    const quotes = [...cleaned.matchAll(/'([^']*)'/g)].map((m) => m[1]);
-    if (quotes.length === 0)
+    const spans = findQuoteSpans(instruction);
+    if (spans.length === 0)
         return null;
-    const value = /^\s*(select|choose|pick)\b/i.test(instruction)
-        ? quotes[0]
-        : quotes[quotes.length - 1];
+    const value = pickValueSpan(instruction, spans).value;
     return value.length > 0 ? value : null;
 }
 /**
@@ -214,10 +365,11 @@ function deriveFillLabelField(instruction) {
  */
 function harvestPersonaBindings(flowSteps, vocabulary, env) {
     const bindings = new Map();
+    const knownFieldValues = buildKnownFieldValues(flowSteps, vocabulary, env);
     for (const step of flowSteps) {
         const isObj = typeof step !== "string";
         const instruction = isObj ? step.step : step;
-        const vocabField = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary);
+        const vocabField = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary, knownFieldValues);
         // Vocabulary wins outright. Only on a miss do we fall back to deriving the
         // field from the instruction's own label — and never when the author opted
         // the step out (`payloadFieldNone`) or the vocabulary explicitly excluded it.
@@ -569,16 +721,22 @@ function firstGraphQLQuery(captures) {
  * flow's own `payloadField` facets appearing in the candidate's query/variables,
  * a non-landing capture phase, and how often the same operation re-fires are
  * combined into one composite score.
+ *
+ * The `payloadField` facets are drawn from {@link resolveStepPayloadField} with
+ * {@link buildKnownFieldValues}'s known-value guard applied, so an operational
+ * Select answer (e.g. a device-type dropdown) never contributes a spurious
+ * facet match to the ranking.
  */
-function selectPrimaryGraphQLOperation(captures, flowSteps, vocabulary) {
+function selectPrimaryGraphQLOperation(captures, flowSteps, vocabulary, env = process.env) {
     const candidates = captures.filter((c) => c.status >= 200 && c.status < 300 && c.query !== null && !/^\s*mutation\b/.test(c.query));
     if (candidates.length === 0)
         return null;
+    const knownFieldValues = buildKnownFieldValues(flowSteps, vocabulary, env);
     const payloadFields = new Set();
     for (const step of flowSteps) {
         const isObj = typeof step !== "string";
         const instruction = isObj ? step.step : step;
-        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary);
+        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary, knownFieldValues);
         if (field !== null)
             payloadFields.add(field);
     }
@@ -1547,6 +1705,7 @@ function buildSelectOptionResolutions(flowSteps, captures, vocabulary, env) {
     const resolutions = [];
     const rawCodeFields = new Map();
     const seenWireKeys = new Set();
+    const knownFieldValues = buildKnownFieldValues(flowSteps, vocabulary, env);
     for (const step of flowSteps) {
         const instruction = typeof step === "string" ? step : step.step;
         if (!/^\s*(select|choose|pick)\b/i.test(instruction) && !/\bselect\b/i.test(instruction)) {
@@ -1604,7 +1763,7 @@ function buildSelectOptionResolutions(flowSteps, captures, vocabulary, env) {
         }
         // Fallback: no id= — resolve the wire key from the vocabulary persona field
         // (lowercased) and the code from the global {label,value} map by label.
-        const field = resolveStepPayloadField(instruction, typeof step === "string" ? undefined : step.payloadField, typeof step === "string" ? undefined : step.payloadFieldNone, vocabulary);
+        const field = resolveStepPayloadField(instruction, typeof step === "string" ? undefined : step.payloadField, typeof step === "string" ? undefined : step.payloadFieldNone, vocabulary, knownFieldValues);
         if (field === null)
             continue;
         const code = labelValue.get(label);
@@ -3243,12 +3402,54 @@ function bindOptionLiteral(headerBindings) {
 // ── 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. */
+/**
+ * Splices payload fields into a string variable that packs filter facets as
+ * delimited `key:value` segments (e.g. a product-catalog `filters` variable
+ * shaped like `category:widgets|priceRange:10~50`) — the shape GraphQL search
+ * endpoints commonly use instead of exposing each facet as its own top-level
+ * variable, which is otherwise invisible to the key-name-equality strategy in
+ * {@link renderGqlVariablesExpr}. Every facet segment whose key correlates
+ * (case-insensitively) with one of `fields` gets its value slot spliced with
+ * `payload.<Field>`; segments that don't correlate are left as their literal
+ * `key:value` piece. Returns `null` for non-string values, strings with no
+ * delimiter-separated `key:value` segment, and strings whose facet keys
+ * correlate with none of `fields`, so opaque tokens, JSON blobs, and plain
+ * literals fall through to the existing JSON.stringify path unchanged.
+ */
+function spliceFacetsIntoStringVariable(value, fields) {
+    if (typeof value !== "string")
+        return null;
+    const segments = value.split(/([|,;])/);
+    const hasFacetShape = segments.some((segment, index) => index % 2 === 0 && segment.includes(":"));
+    if (!hasFacetShape)
+        return null;
+    let hasMatch = false;
+    const body = segments
+        .map((segment, index) => {
+        if (index % 2 !== 0 || !segment.includes(":"))
+            return escapeForTemplateLiteral(segment);
+        const colonIndex = segment.indexOf(":");
+        const facetKey = segment.slice(0, colonIndex);
+        const matchedField = fields.find((field) => field.toLowerCase() === facetKey.toLowerCase());
+        if (!matchedField)
+            return escapeForTemplateLiteral(segment);
+        hasMatch = true;
+        return `${escapeForTemplateLiteral(`${facetKey}:`)}\${payload.${matchedField}}`;
+    })
+        .join("");
+    if (!hasMatch)
+        return null;
+    return `\`${body}\``;
+}
 /**
  * Renders the variables literal for the primary-operation getGql() call —
  * each key from the selected capture's own recorded variables is bound to
  * `payload.<Field>` when it correlates (case-insensitively) with one of the
- * flow's payloadFieldNames, otherwise the captured literal value is emitted
- * verbatim via JSON.stringify.
+ * flow's payloadFieldNames. When no top-level key correlates and the value is
+ * a string packing facets in a delimited `key:value` grammar (see
+ * {@link spliceFacetsIntoStringVariable}), a correlated facet's value slot is
+ * spliced with `payload.<Field>` instead of freezing the whole string; any
+ * other value is emitted verbatim via JSON.stringify.
  */
 function renderGqlVariablesExpr(variables, payloadFieldNames) {
     if (variables === null || typeof variables !== "object" || Array.isArray(variables))
@@ -3256,7 +3457,10 @@ function renderGqlVariablesExpr(variables, payloadFieldNames) {
     const fields = payloadFieldNames ? [...payloadFieldNames] : [];
     const entries = Object.entries(variables).map(([key, value]) => {
         const matchedField = fields.find((field) => field.toLowerCase() === key.toLowerCase());
-        const valueExpr = matchedField ? `payload.${matchedField}` : JSON.stringify(value);
+        const facetSpliceExpr = matchedField ? null : spliceFacetsIntoStringVariable(value, fields);
+        const valueExpr = matchedField
+            ? `payload.${matchedField}`
+            : (facetSpliceExpr ?? JSON.stringify(value));
         return `${key}: ${valueExpr}`;
     });
     return entries.length > 0 ? `{ ${entries.join(", ")} }` : "{}";
@@ -3308,37 +3512,82 @@ function emitContractTs(opts) {
     // longer drives the public schema. A missing inputBody means this is a
     // non-submission (query-type) flow, which keeps its own contract untouched.
     const basePayloadSchemaExpr = inputBody
-        ? `ApplicantContactSchema.extend({\n  Email: z.email(),\n  ClickUrl: z.string().min(1),\n  Answers: multipartJsonObject(z.record(z.string(), z.unknown())),\n})`
+        ? `ApplicantContactSchema`
         : `z.object({\n  query: z.string().min(1),\n})`;
+    // Every field source below (the base extend's own keys, form-schema
+    // discovery, browser-flow splicing, option/raw-option enums, additional
+    // body keys, and structured keys) is merged into a SINGLE `.extend({...})`
+    // object literal, keyed by field name, rather than each becoming its own
+    // chained `.extend()` call. A name that recurs across sources collapses to
+    // one declaration — the later source in this list wins, mirroring the
+    // override semantics a chain of `.extend()` calls used to have (each
+    // subsequent `.extend` replaced an earlier field of the same name).
+    const extendFields = new Map();
+    const addExtendField = (name, line) => {
+        extendFields.set(name, line);
+    };
+    // The base extend's own keys — submission flows only.
+    if (inputBody) {
+        addExtendField("Email", "  Email: z.email(),");
+        addExtendField("ClickUrl", "  ClickUrl: z.string().min(1),");
+        addExtendField("Answers", "  Answers: multipartJsonObject(z.record(z.string(), z.unknown())),");
+    }
+    // ApplicantContactSchema's own merged identity/address/resume field names
+    // (see src/lib/application-identity.ts, application-address.ts,
+    // application-resume.ts, applicant-payload.ts) — reserved so no discovered/
+    // spliced source can redeclare (and silently shadow) a field the base
+    // ApplicantContactSchema already supplies. Only relevant for submission
+    // flows, where basePayloadSchemaExpr actually is ApplicantContactSchema.
+    const applicantContactFieldNames = new Set([
+        "FirstName",
+        "LastName",
+        "Phone",
+        "AddressLine",
+        "City",
+        "State",
+        "PostalCode",
+        "Country",
+        "County",
+        "Resume",
+        "ResumeContentType",
+        "ResumeFilename",
+        "ResumeBase64",
+    ]);
+    const isReservedByApplicantContactSchema = (name) => Boolean(inputBody) && applicantContactFieldNames.has(name);
+    // Multi-step flows that include a multipart upload need the binary asset
+    // on the payload. A query-type flow (no ApplicantContactSchema base) still
+    // needs these fields spelled out explicitly.
+    if (hasMultipartStep && !inputBody) {
+        addExtendField("Resume", "  Resume: z.instanceof(Buffer),");
+        addExtendField("ResumeContentType", "  ResumeContentType: z.string(),");
+        addExtendField("ResumeFilename", "  ResumeFilename: z.string(),");
+    }
     // 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})`
-        : "";
+    if (discoveredFormFields) {
+        for (const name of [...discoveredFormFields].sort()) {
+            if (isReservedByApplicantContactSchema(name))
+                continue;
+            addExtendField(name, `  ${name}: z.string(),`);
+        }
+    }
     // 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})`
-        : "";
+    if (payloadFieldNames) {
+        for (const name of [...payloadFieldNames].sort()) {
+            if (isReservedByApplicantContactSchema(name))
+                continue;
+            addExtendField(name, `  ${name}: ${name === "Email" ? "z.email()" : "z.string()"},`);
+        }
+    }
     // Build per-field OPT_<Name> constant declarations + payload-schema enum
     // entries from the form schema's options. Only fields whose option-id
     // 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.
+    // unused.
     const emittedOptionMappings = [];
     if (fieldOptionsMap && discoveredOptionFields && discoveredOptionFields.size > 0) {
         for (const mapping of fieldOptionsMap.values()) {
@@ -3356,11 +3605,11 @@ function emitContractTs(opts) {
         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})`
-        : "";
+    for (const mapping of emittedOptionMappings) {
+        if (isReservedByApplicantContactSchema(mapping.semanticName))
+            continue;
+        addExtendField(mapping.semanticName, `  ${mapping.semanticName}: z.enum([${mapping.options.map((o) => JSON.stringify(o.value)).join(", ")}]),`);
+    }
     // Phase E raw-option payload fields: options whose label strings are empty in
     // the schema — no semantic enum is possible, so the caller supplies the
     // option-id UUID directly. The recon-observed UUID is documented in a TSDoc
@@ -3368,11 +3617,11 @@ function emitContractTs(opts) {
     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 option-id UUID for this field. */\n  ${name}: z.string(),`)
-            .join("\n")}\n})`
-        : "";
+    for (const [name, reconUuid] of sortedRawOptionEntries) {
+        if (isReservedByApplicantContactSchema(name))
+            continue;
+        addExtendField(name, `  /** Recon-observed: ${reconUuid}. Caller supplies the option-id UUID for this field. */\n  ${name}: z.string(),`);
+    }
     // A non-scalar (Mechanism B) field forces multipart wire encoding just like
     // an upload step does: the multipart body encodes arrays/objects as
     // JSON-stringified strings, so those fields need the same
@@ -3383,25 +3632,23 @@ function emitContractTs(opts) {
     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"
-                    ? payloadNeedsMultipart
-                        ? "z.coerce.number()"
-                        : "z.number()"
-                    : payloadNeedsMultipart
-                        ? "multipartBoolean()"
-                        : "z.boolean()";
-            return `  ${name}: ${zod},`;
-        })
-            .join("\n")}\n})`
-        : "";
+    for (const [name, kind] of sortedAdditionalKeys) {
+        if (isReservedByApplicantContactSchema(name))
+            continue;
+        // Use multipartBoolean() for booleans when multipart is in play, so
+        // multipart string-encoded "true"/"false" round-trip to native booleans
+        // (matches the inputBody boolean handling for parity).
+        const zod = kind === "string"
+            ? "z.string()"
+            : kind === "number"
+                ? payloadNeedsMultipart
+                    ? "z.coerce.number()"
+                    : "z.number()"
+                : payloadNeedsMultipart
+                    ? "multipartBoolean()"
+                    : "z.boolean()";
+        addExtendField(name, `  ${name}: ${zod},`);
+    }
     // Mechanism B: nested caller structures become payload fields carrying their
     // inferred schema. Emitted as an object body so multi-line z.array(z.object(
     // …)) expressions indent cleanly; a leading TSDoc flags eventData's opaque
@@ -3409,15 +3656,13 @@ function emitContractTs(opts) {
     const sortedStructuredEntries = discoveredStructuredKeys
         ? [...discoveredStructuredKeys.entries()].sort(([a], [b]) => a.localeCompare(b))
         : [];
-    const structuredKeysExtension = sortedStructuredEntries.length > 0
-        ? `.extend({\n${sortedStructuredEntries
-            .map(([name, schema]) => {
-            const key = isValidJsIdentifier(name) ? name : JSON.stringify(name);
-            const value = payloadNeedsMultipart ? `multipartJsonObject(${schema})` : schema;
-            return `  ${key}: ${value},`;
-        })
-            .join("\n")}\n})`
-        : "";
+    for (const [name, schema] of sortedStructuredEntries) {
+        if (isReservedByApplicantContactSchema(name))
+            continue;
+        const key = isValidJsIdentifier(name) ? name : JSON.stringify(name);
+        const value = payloadNeedsMultipart ? `multipartJsonObject(${schema})` : schema;
+        addExtendField(name, `  ${key}: ${value},`);
+    }
     // The structural walk over the captured request body that used to BE the
     // public payload schema (see basePayloadSchemaExpr above) is still the
     // right starting point for the plugin author's internal builder — it's
@@ -3430,18 +3675,18 @@ function emitContractTs(opts) {
     const internalRequestReferenceExpr = inputBody
         ? inferZodSchema(inputBody, 0, "", { multipartCoerce: hasMultipartStep })
         : null;
-    // 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) matches the body
-    // emit order and keeps the generated payload type readable.
-    const resumeFieldsExtension = hasMultipartStep && !inputBody
-        ? `.extend({\n  Resume: z.instanceof(Buffer),\n  ResumeContentType: z.string(),\n  ResumeFilename: z.string(),\n})`
-        : "";
-    const payloadSchemaExpr = `${basePayloadSchemaExpr}${resumeFieldsExtension}${formFieldsExtension}${splicedFieldsExtension}${optionSchemaExtension}${rawOptionSchemaExtension}${additionalBodyKeysExtension}${structuredKeysExtension}`;
-    // basePayloadSchemaExpr always wraps Answers in multipartJsonObject() for
-    // submission flows (inputBody set); multipartBoolean() and the
-    // structuredKeysExtension wrapping are needed whenever payloadNeedsMultipart
-    // is true (an upload step OR a non-scalar discoveredStructuredKeys field).
+    // 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
+    // to its last-declared line, rather than becoming a second, dupe-prone
+    // `.extend()` call chained onto the schema.
+    const mergedExtension = extendFields.size > 0 ? `.extend({\n${[...extendFields.values()].join("\n")}\n})` : "";
+    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).
     // Named imports from the same module are combined into one import statement.
     const zodMultipartNamedImports = [
         ...(payloadNeedsMultipart ? ["multipartBoolean"] : []),
@@ -3585,7 +3830,7 @@ const limiter = new Bottleneck({ minTime: ${minTime} });
         : `
   /** Hot path: direct HTTP — no browser, no LLM tokens. */
   async executeHttp(
-    payload: ${pascal}Payload,
+    ${executeHttpBody.includes("payload.") ? "payload" : "_payload"}: ${pascal}Payload,
     ${executeHttpBody.includes("context.") ? "context" : "_context"}: SitePluginContext
   ): Promise<SitePluginResult<${pascal}Response>> {
 ${executeHttpBody}
@@ -3680,59 +3925,50 @@ function escapeForTemplateLiteral(segment) {
  * 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.
+ * The splice site is located by {@link locateSpliceSite} — a reserved
+ * `${RECON_*}` env token when present, otherwise the quoted VALUE span (never
+ * a selector's or label's quoted span), matching {@link extractStepPersonaValue}'s
+ * own choice so the browser-flow and HTTP-body emitters never disagree on
+ * which quoted span is the persona value.
  */
 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 === "")
+    const site = locateSpliceSite(instruction);
+    if (site === null)
         return JSON.stringify(instruction);
-    return `\`${escapeForTemplateLiteral(before)}\${payload.${field}}${escapeForTemplateLiteral(after)}\``;
+    return `\`${escapeForTemplateLiteral(site.before)}\${payload.${field}}${escapeForTemplateLiteral(site.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.
+ * Build the emitted instruction expression for a step whose splice site is the
+ * reserved `${RECON_PASSWORD}` token: a backtick template literal with the
+ * token replaced by `${throwawayPassword}`, the per-run credential minted by
+ * {@link generateThrowawayPassword} — never the recon capture's literal
+ * password, and never routed through `payload.<field>` since no caller-
+ * supplied Password field exists on the applicant payload.
+ */
+function buildPasswordInstructionExpr(instruction) {
+    const site = locateSpliceSite(instruction);
+    if (site === null)
+        return JSON.stringify(instruction);
+    return `\`${escapeForTemplateLiteral(site.before)}\${throwawayPassword}${escapeForTemplateLiteral(site.after)}\``;
+}
+/**
+ * Rewrites one step instruction into the config-manifest templating form: the
+ * splice site located by {@link locateSpliceSite} 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. Reuses {@link locateSpliceSite} so this
+ * emitter never lands the splice on a selector's or label's quoted span, the
+ * same guarantee {@link buildStepInstructionExpr} makes.
  */
 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)
+    const site = locateSpliceSite(instruction);
+    if (site === null)
         return instruction;
-    return (instruction.slice(0, m.index) +
-        `{{ .request.${field} }}` +
-        instruction.slice(m.index + m[0].length));
+    return `${site.before}{{ .request.${field} }}${site.after}`;
 }
 /**
  * The JSON Schema `type` keyword for a sample value. Just the keyword, not a
@@ -3774,12 +4010,28 @@ 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, } = opts;
+    const { siteId, displayName, baseUrl, flowSteps, vocabulary, inputBody, recoveredFields, httpModulePath, env = process.env, } = opts;
     const payloadFieldNames = new Set();
+    const knownFieldValues = buildKnownFieldValues(flowSteps, vocabulary ?? vocabulary_1.EMPTY_VOCABULARY, env);
     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, vocabulary);
+        // A config-only manifest has no compiled code to mint a throwaway credential
+        // at runtime (unlike emitBrowserFlowTs's generateThrowawayPassword() splice),
+        // so ${RECON_PASSWORD} is routed to an explicit "Password" request field
+        // instead — the operator supplies it at call time. Either way the literal
+        // token must never survive into the manifest.
+        if (instruction.includes(RECON_PASSWORD_TOKEN)) {
+            payloadFieldNames.add("Password");
+            const rewritten = buildManifestInstruction(instruction, "Password");
+            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 field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary, knownFieldValues);
         if (field !== null)
             payloadFieldNames.add(field);
         const rewritten = buildManifestInstruction(instruction, field);
@@ -3840,13 +4092,28 @@ function emitConfigManifest(opts) {
  * payload schema (both are driven by this same set).
  */
 function emitBrowserFlowTs(opts) {
-    const { siteId, pascal, flowSteps, isSubmissionFlow, hasMultipartStep = false, vocabulary, frameSelector, } = opts;
+    const { siteId, pascal, flowSteps, isSubmissionFlow, hasMultipartStep = false, vocabulary, frameSelector, env = process.env, } = opts;
     const payloadFieldNames = new Set();
     const hasUploadStep = flowSteps.some((s) => typeof s !== "string" && s.upload === true);
+    const knownFieldValues = buildKnownFieldValues(flowSteps, vocabulary ?? vocabulary_1.EMPTY_VOCABULARY, env);
+    let usesThrowawayPassword = false;
     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, vocabulary);
+        // ${RECON_PASSWORD} is reserved-tooling, not a domain-vocabulary concern —
+        // it names a credential the recon capture needed to authenticate, not a
+        // piece of the caller's applicant identity, so it never reaches
+        // resolveStepPayloadField/vocabulary and never routes through
+        // payload.<field>. It gets a generated throwaway credential instead.
+        if (instruction.includes(RECON_PASSWORD_TOKEN)) {
+            usesThrowawayPassword = true;
+            const instructionExpr = buildPasswordInstructionExpr(instruction);
+            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 field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary, knownFieldValues);
         if (field !== null)
             payloadFieldNames.add(field);
         const instructionExpr = buildStepInstructionExpr(instruction, field);
@@ -3869,7 +4136,7 @@ function emitBrowserFlowTs(opts) {
     // the multipart contract fields and wires the fixture during hand-finish.
     const uploadFixtureExpr = hasUploadStep && hasMultipartStep
         ? `{
-    buffer: Buffer.from(payload.Resume ?? "", "base64"),
+    buffer: Buffer.from(payload.Resume),
     name: payload.ResumeFilename ?? "resume.pdf",
     mimeType: payload.ResumeContentType ?? "application/pdf",
   }`
@@ -3892,7 +4159,7 @@ import type { Stagehand } from "@browserbasehq/stagehand";
 import { z } from "zod/v4";
 
 import { buildAnthropicClient, buildRephraseModel } from "${ENGINE_PKG}/lib/llm/anthropic-client";
-import { getLogger } from "${ENGINE_PKG}/lib/logging";
+import { getLogger } from "${ENGINE_PKG}/lib/logging";${usesThrowawayPassword ? `\nimport { generateThrowawayPassword } from "${ENGINE_PKG}/lib/random";` : ""}
 import { type HealingFlowStep, runHealingFlow, waitForSpaReady } from "${ENGINE_PKG}/scraper/flow-runner";
 import { guardedExtract } from "${ENGINE_PKG}/scraper/stagehand-guard";
 import type { ${pascal}Payload, ${pascal}Response } from "@/sites/${siteId}/contract";
@@ -3920,7 +4187,7 @@ export async function run${pascal}BrowserFlow(
   // 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);
-
+${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" : ""}
   const FLOW_STEPS: HealingFlowStep[] = [
 ${flowStepsBlock}
   ];