@enricai/barnacle 1.3.1 → 1.4.2

package/dist/scripts/recon-generate.js

@@ -20,16 +20,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveStepPayloadField = resolveStepPayloadField;
 exports.inferZodSchemaFromSamples = inferZodSchemaFromSamples;
 exports.selectPayloadAction = selectPayloadAction;
+exports.indexStateValues = indexStateValues;
+exports.compileActionSteps = compileActionSteps;
 exports.loadQuestionPromptKeywords = loadQuestionPromptKeywords;
 exports.emitMultiStepExecuteHttp = emitMultiStepExecuteHttp;
 exports.emitContractTs = emitContractTs;
 exports.emitConfigManifest = emitConfigManifest;
 exports.emitBrowserFlowTs = emitBrowserFlowTs;
+exports.emitIndexTs = emitIndexTs;
 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_api_version_1 = require("../plugins/plugin-api-version");
 const plugin_manifest_envelope_1 = require("../plugins/plugin-manifest-envelope");
+const load_vocabulary_1 = require("../recon/load-vocabulary");
+const vocabulary_1 = require("../recon/vocabulary");
 const recon_shared_1 = require("../scripts/recon-shared");
 const logger = (0, logging_1.getScriptLogger)("recon-generate");
 // ── helpers ──────────────────────────────────────────────────────────────────
@@ -40,46 +46,52 @@ function toPascalCase(siteId) {
         .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.
+ * The recruiting vocabulary the engine used to hardcode, kept only so consumers
+ * who have not yet passed `--vocabulary` keep working through the 1.x line.
+ *
+ * @deprecated Pass `--vocabulary <specifier>` instead. The engine cannot know
+ * what any site's forms mean, and guessing mis-fires on every non-recruiting
+ * domain (a cruise site's "Select the departure port from the Country dropdown"
+ * became `${payload.Country}`). Slated for deletion in 2.0.0, after which an
+ * absent vocabulary on a spliceable flow is a hard error. See `src/recon/vocabulary.ts`.
  */
-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"],
-];
+const DEPRECATED_BUILTIN_ATS_VOCABULARY = {
+    // Naming the subject is what separates "…select the test candidate's state"
+    // (fill with the caller's data) from "…the departure port from the Country
+    // dropdown" (a search facet that merely says Country).
+    subject: /\b(the\s+)?(test\s+)?(candidate|applicant)'?s\b/i,
+    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,
+        // A secondary phone must not fill the primary MobilePhone field.
+        /\bsecondary\b[^.]*\bphone\b/i,
+    ],
+    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
@@ -92,27 +104,29 @@ const PAYLOAD_FIELD_TABLE = [
  * @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)
+ * @param vocabulary the consumer's domain vocabulary; defaults to the deprecated
+ *   built-in recruiting table so 1.x consumers who pass nothing keep working
  * @returns the PascalCase payload field name to splice, or null to keep literal
  */
-function resolveStepPayloadField(instruction, explicit, forceNone) {
+function resolveStepPayloadField(instruction, explicit, forceNone, vocabulary = DEPRECATED_BUILTIN_ATS_VOCABULARY) {
     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);
+    // 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 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
+    // departure port from the Country dropdown" (a facet that merely says Country).
+    // Requiring the subject is what keeps this from mis-firing off-domain.
+    const isDropdownStep = /\bdropdown\b/i.test(instruction) || /\bselect\b[^.]*\bfrom\b/i.test(instruction);
+    const hasSpliceable = hasQuotedConstant || (isDropdownStep && vocabulary.subject.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))
+    if (vocabulary.exclusions.some((rx) => rx.test(instruction)))
         return null;
-    for (const [rx, field] of PAYLOAD_FIELD_TABLE) {
+    for (const [rx, field] of vocabulary.table) {
         if (rx.test(instruction))
             return field;
     }
@@ -1047,12 +1061,35 @@ const MAX_STATE_VALUE_LENGTH = 256;
  * 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"]);
+/**
+ * Splits a raw `Set-Cookie` response-header string into `name`/`value` pairs.
+ * Captures store `responseHeaders` as a flat `Record<string, string>`
+ * (see recon-shared.ts's `Capture`), so multiple `Set-Cookie` headers from the
+ * same response — if the recon browser's CDP session folds them together —
+ * would already have lost their individual boundaries before reaching here;
+ * this only recovers name/value pairs from whatever single string survives.
+ */
+function* walkSetCookiePairs(rawSetCookie) {
+    const pair = rawSetCookie.split(";", 1)[0] ?? "";
+    const eq = pair.indexOf("=");
+    if (eq === -1)
+        return;
+    const name = pair.slice(0, eq).trim();
+    const value = pair.slice(eq + 1).trim();
+    if (name && value)
+        yield { name, value };
+}
 /**
  * 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.
  *
+ * Also indexes response-header/cookie-origin values (e.g. a `Set-Cookie`
+ * auth token) the same way, tagged with `headerOrigin` instead of a body
+ * `path` — this is what lets a stateful API's token-mint response feed a
+ * later call's `Cookie` header via `compileActionSteps`.
+ *
  * 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`,
@@ -1063,6 +1100,8 @@ const PLACEHOLDER_STATE_VALUES = new Set(["00000000-0000-0000-0000-000000000000"
  * the LATER non-placeholder occurrence at the same JSON path becomes the
  * canonical binding instead.
  */
+/** Exported for unit testing — lets tests exercise the produces[] walk (body
+ * AND header/cookie origins) directly against synthetic Capture sequences. */
 function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndices = new Set()) {
     const index = new Map();
     // First pass: identify the earliest origin among ACTION captures for each
@@ -1075,10 +1114,32 @@ function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndi
     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;
+        // Headers/cookies are indexed regardless of responseBody presence — a
+        // token-mint call like disneycruise's `authz/private` returns `{}` and
+        // carries its whole payload in `Set-Cookie`.
+        const rawSetCookie = Object.entries(c.responseHeaders).find(([k]) => k.toLowerCase() === "set-cookie")?.[1];
+        if (rawSetCookie !== undefined) {
+            for (const { name, value } of walkSetCookiePairs(rawSetCookie)) {
+                if (value.length < MIN_STATE_VALUE_LENGTH)
+                    continue;
+                if (value.length > MAX_STATE_VALUE_LENGTH)
+                    continue;
+                if (PLACEHOLDER_STATE_VALUES.has(value))
+                    continue;
+                if (!index.has(value)) {
+                    index.set(value, {
+                        value,
+                        originIndex: i,
+                        path: [],
+                        headerOrigin: { sourceHeader: "set-cookie", cookieName: name },
+                    });
+                }
+            }
+        }
+        if (c.responseBody === undefined || c.responseBody === null)
+            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.
@@ -1115,9 +1176,18 @@ function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndi
 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". */
+/**
+ * Converts a path like ["Auth","Token"] to a JS access expression ".Auth.Token".
+ * Bracket segments (numeric array indices, non-identifier keys) get a trailing
+ * `!` — under `noUncheckedIndexedAccess` an array/index-signature access types
+ * as `T | undefined`, and this accessor is only ever used against a real Zod-
+ * inferred array/object type (payload fields, captured response bodies), never
+ * against the object-literal assertion types `pathToAssertionType` builds (those
+ * use known string-literal keys, which `noUncheckedIndexedAccess` does not
+ * widen). Dot segments stay bare since object property access isn't affected.
+ */
 function pathToAccessor(path) {
-    return path.map((p) => (isValidJsIdentifier(p) ? `.${p}` : `[${JSON.stringify(p)}]`)).join("");
+    return path.map((p) => (isValidJsIdentifier(p) ? `.${p}` : `[${JSON.stringify(p)}]!`)).join("");
 }
 /**
  * Builds a nested TypeScript assertion type matching a JSON path. e.g.
@@ -1151,26 +1221,75 @@ function pathToVarName(path) {
  * var name, the state values its response produces (used by downstream steps),
  * and a multipart flag (request body bytes not captured).
  */
+/** Exported for unit testing — see `indexStateValues`. */
 function compileActionSteps(actions, stateIndex) {
     const usedValues = new Set();
+    // Maps a used state value to the request-header NAME that carries it, for
+    // values whose consuming reference is a request header (not the URL/body).
+    // A header-origin produce needs this as its `targetHeader` — the header the
+    // *next* httpClient call must send the bound value back on. Only the first
+    // consuming header name observed wins; a value used in more than one distinct
+    // header downstream isn't a shape this models (see http-client.ts's `bind`,
+    // which is single-target per binding).
+    const usedValueTargetHeader = new Map();
     // 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);
         }
+        for (const [headerName, headerValue] of Object.entries(capture.requestHeaders)) {
+            for (const sv of stateIndex.values()) {
+                if (!headerValue.includes(sv.value))
+                    continue;
+                usedValues.add(sv.value);
+                if (!usedValueTargetHeader.has(sv.value)) {
+                    usedValueTargetHeader.set(sv.value, headerName);
+                }
+            }
+        }
     }
     let lastHost = null;
     return actions.map(({ capture, index }, i) => {
         const varName = `r${i}`;
         const produces = [];
         const seenNames = new Set();
+        // Header/cookie-origin produces — walked first so a value that appears in
+        // BOTH a Set-Cookie and the JSON body (unlikely, but not ruled out) prefers
+        // the header binding, which is what the runtime actually threads.
+        const rawSetCookie = Object.entries(capture.responseHeaders).find(([k]) => k.toLowerCase() === "set-cookie")?.[1];
+        if (rawSetCookie !== undefined) {
+            for (const { name: cookieName, value } of walkSetCookiePairs(rawSetCookie)) {
+                if (!usedValues.has(value))
+                    continue;
+                const sv = stateIndex.get(value);
+                if (!sv || sv.originIndex !== index || !sv.headerOrigin)
+                    continue;
+                const targetHeader = usedValueTargetHeader.get(value);
+                if (!targetHeader)
+                    continue;
+                let name = `${cookieName.replace(/[^A-Za-z0-9]/g, "")}Cookie`;
+                if (!/^[A-Za-z_$]/.test(name))
+                    name = `_${name}`;
+                let suffix = 1;
+                while (seenNames.has(name)) {
+                    suffix++;
+                    name = `${cookieName.replace(/[^A-Za-z0-9]/g, "")}Cookie${suffix}`;
+                }
+                seenNames.add(name);
+                produces.push({
+                    kind: "header",
+                    name,
+                    sourceHeader: sv.headerOrigin.sourceHeader,
+                    cookieName: sv.headerOrigin.cookieName,
+                    targetHeader,
+                });
+            }
+        }
         if (capture.responseBody !== undefined && capture.responseBody !== null) {
             for (const { value, path } of walkStringLeaves(capture.responseBody)) {
                 if (!usedValues.has(value))
@@ -1186,7 +1305,7 @@ function compileActionSteps(actions, stateIndex) {
                     name = `${pathToVarName(path)}${suffix}`;
                 }
                 seenNames.add(name);
-                produces.push({ name, pathExpr: `${varName}${pathToAccessor(path)}`, path });
+                produces.push({ kind: "body", name, pathExpr: `${varName}${pathToAccessor(path)}`, path });
             }
         }
         const ct = Object.entries(capture.requestHeaders).find(([k]) => k.toLowerCase() === "content-type");
@@ -1203,6 +1322,27 @@ function compileActionSteps(actions, stateIndex) {
         return { capture, varName, produces, isMultipart, isCrossDomain };
     });
 }
+/**
+ * Collects every header/cookie-origin produce across an action sequence, in
+ * step order — this is what `emitContractTs` renders as `createHttpClient`'s
+ * `bind` option so the generated `executeHttp` actually forwards a value like
+ * disneycruise's `Set-Cookie: __pa=<jwt>` mint to the stateful call that 401s
+ * without it. Deduped by `targetHeader`: `HttpResponseBinding` (http-client.ts)
+ * is one binding per target header, so if two steps somehow produced the same
+ * target the earliest wins.
+ */
+function collectHeaderBindings(actionSteps) {
+    const byTarget = new Map();
+    for (const step of actionSteps) {
+        for (const p of step.produces) {
+            if (p.kind !== "header")
+                continue;
+            if (!byTarget.has(p.targetHeader))
+                byTarget.set(p.targetHeader, p);
+        }
+    }
+    return [...byTarget.values()];
+}
 /**
  * Replaces occurrences of state values in `template` with `${varName}`
  * interpolations. Returns a JS template-literal string fragment (no backticks).
@@ -1217,6 +1357,12 @@ function interpolateStateValues(template, priorSteps, payloadAccessorByValue = n
     const varNameByValue = new Map();
     for (const step of priorSteps) {
         for (const p of step.produces) {
+            // Header/cookie-origin produces have no body path — their value never
+            // appears as a literal in a URL/body template (http-client's `bind`
+            // forwards it directly as a request header), so there's nothing to
+            // interpolate here.
+            if (p.kind === "header")
+                continue;
             let cursor = step.capture.responseBody;
             for (const segment of p.path) {
                 if (cursor !== null &&
@@ -1810,6 +1956,11 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
             }
         }
         for (const p of step.produces) {
+            // Header/cookie-origin produces never surface as a JS accessor —
+            // createHttpClient's `bind` option (rendered once, above the steps)
+            // captures and forwards the value internally.
+            if (p.kind === "header")
+                continue;
             if (declaredNames.has(p.name))
                 continue;
             if (!referencedNames.has(p.name))
@@ -1835,11 +1986,30 @@ function summariseResponseShape(value) {
     }
     return obj;
 }
+/**
+ * Renders `headerBindings` as a trailing `, bind: [...]` fragment for
+ * `createHttpClient`'s options object literal — empty string when there are
+ * none, so a plugin with no header/cookie-origin state keeps the exact output
+ * this emitter already produced. Structurally matches `HttpResponseBinding`
+ * (http-client.ts) without importing the type: the object literal typechecks
+ * against `HttpClientOptions.bind` on its own shape.
+ */
+function bindOptionLiteral(headerBindings) {
+    if (headerBindings.length === 0)
+        return "";
+    const entries = headerBindings
+        .map((b) => {
+        const cookieNameField = b.cookieName !== undefined ? ` cookieName: ${JSON.stringify(b.cookieName)},` : "";
+        return `{ sourceHeader: ${JSON.stringify(b.sourceHeader)},${cookieNameField} targetHeader: ${JSON.stringify(b.targetHeader)} }`;
+    })
+        .join(", ");
+    return `, bind: [${entries}]`;
+}
 // ── 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;
+    const { siteId, pascal, baseUrl, baseHeaders, minTime, safeRps, responseBody, gql, gqlQuery, endpointPath, auxFiles, multiStepBody, inputBody, hasMultipartStep = false, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, payloadFieldNames, base64ContentHelper = "", headerBindings = [], } = 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.
@@ -1997,7 +2167,7 @@ function getGql(baseUrl: string): GqlFn {
 }
 `
         : `
-const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottleneck: limiter, baseHeaders: BASE_HEADERS });
+const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottleneck: limiter, baseHeaders: BASE_HEADERS${bindOptionLiteral(headerBindings)} });
 `;
     const executeHttpBody = multiStepBody
         ? multiStepBody
@@ -2019,6 +2189,7 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
     const queryChecklistLine = gql
         ? `\n *   [ ] Trim UI-only fields from ${pascal.toUpperCase()}_QUERY (keep only fields you need)`
         : "";
+    const camel = siteId.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
     return `/**
  * Generated by recon-generate.ts — review before shipping.
  *
@@ -2026,6 +2197,9 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
  *   [ ] 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
+ *   [ ] 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
  */
 
 import Bottleneck from "bottleneck";
@@ -2057,13 +2231,14 @@ ${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> = {
+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)},${hasMultipartStep ? "\n    multipart: true," : ""}
+    defaultBaseUrl: ${JSON.stringify(baseUrl)},
+    apiVersion: ${JSON.stringify(plugin_api_version_1.PLUGIN_API_VERSION)},${hasMultipartStep ? "\n    multipart: true," : ""}
   },
 
   /** Hot path: direct HTTP — no browser, no LLM tokens. */
@@ -2084,6 +2259,11 @@ ${executeHttpBody}
     return { data: raw as ${pascal}Response };
   },
 };
+
+// Out-of-tree loader resolves \`m.plugin ?? m.default ?? m\` — this named
+// alias is what BARNACLE_PLUGINS finds; without it the loader would fall
+// through to \`m.default\` (the response schema above) and 404 at runtime.
+export { ${camel}Plugin as plugin };
 `;
 }
 /**
@@ -2162,12 +2342,12 @@ function buildManifestInstruction(instruction, field) {
  * omitted; a site that needs it keeps the `.ts` path or wires `spec.httpModule`.
  */
 function emitConfigManifest(opts) {
-    const { siteId, displayName, baseUrl, flowSteps } = opts;
+    const { siteId, displayName, baseUrl, flowSteps, vocabulary } = 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);
+        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary);
         if (field !== null)
             payloadFieldNames.add(field);
         const rewritten = buildManifestInstruction(instruction, field);
@@ -2211,13 +2391,13 @@ function emitConfigManifest(opts) {
  * payload schema (both are driven by this same set).
  */
 function emitBrowserFlowTs(opts) {
-    const { siteId, pascal, flowSteps, isSubmissionFlow, hasMultipartStep = false } = opts;
+    const { siteId, pascal, flowSteps, isSubmissionFlow, hasMultipartStep = false, vocabulary, } = 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);
+        const field = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary);
         if (field !== null)
             payloadFieldNames.add(field);
         const instructionExpr = buildStepInstructionExpr(instruction, field);
@@ -2322,30 +2502,71 @@ ${flowStepsBlock}
 `;
     return { code, payloadFieldNames };
 }
+/** Generates the site's index.ts barrel — exported so the out-of-tree e2e
+ * test can drive the emitter directly without spawning the CLI. */
 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:
+ * Build this package, then point BARNACLE_PLUGINS at the compiled module —
+ * no core edits required:
+ *
+ *   BARNACLE_PLUGINS=./dist/sites/${siteId}/index.js pnpm start
  *
- *   import { ${camel}Plugin } from "@/sites/${siteId}";
- *   BUILTIN_SITE_PLUGINS.push(${camel}Plugin as SitePlugin<unknown, unknown>);
+ * The loader resolves \`m.plugin ?? m.default ?? m\` — the \`plugin\` alias
+ * below is what it finds.
  */
 
-export { ${camel}Plugin } from "@/sites/${siteId}/contract";
+export { ${camel}Plugin, ${camel}Plugin as plugin } from "@/sites/${siteId}/contract";
 `;
 }
 // ── main ──────────────────────────────────────────────────────────────────────
+/**
+ * Resolves the vocabulary for this run and reports which one is in play.
+ *
+ * The deprecation warning is the whole point of the 1.x window: removing a
+ * built-in default that consumers silently depend on is only safe if the
+ * transition is loud. It fires only when the built-in would actually change the
+ * output — a flow with nothing to splice gets no nag it can't act on.
+ */
+async function resolveVocabulary(specifier, flowSteps) {
+    if (specifier) {
+        const vocabulary = await (0, load_vocabulary_1.loadReconVocabulary)(specifier, process.cwd());
+        logger.info(`vocabulary: ${specifier === load_vocabulary_1.VOCABULARY_NONE ? "none (splicing disabled)" : `${vocabulary.table.length} row(s) from ${specifier}`}`);
+        return vocabulary;
+    }
+    // Warn only when the built-in table itself changes the outcome. A step with an
+    // explicit payloadField resolves the same under any vocabulary, so nagging
+    // about it would send consumers to fix something that isn't broken.
+    const builtinChangesOutcome = flowSteps.some((step) => {
+        const isObj = typeof step !== "string";
+        const instruction = isObj ? step.step : step;
+        const explicit = isObj ? step.payloadField : undefined;
+        const forceNone = isObj ? step.payloadFieldNone : undefined;
+        const withBuiltin = resolveStepPayloadField(instruction, explicit, forceNone, DEPRECATED_BUILTIN_ATS_VOCABULARY);
+        const withNothing = resolveStepPayloadField(instruction, explicit, forceNone, vocabulary_1.EMPTY_VOCABULARY);
+        return withBuiltin !== withNothing;
+    });
+    if (builtinChangesOutcome) {
+        logger.warn(`DeprecationWarning: no --vocabulary given, falling back to the built-in recruiting table. ` +
+            `It is removed in 2.0.0, after which this is an error. Fix: create a vocabulary module ` +
+            `exporting a ReconVocabulary (see @enricai/barnacle/recon/vocabulary) and pass ` +
+            `--vocabulary ./src/recon/<name>.ts, or --vocabulary none if this site splices no caller data.`);
+    }
+    return DEPRECATED_BUILTIN_ATS_VOCABULARY;
+}
 async function main() {
     const args = process.argv.slice(2);
     let siteId = "";
     let force = false;
     let emit = "ts";
+    let vocabularySpecifier = "";
     for (let i = 0; i < args.length; i++) {
         if (args[i] === "--site-id" && args[i + 1])
             siteId = args[++i];
+        else if (args[i] === "--vocabulary" && args[i + 1])
+            vocabularySpecifier = args[++i];
         else if (args[i] === "--force")
             force = true;
         else if (args[i] === "--emit" && args[i + 1]) {
@@ -2412,6 +2633,10 @@ async function main() {
             return [];
         }
     })();
+    // Resolved once and threaded down, never captured into a module const: a
+    // module-level const would freeze at import time, which is the bug that makes
+    // RECON_QUESTION_KEYWORDS silently inert for anyone setting it after load.
+    const vocabulary = await resolveVocabulary(vocabularySpecifier, flowSteps);
     const pascal = toPascalCase(siteId);
     const baseUrl = deriveBaseUrl(captures);
     const baseHeaders = deriveRequestHeaders(captures, replays, baseUrl);
@@ -2562,6 +2787,7 @@ async function main() {
                     s.capture.url.includes("recruitingCEJobApplicationDrafts"));
                 if (draftPostStep && !draftPostStep.produces.some((p) => p.name === "draftId")) {
                     draftPostStep.produces.push({
+                        kind: "body",
                         name: "draftId",
                         pathExpr: `${draftPostStep.varName}.APPDraftId`,
                         path: ["APPDraftId"],
@@ -2570,6 +2796,7 @@ async function main() {
                 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({
+                        kind: "body",
                         name: "attachmentId",
                         pathExpr: `${attachPostStep.varName}.Id`,
                         path: ["Id"],
@@ -2618,6 +2845,7 @@ async function main() {
         ? emitMultiStepExecuteHttp(actionSteps, inputBody, errorSignals, fieldNameMap, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, base64PatchOverride)
         : multiStepBody;
     const hasMultipartStep = actionSteps.some((s) => s.isMultipart);
+    const headerBindings = collectHeaderBindings(actionSteps);
     // 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.
@@ -2632,6 +2860,7 @@ async function main() {
             displayName: pascal,
             baseUrl,
             flowSteps,
+            vocabulary,
         }));
         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)`);
@@ -2648,6 +2877,7 @@ async function main() {
         flowSteps,
         isSubmissionFlow,
         hasMultipartStep,
+        vocabulary,
     });
     (0, node_fs_1.writeFileSync)(`${outDir}/contract.ts`, emitContractTs({
         siteId,
@@ -2673,6 +2903,7 @@ async function main() {
         discoveredRawOptionFields,
         discoveredAdditionalBodyKeys,
         payloadFieldNames: browserFlow.payloadFieldNames,
+        headerBindings,
     }));
     logger.info(`wrote ${outDir}/contract.ts`);
     (0, node_fs_1.writeFileSync)(`${outDir}/flows/browser-flow.ts`, browserFlow.code);