@enricai/barnacle 1.5.0 → 1.6.0

package/dist/scripts/recon-generate.js

@@ -21,6 +21,7 @@ exports.resolveStepPayloadField = resolveStepPayloadField;
 exports.inferZodSchemaFromSamples = inferZodSchemaFromSamples;
 exports.selectPayloadAction = selectPayloadAction;
 exports.extractActionSequence = extractActionSequence;
+exports.detectFormSchemaFieldNames = detectFormSchemaFieldNames;
 exports.indexStateValues = indexStateValues;
 exports.compileActionSteps = compileActionSteps;
 exports.loadQuestionPromptKeywords = loadQuestionPromptKeywords;
@@ -35,6 +36,8 @@ 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 capture_filters_1 = require("../recon/capture-filters");
+const load_form_schema_1 = require("../recon/load-form-schema");
 const load_vocabulary_1 = require("../recon/load-vocabulary");
 const vocabulary_1 = require("../recon/vocabulary");
 const recon_shared_1 = require("../scripts/recon-shared");
@@ -334,9 +337,8 @@ const IGNORE_REQUEST_HEADERS = new Set([
  * stateless replay phase can't thread), derive headers from the meaningful
  * action POSTs instead — same `extractActionSequence` definition used by
  * the submission-flow detector. This catches load-bearing site-specific
- * headers (Workday's `X-CSRF-Token`, Greenhouse's `Job-Boards-API-Token`,
- * ClearCompany's `API-ShortName`, etc.) without the generator needing to
- * know about any particular site.
+ * headers (a `X-CSRF-Token`, a `Job-Boards-API-Token`, an `API-ShortName`,
+ * etc.) without the generator needing to know about any particular site.
  */
 function deriveRequestHeaders(captures, replays, baseUrl) {
     const successfulUrls = new Set(replays.filter((r) => r.success).map((r) => endpointKey(r.url)));
@@ -403,42 +405,6 @@ function firstEndpointPath(captures) {
     }
     return "/api/search";
 }
-// ── multi-step "submission flow" detection ────────────────────────────────────
-//
-// For transactional sites (apply forms, multi-step checkout, etc.) the captures
-// form an ordered sequence of POSTs that thread state values through subsequent
-// requests (auth tokens, candidate IDs, application IDs). Single-endpoint
-// sites (job search, pricing APIs) have one action capture and skip this path.
-/**
- * Path elements we always treat as noise (analytics, logging). Site-specific
- * trackers belong in RECON_TELEMETRY_URL_PATTERNS (comma-separated), not here —
- * the engine must not carry any one site's ad-tech domains.
- */
-const TELEMETRY_URL_PATTERNS = [
-    "/util/logging/vweb/message",
-    "/blank/page",
-    "stats.g.doubleclick.net",
-    "google-analytics.com",
-    ...(process.env.RECON_TELEMETRY_URL_PATTERNS ?? "")
-        .split(",")
-        .map((p) => p.trim())
-        .filter(Boolean),
-];
-/**
- * A POST to a path whose own segment is `error`/`errors` is a client-side
- * reporting sink, never a call a caller wants replayed.
- *
- * Emitting one is worse than noise. A browser's error reports are frozen at
- * recon time, so the generated plugin re-POSTs a crash that never happened —
- * a stack trace and timestamp from the recon run, sent to the site on every
- * invocation, describing a failure in a page the plugin never loaded.
- *
- * Matched on a whole path segment rather than by substring so `/error-codes`
- * and `/terrorism-screening` stay data endpoints, and kept out of
- * TELEMETRY_URL_PATTERNS because that list is literal substrings — a site's own
- * sink is structural, not an ad-tech domain the operator must enumerate.
- */
-const ERROR_SINK_PATH_SEGMENT = /(^|\/)errors?(\/|$)/i;
 /**
  * Extracts the ordered sequence of meaningful POSTs that represent the
  * transactional flow: same-host 2xx POSTs, minus telemetry and error-reporting
@@ -472,15 +438,8 @@ function extractActionSequence(captures, baseUrl) {
         }
         if (captureHost !== host)
             return false;
-        if (TELEMETRY_URL_PATTERNS.some((p) => capture.url.includes(p)))
-            return false;
-        try {
-            if (ERROR_SINK_PATH_SEGMENT.test(new URL(capture.url).pathname))
-                return false;
-        }
-        catch {
+        if ((0, capture_filters_1.isNoiseUrl)(capture.url))
             return false;
-        }
         return true;
     });
 }
@@ -571,7 +530,7 @@ const KNOWN_TOP_LEVEL_ERROR_KEYS = new Set(["message", "error", "errormessage"])
 /**
  * Suffixes that mark a JSON key as carrying validation/data errors when its
  * value is non-null. Case-sensitive because real APIs use mixed-case in the
- * exact form they ship (e.g. ClearCompany's `ResponseValidationErrors`).
+ * exact form they ship (e.g. a `ResponseValidationErrors` key).
  */
 const NESTED_ERROR_KEY_SUFFIXES = ["ValidationErrors", "DataErrors", "ValidationError"];
 /**
@@ -581,7 +540,7 @@ const NESTED_ERROR_KEY_SUFFIXES = ["ValidationErrors", "DataErrors", "Validation
  * responses (so legitimate success-only fields like `Name` aren't false-
  * flagged as errors).
  *
- * Site-agnostic: ClearCompany uses `Message`/`Sections.ResponseValidationErrors`
+ * Site-agnostic: one ATS may use `Message`/`Sections.ResponseValidationErrors`
  * /`Sections.DataValidationErrors`; a different ATS using `error`/`errors[]`
  * would emit guards for those instead.
  */
@@ -642,7 +601,7 @@ function walkForNestedErrorKeys(value, path, candidates) {
  */
 const UUID_REGEX = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
 /**
- * Converts a FieldSourceCode like "contact.first.name" or "address.country.subdivision"
+ * Converts a machine code like "contact.first.name" or "address.country.subdivision"
  * to PascalCase: "ContactFirstName", "AddressCountrySubdivision". Site-agnostic:
  * operates only on the input string. Returns null for inputs that don't
  * produce a valid JS identifier.
@@ -655,7 +614,7 @@ function sourceCodeToPascalCase(sourceCode) {
     return isValidJsIdentifier(pascal) ? pascal : null;
 }
 /**
- * Converts a free-form FieldName like "Reference #1 First Name" or "Email" to
+ * Converts a free-form field label like "Reference #1 First Name" or "Email" to
  * PascalCase, stripping punctuation in a way that preserves position (so
  * "Reference #1 First Name" → "Reference1FirstName" via a section-heading
  * prefix). Site-agnostic: operates only on input strings.
@@ -691,60 +650,70 @@ function fieldNameToPascalCase(fieldName, prefix) {
 }
 /**
  * Recon-driven detection of form-schema captures. Scans all response bodies
- * for arrays whose objects look like SectionField (UUID-shaped FieldId plus
- * FieldName or FieldSourceCode). Builds FieldId → PascalCase name map.
+ * for arrays whose objects look like form fields (a UUID-shaped field-id key
+ * plus at least one of the schema's name keys). Builds field-id → PascalCase
+ * name map.
+ *
+ * Site-agnostic: identifies form-schema captures by structural fingerprint
+ * against the consumer-supplied keys, not by URL or site name. Any ATS exposing
+ * a matching schema would match.
  *
- * Site-agnostic: identifies form-schema captures by structural fingerprint,
- * not by URL or site name. Any ATS exposing a similar schema would match.
+ * Exported for unit testing — lets tests prove the rewiring: the same field is
+ * recovered whether the supplied keys are one vendor's names or a differing
+ * vendor's, and that a null schema recovers nothing.
  */
-function detectFormSchemaFieldNames(captures) {
+function detectFormSchemaFieldNames(captures, formSchema) {
     const fieldNameMap = new Map();
     const fieldOptionsMap = new Map();
     const allSchemaUuids = new Set();
+    // No form-schema declared → recover nothing. The engine carries no vendor's
+    // wire keys, so there is nothing to fingerprint ATS responses against.
+    if (formSchema === null)
+        return { fieldNameMap, fieldOptionsMap, allSchemaUuids };
     for (const capture of captures) {
-        walkForSectionFieldsArrays(capture.responseBody, fieldNameMap, fieldOptionsMap);
-        walkForSchemaUuids(capture.responseBody, allSchemaUuids);
+        walkForSectionFieldsArrays(capture.responseBody, fieldNameMap, fieldOptionsMap, formSchema);
+        walkForSchemaUuids(capture.responseBody, allSchemaUuids, formSchema);
     }
     return { fieldNameMap, fieldOptionsMap, allSchemaUuids };
 }
 /**
- * Walks a response body collecting UUID-shaped strings under a `FieldId` key, or
- * under the `Id` of an entry in a sibling `FieldOptions` array. These are stable
- * schema anchors that must be shielded from state-threading even when
- * detectFormSchemaFieldNames emits no payload-mappable name for the field (e.g.
- * when the field's FieldName is too long for our naming heuristic).
+ * Walks a response body collecting UUID-shaped strings under the schema's
+ * field-id key, or under the option-id key of an entry in a sibling
+ * field-options array. These are stable schema anchors that must be shielded
+ * from state-threading even when detectFormSchemaFieldNames emits no
+ * payload-mappable name for the field (e.g. when the field name is too long for
+ * our naming heuristic).
  *
- * The key names are exact by design, not an oversight: a differing wire format
- * (a lowercase `fieldId`, another vendor's option key) is the consumer's to
- * declare, not the engine's to guess — see issue #57. Matching case variants
- * here would re-broaden the very fingerprint that issue exists to narrow.
+ * The wire keys come from the consumer-supplied {@link ReconFormSchema}, so a
+ * vendor declares its own keys with `--form-schema` rather than the engine
+ * hardcoding any — the inversion issue #57 asked for.
  */
-function walkForSchemaUuids(value, out) {
+function walkForSchemaUuids(value, out, formSchema) {
     if (value === null || typeof value !== "object")
         return;
     if (Array.isArray(value)) {
         for (const item of value)
-            walkForSchemaUuids(item, out);
+            walkForSchemaUuids(item, out, formSchema);
         return;
     }
     const obj = value;
-    const fieldIdRaw = obj.FieldId;
+    const fieldIdRaw = obj[formSchema.fieldIdKey];
     if (typeof fieldIdRaw === "string" && UUID_REGEX.test(fieldIdRaw)) {
         out.add(fieldIdRaw);
     }
-    const optionsRaw = obj.FieldOptions;
+    const optionsRaw = obj[formSchema.fieldOptionsKey];
     if (Array.isArray(optionsRaw)) {
         for (const opt of optionsRaw) {
             if (opt !== null && typeof opt === "object") {
-                const optId = opt.Id;
+                const optId = opt[formSchema.optionIdKey];
                 if (typeof optId === "string" && UUID_REGEX.test(optId))
                     out.add(optId);
             }
         }
     }
-    // Recurse into nested objects/arrays so nested SectionFields get walked too.
+    // Recurse into nested objects/arrays so nested form fields get walked too.
     for (const v of Object.values(obj))
-        walkForSchemaUuids(v, out);
+        walkForSchemaUuids(v, out, formSchema);
 }
 /**
  * Closed enum of well-known cache-buster query parameter names. Stripped
@@ -767,14 +736,14 @@ function stripCacheBusterParams(url) {
 }
 /**
  * Recon-driven detection of the form-schema fetch capture. Returns the first
- * GET capture (in recon order) whose response body contains a SectionFields-
- * shaped array. Sites without such a capture get `null` and Phase B/C/D
- * become no-ops.
+ * GET capture (in recon order) whose response body contains a form-fields-
+ * shaped array (per the supplied schema keys). Sites without such a capture get
+ * `null` and Phase B/C/D become no-ops.
  *
  * Site-agnostic: identifies the fetch by structural fingerprint of the
  * response body, not by URL or site name.
  */
-function detectFormSchemaFetchCapture(captures, baseUrl) {
+function detectFormSchemaFetchCapture(captures, baseUrl, formSchema) {
     let host;
     try {
         host = new URL(baseUrl).host;
@@ -797,52 +766,52 @@ function detectFormSchemaFetchCapture(captures, baseUrl) {
         }
         if (captureHost !== host)
             continue;
-        if (TELEMETRY_URL_PATTERNS.some((p) => capture.url.includes(p)))
+        if ((0, capture_filters_1.telemetryUrlPatterns)().some((p) => capture.url.includes(p)))
             continue;
-        if (responseContainsSectionFields(capture.responseBody)) {
+        if (responseContainsSectionFields(capture.responseBody, formSchema)) {
             return { capture, index: i };
         }
     }
     return null;
 }
-function responseContainsSectionFields(value) {
+function responseContainsSectionFields(value, formSchema) {
     if (value === null || typeof value !== "object")
         return false;
     if (Array.isArray(value)) {
-        if (looksLikeSectionFieldsArray(value))
+        if (looksLikeSectionFieldsArray(value, formSchema))
             return true;
         for (const item of value) {
-            if (responseContainsSectionFields(item))
+            if (responseContainsSectionFields(item, formSchema))
                 return true;
         }
         return false;
     }
     for (const v of Object.values(value)) {
-        if (responseContainsSectionFields(v))
+        if (responseContainsSectionFields(v, formSchema))
             return true;
     }
     return false;
 }
-function walkForSectionFieldsArrays(value, fieldNameMap, fieldOptionsMap) {
+function walkForSectionFieldsArrays(value, fieldNameMap, fieldOptionsMap, formSchema) {
     if (value === null || typeof value !== "object")
         return;
     if (Array.isArray(value)) {
-        if (looksLikeSectionFieldsArray(value)) {
-            assignFieldNamesFromArray(value, fieldNameMap, fieldOptionsMap);
+        if (looksLikeSectionFieldsArray(value, formSchema)) {
+            assignFieldNamesFromArray(value, fieldNameMap, fieldOptionsMap, formSchema);
         }
         for (const item of value)
-            walkForSectionFieldsArrays(item, fieldNameMap, fieldOptionsMap);
+            walkForSectionFieldsArrays(item, fieldNameMap, fieldOptionsMap, formSchema);
         return;
     }
     for (const v of Object.values(value)) {
-        walkForSectionFieldsArrays(v, fieldNameMap, fieldOptionsMap);
+        walkForSectionFieldsArrays(v, fieldNameMap, fieldOptionsMap, formSchema);
     }
 }
 /**
  * Structural fingerprint: array of objects, at least half of which have a
- * UUID-shaped FieldId AND at least one of FieldName/FieldSourceCode.
+ * UUID-shaped field-id AND at least one of the schema's field-name keys.
  */
-function looksLikeSectionFieldsArray(arr) {
+function looksLikeSectionFieldsArray(arr, formSchema) {
     if (arr.length === 0)
         return false;
     let matches = 0;
@@ -850,26 +819,31 @@ function looksLikeSectionFieldsArray(arr) {
         if (item === null || typeof item !== "object")
             continue;
         const obj = item;
-        const fieldIdRaw = obj.FieldId;
+        const fieldIdRaw = obj[formSchema.fieldIdKey];
         if (typeof fieldIdRaw !== "string")
             continue;
         if (!UUID_REGEX.test(fieldIdRaw))
             continue;
-        if (typeof obj.FieldName === "string" || typeof obj.FieldSourceCode === "string") {
+        if (formSchema.fieldNameKeys.some((key) => typeof obj[key] === "string")) {
             matches++;
         }
     }
     return matches >= Math.max(1, Math.floor(arr.length * 0.5));
 }
-function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap) {
+function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap, formSchema) {
     let currentPrefix = null;
     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).
+    // With one key both branches collapse to the label path.
+    const [codeKey, ...labelKeys] = formSchema.fieldNameKeys;
+    const labelKey = labelKeys[0];
     for (const obj of arr) {
-        const fieldId = obj.FieldId;
+        const fieldId = obj[formSchema.fieldIdKey];
         if (typeof fieldId !== "string")
             continue;
-        const sourceCode = obj.FieldSourceCode;
-        const name = obj.FieldName;
+        const sourceCode = codeKey !== undefined && labelKey !== undefined ? obj[codeKey] : undefined;
+        const name = labelKey !== undefined ? obj[labelKey] : obj[codeKey ?? ""];
         let semantic = null;
         if (typeof sourceCode === "string" && sourceCode.trim().length > 0) {
             semantic = sourceCodeToPascalCase(sourceCode);
@@ -877,7 +851,7 @@ function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap) {
         }
         else if (typeof name === "string" && name.trim().length > 0 && name.length < 250) {
             const hasNoSourceCode = typeof sourceCode !== "string" || sourceCode.trim().length === 0;
-            // Section-heading heuristic: short FieldName, no SourceCode, MOSTLY
+            // Section-heading heuristic: short label, no machine code, MOSTLY
             // uppercase letters (>= 70% of alphabetic chars) OR contains '#'.
             // Whole-name uppercase ratio avoids false positives like "MM/DD/YYYY"
             // appearing as a format hint inside a normal field label.
@@ -903,11 +877,11 @@ function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap) {
             }
             fieldNameMap.set(fieldId, unique);
             usedNames.add(unique);
-            // Capture FieldOptions when present and ALL options have non-empty
-            // semantic Values (SystemFieldOption-tagged). Custom options with empty
-            // Value are skipped — they have no semantic label, so we can't generate
-            // a meaningful enum and leave the field's OptionId baked.
-            const optionsRaw = obj.FieldOptions;
+            // Capture the field's options when present and ALL options have non-empty
+            // semantic labels. Options with an empty label are skipped — with no
+            // semantic value we can't generate a meaningful enum, so we leave the
+            // field's option-id baked.
+            const optionsRaw = obj[formSchema.fieldOptionsKey];
             if (Array.isArray(optionsRaw) && optionsRaw.length > 0) {
                 const options = [];
                 let allSemantic = true;
@@ -917,8 +891,8 @@ function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap) {
                         break;
                     }
                     const opt = optRaw;
-                    const optId = opt.Id;
-                    const optValue = opt.Value;
+                    const optId = opt[formSchema.optionIdKey];
+                    const optValue = opt[formSchema.optionValueKey];
                     if (typeof optId !== "string" ||
                         typeof optValue !== "string" ||
                         optValue.trim().length === 0) {
@@ -935,20 +909,21 @@ function assignFieldNamesFromArray(arr, fieldNameMap, fieldOptionsMap) {
     }
 }
 /**
- * Substitutes Responses[].Value literals with payload accessors based on the
+ * Substitutes the submitted-value literals with payload accessors based on the
  * field-name map from the form schema. Operates on the body string before
  * state interpolation so already-substituted state values (e.g. ${firstName})
  * are preserved.
  *
- * Closed-set substring matching: both FieldId and the literal Value come from
- * the generator's own input (recon).
+ * Closed-set substring matching: both the field-id and the submitted value come
+ * from the generator's own input (recon).
  */
-function applyFormSchemaSubstitutions(rawBody, fieldNameMap, outDiscoveredFields) {
+function applyFormSchemaSubstitutions(rawBody, fieldNameMap, outDiscoveredFields, formSchema) {
     if (fieldNameMap.size === 0)
         return rawBody;
     let result = rawBody;
+    const valueMarker = `"${formSchema.responseValueKey}":"`;
     for (const [fieldId, semanticName] of fieldNameMap) {
-        const fieldIdMarker = `"FieldId":"${fieldId}"`;
+        const fieldIdMarker = `"${formSchema.fieldIdKey}":"${fieldId}"`;
         let cursor = 0;
         while (true) {
             const idx = result.indexOf(fieldIdMarker, cursor);
@@ -958,7 +933,6 @@ function applyFormSchemaSubstitutions(rawBody, fieldNameMap, outDiscoveredFields
             if (objEnd === -1)
                 break;
             const segment = result.slice(idx, objEnd);
-            const valueMarker = `"Value":"`;
             const valueIdx = segment.indexOf(valueMarker);
             if (valueIdx === -1) {
                 cursor = objEnd;
@@ -984,22 +958,23 @@ function applyFormSchemaSubstitutions(rawBody, fieldNameMap, outDiscoveredFields
     return result;
 }
 /**
- * Substitutes Responses[].OptionId literals with payload-driven enum lookups.
- * Operates on the body string before state interpolation. For each FieldId
- * with a captured FieldOptionsMapping, find `"FieldId":"<uuid>"` and rewrite
- * the matching `"OptionId":"<uuid>"` to `"OptionId":"${OPT_<Name>[payload.<Name>]}"`.
+ * Substitutes submitted option-id literals with payload-driven enum lookups.
+ * Operates on the body string before state interpolation. For each field with a
+ * captured FieldOptionsMapping, find the schema's field-id marker and rewrite
+ * the matching option-id value to `${OPT_<Name>[payload.<Name>]}`.
  *
- * Order-insensitive: matches `"OptionId":"<uuid>"` anywhere within the same
- * JSON object as the FieldId (which is between this FieldId marker and the
- * closing `}`). Closed-set substring matching: both FieldId and OptionId
- * come from the generator's own input.
+ * Order-insensitive: matches the option-id marker anywhere within the same
+ * JSON object as the field-id marker (which is between it and the closing `}`).
+ * Closed-set substring matching: both marker values come from the generator's
+ * own input.
  */
-function applyFormSchemaOptionIdSubstitutions(rawBody, fieldOptionsMap, outDiscoveredOptionFields) {
+function applyFormSchemaOptionIdSubstitutions(rawBody, fieldOptionsMap, outDiscoveredOptionFields, formSchema) {
     if (fieldOptionsMap.size === 0)
         return rawBody;
     let result = rawBody;
+    const optionIdMarker = `"${formSchema.responseOptionIdKey}":"`;
     for (const [fieldId, mapping] of fieldOptionsMap) {
-        const fieldIdMarker = `"FieldId":"${fieldId}"`;
+        const fieldIdMarker = `"${formSchema.fieldIdKey}":"${fieldId}"`;
         let cursor = 0;
         while (true) {
             const idx = result.indexOf(fieldIdMarker, cursor);
@@ -1009,7 +984,6 @@ function applyFormSchemaOptionIdSubstitutions(rawBody, fieldOptionsMap, outDisco
             if (objEnd === -1)
                 break;
             const segment = result.slice(idx, objEnd);
-            const optionIdMarker = `"OptionId":"`;
             const optionIdLocal = segment.indexOf(optionIdMarker);
             if (optionIdLocal === -1) {
                 cursor = objEnd;
@@ -1035,25 +1009,26 @@ function applyFormSchemaOptionIdSubstitutions(rawBody, fieldOptionsMap, outDisco
     return result;
 }
 /**
- * For fields whose FieldOptions have NO semantic values (CustomFieldOption
- * options where the recon schema's `.Value` is empty), T3's OPT_* enum
- * mapping can't be emitted. Instead, parameterize the OptionId slot as a
- * caller-supplied `<FieldName>OptionId` payload field with the recon-observed
- * UUID documented in a TSDoc comment.
+ * For fields whose options have NO semantic labels (the schema's option-label
+ * value is empty), T3's OPT_* enum mapping can't be emitted. Instead,
+ * parameterize the submitted option-id slot as a caller-supplied
+ * `<Name>OptionId` payload field with the recon-observed UUID documented in a
+ * TSDoc comment.
  *
- * Operates on the same `"FieldId":"<uuid>"` anchored search as
- * applyFormSchemaOptionIdSubstitutions, but only fires when the FieldId is
- * in fieldNameMap (has a semantic name) AND NOT in fieldOptionsMap (the
- * structured enum substitution didn't fire). Site-agnostic.
+ * Operates on the same field-id-anchored search as
+ * applyFormSchemaOptionIdSubstitutions, but only fires when the field is in
+ * fieldNameMap (has a semantic name) AND NOT in fieldOptionsMap (the structured
+ * enum substitution didn't fire). Site-agnostic.
  */
-function applyRawOptionIdPayloadSubstitutions(rawBody, fieldNameMap, fieldOptionsMap, outDiscoveredRawOptionFields) {
+function applyRawOptionIdPayloadSubstitutions(rawBody, fieldNameMap, fieldOptionsMap, outDiscoveredRawOptionFields, formSchema) {
     if (fieldNameMap.size === 0)
         return rawBody;
     let result = rawBody;
+    const optionIdMarker = `"${formSchema.responseOptionIdKey}":"`;
     for (const [fieldId, fieldName] of fieldNameMap) {
         if (fieldOptionsMap.has(fieldId))
             continue; // T3's OPT_* already handles this.
-        const fieldIdMarker = `"FieldId":"${fieldId}"`;
+        const fieldIdMarker = `"${formSchema.fieldIdKey}":"${fieldId}"`;
         let cursor = 0;
         while (true) {
             const idx = result.indexOf(fieldIdMarker, cursor);
@@ -1063,7 +1038,6 @@ function applyRawOptionIdPayloadSubstitutions(rawBody, fieldNameMap, fieldOption
             if (objEnd === -1)
                 break;
             const segment = result.slice(idx, objEnd);
-            const optionIdMarker = `"OptionId":"`;
             const optionIdLocal = segment.indexOf(optionIdMarker);
             if (optionIdLocal === -1) {
                 cursor = objEnd;
@@ -1097,13 +1071,14 @@ function applyRawOptionIdPayloadSubstitutions(rawBody, fieldNameMap, fieldOption
  * embedded base64 images, etc.) that aren't candidates for state threading. */
 const MAX_STATE_VALUE_LENGTH = 256;
 /** Canonical "uninitialized" sentinel values that some REST APIs return as
- * placeholders before a downstream call populates the real identifier.
- * ClearCompany's `/user/create` returns these for CandidateId/ApplicationId/
- * ApplyProcessId, then `/user/start` returns the real values. Indexing the
- * placeholder would lock the generated plugin's `${candidateId}` binding to
- * the all-zero UUID — every downstream call would then 404 with "candidate
- * does not exist". Closed set, literal-string match — never expand to
- * pattern-based detection (would trip the no-regex-on-open-sets rule). */
+ * placeholders before a downstream call populates the real identifier. An ATS
+ * whose `/user/create` returns these for CandidateId/ApplicationId/
+ * ApplyProcessId, then yields the real values on `/user/start`, is the case that
+ * motivated this: indexing the placeholder would lock the generated plugin's
+ * `${candidateId}` binding to the all-zero UUID — every downstream call would
+ * then 404 with "candidate does not exist". Closed set, literal-string match —
+ * never expand to pattern-based detection (would trip the no-regex-on-open-sets
+ * rule). */
 const PLACEHOLDER_STATE_VALUES = new Set(["00000000-0000-0000-0000-000000000000"]);
 /**
  * Splits a raw `Set-Cookie` response-header string into `name`/`value` pairs.
@@ -1199,8 +1174,9 @@ function indexStateValues(captures, shieldedUuids = new Set(), actionCaptureIndi
                 continue;
             if (PLACEHOLDER_STATE_VALUES.has(value))
                 continue;
-            // Schema-identifier UUIDs (FieldId, OptionId) are stable anchors that
-            // T2/T3 substitution depends on remaining literal in body templates.
+            // Schema-identifier UUIDs (the field-id and option-id anchors) are stable
+            // anchors that T2/T3 substitution depends on remaining literal in body
+            // templates.
             // Indexing them would let state-threading rewrite the anchors and
             // corrupt T2/T3's already-substituted Values.
             if (shieldedUuids.has(value))
@@ -1528,7 +1504,7 @@ function applyPayloadKeyValueSubstitutions(template, inputBody, additionalBodies
 // ── base64 Content parameterization ──────────────────────────────────────────
 /**
  * Maps a site's screening-question prompts to the payload field that answers
- * them, as `{ FieldName: [keyword, …] }`.
+ * them, as `{ payloadField: [keyword, …] }`.
  *
  * Empty by default and supplied by the operator via `RECON_QUESTION_KEYWORDS`
  * (JSON) — the engine cannot know what any site asks or what a caller's payload
@@ -1737,14 +1713,12 @@ function emitErrorSignalGuards(varName, urlPath, signals) {
         parentSegments.reverse();
         out.push(`      const ${parentVar} = (${varName} as { ${parentObjType} }).${parentAccessor};`);
         for (const { errorKey } of errorKeys) {
-            const label = errorKey === "ResponseValidationErrors"
-                ? "validation errors"
-                : errorKey === "DataValidationErrors"
-                    ? "data errors"
-                    : errorKey
-                        .replace(/([A-Z])/g, " $1")
-                        .trim()
-                        .toLowerCase();
+            // Humanize the wire key generically (CamelCase → "camel case"); no
+            // per-vendor special cases — the engine carries no vendor's key vocabulary.
+            const label = errorKey
+                .replace(/([A-Z])/g, " $1")
+                .trim()
+                .toLowerCase();
             out.push(`      if (${parentVar} != null && ${parentVar}.${errorKey} != null) throw new Error(\`step ${varName} ${label}: \${JSON.stringify(${parentVar}.${errorKey})}\`);`);
         }
     }
@@ -1752,7 +1726,7 @@ function emitErrorSignalGuards(varName, urlPath, signals) {
 }
 /** Exported for unit testing — lets tests drive the multipart-upload code path directly
  * without going through the full emitContractTs pipeline. */
-function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap, outDiscoveredFields, fieldOptionsMap, outDiscoveredOptionFields, outDiscoveredRawOptionFields, outDiscoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, base64PatchOverride = new Map()) {
+function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap, outDiscoveredFields, fieldOptionsMap, outDiscoveredOptionFields, outDiscoveredRawOptionFields, outDiscoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, base64PatchOverride = new Map(), formSchema = null) {
     // Walk the first action's request body to map each leaf string value to its
     // `payload.<accessor>` expression. The emit's second interpolation pass uses
     // this to substitute literal occurrences (e.g. "Reginald") with their
@@ -1791,7 +1765,7 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
         outDiscoveredFields.add("BaseUrl");
     }
     // G2: register any tenant-subdomain header values as payload-supplied fields
-    // (e.g. ClearCompany's `API-ShortName: "addus"` becomes `payload.ApiShortName`).
+    // (e.g. an `API-ShortName: "addus"` header becomes `payload.ApiShortName`).
     for (const [headerName, _value] of tenantSubdomainHeaders) {
         outDiscoveredFields.add(headerNameToPayloadFieldName(headerName));
     }
@@ -1819,13 +1793,16 @@ function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap
         const prior = actions.slice(0, i);
         const url = interpolateStateValues(cap.url, prior, payloadAccessorByValue);
         // Form-schema substitution runs first on the raw recon body so its
-        // FieldId-anchored matches see the original JSON. State-threading and
-        // payload key-value passes then run on top. OptionId substitution runs
-        // here too: same closed-set FieldId anchor; rewrites "OptionId":"<uuid>"
-        // slots to "${OPT_X[payload.X]}" lookups.
-        const rawBodyWithFormSubs = cap.requestPostData
-            ? applyRawOptionIdPayloadSubstitutions(applyFormSchemaOptionIdSubstitutions(applyFormSchemaSubstitutions(cap.requestPostData, fieldNameMap, outDiscoveredFields), fieldOptionsMap, outDiscoveredOptionFields), fieldNameMap, fieldOptionsMap, outDiscoveredRawOptionFields)
-            : "";
+        // field-id-anchored matches see the original JSON. State-threading and
+        // payload key-value passes then run on top. Option-id substitution runs
+        // here too: same closed-set field-id anchor; rewrites the submitted
+        // option-id slots to "${OPT_X[payload.X]}" lookups.
+        // Form-schema passes only fire when a `--form-schema` was supplied (which is
+        // also the only way the field maps are non-empty); without one they are
+        // no-ops and the raw recon body flows straight through.
+        const rawBodyWithFormSubs = cap.requestPostData && formSchema !== null
+            ? applyRawOptionIdPayloadSubstitutions(applyFormSchemaOptionIdSubstitutions(applyFormSchemaSubstitutions(cap.requestPostData, fieldNameMap, outDiscoveredFields, formSchema), fieldOptionsMap, outDiscoveredOptionFields, formSchema), fieldNameMap, fieldOptionsMap, outDiscoveredRawOptionFields, formSchema)
+            : (cap.requestPostData ?? "");
         let bodyTemplate = rawBodyWithFormSubs
             ? applyPayloadKeyValueSubstitutions(interpolateStateValues(rawBodyWithFormSubs, prior, payloadAccessorByValue), inputBody, additionalBodies, outDiscoveredAdditionalBodyKeys)
             : "";
@@ -2104,7 +2081,7 @@ function emitContractTs(opts) {
             .join("\n")}\n})`
         : "";
     // Build per-field OPT_<Name> constant declarations + payload-schema enum
-    // entries from the form schema's FieldOptions. Only fields whose OptionId
+    // 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
@@ -2131,16 +2108,16 @@ function emitContractTs(opts) {
             .map((m) => `  ${m.semanticName}: z.enum([${m.options.map((o) => JSON.stringify(o.value)).join(", ")}]),`)
             .join("\n")}\n})`
         : "";
-    // Phase E raw-option payload fields: FieldOptions whose .Value strings are
-    // empty in the schema (CustomFieldOption) — no semantic enum is possible,
-    // so the caller supplies the OptionId UUID directly. The recon-observed
-    // UUID is documented in a TSDoc comment so callers have a starting point.
+    // 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
+    // comment so callers have a starting point.
     const sortedRawOptionEntries = discoveredRawOptionFields
         ? [...discoveredRawOptionFields.entries()].sort(([a], [b]) => a.localeCompare(b))
         : [];
     const rawOptionSchemaExtension = sortedRawOptionEntries.length > 0
         ? `.extend({\n${sortedRawOptionEntries
-            .map(([name, reconUuid]) => `  /** Recon-observed: ${reconUuid}. Caller supplies the OptionId UUID for this field. */\n  ${name}: z.string(),`)
+            .map(([name, reconUuid]) => `  /** Recon-observed: ${reconUuid}. Caller supplies the option-id UUID for this field. */\n  ${name}: z.string(),`)
             .join("\n")}\n})`
         : "";
     // Phase F: additional-body keys (from action POSTs beyond r0). Each gets a
@@ -2415,12 +2392,16 @@ function jsonSchemaTypeOf(value) {
  * `recovered` carries the request contract the `.ts` path infers from real
  * captures — the first POST body's fields plus form-schema discoveries — so
  * `--emit config` no longer throws that away and emit a request schema built
- * only from the handful of flow-step splice hints. The direct-HTTP hot path is
- * still omitted; a site that needs it keeps the `.ts` path or wires
- * `spec.httpModule` by hand.
+ * only from the handful of flow-step splice hints.
+ *
+ * When the site has a direct-HTTP path (a submission flow whose `.ts` emit would
+ * carry an `executeHttp`), `httpModulePath` emits a `spec.httpModule` reference
+ * to a compiled module the operator drops in — the config plugin's escape hatch
+ * for the imperative hot path a JSON manifest cannot express. Absent that, the
+ * browser `flow` is the only execution path, and the field is omitted.
  */
 function emitConfigManifest(opts) {
-    const { siteId, displayName, baseUrl, flowSteps, vocabulary, inputBody, recoveredFields } = opts;
+    const { siteId, displayName, baseUrl, flowSteps, vocabulary, inputBody, recoveredFields, httpModulePath, } = opts;
     const payloadFieldNames = new Set();
     const steps = flowSteps.map((step) => {
         const isObj = typeof step !== "string";
@@ -2459,6 +2440,7 @@ function emitConfigManifest(opts) {
         metadata: { siteId, displayName },
         spec: {
             defaultBaseUrl: baseUrl,
+            ...(httpModulePath ? { httpModule: httpModulePath } : {}),
             request: { type: "object", properties: sortedRequestProperties },
             response: {
                 type: "object",
@@ -2650,17 +2632,36 @@ async function resolveVocabulary(specifier, flowSteps) {
     }
     return DEPRECATED_BUILTIN_ATS_VOCABULARY;
 }
+/**
+ * Resolves the form-schema for this run and reports which one is in play.
+ *
+ * The engine carries no vendor's wire format (issue #57): a consumer whose ATS
+ * exposes a form definition declares its keys with `--form-schema`. Absent one
+ * (or `--form-schema none`), form-key recovery does not run and the generator
+ * recovers nothing from ATS-shaped responses — the same "absence means none"
+ * discipline `--vocabulary` uses.
+ */
+async function resolveFormSchema(specifier) {
+    if (!specifier)
+        return null;
+    const formSchema = await (0, load_form_schema_1.loadReconFormSchema)(specifier, process.cwd());
+    logger.info(`form-schema: ${specifier === load_form_schema_1.FORM_SCHEMA_NONE ? "none (no ATS form recovery)" : `custom keys from ${specifier}`}`);
+    return formSchema;
+}
 async function main() {
     const args = process.argv.slice(2);
     let siteId = "";
     let force = false;
     let emit = "ts";
     let vocabularySpecifier = "";
+    let formSchemaSpecifier = "";
     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] === "--form-schema" && args[i + 1])
+            formSchemaSpecifier = args[++i];
         else if (args[i] === "--force")
             force = true;
         else if (args[i] === "--emit" && args[i + 1]) {
@@ -2731,6 +2732,9 @@ async function main() {
     // 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);
+    // Consumer-supplied wire keys for ATS form-schema recovery, or null. When
+    // null the recovery functions no-op — the engine hardcodes no vendor format.
+    const formSchema = await resolveFormSchema(formSchemaSpecifier);
     const pascal = toPascalCase(siteId);
     const baseUrl = deriveBaseUrl(captures);
     const baseHeaders = deriveRequestHeaders(captures, replays, baseUrl);
@@ -2746,15 +2750,15 @@ async function main() {
     const rawActionCaptures = gql
         ? []
         : collapseRedundantPatches(extractActionSequence(captures, baseUrl));
-    // Form-schema detection runs BEFORE state-indexing so the FieldId/OptionId
+    // Form-schema detection runs BEFORE state-indexing so the field-id/option-id
     // UUIDs can be shielded from indexing — those UUIDs are stable schema
     // anchors that T2/T3 substitution depends on remaining literal in body
     // templates.
-    const { fieldNameMap, fieldOptionsMap, allSchemaUuids } = detectFormSchemaFieldNames(captures);
-    // Shield ALL FieldId/OptionId UUIDs that appear in any schema response, not
+    const { fieldNameMap, fieldOptionsMap, allSchemaUuids } = detectFormSchemaFieldNames(captures, formSchema);
+    // Shield ALL field-id/option-id UUIDs that appear in any schema response, not
     // just the ones that detectFormSchemaFieldNames emits a payload name for.
-    // Some fields have FieldNames too long for the naming heuristic (>80 chars)
-    // and would be skipped by fieldNameMap; their FieldIds still need shielding
+    // Some fields have names too long for the naming heuristic (>80 chars) and
+    // would be skipped by fieldNameMap; their field-ids still need shielding
     // because they appear as anchors in the T2-substituted body templates.
     const shieldedUuids = new Set(allSchemaUuids);
     // T4 — Phase B+C: detect a form-schema GET capture and insert it into the
@@ -2764,7 +2768,7 @@ async function main() {
     // params (recon timestamps) from the captured URL so the emitted runtime
     // fetch uses a clean template. Sites without a schema-fetch capture
     // (rawSchemaFetch === null) get unchanged behavior.
-    const rawSchemaFetch = gql ? null : detectFormSchemaFetchCapture(captures, baseUrl);
+    const rawSchemaFetch = gql || formSchema === null ? null : detectFormSchemaFetchCapture(captures, baseUrl, formSchema);
     const schemaFetchCleaned = rawSchemaFetch
         ? { ...rawSchemaFetch.capture, url: stripCacheBusterParams(rawSchemaFetch.capture.url) }
         : null;
@@ -2805,9 +2809,9 @@ async function main() {
     const errorSignals = detectErrorSignals(actionSteps);
     const discoveredFormFields = new Set();
     const discoveredOptionFields = new Set();
-    // Phase E: maps FieldName-derived raw-option payload field name (e.g.
-    // "AreYouOverTheAgeOf18OptionId") → recon-observed OptionId UUID. Used to
-    // emit `<FieldName>OptionId: z.string()` payload fields with TSDoc docs.
+    // Phase E: maps label-derived raw-option payload field name (e.g.
+    // "AreYouOverTheAgeOf18OptionId") → recon-observed option-id UUID. Used to
+    // emit `<Name>OptionId: z.string()` payload fields with TSDoc docs.
     const discoveredRawOptionFields = new Map();
     // Phase F: keys from additional action POST bodies (beyond inputBody/r0)
     // that get parameterized. Recorded with their value type so the contract
@@ -2844,7 +2848,7 @@ async function main() {
         }
     }
     const multiStepBody = isSubmissionFlow
-        ? emitMultiStepExecuteHttp(actionSteps, inputBody, errorSignals, fieldNameMap, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders)
+        ? emitMultiStepExecuteHttp(actionSteps, inputBody, errorSignals, fieldNameMap, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, new Map(), formSchema)
         : undefined;
     let base64ContentHelper = "";
     const base64PatchOverride = new Map();
@@ -2936,7 +2940,7 @@ async function main() {
         }
     }
     const processedMultiStepBody = isSubmissionFlow
-        ? emitMultiStepExecuteHttp(actionSteps, inputBody, errorSignals, fieldNameMap, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, base64PatchOverride)
+        ? emitMultiStepExecuteHttp(actionSteps, inputBody, errorSignals, fieldNameMap, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, base64PatchOverride, formSchema)
         : multiStepBody;
     const hasMultipartStep = actionSteps.some((s) => s.isMultipart);
     const headerBindings = collectHeaderBindings(actionSteps);
@@ -2957,6 +2961,10 @@ async function main() {
             vocabulary,
             inputBody,
             recoveredFields: [...discoveredFormFields, ...discoveredOptionFields],
+            // 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.
+            httpModulePath: isSubmissionFlow ? `./${siteId}.http.js` : undefined,
         }));
         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)`);