@coool/opencode-adaptive 0.0.0-stage → 1.0.1

package/dist/health/capacity/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Capacity sensor boundary (ADP-020).
+ *
+ * Capacity is observed, never inferred: a sensor reports what its telemetry
+ * actually shows (used/remaining ratios, retry-after, reset time) and grades
+ * its own confidence. A `null` reading or assessment means "no trustworthy
+ * estimate" — callers must treat that as unknown, never as healthy. Provider
+ * specific sensing (passive Codex headers, optional quota endpoints) lives in
+ * adapters; this module owns the boundary type, the deterministic merge of
+ * concurrent readings for one resource, and the derivation of the
+ * draining/exhausted signals consumed by the health layer (ADP-021).
+ */
+import type { ResourceKey } from "../resource-health/types.js";
+export declare const CONFIDENCE_LEVELS: readonly ["low", "medium", "high"];
+/** How much a sensor trusts its own numbers. `high` is required for draining. */
+export type Confidence = (typeof CONFIDENCE_LEVELS)[number];
+/**
+ * One observation of a resource's capacity. Ratios are fractions in [0, 1].
+ * A reading may carry any subset of the measured fields (e.g. a header that
+ * only reports a Retry-After); a reading with none of them carries no
+ * information and is discarded. `observedAt` is when the underlying telemetry
+ * was seen, not when the sensor was asked.
+ */
+export interface CapacityReading {
+    readonly usedRatio?: number | undefined;
+    readonly remainingRatio?: number | undefined;
+    readonly retryAfterMs?: number | undefined;
+    /** Epoch milliseconds at which capacity is expected to reset. */
+    readonly resetAt?: number | undefined;
+    readonly confidence: Confidence;
+    readonly observedAt: number;
+    /** Bounded, secret-free label of the data source (e.g. a header name). */
+    readonly evidence?: string | undefined;
+}
+/** A source of capacity observations for exactly one resource. */
+export interface CapacitySensor {
+    readonly id: string;
+    readonly resource: ResourceKey;
+    /**
+     * Returns the latest reading, or `null` when the sensor has no trustworthy
+     * estimate. Expected "no data" must be returned as `null`, never thrown;
+     * the registry still guards against throws (fail-open: a failing sensor is
+     * no estimate, not an error).
+     */
+    read(): Promise<CapacityReading | null>;
+}
+export interface CapacityConfig {
+    /** Readings older than this are treated as absent (no estimate). */
+    readonly maxAgeMs: number;
+    /**
+     * Near-exhaustion bound at or below which high-confidence evidence marks
+     * the resource `draining` (ADP-021). A fixed product constant, deliberately
+     * not user-configurable — no threshold sliders.
+     */
+    readonly drainingRemainingThreshold: number;
+}
+export declare const DEFAULT_CAPACITY_CONFIG: CapacityConfig;
+/** Drain/exhaust derivation for a merged reading. */
+export interface CapacitySignals {
+    readonly exhausted: boolean;
+    readonly draining: boolean;
+}
+/**
+ * Scheduler-facing view for one resource. `none` is the explicit "no
+ * estimate" answer — unknown capacity, not zero capacity.
+ */
+export type CapacityAssessment = {
+    readonly kind: "none";
+} | {
+    readonly kind: "estimate";
+    readonly reading: CapacityReading;
+    readonly signals: CapacitySignals;
+};

package/dist/health/capacity/types.js

@@ -0,0 +1,6 @@
+export const CONFIDENCE_LEVELS = ["low", "medium", "high"];
+export const DEFAULT_CAPACITY_CONFIG = {
+    maxAgeMs: 60_000,
+    drainingRemainingThreshold: 0.1,
+};
+//# sourceMappingURL=types.js.map

package/dist/health/capacity/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/health/capacity/types.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAsC,CAAA;AAgD/F,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,QAAQ,EAAE,MAAM;IAChB,0BAA0B,EAAE,GAAG;CAChC,CAAA","sourcesContent":["/**\n * Capacity sensor boundary (ADP-020).\n *\n * Capacity is observed, never inferred: a sensor reports what its telemetry\n * actually shows (used/remaining ratios, retry-after, reset time) and grades\n * its own confidence. A `null` reading or assessment means \"no trustworthy\n * estimate\" — callers must treat that as unknown, never as healthy. Provider\n * specific sensing (passive Codex headers, optional quota endpoints) lives in\n * adapters; this module owns the boundary type, the deterministic merge of\n * concurrent readings for one resource, and the derivation of the\n * draining/exhausted signals consumed by the health layer (ADP-021).\n */\nimport type { ResourceKey } from \"../resource-health/types.js\"\n\nexport const CONFIDENCE_LEVELS = [\"low\", \"medium\", \"high\"] as const satisfies readonly string[]\n\n/** How much a sensor trusts its own numbers. `high` is required for draining. */\nexport type Confidence = (typeof CONFIDENCE_LEVELS)[number]\n\n/**\n * One observation of a resource's capacity. Ratios are fractions in [0, 1].\n * A reading may carry any subset of the measured fields (e.g. a header that\n * only reports a Retry-After); a reading with none of them carries no\n * information and is discarded. `observedAt` is when the underlying telemetry\n * was seen, not when the sensor was asked.\n */\nexport interface CapacityReading {\n  readonly usedRatio?: number | undefined\n  readonly remainingRatio?: number | undefined\n  readonly retryAfterMs?: number | undefined\n  /** Epoch milliseconds at which capacity is expected to reset. */\n  readonly resetAt?: number | undefined\n  readonly confidence: Confidence\n  readonly observedAt: number\n  /** Bounded, secret-free label of the data source (e.g. a header name). */\n  readonly evidence?: string | undefined\n}\n\n/** A source of capacity observations for exactly one resource. */\nexport interface CapacitySensor {\n  readonly id: string\n  readonly resource: ResourceKey\n  /**\n   * Returns the latest reading, or `null` when the sensor has no trustworthy\n   * estimate. Expected \"no data\" must be returned as `null`, never thrown;\n   * the registry still guards against throws (fail-open: a failing sensor is\n   * no estimate, not an error).\n   */\n  read(): Promise<CapacityReading | null>\n}\n\nexport interface CapacityConfig {\n  /** Readings older than this are treated as absent (no estimate). */\n  readonly maxAgeMs: number\n  /**\n   * Near-exhaustion bound at or below which high-confidence evidence marks\n   * the resource `draining` (ADP-021). A fixed product constant, deliberately\n   * not user-configurable — no threshold sliders.\n   */\n  readonly drainingRemainingThreshold: number\n}\n\nexport const DEFAULT_CAPACITY_CONFIG: CapacityConfig = {\n  maxAgeMs: 60_000,\n  drainingRemainingThreshold: 0.1,\n}\n\n/** Drain/exhaust derivation for a merged reading. */\nexport interface CapacitySignals {\n  readonly exhausted: boolean\n  readonly draining: boolean\n}\n\n/**\n * Scheduler-facing view for one resource. `none` is the explicit \"no\n * estimate\" answer — unknown capacity, not zero capacity.\n */\nexport type CapacityAssessment =\n  | { readonly kind: \"none\" }\n  | {\n      readonly kind: \"estimate\"\n      readonly reading: CapacityReading\n      readonly signals: CapacitySignals\n    }\n"]}

package/dist/health/circuit-breaker/breaker.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Pure circuit breaker state machine (ADP-019).
+ *
+ * All functions are total, synchronous, and clock-free: `now` is always an
+ * injected parameter. The single-probe guarantee comes from the admission
+ * protocol: `admitProbe` synchronously transitions an open (and due) breaker
+ * to half-open, so the second concurrent caller observes `half_open` and is
+ * blocked — there is never an await between the state check and the
+ * transition. Callers must persist the returned record immediately.
+ */
+import type { FailureCategory } from "../classifier/types.js";
+import { type BreakerConfig, type BreakerRecord } from "./types.js";
+export declare function initialBreaker(): BreakerRecord;
+export interface BreakerFailureResult {
+    readonly record: BreakerRecord;
+    /** True exactly when this failure tripped the breaker from closed to open. */
+    readonly opened: boolean;
+}
+/**
+ * Records a countable failure. Callers route only infrastructure failures
+ * here (the resource-health transitions layer sends outage, overload, and
+ * timeout); the breaker additionally exempts rate limiting and quota
+ * exhaustion, which own their windowed resource states. Failures observed
+ * while the breaker is not closed cannot happen through the admission
+ * protocol (non-probe callers are blocked) and are ignored defensively.
+ */
+export declare function recordBreakerFailure(record: BreakerRecord, category: FailureCategory, now: number, config: BreakerConfig): BreakerFailureResult;
+/**
+ * Observed success closes the breaker and resets the failure/backoff state.
+ * Evidence beats inference: a success is proof the resource works, from any
+ * prior breaker state.
+ */
+export declare function recordBreakerSuccess(): BreakerRecord;
+export type ProbeAdmission = {
+    kind: "closed";
+    record: BreakerRecord;
+} | {
+    kind: "waiting";
+    record: BreakerRecord;
+    retryAtMs: number;
+} | {
+    kind: "in-flight";
+    record: BreakerRecord;
+} | {
+    kind: "admitted";
+    record: BreakerRecord;
+};
+/**
+ * Attempts to admit the single half-open probe. Callers must persist the
+ * returned record synchronously; the returned record carries no probeId — the
+ * registry stamps its own ticket id on the persisted copy.
+ */
+/**
+ * Non-mutating wait computation for an open breaker, admission view: the
+ * remaining backoff in ms, or `undefined` when the window has elapsed (or the
+ * record is not open). Used to decide whether a probe may be admitted.
+ */
+export declare function breakerWait(record: BreakerRecord, now: number): number | undefined;
+/**
+ * Non-mutating block computation for an open breaker, observer view: an open
+ * breaker blocks regardless of elapsed backoff — recovery counts only once a
+ * probe proved it — so an elapsed (or, unreachable through the state machine,
+ * missing) stamp simply means zero remaining wait.
+ */
+export declare function breakerBlockWait(record: BreakerRecord, now: number): number | undefined;
+export declare function admitProbe(record: BreakerRecord, now: number): ProbeAdmission;
+/** Closes the breaker when a probe report confirms recovery. */
+export declare function recordProbeSuccess(record: BreakerRecord): BreakerRecord;
+/**
+ * Expires a probe whose episode never reported an outcome. A lost probe is
+ * no health evidence: the breaker re-arms the SAME backoff window (no
+ * doubling) so a fresh probe can be admitted after it. Evaluated lazily by
+ * the registry's assessment sweep — there are no timers.
+ */
+export declare function expireProbe(record: BreakerRecord, now: number, config: BreakerConfig): BreakerRecord;
+/**
+ * Returns an admitted probe that was never dispatched (the admission picked
+ * another resource, only observed, or failed to switch). No request ran, so
+ * this is no evidence at all: the breaker goes back to open with the window
+ * it was admitted under — still due — instead of restarting the backoff,
+ * which would push a passed-over resource back on every admission.
+ */
+export declare function releaseProbe(record: BreakerRecord): BreakerRecord;
+/**
+ * Records a failed probe. A non-exempt failure reopens the breaker with a
+ * doubled backoff. An exempt failure (the probe was rate limited or quota
+ * blocked) re-arms the same backoff window without escalation: the resource
+ * was rejected for demand reasons, not degraded health, so doubling would
+ * overstate the failure.
+ */
+export declare function recordProbeFailure(record: BreakerRecord, category: FailureCategory, now: number, config: BreakerConfig): BreakerRecord;

package/dist/health/circuit-breaker/breaker.js

@@ -0,0 +1,150 @@
+import { BREAKER_EXEMPT_CATEGORIES } from "./types.js";
+export function initialBreaker() {
+    return { state: "closed", failures: 0, openCount: 0 };
+}
+/**
+ * Backoff window for the `openCount`-th opening: doubling, capped at
+ * `maxBackoffMs` so a persistently failing resource never waits longer than
+ * the configured ceiling.
+ */
+function backoffMs(openCount, config) {
+    return Math.min(config.baseOpenMs * 2 ** (openCount - 1), config.maxBackoffMs);
+}
+function openBreaker(record, openCount, now, config) {
+    return {
+        state: "open",
+        failures: record.failures,
+        openCount,
+        reopenAt: now + backoffMs(openCount, config),
+    };
+}
+/**
+ * Records a countable failure. Callers route only infrastructure failures
+ * here (the resource-health transitions layer sends outage, overload, and
+ * timeout); the breaker additionally exempts rate limiting and quota
+ * exhaustion, which own their windowed resource states. Failures observed
+ * while the breaker is not closed cannot happen through the admission
+ * protocol (non-probe callers are blocked) and are ignored defensively.
+ */
+export function recordBreakerFailure(record, category, now, config) {
+    if (BREAKER_EXEMPT_CATEGORIES.includes(category) || record.state !== "closed") {
+        return { record, opened: false };
+    }
+    const failures = record.failures + 1;
+    if (failures < config.failureThreshold) {
+        return { record: { ...record, failures }, opened: false };
+    }
+    return {
+        record: openBreaker({ ...record, failures }, record.openCount + 1, now, config),
+        opened: true,
+    };
+}
+/**
+ * Observed success closes the breaker and resets the failure/backoff state.
+ * Evidence beats inference: a success is proof the resource works, from any
+ * prior breaker state.
+ */
+export function recordBreakerSuccess() {
+    return { state: "closed", failures: 0, openCount: 0 };
+}
+/**
+ * Attempts to admit the single half-open probe. Callers must persist the
+ * returned record synchronously; the returned record carries no probeId — the
+ * registry stamps its own ticket id on the persisted copy.
+ */
+/**
+ * Non-mutating wait computation for an open breaker, admission view: the
+ * remaining backoff in ms, or `undefined` when the window has elapsed (or the
+ * record is not open). Used to decide whether a probe may be admitted.
+ */
+export function breakerWait(record, now) {
+    if (record.state !== "open")
+        return undefined;
+    const reopenAt = record.reopenAt;
+    if (reopenAt !== undefined && now < reopenAt)
+        return reopenAt - now;
+    return undefined;
+}
+/**
+ * Non-mutating block computation for an open breaker, observer view: an open
+ * breaker blocks regardless of elapsed backoff — recovery counts only once a
+ * probe proved it — so an elapsed (or, unreachable through the state machine,
+ * missing) stamp simply means zero remaining wait.
+ */
+export function breakerBlockWait(record, now) {
+    if (record.state !== "open")
+        return undefined;
+    return Math.max(0, (record.reopenAt ?? 0) - now);
+}
+export function admitProbe(record, now) {
+    if (record.state === "closed") {
+        return { kind: "closed", record };
+    }
+    if (record.state === "half_open") {
+        return { kind: "in-flight", record };
+    }
+    const wait = breakerWait(record, now);
+    if (wait !== undefined) {
+        return { kind: "waiting", record, retryAtMs: wait };
+    }
+    return {
+        kind: "admitted",
+        record: { state: "half_open", failures: record.failures, openCount: record.openCount },
+    };
+}
+/** Closes the breaker when a probe report confirms recovery. */
+export function recordProbeSuccess(record) {
+    if (record.state !== "half_open") {
+        return record;
+    }
+    return { state: "closed", failures: 0, openCount: 0 };
+}
+/**
+ * Expires a probe whose episode never reported an outcome. A lost probe is
+ * no health evidence: the breaker re-arms the SAME backoff window (no
+ * doubling) so a fresh probe can be admitted after it. Evaluated lazily by
+ * the registry's assessment sweep — there are no timers.
+ */
+export function expireProbe(record, now, config) {
+    if (record.state !== "half_open" ||
+        record.probeAt === undefined ||
+        now - record.probeAt < config.probeTimeoutMs) {
+        return record;
+    }
+    return openBreaker(record, record.openCount, now, config);
+}
+/**
+ * Returns an admitted probe that was never dispatched (the admission picked
+ * another resource, only observed, or failed to switch). No request ran, so
+ * this is no evidence at all: the breaker goes back to open with the window
+ * it was admitted under — still due — instead of restarting the backoff,
+ * which would push a passed-over resource back on every admission.
+ */
+export function releaseProbe(record) {
+    if (record.state !== "half_open") {
+        return record;
+    }
+    return {
+        state: "open",
+        failures: record.failures,
+        openCount: record.openCount,
+        ...(record.probeAt !== undefined ? { reopenAt: record.probeAt } : {}),
+    };
+}
+/**
+ * Records a failed probe. A non-exempt failure reopens the breaker with a
+ * doubled backoff. An exempt failure (the probe was rate limited or quota
+ * blocked) re-arms the same backoff window without escalation: the resource
+ * was rejected for demand reasons, not degraded health, so doubling would
+ * overstate the failure.
+ */
+export function recordProbeFailure(record, category, now, config) {
+    if (record.state !== "half_open") {
+        return record;
+    }
+    if (BREAKER_EXEMPT_CATEGORIES.includes(category)) {
+        return openBreaker(record, record.openCount, now, config);
+    }
+    return openBreaker(record, record.openCount + 1, now, config);
+}
+//# sourceMappingURL=breaker.js.map

package/dist/health/circuit-breaker/breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breaker.js","sourceRoot":"","sources":["../../../src/health/circuit-breaker/breaker.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure circuit breaker state machine (ADP-019).\n *\n * All functions are total, synchronous, and clock-free: `now` is always an\n * injected parameter. The single-probe guarantee comes from the admission\n * protocol: `admitProbe` synchronously transitions an open (and due) breaker\n * to half-open, so the second concurrent caller observes `half_open` and is\n * blocked — there is never an await between the state check and the\n * transition. Callers must persist the returned record immediately.\n */\nimport type { FailureCategory } from \"../classifier/types.js\"\nimport { BREAKER_EXEMPT_CATEGORIES, type BreakerConfig, type BreakerRecord } from \"./types.js\"\n\nexport function initialBreaker(): BreakerRecord {\n  return { state: \"closed\", failures: 0, openCount: 0 }\n}\n\n/**\n * Backoff window for the `openCount`-th opening: doubling, capped at\n * `maxBackoffMs` so a persistently failing resource never waits longer than\n * the configured ceiling.\n */\nfunction backoffMs(openCount: number, config: BreakerConfig): number {\n  return Math.min(config.baseOpenMs * 2 ** (openCount - 1), config.maxBackoffMs)\n}\n\nfunction openBreaker(\n  record: BreakerRecord,\n  openCount: number,\n  now: number,\n  config: BreakerConfig,\n): BreakerRecord {\n  return {\n    state: \"open\",\n    failures: record.failures,\n    openCount,\n    reopenAt: now + backoffMs(openCount, config),\n  }\n}\n\nexport interface BreakerFailureResult {\n  readonly record: BreakerRecord\n  /** True exactly when this failure tripped the breaker from closed to open. */\n  readonly opened: boolean\n}\n\n/**\n * Records a countable failure. Callers route only infrastructure failures\n * here (the resource-health transitions layer sends outage, overload, and\n * timeout); the breaker additionally exempts rate limiting and quota\n * exhaustion, which own their windowed resource states. Failures observed\n * while the breaker is not closed cannot happen through the admission\n * protocol (non-probe callers are blocked) and are ignored defensively.\n */\nexport function recordBreakerFailure(\n  record: BreakerRecord,\n  category: FailureCategory,\n  now: number,\n  config: BreakerConfig,\n): BreakerFailureResult {\n  if (BREAKER_EXEMPT_CATEGORIES.includes(category) || record.state !== \"closed\") {\n    return { record, opened: false }\n  }\n  const failures = record.failures + 1\n  if (failures < config.failureThreshold) {\n    return { record: { ...record, failures }, opened: false }\n  }\n  return {\n    record: openBreaker({ ...record, failures }, record.openCount + 1, now, config),\n    opened: true,\n  }\n}\n\n/**\n * Observed success closes the breaker and resets the failure/backoff state.\n * Evidence beats inference: a success is proof the resource works, from any\n * prior breaker state.\n */\nexport function recordBreakerSuccess(): BreakerRecord {\n  return { state: \"closed\", failures: 0, openCount: 0 }\n}\n\nexport type ProbeAdmission =\n  | { kind: \"closed\"; record: BreakerRecord }\n  | { kind: \"waiting\"; record: BreakerRecord; retryAtMs: number }\n  | { kind: \"in-flight\"; record: BreakerRecord }\n  | { kind: \"admitted\"; record: BreakerRecord }\n\n/**\n * Attempts to admit the single half-open probe. Callers must persist the\n * returned record synchronously; the returned record carries no probeId — the\n * registry stamps its own ticket id on the persisted copy.\n */\n/**\n * Non-mutating wait computation for an open breaker, admission view: the\n * remaining backoff in ms, or `undefined` when the window has elapsed (or the\n * record is not open). Used to decide whether a probe may be admitted.\n */\nexport function breakerWait(record: BreakerRecord, now: number): number | undefined {\n  if (record.state !== \"open\") return undefined\n  const reopenAt = record.reopenAt\n  if (reopenAt !== undefined && now < reopenAt) return reopenAt - now\n  return undefined\n}\n\n/**\n * Non-mutating block computation for an open breaker, observer view: an open\n * breaker blocks regardless of elapsed backoff — recovery counts only once a\n * probe proved it — so an elapsed (or, unreachable through the state machine,\n * missing) stamp simply means zero remaining wait.\n */\nexport function breakerBlockWait(record: BreakerRecord, now: number): number | undefined {\n  if (record.state !== \"open\") return undefined\n  return Math.max(0, (record.reopenAt ?? 0) - now)\n}\n\nexport function admitProbe(record: BreakerRecord, now: number): ProbeAdmission {\n  if (record.state === \"closed\") {\n    return { kind: \"closed\", record }\n  }\n  if (record.state === \"half_open\") {\n    return { kind: \"in-flight\", record }\n  }\n  const wait = breakerWait(record, now)\n  if (wait !== undefined) {\n    return { kind: \"waiting\", record, retryAtMs: wait }\n  }\n  return {\n    kind: \"admitted\",\n    record: { state: \"half_open\", failures: record.failures, openCount: record.openCount },\n  }\n}\n\n/** Closes the breaker when a probe report confirms recovery. */\nexport function recordProbeSuccess(record: BreakerRecord): BreakerRecord {\n  if (record.state !== \"half_open\") {\n    return record\n  }\n  return { state: \"closed\", failures: 0, openCount: 0 }\n}\n\n/**\n * Expires a probe whose episode never reported an outcome. A lost probe is\n * no health evidence: the breaker re-arms the SAME backoff window (no\n * doubling) so a fresh probe can be admitted after it. Evaluated lazily by\n * the registry's assessment sweep — there are no timers.\n */\nexport function expireProbe(\n  record: BreakerRecord,\n  now: number,\n  config: BreakerConfig,\n): BreakerRecord {\n  if (\n    record.state !== \"half_open\" ||\n    record.probeAt === undefined ||\n    now - record.probeAt < config.probeTimeoutMs\n  ) {\n    return record\n  }\n  return openBreaker(record, record.openCount, now, config)\n}\n\n/**\n * Returns an admitted probe that was never dispatched (the admission picked\n * another resource, only observed, or failed to switch). No request ran, so\n * this is no evidence at all: the breaker goes back to open with the window\n * it was admitted under — still due — instead of restarting the backoff,\n * which would push a passed-over resource back on every admission.\n */\nexport function releaseProbe(record: BreakerRecord): BreakerRecord {\n  if (record.state !== \"half_open\") {\n    return record\n  }\n  return {\n    state: \"open\",\n    failures: record.failures,\n    openCount: record.openCount,\n    ...(record.probeAt !== undefined ? { reopenAt: record.probeAt } : {}),\n  }\n}\n\n/**\n * Records a failed probe. A non-exempt failure reopens the breaker with a\n * doubled backoff. An exempt failure (the probe was rate limited or quota\n * blocked) re-arms the same backoff window without escalation: the resource\n * was rejected for demand reasons, not degraded health, so doubling would\n * overstate the failure.\n */\nexport function recordProbeFailure(\n  record: BreakerRecord,\n  category: FailureCategory,\n  now: number,\n  config: BreakerConfig,\n): BreakerRecord {\n  if (record.state !== \"half_open\") {\n    return record\n  }\n  if (BREAKER_EXEMPT_CATEGORIES.includes(category)) {\n    return openBreaker(record, record.openCount, now, config)\n  }\n  return openBreaker(record, record.openCount + 1, now, config)\n}\n"]}

package/dist/health/circuit-breaker/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./breaker.js";
+export * from "./types.js";

package/dist/health/circuit-breaker/index.js

@@ -0,0 +1,3 @@
+export * from "./breaker.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/health/circuit-breaker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/health/circuit-breaker/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA","sourcesContent":["export * from \"./breaker.js\"\nexport * from \"./types.js\"\n"]}

package/dist/health/circuit-breaker/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Circuit breaker types (ADP-019).
+ *
+ * The breaker is the quarantine mechanism for transient infrastructure
+ * failures (outage, overload, timeout): repeated failures open the resource
+ * for a backoff window, after which exactly one probe request is admitted
+ * (half-open state). Rate limiting and quota exhaustion are deliberately
+ * exempt from breaker counting because they already have their own windowed
+ * resource states; counting them here would double-punish a resource that is
+ * already known to need a cooldown.
+ */
+import type { FailureCategory } from "../classifier/types.js";
+export declare const BREAKER_STATES: readonly ["closed", "open", "half_open"];
+export type BreakerState = (typeof BREAKER_STATES)[number];
+export interface BreakerConfig {
+    /** Consecutive countable failures in the closed state that trip the breaker. */
+    readonly failureThreshold: number;
+    /** Backoff for the first opening; doubles on each reopening, capped below. */
+    readonly baseOpenMs: number;
+    /** Upper bound for the backoff window. */
+    readonly maxBackoffMs: number;
+    /**
+     * How long a half-open probe may stay unreported before assessment treats
+     * it as lost. Generous by design: a probe episode is a real work unit and
+     * may run for minutes; the deadline only exists so a probe whose terminal
+     * event never arrives cannot wedge the resource in half_open forever.
+     */
+    readonly probeTimeoutMs: number;
+}
+export declare const DEFAULT_BREAKER_CONFIG: BreakerConfig;
+export declare const BREAKER_EXEMPT_CATEGORIES: readonly FailureCategory[];
+/**
+ * Persistent breaker record for one resource. `openCount` drives the doubling
+ * backoff and resets only when the breaker closes (a probe or an observed
+ * success). Rate limiting, quota exhaustion and user cancellation are
+ * deliberately exempt from breaker counting: the first two own their own
+ * windowed resource states (counting them would double-punish a resource
+ * already known to need a cooldown), and a user-interrupted probe says
+ * nothing about resource health, so an interrupted probe re-arms the same
+ * window rather than doubling it. `probeId` identifies the single admitted
+ * probe while half-open so stale or forged probe reports can be rejected;
+ * `probeAt` records when it was admitted so a probe whose outcome report is
+ * lost can expire instead of wedging the resource half-open forever.
+ */
+export interface BreakerRecord {
+    readonly state: BreakerState;
+    readonly failures: number;
+    readonly openCount: number;
+    readonly reopenAt?: number | undefined;
+    readonly probeId?: string | undefined;
+    readonly probeAt?: number | undefined;
+}

package/dist/health/circuit-breaker/types.js

@@ -0,0 +1,13 @@
+export const BREAKER_STATES = ["closed", "open", "half_open"];
+export const DEFAULT_BREAKER_CONFIG = {
+    failureThreshold: 5,
+    baseOpenMs: 30_000,
+    maxBackoffMs: 1_800_000,
+    probeTimeoutMs: 600_000,
+};
+export const BREAKER_EXEMPT_CATEGORIES = [
+    "rate_limited",
+    "quota_exhausted",
+    "user_cancelled",
+];
+//# sourceMappingURL=types.js.map

package/dist/health/circuit-breaker/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/health/circuit-breaker/types.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAsC,CAAA;AAoBlG,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACnD,gBAAgB,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM;IAClB,YAAY,EAAE,SAAS;IACvB,cAAc,EAAE,OAAO;CACxB,CAAA;AAED,MAAM,CAAC,MAAM,yBAAyB,GAA+B;IACnE,cAAc;IACd,iBAAiB;IACjB,gBAAgB;CACjB,CAAA","sourcesContent":["/**\n * Circuit breaker types (ADP-019).\n *\n * The breaker is the quarantine mechanism for transient infrastructure\n * failures (outage, overload, timeout): repeated failures open the resource\n * for a backoff window, after which exactly one probe request is admitted\n * (half-open state). Rate limiting and quota exhaustion are deliberately\n * exempt from breaker counting because they already have their own windowed\n * resource states; counting them here would double-punish a resource that is\n * already known to need a cooldown.\n */\nimport type { FailureCategory } from \"../classifier/types.js\"\n\nexport const BREAKER_STATES = [\"closed\", \"open\", \"half_open\"] as const satisfies readonly string[]\n\nexport type BreakerState = (typeof BREAKER_STATES)[number]\n\nexport interface BreakerConfig {\n  /** Consecutive countable failures in the closed state that trip the breaker. */\n  readonly failureThreshold: number\n  /** Backoff for the first opening; doubles on each reopening, capped below. */\n  readonly baseOpenMs: number\n  /** Upper bound for the backoff window. */\n  readonly maxBackoffMs: number\n  /**\n   * How long a half-open probe may stay unreported before assessment treats\n   * it as lost. Generous by design: a probe episode is a real work unit and\n   * may run for minutes; the deadline only exists so a probe whose terminal\n   * event never arrives cannot wedge the resource in half_open forever.\n   */\n  readonly probeTimeoutMs: number\n}\n\nexport const DEFAULT_BREAKER_CONFIG: BreakerConfig = {\n  failureThreshold: 5,\n  baseOpenMs: 30_000,\n  maxBackoffMs: 1_800_000,\n  probeTimeoutMs: 600_000,\n}\n\nexport const BREAKER_EXEMPT_CATEGORIES: readonly FailureCategory[] = [\n  \"rate_limited\",\n  \"quota_exhausted\",\n  \"user_cancelled\",\n]\n\n/**\n * Persistent breaker record for one resource. `openCount` drives the doubling\n * backoff and resets only when the breaker closes (a probe or an observed\n * success). Rate limiting, quota exhaustion and user cancellation are\n * deliberately exempt from breaker counting: the first two own their own\n * windowed resource states (counting them would double-punish a resource\n * already known to need a cooldown), and a user-interrupted probe says\n * nothing about resource health, so an interrupted probe re-arms the same\n * window rather than doubling it. `probeId` identifies the single admitted\n * probe while half-open so stale or forged probe reports can be rejected;\n * `probeAt` records when it was admitted so a probe whose outcome report is\n * lost can expire instead of wedging the resource half-open forever.\n */\nexport interface BreakerRecord {\n  readonly state: BreakerState\n  readonly failures: number\n  readonly openCount: number\n  readonly reopenAt?: number | undefined\n  readonly probeId?: string | undefined\n  readonly probeAt?: number | undefined\n}\n"]}

package/dist/health/classifier/classify.d.ts

@@ -0,0 +1,8 @@
+import type { ErrorEvidence, FailureClassification } from "./types.js";
+/**
+ * Total classification of layered failure evidence. Never throws and always
+ * returns a category: any evidence shape outside the documented vocabularies
+ * classifies as `unknown` via the `none` layer, deferring to OpenCode's
+ * native failure handling (ADP-009, ADP-012).
+ */
+export declare function classifyFailure(evidence: ErrorEvidence): FailureClassification;