agentfootprint 2.11.0 → 2.11.1

package/dist/reliability/CircuitBreaker.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * CircuitBreaker — pure state-machine functions for the Nygard breaker
+ * pattern.
+ *
+ * Refactored from a class-with-instance-state to PURE FUNCTIONS that
+ * take a state record and return a new one. Reasons:
+ *
+ *   1. **No hidden runtime state.** Breaker state lives in scope where
+ *      it's visible to commitLog, narrative, and rules — the footprintjs
+ *      "everything in scope" principle. The closure used to be the
+ *      source of truth and scope held only a projection; now scope IS
+ *      the source of truth.
+ *
+ *   2. **Round-trippable across gate invocations.** Because state is a
+ *      plain record, gate's outputMapper writes it back to agent scope;
+ *      agent scope persists across the ReAct loop's many LLM-call gate
+ *      invocations; gate's inputMapper reads it back in for the next
+ *      call. Per-process persistence comes from the agent scope, not
+ *      from a closure that hides between runs.
+ *
+ *   3. **Distributable later.** A future v2.12 `BreakerStateStore`
+ *      adapter (Redis/DynamoDB) just needs to serialize/deserialize the
+ *      state record. No class instances to reconstruct.
+ *
+ *   4. **Testable in isolation.** Pure functions; no instance setup.
+ *
+ * Pattern: Nygard *Release It!* — three states (CLOSED → OPEN →
+ *          HALF-OPEN) with cooldown and probe-success thresholds.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextProbeTime = exports.recordFailure = exports.recordSuccess = exports.admitCall = exports.initialBreakerState = exports.CircuitOpenError = void 0;
+/**
+ * Thrown by `assertAdmit()` when the breaker is OPEN and the cooldown
+ * window has not elapsed. The reliability gate stage catches this,
+ * classifies via `classifyError` → `'circuit-open'`, and lets the
+ * post-decide rules route on it.
+ */
+class CircuitOpenError extends Error {
+    code = 'ERR_CIRCUIT_OPEN';
+    cause;
+    retryAfter;
+    constructor(providerName, lastErrorMessage, retryAfter) {
+        super(`[${providerName}] circuit breaker is OPEN — failing fast (next probe at ${new Date(retryAfter).toISOString()}). Underlying error: ${lastErrorMessage ?? 'unknown'}`);
+        this.name = 'CircuitOpenError';
+        this.cause = lastErrorMessage;
+        this.retryAfter = retryAfter;
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
+// ─── Defaults ────────────────────────────────────────────────────────
+const DEFAULT_FAILURE_THRESHOLD = 5;
+const DEFAULT_COOLDOWN_MS = 30_000;
+const DEFAULT_HALF_OPEN_SUCCESS_THRESHOLD = 2;
+function defaultShouldCount(error) {
+    // User cancellations don't indicate vendor health
+    const e = error;
+    if (e?.name === 'AbortError')
+        return false;
+    if (e?.code === 'ABORT_ERR')
+        return false;
+    return true;
+}
+// ─── Constructors ────────────────────────────────────────────────────
+/** Initial state for a freshly-CLOSED breaker. */
+function initialBreakerState() {
+    return {
+        state: 'closed',
+        consecutiveFailures: 0,
+        consecutiveSuccesses: 0,
+        openedAt: 0,
+    };
+}
+exports.initialBreakerState = initialBreakerState;
+// ─── Pure transitions ────────────────────────────────────────────────
+/**
+ * Decide whether to admit a call. Returns the (possibly-updated) state
+ * AND whether to admit. If OPEN and cooldown elapsed, transitions to
+ * HALF-OPEN and admits. Pure: caller must use the returned state.
+ *
+ * Usage in the gate stage:
+ * ```ts
+ * const { admitted, nextState } = admitCall(scope.breakerStates[name], config);
+ * scope.breakerStates[name] = nextState;
+ * if (!admitted) throw new CircuitOpenError(name, nextState.lastErrorMessage, ...);
+ * ```
+ */
+function admitCall(state, config) {
+    const cooldownMs = config?.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+    if (state.state === 'closed' || state.state === 'half-open') {
+        return { admitted: true, nextState: state };
+    }
+    // OPEN — check cooldown
+    if (Date.now() - state.openedAt >= cooldownMs) {
+        return {
+            admitted: true,
+            nextState: { ...state, state: 'half-open', consecutiveSuccesses: 0 },
+        };
+    }
+    return { admitted: false, nextState: state };
+}
+exports.admitCall = admitCall;
+/** Record a successful call. Returns the (possibly-updated) state. */
+function recordSuccess(state, config) {
+    const halfOpenSuccessThreshold = config?.halfOpenSuccessThreshold ?? DEFAULT_HALF_OPEN_SUCCESS_THRESHOLD;
+    if (state.state === 'half-open') {
+        const consecutiveSuccesses = state.consecutiveSuccesses + 1;
+        if (consecutiveSuccesses >= halfOpenSuccessThreshold) {
+            // Probe successes met threshold → fully CLOSE
+            return {
+                state: 'closed',
+                consecutiveFailures: 0,
+                consecutiveSuccesses: 0,
+                openedAt: 0,
+            };
+        }
+        return { ...state, consecutiveSuccesses };
+    }
+    if (state.state === 'closed') {
+        // Reset failure counter on success
+        return state.consecutiveFailures === 0 ? state : { ...state, consecutiveFailures: 0 };
+    }
+    return state;
+}
+exports.recordSuccess = recordSuccess;
+/** Record a failed call. Returns the (possibly-updated) state. */
+function recordFailure(state, err, config) {
+    const shouldCount = config?.shouldCount ?? defaultShouldCount;
+    if (!shouldCount(err))
+        return state;
+    const failureThreshold = config?.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
+    const lastErrorMessage = err?.message ?? String(err);
+    if (state.state === 'half-open') {
+        // Probe failed → re-OPEN
+        return {
+            state: 'open',
+            consecutiveFailures: state.consecutiveFailures,
+            consecutiveSuccesses: 0,
+            openedAt: Date.now(),
+            lastErrorMessage,
+        };
+    }
+    if (state.state === 'closed') {
+        const consecutiveFailures = state.consecutiveFailures + 1;
+        if (consecutiveFailures >= failureThreshold) {
+            return {
+                state: 'open',
+                consecutiveFailures,
+                consecutiveSuccesses: 0,
+                openedAt: Date.now(),
+                lastErrorMessage,
+            };
+        }
+        return { ...state, consecutiveFailures, lastErrorMessage };
+    }
+    // OPEN: leave state unchanged (admitCall handles cooldown)
+    return state;
+}
+exports.recordFailure = recordFailure;
+/** Compute the next probe time given a state + config. */
+function nextProbeTime(state, config) {
+    return state.openedAt + (config?.cooldownMs ?? DEFAULT_COOLDOWN_MS);
+}
+exports.nextProbeTime = nextProbeTime;
+//# sourceMappingURL=CircuitBreaker.js.map

package/dist/reliability/CircuitBreaker.js.map

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

package/dist/reliability/buildReliabilityGateChart.js

@@ -0,0 +1,363 @@
+"use strict";
+/**
+ * buildReliabilityGateChart — produces a footprintjs FlowChart that wraps
+ * an LLM call with rules-based reliability semantics, using the native
+ * `decide()` DSL via `addDeciderFunction` decider stages.
+ *
+ * The returned chart is mounted as a subflow in the agent's chart at
+ * Agent.build() time (only when reliability is configured). Inside the
+ * subflow:
+ *
+ *   PreCheck (decider) → CallProvider (function) → PostDecide (decider)
+ *                                                       │
+ *                                       ┌───────────────┘
+ *                                       ▼ loopTo('pre-check')
+ *
+ * Branch outcomes (escape via $break() to stop the gate's loop;
+ * fall-through via no-$break to trigger loopTo back to PreCheck):
+ *
+ *   PreCheck:
+ *     'continue'   → no-op   → falls through to CallProvider
+ *     'fail-fast'  → set failKind, $emit, $break(reason)
+ *
+ *   PostDecide:
+ *     'ok'          → $break() (subflow exits normally; agent continues)
+ *     'retry'       → bump attempt; falls through to loopTo
+ *     'retry-other' → bump providerIdx; falls through to loopTo
+ *     'fallback'    → call config.fallback(); $break() on success
+ *     'fail-fast'   → set failKind, $emit, $break(reason)
+ *
+ * The subflow is mounted WITHOUT `propagateBreak: true`. Subflow $break is
+ * local — agent.ts adds a `TranslateFailFast` agent-level stage AFTER the
+ * subflow that reads scope.reliabilityFailKind and converts it into an
+ * agent-level `$break(reason)`. This split lets normal subflow exits
+ * (`ok`/`fallback`) leave the agent running while fail-fast stops it.
+ *
+ * Three-channel discipline preserved:
+ *   • SCOPE STATE  — failKind/failPayload/failReason mapped to parent via
+ *                    outputMapper; consumed by agent's TranslateFailFast.
+ *   • $emit        — passive observability for external consumers.
+ *   • $break(reason)— control flow + human reason for narrative.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildReliabilityGateChart = void 0;
+const footprintjs_1 = require("footprintjs");
+const CircuitBreaker_js_1 = require("./CircuitBreaker.js");
+const classifyError_js_1 = require("./classifyError.js");
+// ─── Stage IDs (also used for narrative/topology readability) ────────
+const STAGE_IDS = {
+    INIT: 'reliability-init',
+    PRE_CHECK: 'pre-check',
+    CALL_PROVIDER: 'call-provider',
+    POST_DECIDE: 'post-decide',
+};
+// Branch IDs must be globally unique within the chart's stageMap, so
+// each branch carries its decider's prefix. The decider's RETURN value
+// from preCheckDeciderFn / postDecideDeciderFn is the branch's local id
+// (e.g., 'continue', 'ok') — the decide() result map below translates.
+const BRANCH_IDS = {
+    // PreCheck branches
+    PRE_CONTINUE: 'pre-continue',
+    PRE_FAIL_FAST: 'pre-fail-fast',
+    // PostDecide branches
+    POST_OK: 'post-ok',
+    POST_RETRY: 'post-retry',
+    POST_RETRY_OTHER: 'post-retry-other',
+    POST_FALLBACK: 'post-fallback',
+    POST_FAIL_FAST: 'post-fail-fast',
+};
+// Map from `ReliabilityDecision` (consumer-facing rule.then values) to
+// the prefixed branch ids. The decider functions translate before
+// returning so consumers never see the prefixed names.
+const PRE_DECISION_TO_BRANCH = {
+    continue: BRANCH_IDS.PRE_CONTINUE,
+    'fail-fast': BRANCH_IDS.PRE_FAIL_FAST,
+};
+const POST_DECISION_TO_BRANCH = {
+    ok: BRANCH_IDS.POST_OK,
+    retry: BRANCH_IDS.POST_RETRY,
+    'retry-other': BRANCH_IDS.POST_RETRY_OTHER,
+    fallback: BRANCH_IDS.POST_FALLBACK,
+    'fail-fast': BRANCH_IDS.POST_FAIL_FAST,
+};
+// ─── Helpers ─────────────────────────────────────────────────────────
+/** Build the structured failure payload from current scope state. */
+function buildFailPayload(scope, phase) {
+    return {
+        phase,
+        attempt: scope.attempt,
+        providerUsed: scope.currentProvider,
+        errorKind: scope.errorKind,
+        ...(scope.error?.message !== undefined && { errorMessage: scope.error.message }),
+    };
+}
+/** Find the matched rule's index in a DecisionResult evidence list. */
+function findMatchedIndex(evidence) {
+    for (let i = 0; i < evidence.rules.length; i++) {
+        if (evidence.rules[i].matched)
+            return i;
+    }
+    return undefined;
+}
+/** Resolve {kind, label} from a rule list and the matched index. */
+function matchedKindLabel(rules, matchedIdx) {
+    if (matchedIdx === undefined || matchedIdx < 0 || matchedIdx >= rules.length) {
+        return { kind: 'unknown', label: 'unknown' };
+    }
+    const rule = rules[matchedIdx];
+    return { kind: rule.kind, label: rule.label ?? rule.kind };
+}
+// ─── Build the chart ─────────────────────────────────────────────────
+/**
+ * Build the reliability gate FlowChart from a config. Mount via
+ * `addSubFlowChartNext` in the agent's chart — see `Agent.build()`.
+ *
+ * Closure state captured by stage functions:
+ *   • `breakers` — Map<providerName, CircuitBreaker>; per-instance state
+ *     persists across gate invocations within ONE agent process.
+ *   • `preRules` / `postRules` — frozen rule arrays.
+ *   • `fallbackFn` — consumer's fallback function, if configured.
+ */
+function buildReliabilityGateChart(config) {
+    // FROZEN CONFIG captured by the factory closure. None of these mutate
+    // at runtime — they're the chart's CODE, not state. Same pattern as
+    // every other footprintjs chart factory (cacheDecisionSubflow,
+    // injectionEngineSubflow, etc.) capturing rules/directives at build.
+    //
+    //   • providers     — functions can't structuredClone into scope
+    //   • preRules/postRules — frozen at chart-build time
+    //   • fallbackFn    — function, can't structuredClone into scope
+    //
+    // RUNTIME STATE (attempt counts, errorKind, breaker counters,
+    // response, latency, etc.) lives in SCOPE. Breaker state in
+    // particular is a plain serializable record that round-trips across
+    // gate invocations via inputMapper/outputMapper — no closure.
+    const providers = config.providers ?? [];
+    const breakerConfig = config.circuitBreaker;
+    const preRules = config.preCheck ?? [];
+    const postRules = config.postDecide ?? [];
+    const fallbackFn = config.fallback;
+    // ─── PreCheck decider function ───────────────────────────────
+    // Returns one of the PRE_* branch ids. If consumer rules use
+    // ReliabilityDecision values ('continue'/'fail-fast'), map them.
+    const preCheckDeciderFn = (scope) => {
+        if (preRules.length === 0)
+            return BRANCH_IDS.PRE_CONTINUE;
+        const result = (0, footprintjs_1.decide)(scope, preRules, 'continue');
+        return PRE_DECISION_TO_BRANCH[result.branch] ?? BRANCH_IDS.PRE_CONTINUE;
+    };
+    // ─── PreCheck 'fail-fast' branch fn ──────────────────────────
+    const preFailFastBranchFn = (scope) => {
+        // Pre-check rules carry kind via the decide() result. Re-evaluate
+        // to extract the matched rule's kind/label for the failure payload.
+        if (preRules.length === 0)
+            return;
+        const result = (0, footprintjs_1.decide)(scope, preRules, 'continue');
+        const matchedIdx = findMatchedIndex(result.evidence);
+        const { kind, label } = matchedKindLabel(preRules, matchedIdx);
+        scope.failKind = kind;
+        scope.failPayload = buildFailPayload(scope, 'pre-check');
+        scope.$emit('agentfootprint.reliability.fail_fast', {
+            phase: 'pre-check',
+            kind,
+            label,
+            attempt: scope.attempt,
+            providerUsed: scope.currentProvider,
+        });
+        scope.$break(`reliability-pre-check: ${label}`);
+    };
+    // ─── CallProvider stage fn ───────────────────────────────────
+    const callProviderStageFn = async (scope) => {
+        const providerEntry = providers[scope.providerIdx];
+        if (!providerEntry) {
+            // Misconfiguration — no provider at this index. Fail-fast cleanly.
+            scope.failKind = 'misconfigured-provider';
+            scope.failPayload = buildFailPayload(scope, 'pre-check');
+            scope.$emit('agentfootprint.reliability.fail_fast', {
+                phase: 'pre-check',
+                kind: 'misconfigured-provider',
+                providerIdx: scope.providerIdx,
+            });
+            scope.$break(`reliability-pre-check: misconfigured-provider (idx ${scope.providerIdx} out of bounds)`);
+            return;
+        }
+        const t0 = Date.now();
+        try {
+            // Breaker check (pure): admit + transition based on cooldown.
+            if (breakerConfig !== undefined) {
+                const current = scope.breakerStates[providerEntry.name] ?? (0, CircuitBreaker_js_1.initialBreakerState)();
+                const { admitted, nextState } = (0, CircuitBreaker_js_1.admitCall)(current, breakerConfig);
+                scope.breakerStates[providerEntry.name] = nextState;
+                if (!admitted) {
+                    throw new CircuitBreaker_js_1.CircuitOpenError(providerEntry.name, nextState.lastErrorMessage, (0, CircuitBreaker_js_1.nextProbeTime)(nextState, breakerConfig));
+                }
+            }
+            const response = await providerEntry.provider.complete(scope.request);
+            scope.response = response;
+            scope.error = undefined;
+            scope.errorKind = 'ok';
+            // Record success (pure): may CLOSE a HALF-OPEN breaker
+            if (breakerConfig !== undefined) {
+                scope.breakerStates[providerEntry.name] = (0, CircuitBreaker_js_1.recordSuccess)(scope.breakerStates[providerEntry.name] ?? (0, CircuitBreaker_js_1.initialBreakerState)(), breakerConfig);
+            }
+        }
+        catch (err) {
+            scope.response = undefined;
+            scope.error = err instanceof Error ? err : new Error(String(err));
+            scope.errorKind = (0, classifyError_js_1.classifyError)(err);
+            // CircuitOpenError is the breaker rejecting; don't double-count.
+            if (breakerConfig !== undefined && !(err instanceof CircuitBreaker_js_1.CircuitOpenError)) {
+                scope.breakerStates[providerEntry.name] = (0, CircuitBreaker_js_1.recordFailure)(scope.breakerStates[providerEntry.name] ?? (0, CircuitBreaker_js_1.initialBreakerState)(), err, breakerConfig);
+            }
+        }
+        finally {
+            scope.latencyMs = Date.now() - t0;
+            scope.attemptsPerProvider[providerEntry.name] =
+                (scope.attemptsPerProvider[providerEntry.name] ?? 0) + 1;
+            scope.attempt += 1;
+            scope.canSwitchProvider = scope.providerIdx < providers.length - 1;
+        }
+    };
+    // ─── PostDecide decider function ─────────────────────────────
+    // Returns one of the POST_* branch ids. Maps ReliabilityDecision
+    // values from rule.then to the prefixed branch ids.
+    const postDecideDeciderFn = (scope) => {
+        if (postRules.length === 0) {
+            return scope.error === undefined ? BRANCH_IDS.POST_OK : BRANCH_IDS.POST_FAIL_FAST;
+        }
+        const result = (0, footprintjs_1.decide)(scope, postRules, 'ok');
+        return POST_DECISION_TO_BRANCH[result.branch] ?? BRANCH_IDS.POST_OK;
+    };
+    // ─── PostDecide branch fns ───────────────────────────────────
+    const okBranchFn = (scope) => {
+        // Success exit — $break stops subflow; outputMapper still runs.
+        scope.$break();
+    };
+    const retryBranchFn = (_scope) => {
+        // No-op — `attempt` was already incremented by CallProvider's
+        // finally block. Falling through (no $break) triggers loopTo
+        // back to PreCheck.
+        void _scope;
+    };
+    const retryOtherBranchFn = (scope) => {
+        // Advance to the next provider in the failover list (held in closure).
+        scope.providerIdx += 1;
+        if (scope.providerIdx < providers.length) {
+            scope.currentProvider = providers[scope.providerIdx].name;
+        }
+        scope.canSwitchProvider = scope.providerIdx < providers.length - 1;
+        // No $break — loopTo re-enters PreCheck with the new provider.
+    };
+    const fallbackBranchFn = async (scope) => {
+        if (!fallbackFn) {
+            // Routed here but no fallback configured — convert to fail-fast.
+            scope.failKind = 'fallback-not-configured';
+            scope.failPayload = buildFailPayload(scope, 'post-decide');
+            scope.$emit('agentfootprint.reliability.fail_fast', {
+                phase: 'post-decide',
+                kind: 'fallback-not-configured',
+                attempt: scope.attempt,
+                providerUsed: scope.currentProvider,
+            });
+            scope.$break('reliability-post-decide: fallback-not-configured');
+            return;
+        }
+        try {
+            const repaired = await fallbackFn(scope.request, scope.error);
+            scope.response = repaired;
+            scope.error = undefined;
+            scope.errorKind = 'ok';
+            scope.$break(); // success via fallback; exit subflow
+        }
+        catch (fallbackErr) {
+            // Fallback threw — re-classify and let next iteration's
+            // post-decide rules route on the new error (typically fail-fast).
+            scope.error = fallbackErr instanceof Error ? fallbackErr : new Error(String(fallbackErr));
+            scope.errorKind = (0, classifyError_js_1.classifyError)(fallbackErr);
+            // Don't $break — loopTo re-enters PreCheck with new error state.
+        }
+    };
+    const failFastBranchFn = (scope) => {
+        if (postRules.length === 0) {
+            // Default-path fail-fast (no rules configured but error occurred)
+            scope.failKind = scope.errorKind;
+            scope.failPayload = buildFailPayload(scope, 'post-decide');
+            scope.$emit('agentfootprint.reliability.fail_fast', {
+                phase: 'post-decide',
+                kind: scope.errorKind,
+                attempt: scope.attempt,
+                providerUsed: scope.currentProvider,
+                ...(scope.error?.message !== undefined && { errorMessage: scope.error.message }),
+            });
+            scope.$break(`reliability-post-decide: ${scope.errorKind}`);
+            return;
+        }
+        // Re-evaluate to extract the matched rule's kind/label.
+        const result = (0, footprintjs_1.decide)(scope, postRules, 'ok');
+        const matchedIdx = findMatchedIndex(result.evidence);
+        const { kind, label } = matchedKindLabel(postRules, matchedIdx);
+        scope.failKind = kind;
+        scope.failPayload = buildFailPayload(scope, 'post-decide');
+        scope.$emit('agentfootprint.reliability.fail_fast', {
+            phase: 'post-decide',
+            kind,
+            label,
+            attempt: scope.attempt,
+            providerUsed: scope.currentProvider,
+            errorKind: scope.errorKind,
+            ...(scope.error?.message !== undefined && { errorMessage: scope.error.message }),
+        });
+        scope.$break(`reliability-post-decide: ${label}`);
+    };
+    // ─── Compose the chart ───────────────────────────────────────
+    // The chart starts with an Init stage that seeds the MUTABLE scope
+    // state (attempt, providerIdx, errorKind, attemptsPerProvider, etc.).
+    // We can't seed mutable state via inputMapper because inputMapper
+    // supplies READ-ONLY inputs (the subflow's "args"). Instead, only
+    // truly-readonly inputs (request, providersCount, hasFallback,
+    // cumulativeCostUsd) come via inputMapper; the rest is initialized
+    // here.
+    return (0, footprintjs_1.flowChart)('Init', (scope) => {
+        // Seed mutable state. Read-only inputs (request, providersCount,
+        // hasFallback, cumulativeCostUsd, AND incomingBreakerStates) come
+        // via inputMapper and are accessible via $getArgs(); only mutable
+        // fields seeded into scope here.
+        const args = scope.$getArgs();
+        scope.attempt = 0;
+        scope.providerIdx = 0;
+        scope.currentProvider = providers[0]?.name ?? '';
+        scope.canSwitchProvider = providers.length > 1;
+        scope.errorKind = 'ok';
+        scope.latencyMs = 0;
+        scope.attemptsPerProvider = {};
+        // Breaker state restoration: if the agent passed prior breaker
+        // states (across gate invocations within one ReAct loop, or
+        // hydrated from a persistence store), use them; else start fresh.
+        // This is the round-trip mechanism that replaces closure state.
+        const incoming = args.incomingBreakerStates ?? {};
+        scope.breakerStates = {};
+        if (breakerConfig !== undefined) {
+            for (const p of providers) {
+                scope.breakerStates[p.name] = incoming[p.name] ?? (0, CircuitBreaker_js_1.initialBreakerState)();
+            }
+        }
+    }, STAGE_IDS.INIT, undefined, 'Reliability gate state init')
+        .addDeciderFunction('PreCheck', preCheckDeciderFn, STAGE_IDS.PRE_CHECK, 'Reliability: pre-call rule check')
+        .addFunctionBranch(BRANCH_IDS.PRE_CONTINUE, 'PreContinue', () => { })
+        .addFunctionBranch(BRANCH_IDS.PRE_FAIL_FAST, 'PreFailFast', preFailFastBranchFn)
+        .setDefault(BRANCH_IDS.PRE_CONTINUE)
+        .end()
+        .addFunction('CallProvider', callProviderStageFn, STAGE_IDS.CALL_PROVIDER, 'Invoke LLM provider; capture response/error to scope')
+        .addDeciderFunction('PostDecide', postDecideDeciderFn, STAGE_IDS.POST_DECIDE, 'Reliability: post-call rule check')
+        .addFunctionBranch(BRANCH_IDS.POST_OK, 'PostOk', okBranchFn)
+        .addFunctionBranch(BRANCH_IDS.POST_RETRY, 'PostRetry', retryBranchFn)
+        .addFunctionBranch(BRANCH_IDS.POST_RETRY_OTHER, 'PostRetryOther', retryOtherBranchFn)
+        .addFunctionBranch(BRANCH_IDS.POST_FALLBACK, 'PostFallback', fallbackBranchFn)
+        .addFunctionBranch(BRANCH_IDS.POST_FAIL_FAST, 'PostFailFast', failFastBranchFn)
+        .setDefault(BRANCH_IDS.POST_OK)
+        .end()
+        .loopTo(STAGE_IDS.PRE_CHECK)
+        .build();
+}
+exports.buildReliabilityGateChart = buildReliabilityGateChart;
+//# sourceMappingURL=buildReliabilityGateChart.js.map

package/dist/reliability/buildReliabilityGateChart.js.map

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

package/dist/reliability/classifyError.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * classifyError — pure function mapping a thrown error to one of the
+ * coarse `ReliabilityScope.errorKind` categories used by reliability rules.
+ *
+ * Centralized so rules read structured `errorKind` instead of doing
+ * regex on `error.message` themselves. Add new categories ONLY when a
+ * new rule needs to discriminate them — keep the taxonomy small.
+ *
+ * Categories:
+ *   • 'ok'             — no error (caller should pass `undefined` or omit)
+ *   • 'circuit-open'   — `CircuitOpenError` from the breaker layer
+ *   • 'rate-limit'     — HTTP 429 or vendor rate-limit signal
+ *   • '5xx-transient'  — HTTP 5xx, ETIMEDOUT, ECONNRESET, ECONNREFUSED
+ *   • 'schema-fail'    — `OutputSchemaError` from the schema validator
+ *   • 'unknown'        — anything else (default; still routable but
+ *                        consumers usually `'fail-fast'` on this)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyError = void 0;
+/**
+ * Classify an error into a `ReliabilityScope['errorKind']` category.
+ *
+ * @param err - The thrown value. May be an Error, a vendor SDK error
+ *   shape with `.status`/`.code`, or anything else (`unknown` defaults).
+ * @returns the matching coarse category string.
+ */
+function classifyError(err) {
+    if (err === undefined || err === null)
+        return 'ok';
+    const e = err;
+    // Circuit breaker tripped — most specific check first
+    if (e.code === 'ERR_CIRCUIT_OPEN')
+        return 'circuit-open';
+    // Output schema validation failure — common after LLM produces
+    // malformed JSON when an outputSchema is configured
+    if (e.code === 'ERR_OUTPUT_SCHEMA')
+        return 'schema-fail';
+    // HTTP status discrimination (status OR statusCode — vendors differ)
+    const status = e.status ?? e.statusCode;
+    if (typeof status === 'number') {
+        if (status === 429)
+            return 'rate-limit';
+        if (status >= 500 && status < 600)
+            return '5xx-transient';
+    }
+    // String-based detection for transient network errors that don't
+    // carry a status code (Node's net/dns error shapes)
+    const msg = (e.message ?? '').toString();
+    if (/(ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN|socket hang up)/i.test(msg)) {
+        return '5xx-transient';
+    }
+    // Some vendor SDKs include "rate limit" in the message even when status
+    // is null (e.g., on streaming pipelines that surface errors mid-stream)
+    if (/rate.?limit|too many requests/i.test(msg))
+        return 'rate-limit';
+    return 'unknown';
+}
+exports.classifyError = classifyError;
+//# sourceMappingURL=classifyError.js.map

package/dist/reliability/classifyError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifyError.js","sourceRoot":"","sources":["../../src/reliability/classifyError.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAcH;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,GAAY;IACxC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEnD,MAAM,CAAC,GAAG,GAAgB,CAAC;IAE3B,sDAAsD;IACtD,IAAI,CAAC,CAAC,IAAI,KAAK,kBAAkB;QAAE,OAAO,cAAc,CAAC;IAEzD,+DAA+D;IAC/D,oDAAoD;IACpD,IAAI,CAAC,CAAC,IAAI,KAAK,mBAAmB;QAAE,OAAO,aAAa,CAAC;IAEzD,qEAAqE;IACrE,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC;IACxC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,YAAY,CAAC;QACxC,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;YAAE,OAAO,eAAe,CAAC;IAC5D,CAAC;IAED,iEAAiE;IACjE,oDAAoD;IACpD,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;IACzC,IAAI,+DAA+D,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9E,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,wEAAwE;IACxE,wEAAwE;IACxE,IAAI,gCAAgC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IAEpE,OAAO,SAAS,CAAC;AACnB,CAAC;AA9BD,sCA8BC"}