@enricai/barnacle 1.0.0

package/dist/api/schemas/telemetry.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.judgeVerdictSchema = exports.llmCallSampleSchema = exports.llmCallFailureKindSchema = void 0;
+const v4_1 = require("zod/v4");
+/**
+ * Re-exports of the call-capture telemetry types so the schema stays the
+ * single source of truth. The lib/telemetry/call-capture module is the
+ * canonical writer (it owns the schema + classifier helper); this barrel
+ * makes the same types available to the judge / self-heal reader paths
+ * without a redundant definition that could silently diverge.
+ */
+var call_capture_1 = require("../../lib/telemetry/call-capture");
+Object.defineProperty(exports, "llmCallFailureKindSchema", { enumerable: true, get: function () { return call_capture_1.llmCallFailureKindSchema; } });
+Object.defineProperty(exports, "llmCallSampleSchema", { enumerable: true, get: function () { return call_capture_1.llmCallSampleSchema; } });
+/**
+ * Per-sample verdict produced by the judge skill. Three boolean dimensions
+ * plus an aggregate `pass` (all three must be true).
+ */
+const judgeVerdictEntrySchema = v4_1.z.object({
+    callId: v4_1.z.string(),
+    schemaOk: v4_1.z.boolean(),
+    schemaRationale: v4_1.z.string(),
+    factuallyGrounded: v4_1.z.boolean(),
+    factualRationale: v4_1.z.string(),
+    hallucinationFree: v4_1.z.boolean(),
+    hallucinationRationale: v4_1.z.string(),
+    worstOffender: v4_1.z.string().optional(),
+    pass: v4_1.z.boolean(),
+});
+/**
+ * Aggregate counts across all judged samples in a verdict file.
+ */
+const judgeAggregateSchema = v4_1.z.object({
+    n: v4_1.z.number().int(),
+    schemaPass: v4_1.z.number().int(),
+    factualPass: v4_1.z.number().int(),
+    hallucinationFreePass: v4_1.z.number().int(),
+    overallPass: v4_1.z.number().int(),
+});
+/**
+ * Top-level verdict file produced by the judge skill for one batch. Mirrors
+ * beacon/pila's verdict-JSON shape but in Barnacle's camelCase convention.
+ */
+exports.judgeVerdictSchema = v4_1.z.object({
+    callType: v4_1.z.string(),
+    batchIndex: v4_1.z.number().int(),
+    judgedAt: v4_1.z.string(),
+    judgeModel: v4_1.z.string(),
+    verdicts: v4_1.z.array(judgeVerdictEntrySchema),
+    aggregate: judgeAggregateSchema,
+});
+//# sourceMappingURL=telemetry.js.map

package/dist/api/schemas/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../../src/api/schemas/telemetry.ts"],"names":[],"mappings":";;;AAAA,+BAA2B;AAE3B;;;;;;GAMG;AACH,6DAKsC;AAFpC,wHAAA,wBAAwB,OAAA;AACxB,mHAAA,mBAAmB,OAAA;AAGrB;;;GAGG;AACH,MAAM,uBAAuB,GAAG,MAAC,CAAC,MAAM,CAAC;IACvC,MAAM,EAAE,MAAC,CAAC,MAAM,EAAE;IAClB,QAAQ,EAAE,MAAC,CAAC,OAAO,EAAE;IACrB,eAAe,EAAE,MAAC,CAAC,MAAM,EAAE;IAC3B,iBAAiB,EAAE,MAAC,CAAC,OAAO,EAAE;IAC9B,gBAAgB,EAAE,MAAC,CAAC,MAAM,EAAE;IAC5B,iBAAiB,EAAE,MAAC,CAAC,OAAO,EAAE;IAC9B,sBAAsB,EAAE,MAAC,CAAC,MAAM,EAAE;IAClC,aAAa,EAAE,MAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,IAAI,EAAE,MAAC,CAAC,OAAO,EAAE;CAClB,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,oBAAoB,GAAG,MAAC,CAAC,MAAM,CAAC;IACpC,CAAC,EAAE,MAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACnB,UAAU,EAAE,MAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC5B,WAAW,EAAE,MAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC7B,qBAAqB,EAAE,MAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACvC,WAAW,EAAE,MAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CAC9B,CAAC,CAAC;AAIH;;;GAGG;AACU,QAAA,kBAAkB,GAAG,MAAC,CAAC,MAAM,CAAC;IACzC,QAAQ,EAAE,MAAC,CAAC,MAAM,EAAE;IACpB,UAAU,EAAE,MAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC5B,QAAQ,EAAE,MAAC,CAAC,MAAM,EAAE;IACpB,UAAU,EAAE,MAAC,CAAC,MAAM,EAAE;IACtB,QAAQ,EAAE,MAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;IAC1C,SAAS,EAAE,oBAAoB;CAChC,CAAC,CAAC"}

package/dist/cache/keyed-ttl-cache.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Generic per-key TTL cache factory with single-flight warmup coalescing.
+ *
+ * Why this exists: both `src/cache/response-cache.ts` and
+ * `src/sites/appcast/tokens/cache.ts` independently hand-roll the same
+ * inFlight Map + LRUCache wiring. Any future site needing a per-key token
+ * or session cache would copy it a third time. This factory captures the
+ * shared invariant — promise registered synchronously before any yield so
+ * concurrent callers coalesce onto one warmup — and adds the shallow-copy-
+ * on-read behaviour the token cache needs (returned snapshot is isolated
+ * from subsequent in-place mutations of the master entry).
+ */
+export interface KeyedTtlCacheOptions {
+    max: number;
+    ttlMs: number;
+    keyPrefix?: string;
+}
+export interface KeyedTtlCache<T extends object> {
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    invalidate(key: string): void;
+    getOrWarm(key: string, warmer: () => Promise<T>): Promise<T>;
+    reset(): void;
+}
+/**
+ * Builds a keyed TTL cache with single-flight coalescing and copy-on-read.
+ *
+ * Pass `{ max, ttlMs }` to control capacity and expiry. An optional
+ * `keyPrefix` namespaces the underlying LRU keys so multiple caches in the
+ * same process can share a debug view without colliding.
+ *
+ * The returned `getOrWarm` uses `.then/.finally` (not `await`) so the
+ * in-flight promise is written to the map *synchronously* — before any
+ * microtask yield — guaranteeing that every concurrent caller for the same
+ * key awaits the same promise instead of kicking off a duplicate warmup.
+ * See the same pattern at `response-cache.ts:108-111` and
+ * `appcast/tokens/cache.ts:124-125`.
+ *
+ * `getOrWarm` returns `{ ...value }` (a shallow copy) to each caller so
+ * that an in-place mutation of the master cache entry (e.g. rotating a
+ * header field) does not bleed into a snapshot already in the hands of
+ * another caller.
+ */
+export declare function createKeyedTtlCache<T extends object>(options: KeyedTtlCacheOptions): KeyedTtlCache<T>;
+//# sourceMappingURL=keyed-ttl-cache.d.ts.map

package/dist/cache/keyed-ttl-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-ttl-cache.d.ts","sourceRoot":"","sources":["../../src/cache/keyed-ttl-cache.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM;IAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7D,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAAC,CAAC,CAAC,CAoDlB"}

package/dist/cache/keyed-ttl-cache.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKeyedTtlCache = createKeyedTtlCache;
+const lru_cache_1 = require("lru-cache");
+/**
+ * Builds a keyed TTL cache with single-flight coalescing and copy-on-read.
+ *
+ * Pass `{ max, ttlMs }` to control capacity and expiry. An optional
+ * `keyPrefix` namespaces the underlying LRU keys so multiple caches in the
+ * same process can share a debug view without colliding.
+ *
+ * The returned `getOrWarm` uses `.then/.finally` (not `await`) so the
+ * in-flight promise is written to the map *synchronously* — before any
+ * microtask yield — guaranteeing that every concurrent caller for the same
+ * key awaits the same promise instead of kicking off a duplicate warmup.
+ * See the same pattern at `response-cache.ts:108-111` and
+ * `appcast/tokens/cache.ts:124-125`.
+ *
+ * `getOrWarm` returns `{ ...value }` (a shallow copy) to each caller so
+ * that an in-place mutation of the master cache entry (e.g. rotating a
+ * header field) does not bleed into a snapshot already in the hands of
+ * another caller.
+ */
+function createKeyedTtlCache(options) {
+    const { max, ttlMs, keyPrefix = "" } = options;
+    const lru = new lru_cache_1.LRUCache({ max, ttl: ttlMs });
+    const inFlight = new Map();
+    function prefixed(key) {
+        return keyPrefix ? `${keyPrefix}:${key}` : key;
+    }
+    function get(key) {
+        return lru.get(prefixed(key));
+    }
+    function set(key, value) {
+        lru.set(prefixed(key), value);
+    }
+    function invalidate(key) {
+        lru.delete(prefixed(key));
+    }
+    function getOrWarm(key, warmer) {
+        const cached = get(key);
+        if (cached)
+            return Promise.resolve({ ...cached });
+        const pk = prefixed(key);
+        const existing = inFlight.get(pk);
+        if (existing)
+            return existing.then((v) => ({ ...v }));
+        // Deliberately .then/.finally rather than await: we must register the
+        // promise in `inFlight` synchronously so concurrent callers that race
+        // into this function hit the existing entry. An `await` here would
+        // yield before the `inFlight.set` below, defeating coalescing.
+        const promise = warmer()
+            .then((value) => {
+            lru.set(pk, value);
+            return value;
+        })
+            .finally(() => {
+            inFlight.delete(pk);
+        });
+        inFlight.set(pk, promise);
+        return promise.then((v) => ({ ...v }));
+    }
+    function reset() {
+        lru.clear();
+        inFlight.clear();
+    }
+    return { get, set, invalidate, getOrWarm, reset };
+}
+//# sourceMappingURL=keyed-ttl-cache.js.map

package/dist/cache/keyed-ttl-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed-ttl-cache.js","sourceRoot":"","sources":["../../src/cache/keyed-ttl-cache.ts"],"names":[],"mappings":";;AAgDA,kDAsDC;AAtGD,yCAAqC;AA6BrC;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,mBAAmB,CACjC,OAA6B;IAE7B,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAE/C,MAAM,GAAG,GAAG,IAAI,oBAAQ,CAAY,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE/C,SAAS,QAAQ,CAAC,GAAW;QAC3B,OAAO,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACjD,CAAC;IAED,SAAS,GAAG,CAAC,GAAW;QACtB,OAAO,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,SAAS,GAAG,CAAC,GAAW,EAAE,KAAQ;QAChC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,SAAS,UAAU,CAAC,GAAW;QAC7B,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,SAAS,SAAS,CAAC,GAAW,EAAE,MAAwB;QACtD,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,MAAM;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,MAAM,EAAO,CAAC,CAAC;QAEvD,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAM,CAAC,CAAC;QAE3D,sEAAsE;QACtE,sEAAsE;QACtE,mEAAmE;QACnE,+DAA+D;QAC/D,MAAM,OAAO,GAAG,MAAM,EAAE;aACrB,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YACd,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YACnB,OAAO,KAAK,CAAC;QACf,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;QACL,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC1B,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAM,CAAC,CAAC;IAC9C,CAAC;IAED,SAAS,KAAK;QACZ,GAAG,CAAC,KAAK,EAAE,CAAC;QACZ,QAAQ,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACpD,CAAC"}

package/dist/cache/response-cache.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Looks up a cached response by `endpoint` + `payload` (the normalized
+ * request body). Returns the cache key so callers can write the value
+ * back via `getOrCreateInFlight` without re-hashing.
+ */
+export declare function getCachedResponse<T>(endpoint: string, payload: unknown): {
+    value: T | undefined;
+    key: string;
+};
+/**
+ * Clears the entire cache. Used by tests and by the daily refresh
+ * worker after a full rebuild.
+ */
+export declare function clearResponseCache(): void;
+/**
+ * Returns a snapshot of cache internals for the `/readyz` observability
+ * endpoint. Exposed so the health route can surface cache pressure without
+ * importing the LRU cache instance directly.
+ */
+export declare function cacheStats(): {
+    size: number;
+    max: number;
+    inFlight: number;
+};
+/**
+ * Runs `producer` once per key even when multiple callers race on a
+ * cache miss. The first caller kicks off the upstream call and all
+ * concurrent callers await the same promise. On resolve, the value is
+ * written to the LRU cache so subsequent (non-racing) reads hit
+ * normally.
+ *
+ * Callers still do the `getCachedResponse` check first — this helper
+ * is only invoked on a miss. Rejection propagates to every awaiter so
+ * one caller's failure doesn't look like success to the rest.
+ */
+export declare function getOrCreateInFlight<T extends object>(key: string, producer: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=response-cache.d.ts.map

package/dist/cache/response-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-cache.d.ts","sourceRoot":"","sources":["../../src/cache/response-cache.ts"],"names":[],"mappings":"AA2DA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,GACf;IAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAGvC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAE5E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EACxD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAiBZ"}

package/dist/cache/response-cache.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCachedResponse = getCachedResponse;
+exports.clearResponseCache = clearResponseCache;
+exports.cacheStats = cacheStats;
+exports.getOrCreateInFlight = getOrCreateInFlight;
+const node_crypto_1 = require("node:crypto");
+const lru_cache_1 = require("lru-cache");
+const config_1 = require("../config");
+/**
+ * Shared in-process response cache keyed by (endpoint, normalized body).
+ * Scrape runs are expensive; a 15-minute TTL on identical requests
+ * collapses duplicate traffic without staling data for typical integration
+ * use cases.
+ *
+ * Why lru-cache: zero-dep, maintained, O(1) operations, battle-tested.
+ * We set `ttl` at construction and rely on lazy expiry on get().
+ */
+const cache = new lru_cache_1.LRUCache({
+    max: config_1.config.cache.maxEntries,
+    ttl: config_1.config.cache.ttlMs,
+});
+/**
+ * Tracks upstream calls that are currently resolving for a given key so
+ * concurrent cache misses don't all fan out to the scraper. First miss
+ * kicks off the work; subsequent misses await the same promise. Each
+ * entry is removed after the promise settles (resolve or reject).
+ */
+const inFlight = new Map();
+/**
+ * Deterministically hashes a JSON-serializable payload for cache keys.
+ * Sorts keys so object-key ordering never causes misses.
+ */
+function hashKey(endpoint, payload) {
+    const canonical = JSON.stringify(payload, canonicalReplacer);
+    return `${endpoint}:${(0, node_crypto_1.createHash)("sha256").update(canonical).digest("hex").slice(0, 32)}`;
+}
+function canonicalReplacer(_key, value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const obj = value;
+        const sorted = {};
+        for (const key of Object.keys(obj).sort()) {
+            sorted[key] = obj[key];
+        }
+        return sorted;
+    }
+    // Primitive-only arrays are set-semantic in request bodies where field
+    // order carries no meaning (e.g. a list of filter tags). Sorting them
+    // in the canonical form collapses ["a","b"] and ["b","a"] to the same
+    // cache entry without touching arrays of objects (where order may carry
+    // meaning).
+    if (Array.isArray(value) && value.every((v) => typeof v === "string" || typeof v === "number")) {
+        const copy = [...value];
+        copy.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        return copy;
+    }
+    return value;
+}
+/**
+ * Looks up a cached response by `endpoint` + `payload` (the normalized
+ * request body). Returns the cache key so callers can write the value
+ * back via `getOrCreateInFlight` without re-hashing.
+ */
+function getCachedResponse(endpoint, payload) {
+    const key = hashKey(endpoint, payload);
+    return { value: cache.get(key), key };
+}
+/**
+ * Clears the entire cache. Used by tests and by the daily refresh
+ * worker after a full rebuild.
+ */
+function clearResponseCache() {
+    cache.clear();
+    inFlight.clear();
+}
+/**
+ * Returns a snapshot of cache internals for the `/readyz` observability
+ * endpoint. Exposed so the health route can surface cache pressure without
+ * importing the LRU cache instance directly.
+ */
+function cacheStats() {
+    return { size: cache.size, max: cache.max, inFlight: inFlight.size };
+}
+/**
+ * Runs `producer` once per key even when multiple callers race on a
+ * cache miss. The first caller kicks off the upstream call and all
+ * concurrent callers await the same promise. On resolve, the value is
+ * written to the LRU cache so subsequent (non-racing) reads hit
+ * normally.
+ *
+ * Callers still do the `getCachedResponse` check first — this helper
+ * is only invoked on a miss. Rejection propagates to every awaiter so
+ * one caller's failure doesn't look like success to the rest.
+ */
+async function getOrCreateInFlight(key, producer) {
+    const existing = inFlight.get(key);
+    if (existing)
+        return existing;
+    // Deliberately .then/.finally rather than await: we must register the
+    // promise in `inFlight` synchronously so concurrent callers that race
+    // into this function hit the existing entry. An `await` here would
+    // yield before the `inFlight.set` below, defeating coalescing.
+    const promise = producer()
+        .then((value) => {
+        cache.set(key, value);
+        return value;
+    })
+        .finally(() => {
+        inFlight.delete(key);
+    });
+    inFlight.set(key, promise);
+    return promise;
+}
+//# sourceMappingURL=response-cache.js.map

package/dist/cache/response-cache.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Fully resolved, strongly typed application config derived from environment
+ * variables at process start. Consumers import the `config` singleton instead
+ * of reading `process.env` directly so that required vars are validated once.
+ */
+export interface AppConfig {
+    appName: string;
+    nodeEnv: "development" | "production" | "test";
+    host: string;
+    port: number;
+    logLevel: string;
+    auth: {
+        hashedKeys: readonly string[];
+        devBypass: boolean;
+    };
+    /**
+     * Whether Fastify trusts inbound `X-Forwarded-For` / `X-Forwarded-Proto`.
+     * True is correct when Barnacle runs behind a reverse proxy (ALB, nginx,
+     * Cloudflare). False is required when deployed directly to the internet
+     * — otherwise clients can spoof `X-Forwarded-For` to bypass rate
+     * limiting, since the rate-limit key falls back to `request.ip` for
+     * unauthenticated traffic.
+     */
+    trustProxy: boolean;
+    scraper: {
+        /**
+         * Default browser-session provider. Browserbase is the default because
+         * Stagehand v3's payload-injection upload path is gated on
+         * `env === "BROWSERBASE"` and several other code paths (CDP timeouts,
+         * session recovery, event-window timing) only activate in that mode.
+         * Steel remains a supported fallback via `SCRAPER_PROVIDER=steel` or the
+         * `--provider steel` CLI flag.
+         */
+        provider: "browserbase" | "steel";
+        browserbaseApiKey: string | undefined;
+        browserbaseProjectId: string | undefined;
+        steelApiKey: string | undefined;
+        anthropicApiKey: string | undefined;
+        model: string;
+        proxyType: string;
+        solveCaptcha: boolean;
+        poolSize: number;
+        minActionDelayMs: number;
+        maxActionDelayMs: number;
+        readinessQueueThreshold: number;
+        /**
+         * Per-site base URL overrides keyed by `meta.siteId`. Populated at startup
+         * from `BARNACLE_SITE_<UPPERCASE_SITE_ID>_BASE_URL` env vars — underscores
+         * in the env key map to hyphens in the siteId. Example:
+         * `BARNACLE_SITE_MY_SHOP_BASE_URL=https://staging.my-shop.com` overrides
+         * the `my-shop` plugin's `defaultBaseUrl` without any source change.
+         * Falls back to `SitePluginMeta.defaultBaseUrl` when the key is absent.
+         */
+        siteBaseUrls: Record<string, string>;
+        /** Master switch: routes Stagehand LLM calls through AWS Bedrock when true. */
+        useBedrock: boolean;
+        /** Anthropic SDK request timeout in ms. Raise for slow network paths to api.anthropic.com. */
+        anthropicTimeoutMs: number;
+        /** TCP connect timeout for all outbound fetch calls. Undici default is 10 s; raised to 120 s to match anthropicTimeoutMs. */
+        connectTimeoutMs: number;
+        /** Steel session wall-clock timeout in ms. Default is 1 hour; lower via STEEL_SESSION_TIMEOUT_MS on plans with shorter limits. */
+        steelSessionTimeoutMs: number;
+    };
+    bedrock: {
+        region: string;
+        accessKeyId: string | undefined;
+        secretAccessKey: string | undefined;
+        sessionToken: string | undefined;
+        model: string;
+    };
+    cache: {
+        ttlMs: number;
+        maxEntries: number;
+    };
+    rateLimit: {
+        max: number;
+        windowMs: number;
+    };
+    docs: {
+        enabled: boolean;
+    };
+    telemetry: {
+        /**
+         * Master switch — set to false to disable all NDJSON telemetry writes.
+         * Useful for environments where the disk path is unavailable or I/O is
+         * cost-sensitive; the capture sink checks this before every append.
+         */
+        enabled: boolean;
+        /**
+         * Directory that holds per-run NDJSON event stream files. The event-writer
+         * creates `<eventsDir>/<runId>.ndjson` at session start. Default matches
+         * the `.barnacle/events` path referenced in run-state.ts so operator docs
+         * and `.gitignore` stay consistent.
+         */
+        eventsDir: string;
+        /**
+         * Absolute or cwd-relative path for the append-only NDJSON file that
+         * records one line per LLM/Stagehand call. Feed this to the judge and
+         * self-heal skills. Default keeps it alongside the event-stream files.
+         */
+        callsNdjsonPath: string;
+        /**
+         * Absolute or cwd-relative path for the append-only NDJSON file that
+         * records one line per dispatch outcome — the submission envelope. This
+         * is the durable source-of-truth for "what did we submit for jobId X,
+         * what did the site return, and did it succeed." Kept on a separate
+         * sink from `callsNdjsonPath` so existing judge/heal readers (which
+         * Zod-parse every line as an LlmCallSample) stay untouched.
+         */
+        submissionsNdjsonPath: string;
+        /**
+         * Rotate / drop the calls NDJSON once it exceeds this byte count.
+         * Guards against unbounded disk growth on long-running deployments.
+         * Default is 100 MB.
+         */
+        maxFileSizeBytes: number;
+        /**
+         * Drop event-stream files older than this many milliseconds. Default is
+         * 30 days — long enough for a monthly judge/heal cadence.
+         */
+        maxRetentionMs: number;
+        /**
+         * Opt-in buffered S3 sink that mirrors local NDJSON telemetry so it
+         * survives ECS container restarts. Entirely inert when `bucket` is
+         * undefined — the sink checks this before buffering or flushing.
+         */
+        s3: {
+            /** `TELEMETRY_S3_BUCKET` — destination bucket. Sink is a no-op when unset. */
+            bucket: string | undefined;
+            /** `TELEMETRY_S3_PREFIX` — key prefix for uploaded NDJSON objects. */
+            prefix: string;
+            /** `TELEMETRY_S3_FLUSH_INTERVAL_MS` — periodic flush interval. */
+            flushIntervalMs: number;
+            /** `TELEMETRY_S3_MAX_BUFFER_LINES` — threshold-flush trigger per buffer. */
+            maxBufferLines: number;
+        };
+    };
+    judging: {
+        /**
+         * Anthropic model used by the judge script to score captured call samples.
+         * Defaults to the Bedrock cross-region inference profile so it reuses the
+         * scraper's AWS creds without a separate billing account.
+         */
+        model: string;
+        /**
+         * Sampling temperature for judge LLM calls. Lower values (≤ 0.3) produce
+         * more deterministic verdicts; raise only for exploratory runs.
+         */
+        temperature: number;
+        /**
+         * Number of call samples sent to the judge in one LLM request. Larger
+         * batches reduce round-trips but increase per-call token cost.
+         */
+        batchSize: number;
+        /**
+         * Anthropic SDK request timeout for judge calls in ms. Judge batches are
+         * larger than scraper calls so a longer timeout is warranted.
+         */
+        timeoutMs: number;
+    };
+    /**
+     * testmail.app — fresh inboxes for recon runs + integration tests.
+     * Both fields nullable so a missing API key doesn't break unrelated
+     * config loads; the testmail helpers throw clear errors when called
+     * without configuration.
+     */
+    testmail: {
+        /** `TESTMAIL_API_KEY` — get from https://testmail.app/console */
+        apiKey: string | undefined;
+        /** `TESTMAIL_NAMESPACE` — the subdomain piece (e.g. "abc12" for `abc12.{tag}@inbox.testmail.app`). */
+        namespace: string | undefined;
+    };
+    selfheal: {
+        /**
+         * Maximum patch→replay→score iterations before giving up with
+         * BUDGET_EXHAUSTED. Mirrors the recon-heal default of 5.
+         */
+        maxIterations: number;
+        /**
+         * Number of replay runs per iteration arm. Replays are cheap (no browser),
+         * so a higher n gives a more stable pass-rate estimate.
+         */
+        nReplays: number;
+        /**
+         * Minimum pass rate (0..1) to declare SUCCESS and stop iterating.
+         * Mirrors the pila llm-self-heal SKILL default of 0.9.
+         */
+        successThreshold: number;
+        /**
+         * Consecutive iterations whose pass-rate improvement is below
+         * `plateauDelta` that triggers a PLATEAUED verdict. Mirrors recon-heal.
+         */
+        plateauWindow: number;
+        /**
+         * Minimum absolute improvement in pass rate between iterations to be
+         * considered meaningful progress; below this the run plateaus.
+         */
+        plateauDelta: number;
+        /**
+         * Per-replay LLM request timeout in ms. Patch replay calls are small
+         * single-turn requests so a tighter timeout keeps the loop fast.
+         */
+        timeoutMs: number;
+    };
+    datadog: {
+        /** Master switch — dd-trace only initializes when true. */
+        traceEnabled: boolean;
+        /** Hostname of the DD agent sidecar (localhost in ECS Fargate). */
+        agentHost: string;
+        /** DogStatsD UDP port on the agent host. */
+        statsdPort: number;
+        /** Service name emitted on all spans, metrics, and logs. */
+        service: string;
+        /** Deployment environment tag (production, staging, development). */
+        env: string;
+        /** Application version tag — git SHA or package version. */
+        version: string;
+    };
+    /**
+     * Out-of-tree plugin loading. Operators point `BARNACLE_PLUGINS` at their
+     * own compiled plugin modules; core discovers, validates, and registers them
+     * at startup without any source change.
+     */
+    plugins: {
+        /**
+         * Comma-separated list of plugin specifiers — relative paths
+         * (`./plugins/acme`) or package names (`@acme/barnacle-plugin`).
+         * Parsed from `BARNACLE_PLUGINS`; empty by default (built-ins only).
+         */
+        specifiers: readonly string[];
+        /**
+         * When true, any plugin that fails to load aborts the process.
+         * When false (default), failures produce a disabled record and a warn log.
+         */
+        strict: boolean;
+        /**
+         * Base directory used to resolve relative plugin specifiers and to locate
+         * the operator's `node_modules` for package-name specifiers. Defaults to
+         * `process.cwd()` so paths are relative to wherever the operator runs the
+         * binary — NOT the installed Barnacle package root.
+         */
+        baseDir: string;
+        /**
+         * Optional directory scanned at startup for `*.plugin.json` manifests, each
+         * loaded as a config-only plugin. Lets operators register sites by dropping
+         * a file in a directory instead of editing `BARNACLE_PLUGINS`. Parsed from
+         * `BARNACLE_PLUGINS_CONFIG_DIR`; unset means no directory scan.
+         */
+        configDir: string | undefined;
+    };
+}
+/**
+ * Loads and validates the application config. Call this once at process
+ * startup; subsequent calls return the same frozen object.
+ */
+export declare function loadConfig(): AppConfig;
+export declare const config: AppConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

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