@enricai/barnacle 1.5.0 → 1.6.1

package/README.md

@@ -106,6 +106,63 @@ Each step runs through a self-healing cascade (`act` → `observe + act` → `ob
 
 Total runtime: 20–40 minutes for a typical flow (longer if healing or replans fire), fully unattended.
 
+#### Cookie-jar snapshots
+
+Alongside the network captures, every run snapshots the browser's complete cookie jar (via CDP `Network.getAllCookies`, which returns the whole-browser jar regardless of the current page's URL — unlike `document.cookie` or `Page.getCookies`, it also sees HttpOnly cookies) at each phase boundary: the initial goto, immediately before each flow step (`pre-step`), immediately after each flow step completes (`post-step`), and once more at run completion (`run-complete`).
+
+Snapshots land in `/tmp/recon/cookies/<NNN>-<label>-<phase>.json` — one file per boundary, using the same zero-padded chronological index convention as the network captures. `<label>` is the boundary kind (`goto`, `pre-step`, `post-step`, `run-complete`); `<phase>` is the current step's slugified instruction (e.g. `click-the-apply-button`), or `home` before the first step starts.
+
+Each file is a JSON object:
+
+```json
+{
+  "label": "post-step",
+  "phase": "click-the-apply-button",
+  "stepIndex": 2,
+  "timestamp": "2026-07-18T12:34:56.789Z",
+  "cookies": [
+    {
+      "name": "_appcast_attr",
+      "value": "abc123",
+      "domain": ".appcast.io",
+      "path": "/",
+      "expires": 1234567890,
+      "size": 20,
+      "httpOnly": true,
+      "secure": true,
+      "session": false,
+      "sameSite": "Lax"
+    }
+  ]
+}
+```
+
+Field reference (mirrors CDP's `Network.Cookie` type verbatim — no remapping between capture and disk):
+
+| Field | Meaning |
+| --- | --- |
+| `name` / `value` | The cookie's name and value. |
+| `domain` | Scope, e.g. `.appcast.io` (all subdomains) vs. `apply.appcast.io` (exact host) — the detail needed to tell a click-domain cookie from an apply-domain cookie. |
+| `path` | Cookie path scope. |
+| `expires` | Raw CDP epoch-seconds number; `-1` means a session cookie (also reflected in `session: true`). Not reformatted — read it as CDP reports it. |
+| `size` | Cookie size in bytes, as reported by CDP. |
+| `httpOnly` / `secure` | Standard cookie flags. |
+| `session` | `true` for a session cookie (no persistent expiry). |
+| `sameSite` | `"Strict" \| "Lax" \| "None" \| null` — `null` when the cookie doesn't set the attribute. |
+
+If the CDP call fails, the file still writes but with an empty `cookies` array and an `error` string field carrying the failure message — cookie telemetry is best-effort and never aborts the run.
+
+**Diffing what a phase established:** to isolate what a specific traversal (e.g. the click.appcast.io redirect) minted, diff its `post-step` snapshot against the `pre-step` snapshot for the *next* step — cookies present in the later file but absent from the earlier one were established during that step:
+
+```bash
+diff <(jq -S .cookies /tmp/recon/cookies/004-post-step-click-the-apply-button.json) \
+     <(jq -S .cookies /tmp/recon/cookies/005-pre-step-fill-in-your-name.json)
+```
+
+**Cookies actually sent per request:** the jar snapshot shows what's *available*, not what's *sent*. Each network capture in `/tmp/recon/graphql/` separately carries the outgoing `Cookie` header in its `requestHeaders` (recovered via CDP's `Network.requestWillBeSentExtraInfo`, since `requestWillBeSent` omits it by design) — cross-reference that capture's `requestHeaders.Cookie` against a jar snapshot to see which of the available cookies a given request, e.g. the application submit, actually sent.
+
+**Caveat on `Set-Cookie`:** response captures fold `responseReceivedExtraInfo` headers (which is where `Set-Cookie` actually appears — `responseReceived` omits it) into `responseHeaders` as a flat `Record<string, string>`. CDP does not guarantee multiple `Set-Cookie` values on one response stay distinguishable once folded into that shape — if a single response mints more than one cookie, treat the jar snapshot (not the response capture's `Set-Cookie` header) as the source of truth for what actually landed.
+
 ### Phase 2–3 — Replay and probe
 
 ```bash
@@ -165,6 +222,35 @@ pnpm run recon:generate -- --site-id my-site --vocabulary ./src/recon/my-vocabul
 
 > **Deprecated fallback:** omit `--vocabulary` and the generator falls back to a built-in recruiting table (first/last name, email, phone, address), warning as it does. That table is **removed in 2.0.0**, after which an absent vocabulary on a spliceable flow is an error. Supply one now.
 
+#### Telling the generator your ATS's form-schema wire keys
+
+Where `--vocabulary` matches instruction *prose*, `--form-schema` names the JSON *keys* the generator reads out of an ATS's form-definition responses when recovering field ids, option ids, and submitted values. The engine ships no vendor's format; a site whose ATS exposes a form definition declares its keys with `--form-schema`:
+
+```ts
+// src/recon/my-form-schema.ts
+import type { ReconFormSchema } from "@enricai/barnacle/recon/form-schema";
+
+export const formSchema: ReconFormSchema = {
+  fieldIdKey: "fieldId",                    // UUID-valued field identity
+  fieldNameKeys: ["code", "label"],         // code, then human label — code preferred
+  fieldOptionsKey: "options",
+  optionIdKey: "optionId",                  // option id, inside the options array
+  optionValueKey: "optionLabel",            // option label, inside the options array
+  responseValueKey: "submittedValue",       // submitted free value
+  responseOptionIdKey: "submittedOptionId", // submitted option reference
+};
+```
+
+```bash
+pnpm run recon:generate -- --site-id my-site --form-schema ./src/recon/my-form-schema.ts
+```
+
+- The specifier follows the same rule as `--vocabulary`: a leading `.` or `/` is a filesystem path; anything else resolves from your `node_modules`. The module may export `formSchema` or a default.
+- **`--form-schema none`** for a site with no ATS form definition (a search API, a cruise site) — same as omitting it. "none" is the explicit form.
+- Wire keys anchor `"key":"uuid"` markers, so they may be any non-empty string without a quote or backslash — the JS-identifier rule that governs vocabulary field names does **not** apply here.
+- `fieldNameKeys` models two roles: the first key is a machine code (PascalCased directly), the second is a human label (run through the section-heading heuristic). Supply one key for a label-only ATS, or two for one that exposes both. Additional keys are unused.
+- Omit `--form-schema` (or pass `none`) and ATS form-key recovery does not run — the engine hardcodes no vendor's wire format. A site whose ATS exposes a form definition must supply one to recover its option fields. See issue #57.
+
 #### Mapping the site's screening questions
 
 If the site asks screening questions, tell the generator which payload field answers each one — the same reasoning applies, it cannot know what your site asks:

package/dist/api/errors.d.ts

@@ -54,7 +54,8 @@ export declare class ThrottledRequestError extends ApiError {
     constructor(message?: string);
 }
 /**
- * The upstream vendor has locked the target URL (e.g. Oracle ORA_URL_LOCKED).
+ * The upstream site has locked the target URL (a plugin raises the underlying
+ * `HttpUrlLockedError`, e.g. from a `classifyResponseBody` sentinel).
  * Signals "back off and retry later" — not a browser-fallback trigger.
  */
 export declare class UrlLockedError extends ApiError {

package/dist/api/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5F;;;;GAIG;AACH,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,eAAe,EAAE,CAAC;KAC5B,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAgCzD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,YAAY,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,SAAU,EAKjE;CACF;AAED,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,YAAY,OAAO,SAA4C,EAE9D;CACF;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,YAAY,OAAO,SAAwB,EAE1C;CACF;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,YAAY,OAAO,SAA6D,EAE/E;CACF;AAED,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,YAAY,OAAO,SAA0C,EAE5D;CACF;AAED,qBAAa,uBAAwB,SAAQ,QAAQ;IACnD,YAAY,OAAO,SAA2C,EAE7D;CACF;AAED,qBAAa,oBAAqB,SAAQ,QAAQ;IAChD,YAAY,OAAO,SAA6C,EAE/D;CACF;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,YAAY,OAAO,SAA4C,EAE9D;CACF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,UAAU,SAAU,GACnB,gBAAgB,CAgBlB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5F;;;;GAIG;AACH,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,eAAe,EAAE,CAAC;KAC5B,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAgCzD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,YAAY,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,SAAU,EAKjE;CACF;AAED,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,YAAY,OAAO,SAA4C,EAE9D;CACF;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,YAAY,OAAO,SAAwB,EAE1C;CACF;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,YAAY,OAAO,SAA2D,EAE7E;CACF;AAED,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,YAAY,OAAO,SAA0C,EAE5D;CACF;AAED,qBAAa,uBAAwB,SAAQ,QAAQ;IACnD,YAAY,OAAO,SAA2C,EAE7D;CACF;AAED,qBAAa,oBAAqB,SAAQ,QAAQ;IAChD,YAAY,OAAO,SAA6C,EAE/D;CACF;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,YAAY,OAAO,SAA4C,EAE9D;CACF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,UAAU,SAAU,GACnB,gBAAgB,CAgBlB"}

package/dist/api/errors.js

@@ -100,11 +100,12 @@ class ThrottledRequestError extends ApiError {
 }
 exports.ThrottledRequestError = ThrottledRequestError;
 /**
- * The upstream vendor has locked the target URL (e.g. Oracle ORA_URL_LOCKED).
+ * The upstream site has locked the target URL (a plugin raises the underlying
+ * `HttpUrlLockedError`, e.g. from a `classifyResponseBody` sentinel).
  * Signals "back off and retry later" — not a browser-fallback trigger.
  */
 class UrlLockedError extends ApiError {
-    constructor(message = "target URL is locked by the upstream vendor; retry later") {
+    constructor(message = "target URL is locked by the upstream site; retry later") {
         super(common_1.ERROR_CODES.URL_LOCKED, message);
     }
 }

package/dist/api/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"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"}

package/dist/lib/llm/judge.d.ts

@@ -3,7 +3,7 @@
  * routes through this — submit-verification, invalid-field detection, modal-
  * priority ranking, error-message extraction. Replaces deterministic regexes
  * that silently miss patterns outside what we've happened to observe across
- * AppCast + ClearCompany (both Angular).
+ * the Angular-based ATS sites.
  *
  * Why a separate primitive instead of inlining into each call site:
  *  - Single chokepoint for telemetry, error classification, and latency

package/dist/lib/llm/judge.js

@@ -4,7 +4,7 @@
  * routes through this — submit-verification, invalid-field detection, modal-
  * priority ranking, error-message extraction. Replaces deterministic regexes
  * that silently miss patterns outside what we've happened to observe across
- * AppCast + ClearCompany (both Angular).
+ * the Angular-based ATS sites.
  *
  * Why a separate primitive instead of inlining into each call site:
  *  - Single chokepoint for telemetry, error classification, and latency

package/dist/recon/capture-filters.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared predicates for deciding which captured requests are the site's real
+ * flow versus incidental browser noise (analytics beacons, ad-tech, a page's own
+ * error-reporting sink, static assets).
+ *
+ * Lives outside `src/scripts/` so both the emitter (`recon-generate.ts`, which
+ * must not emit noise into a generated plugin) and the HTTP probe
+ * (`recon-http.ts`, which must not burn hours replaying third-party hosts) apply
+ * ONE definition of "noise." Previously only the emitter filtered; the probe
+ * replayed and rate-limited everything, including `clicktale`/`adsrvr`/`tiktok`.
+ */
+/**
+ * Path/URL substrings we always treat as analytics or logging noise. Site-specific
+ * trackers belong in the `RECON_TELEMETRY_URL_PATTERNS` env var (comma-separated),
+ * not here — the engine must not carry any one site's ad-tech domains.
+ *
+ * Read at call time, not frozen at import: a module-level const would ignore an
+ * env var set after load, the exact foot-gun `RECON_QUESTION_KEYWORDS` documents.
+ */
+export declare function telemetryUrlPatterns(): string[];
+/**
+ * A path whose own segment is `error`/`errors` is a client-side reporting sink,
+ * never a call a caller wants replayed or emitted.
+ *
+ * Matched on a whole path segment rather than by substring so `/error-codes` and
+ * `/terrorism-screening` stay data endpoints, and kept out of the telemetry list
+ * because that list is literal substrings — a site's own sink is structural, not
+ * an ad-tech domain the operator must enumerate.
+ */
+export declare const ERROR_SINK_PATH_SEGMENT: RegExp;
+/**
+ * True when a captured URL is noise the recon pipeline should skip: a telemetry
+ * pattern (including any `RECON_TELEMETRY_URL_PATTERNS` addition), a third-party
+ * asset/tracking host, a same-host error-reporting sink, or a static asset.
+ *
+ * The one gate both the emitter and the probe consult so "what counts as the
+ * site's real flow" cannot drift between them.
+ */
+export declare function isNoiseUrl(url: string): boolean;
+//# sourceMappingURL=capture-filters.d.ts.map

package/dist/recon/capture-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-filters.d.ts","sourceRoot":"","sources":["../../src/recon/capture-filters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAW/C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,QAAyB,CAAC;AAmC9D;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAc/C"}

package/dist/recon/capture-filters.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Shared predicates for deciding which captured requests are the site's real
+ * flow versus incidental browser noise (analytics beacons, ad-tech, a page's own
+ * error-reporting sink, static assets).
+ *
+ * Lives outside `src/scripts/` so both the emitter (`recon-generate.ts`, which
+ * must not emit noise into a generated plugin) and the HTTP probe
+ * (`recon-http.ts`, which must not burn hours replaying third-party hosts) apply
+ * ONE definition of "noise." Previously only the emitter filtered; the probe
+ * replayed and rate-limited everything, including `clicktale`/`adsrvr`/`tiktok`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_SINK_PATH_SEGMENT = void 0;
+exports.telemetryUrlPatterns = telemetryUrlPatterns;
+exports.isNoiseUrl = isNoiseUrl;
+/**
+ * Path/URL substrings we always treat as analytics or logging noise. Site-specific
+ * trackers belong in the `RECON_TELEMETRY_URL_PATTERNS` env var (comma-separated),
+ * not here — the engine must not carry any one site's ad-tech domains.
+ *
+ * Read at call time, not frozen at import: a module-level const would ignore an
+ * env var set after load, the exact foot-gun `RECON_QUESTION_KEYWORDS` documents.
+ */
+function telemetryUrlPatterns() {
+    return [
+        "/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 path whose own segment is `error`/`errors` is a client-side reporting sink,
+ * never a call a caller wants replayed or emitted.
+ *
+ * Matched on a whole path segment rather than by substring so `/error-codes` and
+ * `/terrorism-screening` stay data endpoints, and kept out of the telemetry list
+ * because that list is literal substrings — a site's own sink is structural, not
+ * an ad-tech domain the operator must enumerate.
+ */
+exports.ERROR_SINK_PATH_SEGMENT = /(^|\/)errors?(\/|$)/i;
+/**
+ * Third-party hosts recon repeatedly wastes time on: ad-tech, session replay,
+ * social pixels, tag managers. A capture whose host matches is not the site's
+ * own endpoint and never worth replaying or rate-limiting.
+ *
+ * A suffix match on the registrable-ish host substring, so `x.clicktale.net`
+ * and `sync.adsrvr.org` both match. Extendable per-site via
+ * `RECON_TELEMETRY_URL_PATTERNS`, which {@link isNoiseUrl} also honors.
+ */
+const THIRD_PARTY_ASSET_HOSTS = [
+    "clicktale.net",
+    "adsrvr.org",
+    "tiktok.com",
+    "doubleclick.net",
+    "google-analytics.com",
+    "googletagmanager.com",
+    "facebook.net",
+    "facebook.com",
+    "hotjar.com",
+    "segment.io",
+    "segment.com",
+    "fullstory.com",
+    "cdn.cookielaw.org",
+    "onetrust.com",
+    "demdex.net",
+    "omtrdc.net",
+    "quantserve.com",
+    "scorecardresearch.com",
+];
+/** Static-asset extensions a probe should never replay as an API endpoint. */
+const ASSET_EXTENSION = /\.(js|mjs|css|png|jpe?g|gif|svg|webp|ico|woff2?|ttf|eot|map)$/i;
+/**
+ * True when a captured URL is noise the recon pipeline should skip: a telemetry
+ * pattern (including any `RECON_TELEMETRY_URL_PATTERNS` addition), a third-party
+ * asset/tracking host, a same-host error-reporting sink, or a static asset.
+ *
+ * The one gate both the emitter and the probe consult so "what counts as the
+ * site's real flow" cannot drift between them.
+ */
+function isNoiseUrl(url) {
+    const patterns = telemetryUrlPatterns();
+    if (patterns.some((p) => url.includes(p)))
+        return true;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    const host = parsed.host.toLowerCase();
+    if (THIRD_PARTY_ASSET_HOSTS.some((h) => host === h || host.endsWith(`.${h}`)))
+        return true;
+    if (exports.ERROR_SINK_PATH_SEGMENT.test(parsed.pathname))
+        return true;
+    if (ASSET_EXTENSION.test(parsed.pathname))
+        return true;
+    return false;
+}
+//# sourceMappingURL=capture-filters.js.map

package/dist/recon/capture-filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-filters.js","sourceRoot":"","sources":["../../src/recon/capture-filters.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;;;AAEH;;;;;;;GAOG;AACH;IACE,OAAO;QACL,4BAA4B;QAC5B,aAAa;QACb,yBAAyB;QACzB,sBAAsB;QACtB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,EAAE,CAAC;aAChD,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC;KACnB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACU,QAAA,uBAAuB,GAAG,sBAAsB,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,uBAAuB,GAAG;IAC9B,eAAe;IACf,YAAY;IACZ,YAAY;IACZ,iBAAiB;IACjB,sBAAsB;IACtB,sBAAsB;IACtB,cAAc;IACd,cAAc;IACd,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,eAAe;IACf,mBAAmB;IACnB,cAAc;IACd,YAAY;IACZ,YAAY;IACZ,gBAAgB;IAChB,uBAAuB;CACxB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,eAAe,GAAG,gEAAgE,CAAC;AAEzF;;;;;;;GAOG;AACH,oBAA2B,GAAW;IACpC,MAAM,QAAQ,GAAG,oBAAoB,EAAE,CAAC;IACxC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3F,IAAI,QAAA,uBAAuB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/D,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/recon/form-schema.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Consumer-supplied form-schema that names the wire keys the generator reads out
+ * of an ATS's form-definition responses (field ids, option ids, submitted values).
+ *
+ * A sibling to {@link @/recon/vocabulary}, not a field on it: a vocabulary matches
+ * English instruction prose, this matches JSON response keys. Different inputs,
+ * different validation, independent applicability — a cruise site needs a
+ * vocabulary and no form-schema. Published at `@enricai/barnacle/recon/form-schema`;
+ * all imports are type-only so there are zero runtime side effects.
+ *
+ * Why this exists (issue #57): the generator hardcoded one ATS vendor's wire
+ * format in ~8 private functions. That is a claim about a *vendor's schema*, not
+ * about HTTP — so the engine no longer carries any vendor's keys. A consumer
+ * whose ATS exposes a form definition declares its keys with `--form-schema`;
+ * absent one, form-key recovery does not run. This is the same inversion
+ * `--vocabulary` already made for instruction prose.
+ */
+/**
+ * The response-key names the generator threads into raw-body string anchors when
+ * recovering an ATS form definition.
+ *
+ * These are *key names, not values*: each is interpolated into a
+ * `"${key}":"${uuid}"` marker used to locate and substitute UUIDs in a captured
+ * request body. A legal wire key like `field-id` is therefore fine — the loader
+ * rejects only quotes and backslashes, which would break the marker, NOT the
+ * JS-identifier rule the vocabulary uses (those keys splice into `payload.<name>`
+ * code; these do not).
+ */
+export interface ReconFormSchema {
+    /** The UUID-valued field-identity key. Anchors the substitution passes. */
+    fieldIdKey: string;
+    /**
+     * The name key(s), by role: the first is a machine code (PascalCased
+     * directly), the second is a human label (run through the section-heading
+     * heuristic). Supply one key for a label-only ATS, two for one exposing both
+     * (the code is preferred when present). Must be non-empty; a third+ key is
+     * unused — the model has exactly the two roles.
+     */
+    fieldNameKeys: string[];
+    /** The options-array key on a field. */
+    fieldOptionsKey: string;
+    /** The option-id key, INSIDE a `fieldOptionsKey` entry. */
+    optionIdKey: string;
+    /** The option-label key, inside a `fieldOptionsKey` entry. */
+    optionValueKey: string;
+    /** The submitted free-value key (a distinct role from {@link optionValueKey}). */
+    responseValueKey: string;
+    /** The submitted option-reference key (distinct from the schema-side {@link optionIdKey}). */
+    responseOptionIdKey: string;
+}
+//# sourceMappingURL=form-schema.d.ts.map

package/dist/recon/form-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-schema.d.ts","sourceRoot":"","sources":["../../src/recon/form-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,cAAc,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,gBAAgB,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,mBAAmB,EAAE,MAAM,CAAC;CAC7B"}

package/dist/recon/form-schema.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Consumer-supplied form-schema that names the wire keys the generator reads out
+ * of an ATS's form-definition responses (field ids, option ids, submitted values).
+ *
+ * A sibling to {@link @/recon/vocabulary}, not a field on it: a vocabulary matches
+ * English instruction prose, this matches JSON response keys. Different inputs,
+ * different validation, independent applicability — a cruise site needs a
+ * vocabulary and no form-schema. Published at `@enricai/barnacle/recon/form-schema`;
+ * all imports are type-only so there are zero runtime side effects.
+ *
+ * Why this exists (issue #57): the generator hardcoded one ATS vendor's wire
+ * format in ~8 private functions. That is a claim about a *vendor's schema*, not
+ * about HTTP — so the engine no longer carries any vendor's keys. A consumer
+ * whose ATS exposes a form definition declares its keys with `--form-schema`;
+ * absent one, form-key recovery does not run. This is the same inversion
+ * `--vocabulary` already made for instruction prose.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=form-schema.js.map

package/dist/recon/form-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-schema.js","sourceRoot":"","sources":["../../src/recon/form-schema.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/recon/load-form-schema.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Engine-internal loader for `--form-schema`. Like {@link @/recon/load-vocabulary},
+ * deliberately NOT in the package's `exports` map: consumers author a form-schema
+ * against the `./recon/form-schema` type contract, and only `recon-generate` ever
+ * loads one. Exporting this would publish an import-time side effect (dynamic
+ * `import()` of arbitrary consumer code) as public API for no caller.
+ */
+import type { ReconFormSchema } from "../recon/form-schema";
+/** The `--form-schema` value that opts a site out of form-key recovery entirely. */
+export declare const FORM_SCHEMA_NONE = "none";
+/**
+ * Loads a consumer's form-schema module.
+ *
+ * Resolution reuses {@link resolvePluginSpecifier}, so `--form-schema` accepts the
+ * same specifier forms as `BARNACLE_PLUGINS` and `--vocabulary`. Export resolution
+ * mirrors the plugin loader's `m.formSchema ?? m.default ?? m`. The
+ * {@link FORM_SCHEMA_NONE} sentinel returns `null` (not an empty struct — see the
+ * form-schema module for why), the shape for "this site has no ATS form data."
+ *
+ * Throws rather than falling back: a form-schema that was asked for and is broken
+ * is an error, while asking for nothing is the caller's explicit `none`.
+ */
+export declare function loadReconFormSchema(specifier: string, baseDir: string): Promise<ReconFormSchema | null>;
+//# sourceMappingURL=load-form-schema.d.ts.map

package/dist/recon/load-form-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-form-schema.d.ts","sourceRoot":"","sources":["../../src/recon/load-form-schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AA4BvC;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAejC"}

package/dist/recon/load-form-schema.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Engine-internal loader for `--form-schema`. Like {@link @/recon/load-vocabulary},
+ * deliberately NOT in the package's `exports` map: consumers author a form-schema
+ * against the `./recon/form-schema` type contract, and only `recon-generate` ever
+ * loads one. Exporting this would publish an import-time side effect (dynamic
+ * `import()` of arbitrary consumer code) as public API for no caller.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORM_SCHEMA_NONE = void 0;
+exports.loadReconFormSchema = loadReconFormSchema;
+const v4_1 = require("zod/v4");
+const errors_1 = require("../lib/errors");
+const discover_1 = require("../plugins/discover");
+/** The `--form-schema` value that opts a site out of form-key recovery entirely. */
+exports.FORM_SCHEMA_NONE = "none";
+/**
+ * Wire keys interpolate into `"${key}":"${uuid}"` markers, not into code, so the
+ * rule is NOT the vocabulary's JS-identifier rule: a legal response key like
+ * `field-id` must be accepted. Reject only what would break the marker — an empty
+ * key (matches every field), or a quote/backslash (escapes the JSON string anchor).
+ */
+const wireKeySchema = v4_1.z
+    .string()
+    .min(1, "wire key must be non-empty")
+    .regex(/^[^"\\]+$/, "wire key must not contain a quote or backslash (it anchors a JSON string)");
+/**
+ * Validates the shape at the boundary so a malformed preset fails at generate
+ * time with a field path, rather than silently recovering no form fields and
+ * emitting a plugin that ignores the site's option data.
+ */
+const formSchemaSchema = v4_1.z.object({
+    fieldIdKey: wireKeySchema,
+    fieldNameKeys: v4_1.z.array(wireKeySchema).min(1, "fieldNameKeys must list at least one key"),
+    fieldOptionsKey: wireKeySchema,
+    optionIdKey: wireKeySchema,
+    optionValueKey: wireKeySchema,
+    responseValueKey: wireKeySchema,
+    responseOptionIdKey: wireKeySchema,
+});
+/**
+ * Loads a consumer's form-schema module.
+ *
+ * Resolution reuses {@link resolvePluginSpecifier}, so `--form-schema` accepts the
+ * same specifier forms as `BARNACLE_PLUGINS` and `--vocabulary`. Export resolution
+ * mirrors the plugin loader's `m.formSchema ?? m.default ?? m`. The
+ * {@link FORM_SCHEMA_NONE} sentinel returns `null` (not an empty struct — see the
+ * form-schema module for why), the shape for "this site has no ATS form data."
+ *
+ * Throws rather than falling back: a form-schema that was asked for and is broken
+ * is an error, while asking for nothing is the caller's explicit `none`.
+ */
+async function loadReconFormSchema(specifier, baseDir) {
+    if (specifier === exports.FORM_SCHEMA_NONE)
+        return null;
+    const href = (0, discover_1.resolvePluginSpecifier)(specifier, baseDir);
+    const mod = await import(href);
+    const record = mod;
+    const raw = record.formSchema ?? record.default ?? mod;
+    const parsed = formSchemaSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`form-schema module ${JSON.stringify(specifier)} does not export a valid ReconFormSchema: ${(0, errors_1.toErrorMessage)(parsed.error)}`);
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=load-form-schema.js.map

package/dist/recon/load-form-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-form-schema.js","sourceRoot":"","sources":["../../src/recon/load-form-schema.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;AAEH,+BAA2B;AAE3B,yCAA8C;AAC9C,iDAA4D;AAG5D,oFAAoF;AACvE,QAAA,gBAAgB,GAAG,MAAM,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,aAAa,GAAG,MAAC;KACpB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,EAAE,4BAA4B,CAAC;KACpC,KAAK,CAAC,WAAW,EAAE,2EAA2E,CAAC,CAAC;AAEnG;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,MAAC,CAAC,MAAM,CAAC;IAChC,UAAU,EAAE,aAAa;IACzB,aAAa,EAAE,MAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,0CAA0C,CAAC;IACxF,eAAe,EAAE,aAAa;IAC9B,WAAW,EAAE,aAAa;IAC1B,cAAc,EAAE,aAAa;IAC7B,gBAAgB,EAAE,aAAa;IAC/B,mBAAmB,EAAE,aAAa;CACnC,CAAC,CAAC;AAEH;;;;;;;;;;;GAWG;AACI,KAAK,8BACV,SAAiB,EACjB,OAAe;IAEf,IAAI,SAAS,KAAK,QAAA,gBAAgB;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,IAAI,GAAG,IAAA,iCAAsB,EAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,GAAG,GAAY,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,GAA8B,CAAC;IAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,OAAO,IAAI,GAAG,CAAC;IAEvD,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,6CAA6C,IAAA,uBAAc,EAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC3H,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/scraper/cookie-jar.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cookie-jar snapshot capture via CDP `Network.getAllCookies`. `document.cookie`
+ * and Stagehand's own cookie helpers can't see HttpOnly cookies, and
+ * `Page.getCookies`/`Network.getCookies` only return cookies scoped to the
+ * current frame's URLs — a journey that navigated click.appcast.io ->
+ * apply.appcast.io would miss the click-domain cookies once on the apply
+ * page. `Network.getAllCookies` returns the whole-browser jar regardless of
+ * the page's current URL, which is what attribution analysis needs.
+ */
+import type { Page } from "@browserbasehq/stagehand";
+import type { CookieJarSnapshot } from "../scripts/recon-shared";
+/**
+ * Reads the browser's complete cookie jar and returns it as a labeled
+ * snapshot. Never throws — telemetry capture is best-effort, so a failed CDP
+ * call yields a snapshot with an `error` field and an empty `cookies` array
+ * rather than aborting the recon run.
+ */
+export declare function captureCookieJarSnapshot(page: Page, label: string, phase: string, stepIndex: number): Promise<CookieJarSnapshot>;
+//# sourceMappingURL=cookie-jar.d.ts.map

package/dist/scraper/cookie-jar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-jar.d.ts","sourceRoot":"","sources":["../../src/scraper/cookie-jar.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAGrD,OAAO,KAAK,EAAE,iBAAiB,EAAgB,MAAM,wBAAwB,CAAC;AAI9E;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,CAAC,CAqB5B"}

package/dist/scraper/cookie-jar.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Cookie-jar snapshot capture via CDP `Network.getAllCookies`. `document.cookie`
+ * and Stagehand's own cookie helpers can't see HttpOnly cookies, and
+ * `Page.getCookies`/`Network.getCookies` only return cookies scoped to the
+ * current frame's URLs — a journey that navigated click.appcast.io ->
+ * apply.appcast.io would miss the click-domain cookies once on the apply
+ * page. `Network.getAllCookies` returns the whole-browser jar regardless of
+ * the page's current URL, which is what attribution analysis needs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureCookieJarSnapshot = captureCookieJarSnapshot;
+const errors_1 = require("../lib/errors");
+/**
+ * Reads the browser's complete cookie jar and returns it as a labeled
+ * snapshot. Never throws — telemetry capture is best-effort, so a failed CDP
+ * call yields a snapshot with an `error` field and an empty `cookies` array
+ * rather than aborting the recon run.
+ */
+async function captureCookieJarSnapshot(page, label, phase, stepIndex) {
+    const timestamp = new Date().toISOString();
+    try {
+        const result = await page.sendCDP("Network.getAllCookies");
+        return {
+            label,
+            phase,
+            stepIndex,
+            timestamp,
+            cookies: result.cookies,
+        };
+    }
+    catch (err) {
+        return {
+            label,
+            phase,
+            stepIndex,
+            timestamp,
+            cookies: [],
+            error: (0, errors_1.toErrorMessage)(err),
+        };
+    }
+}
+//# sourceMappingURL=cookie-jar.js.map

package/dist/scraper/cookie-jar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-jar.js","sourceRoot":"","sources":["../../src/scraper/cookie-jar.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAIH,yCAA8C;AAK9C;;;;;GAKG;AACI,KAAK,mCACV,IAAU,EACV,KAAa,EACb,KAAa,EACb,SAAiB;IAEjB,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAwB,uBAAuB,CAAC,CAAC;QAClF,OAAO;YACL,KAAK;YACL,KAAK;YACL,SAAS;YACT,SAAS;YACT,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,KAAK;YACL,KAAK;YACL,SAAS;YACT,SAAS;YACT,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,IAAA,uBAAc,EAAC,GAAG,CAAC;SAC3B,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/scraper/errors.d.ts

@@ -133,25 +133,25 @@ export declare class HttpRateLimitError extends ScraperError {
     constructor(message?: string);
 }
 /**
- * Oracle HCM returned a plain-text `ORA_URL_LOCKED` sentinel body, meaning the
- * requisition URL has been locked by Oracle after repeated requests. Non-retryable
- * and NOT a browser-fallback trigger — the URL is locked at Oracle's end, so
- * neither a retry of the identical HTTP request nor a fresh Stagehand browser
- * session can succeed. The caller must back off and surface a "retry later"
- * state rather than burning a Steel session. Kept distinct from HttpRateLimitError
- * so metrics/logs (classifyDispatchError) can tell an Oracle requisition lock
- * apart from a self-inflicted 429 rate limit.
+ * A backend has locked the requested URL — a terminal "come back later" signal a
+ * plugin raises (e.g. via `classifyResponseBody`) when the target refuses the
+ * resource after repeated requests. Non-retryable and NOT a browser-fallback
+ * trigger — the lock is at the target's end, so neither a retry of the identical
+ * HTTP request nor a fresh Stagehand browser session can succeed. The caller must
+ * back off and surface a "retry later" state rather than burning a Steel session.
+ * Kept distinct from HttpRateLimitError so metrics/logs (classifyDispatchError)
+ * can tell a requisition lock apart from a self-inflicted 429 rate limit.
  */
 export declare class HttpUrlLockedError extends ScraperError {
     constructor(message?: string);
 }
 /**
- * Oracle HCM returned a plain-text `ORA_IRC_TOKEN_EXPIRED` sentinel body during
- * a burst / rate-limit / token-expiry window. Retryable so pRetry keeps retrying,
- * but kept distinct from the generic {@link UnknownScraperError} so the encompass
- * http-flow can catch exactly this class and re-mint the AccessCode before
- * retrying — replaying the same stale token would produce the same sentinel
- * indefinitely. Distinct from {@link HttpUrlLockedError} which is terminal.
+ * @deprecated Removed in 2.0.0. Oracle-specific and no longer thrown by the
+ * engine — response-body sentinel detection now lives in the plugin via
+ * `HttpClientOptions.classifyResponseBody`. A plugin that needs a retryable
+ * token-expiry signal should define its own `ScraperError` subclass (see the
+ * encompasshealth plugin). Retained only so existing importers of
+ * `@enricai/barnacle/scraper/errors` keep resolving under a minor release.
  */
 export declare class OracleTokenExpiredError extends ScraperError {
     constructor(message?: string);