@coool/opencode-adaptive 0.0.0-stage → 1.0.0

package/dist/health/resource-health/registry.js

@@ -0,0 +1,258 @@
+/**
+ * Resource health registry (ADP-007, ADP-019, ADP-021).
+ *
+ * Stateful façade over the pure transition layer: one record per resource
+ * key, an injected clock, and assessment that composes the record's chain of
+ * ancestor scopes. Time only advances through the injected clock — there are
+ * no timers; windows and breaker backoffs are evaluated (swept) lazily on
+ * every observation, assessment, and snapshot.
+ *
+ * The single-probe guarantee (ADP-019) lives here: `assess` synchronously
+ * flips a due open breaker to half-open and issues the probe ticket, so
+ * concurrent assessors can never observe two admissions.
+ */
+import { admitProbe, breakerBlockWait, expireProbe, recordProbeFailure, recordProbeSuccess, } from "../circuit-breaker/breaker.js";
+import { resourceChain, resourceKeyID } from "./key.js";
+import { applyHealthEvent, initialRecord, sweepRecord } from "./transitions.js";
+import { DEFAULT_HEALTH_CONFIG, } from "./types.js";
+/**
+ * Severity of the three hard resource states. Used only to choose which
+ * blocker a report names when several scopes in a chain are blocked at once;
+ * every candidate still blocks regardless of which wins the report.
+ */
+const HARD_BLOCK_SEVERITY = {
+    unavailable: 3,
+    "quota-exhausted": 2,
+    "rate-limited": 1,
+};
+function blocked(reason, key, retryAtMs) {
+    if (retryAtMs === undefined) {
+        return { kind: "blocked", reason, key };
+    }
+    return { kind: "blocked", reason, key, retryAtMs };
+}
+function hardBlocker(record, now) {
+    const retryAtMs = record.window === undefined ? undefined : record.window.until - now;
+    switch (record.health) {
+        case "unavailable":
+            return {
+                reason: "unavailable",
+                key: record.key,
+                retryAtMs: undefined,
+                severity: HARD_BLOCK_SEVERITY.unavailable,
+            };
+        case "quota_exhausted":
+            return {
+                reason: "quota-exhausted",
+                key: record.key,
+                retryAtMs,
+                severity: HARD_BLOCK_SEVERITY["quota-exhausted"],
+            };
+        case "rate_limited":
+            return {
+                reason: "rate-limited",
+                key: record.key,
+                retryAtMs,
+                severity: HARD_BLOCK_SEVERITY["rate-limited"],
+            };
+        default:
+            return undefined;
+    }
+}
+/** Most severe hard block across a chain; narrowest scope wins ties. */
+function hardest(records, now) {
+    let hard;
+    for (const record of records) {
+        if (record === undefined) {
+            continue;
+        }
+        const candidate = hardBlocker(record, now);
+        if (candidate === undefined) {
+            continue;
+        }
+        if (hard === undefined || candidate.severity >= hard.severity) {
+            hard = candidate;
+        }
+    }
+    return hard;
+}
+export class ResourceHealthRegistry {
+    #records = new Map();
+    #clock;
+    #config;
+    #probeCounter = 0;
+    constructor(clock, config = DEFAULT_HEALTH_CONFIG) {
+        this.#clock = clock;
+        this.#config = config;
+    }
+    /**
+     * Seeds the registry from persisted records (restart / cross-instance
+     * reload). Records are swept against the current clock and inserted
+     * without persisting — hydration must not write back what it just read.
+     * A hydrated half_open record cannot keep its probe (the ticket lived in
+     * the previous instance's memory), so it re-opens due immediately — its
+     * backoff window had already elapsed when it went half-open, and the next
+     * assessment admits exactly one probe as usual.
+     */
+    hydrate(records) {
+        const now = this.#clock();
+        for (const record of records) {
+            const swept = sweepRecord(record, now);
+            const breaker = swept.breaker.state === "half_open"
+                ? {
+                    state: "open",
+                    failures: swept.breaker.failures,
+                    openCount: swept.breaker.openCount,
+                    reopenAt: now,
+                }
+                : swept.breaker;
+            this.#records.set(resourceKeyID(swept.key), { ...swept, breaker, updatedAt: now });
+        }
+    }
+    observe(event) {
+        const now = this.#clock();
+        const id = resourceKeyID(event.key);
+        const existing = this.#records.get(id);
+        const swept = existing === undefined ? initialRecord(event.key, now) : sweepRecord(existing, now);
+        const updated = applyHealthEvent(swept, event, now, this.#config);
+        this.#records.set(id, updated);
+        return updated;
+    }
+    #sweptRecord(key, now) {
+        const id = resourceKeyID(key);
+        const record = this.#records.get(id);
+        if (record === undefined) {
+            return undefined;
+        }
+        const swept = sweepRecord(record, now);
+        if (swept !== record) {
+            this.#records.set(id, swept);
+        }
+        return swept;
+    }
+    /**
+     * Assesses whether the resource may take new work right now, composing the
+     * full ancestor chain. Precedence: the most severe hard resource state
+     * wins (narrowest scope on ties), then the breaker scan (widest scope
+     * first — a due wide breaker is probed before a narrow one), then draining,
+     * then available.
+     */
+    assess(key) {
+        const now = this.#clock();
+        const records = resourceChain(key).map((chainKey) => this.#sweptRecord(chainKey, now));
+        const hard = hardest(records, now);
+        if (hard !== undefined) {
+            return blocked(hard.reason, hard.key, hard.retryAtMs);
+        }
+        for (const record of records) {
+            if (record === undefined) {
+                continue;
+            }
+            // A probe whose outcome report never arrived must not wedge the
+            // resource in half_open: expire it (same backoff window, no doubling)
+            // before attempting admission.
+            const expired = expireProbe(record.breaker, now, this.#config.breaker);
+            const current = expired === record.breaker ? record : { ...record, breaker: expired, updatedAt: now };
+            if (current !== record) {
+                this.#records.set(resourceKeyID(record.key), current);
+            }
+            const admission = admitProbe(current.breaker, now);
+            if (admission.kind === "closed") {
+                continue;
+            }
+            if (admission.kind === "waiting") {
+                return blocked("breaker-open", record.key, admission.retryAtMs);
+            }
+            if (admission.kind === "in-flight") {
+                return blocked("probe-in-flight", record.key, undefined);
+            }
+            const probeId = String(++this.#probeCounter);
+            this.#records.set(resourceKeyID(record.key), {
+                ...record,
+                breaker: { ...admission.record, probeId, probeAt: now },
+                updatedAt: now,
+            });
+            return { kind: "probe", ticket: { id: probeId, key: record.key } };
+        }
+        // Draining is the softest blocker; report the narrowest draining scope.
+        let draining;
+        for (const record of records) {
+            if (record?.health === "draining") {
+                draining = record;
+            }
+        }
+        if (draining !== undefined) {
+            return blocked("draining", draining.key, undefined);
+        }
+        return { kind: "available" };
+    }
+    /**
+     * Non-mutating assessment for decisions that must not admit a probe
+     * (escalation-target gating): identical hard-state and draining walk, but
+     * an open or half-open breaker blocks without being flipped or ticketed.
+     */
+    evaluate(key) {
+        const now = this.#clock();
+        const records = resourceChain(key).map((chainKey) => this.#sweptRecord(chainKey, now));
+        const hard = hardest(records, now);
+        if (hard !== undefined) {
+            return blocked(hard.reason, hard.key, hard.retryAtMs);
+        }
+        for (const record of records) {
+            if (record === undefined)
+                continue;
+            // Observer view (non-mutating): an open breaker blocks even when its
+            // backoff elapsed — assess is what flips it to half_open and issues
+            // the probe ticket.
+            const wait = breakerBlockWait(record.breaker, now);
+            if (wait !== undefined) {
+                return blocked("breaker-open", record.key, wait);
+            }
+            if (record.breaker.state === "half_open") {
+                return blocked("probe-in-flight", record.key, undefined);
+            }
+        }
+        let draining;
+        for (const record of records) {
+            if (record?.health === "draining") {
+                draining = record;
+            }
+        }
+        if (draining !== undefined) {
+            return blocked("draining", draining.key, undefined);
+        }
+        return { kind: "available" };
+    }
+    /**
+     * Reports the outcome of an admitted probe. Only the ticket issued for the
+     * current half-open record is honored; stale tickets (probe already
+     * resolved, record reset, or unknown key) are rejected.
+     */
+    reportProbe(ticket, outcome) {
+        const now = this.#clock();
+        const id = resourceKeyID(ticket.key);
+        const record = this.#records.get(id);
+        if (record === undefined) {
+            return false;
+        }
+        const breaker = record.breaker;
+        if (breaker.state !== "half_open" || breaker.probeId !== ticket.id) {
+            return false;
+        }
+        const next = outcome.success
+            ? recordProbeSuccess(breaker)
+            : recordProbeFailure(breaker, outcome.category, now, this.#config.breaker);
+        this.#records.set(id, { ...record, breaker: next, updatedAt: now });
+        return true;
+    }
+    /** Current (swept) record for one key, if the registry tracks it. */
+    recordFor(key) {
+        return this.#sweptRecord(key, this.#clock());
+    }
+    /** All tracked records, swept against the clock. */
+    snapshot() {
+        const now = this.#clock();
+        return [...this.#records.values()].map((record) => sweepRecord(record, now));
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/health/resource-health/registry.js.map

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

package/dist/health/resource-health/transitions.d.ts

@@ -0,0 +1,11 @@
+import type { HealthEvent, ResourceHealthConfig, ResourceKey, ResourceRecord } from "./types.js";
+export declare function initialRecord(key: ResourceKey, now: number): ResourceRecord;
+/**
+ * Elapses time-bounded windows: once a window's `until` passes, the windowed
+ * state (rate limited, quota exhausted with a known reset) lifts back to
+ * healthy. Records without a window, or with one still in the future, pass
+ * through unchanged.
+ */
+export declare function sweepRecord(record: ResourceRecord, now: number): ResourceRecord;
+export declare function applyHealthEvent(record: ResourceRecord, event: HealthEvent, now: number, config: ResourceHealthConfig): ResourceRecord;
+//# sourceMappingURL=transitions.d.ts.map

package/dist/health/resource-health/transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.d.ts","sourceRoot":"","sources":["../../../src/health/resource-health/transitions.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhG,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAM/E;AAoFD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,oBAAoB,GAC3B,cAAc,CAgDhB"}

package/dist/health/resource-health/transitions.js

@@ -0,0 +1,165 @@
+/**
+ * Pure resource health transitions (ADP-007, ADP-012, ADP-019, ADP-021).
+ *
+ * `applyHealthEvent` is the single authority for how evidence changes a
+ * resource record: total, synchronous, and clock-free (`now` is injected).
+ *
+ * Policy notes:
+ * - Rate limiting and quota exhaustion set their own windowed states;
+ *   a windowed state is never downgraded by weaker evidence (a 429 while
+ *   quota-exhausted does not erase the quota signal).
+ * - Outage, overload, and timeout count toward the circuit breaker and mark
+ *   the resource degraded. They never hard-quarantine on their own: a single
+ *   definitive outage signal can be a blip, so the breaker owns transient
+ *   failure quarantine with backoff windows and probe recovery.
+ * - Definitive configuration failures (auth, invalid model) hard-quarantine
+ *   the resource: the evidence proves the resource cannot work. Non-definitive
+ *   evidence of the same categories (the textual last resort, ADP-008) is
+ *   transient and breaker-owned instead — one fuzzy substring in an error
+ *   body must never permanently blacklist a resource with no recovery path
+ *   (ADP-012).
+ * - The `definitive` flag otherwise guides scheduling deference, not health:
+ *   both definitive and non-definitive infra failures leave the resource
+ *   degraded.
+ * - Ambiguous or request-level failures (context overflow, content policy,
+ *   user cancellation, unknown) never change health: they say nothing about
+ *   the resource.
+ * - Draining is a policy request (ADP-021), not degraded health: it applies
+ *   on top of healthy/degraded and never masks a harder state.
+ */
+import { recordBreakerFailure, recordBreakerSuccess, initialBreaker, } from "../circuit-breaker/breaker.js";
+import { resourceScope } from "./key.js";
+export function initialRecord(key, now) {
+    return { key, health: "healthy", breaker: initialBreaker(), updatedAt: now };
+}
+/**
+ * Elapses time-bounded windows: once a window's `until` passes, the windowed
+ * state (rate limited, quota exhausted with a known reset) lifts back to
+ * healthy. Records without a window, or with one still in the future, pass
+ * through unchanged.
+ */
+export function sweepRecord(record, now) {
+    const window = record.window;
+    if (window === undefined || now < window.until) {
+        return record;
+    }
+    return { key: record.key, health: "healthy", breaker: record.breaker, updatedAt: now };
+}
+function touched(record, now) {
+    return { ...record, updatedAt: now };
+}
+/**
+ * Defensive re-validation of a parsed retry delay: the classifier already
+ * rejects malformed values, but the health layer never trusts a negative or
+ * fractional delay to compute a window.
+ */
+function validRetryAfterMs(value) {
+    return value !== undefined && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+function failureEvent(record, event, now, config) {
+    switch (event.category) {
+        case "rate_limited": {
+            if (record.health === "quota_exhausted" || record.health === "unavailable") {
+                return touched(record, now);
+            }
+            const retryAfterMs = validRetryAfterMs(event.retryAfterMs);
+            const until = now + (retryAfterMs ?? config.defaultRateLimitWindowMs);
+            return {
+                ...record,
+                health: "rate_limited",
+                window: { kind: "rate-limit", until },
+                updatedAt: now,
+            };
+        }
+        case "quota_exhausted": {
+            if (record.health === "unavailable") {
+                return touched(record, now);
+            }
+            const retryAfterMs = validRetryAfterMs(event.retryAfterMs);
+            return {
+                ...record,
+                health: "quota_exhausted",
+                window: retryAfterMs === undefined ? undefined : { kind: "quota", until: now + retryAfterMs },
+                updatedAt: now,
+            };
+        }
+        case "outage":
+        case "overload":
+        case "timeout": {
+            const breaker = recordBreakerFailure(record.breaker, event.category, now, config.breaker);
+            const health = record.health === "healthy" || record.health === "draining" ? "degraded" : record.health;
+            return { ...record, health, breaker: breaker.record, updatedAt: now };
+        }
+        case "auth_failure":
+        case "invalid_model": {
+            // An invalid model says nothing about the provider or account; only
+            // model-scoped and variant-scoped keys may be quarantined by it.
+            if (event.category === "invalid_model") {
+                const scope = resourceScope(record.key);
+                if (scope !== "model" && scope !== "variant") {
+                    return touched(record, now);
+                }
+            }
+            if (!event.definitive) {
+                // Non-definitive evidence (bounded-textual last resort) is not proof
+                // the resource cannot work: quarantine through the breaker's bounded
+                // failure counting instead of a windowless, unrecoverable state.
+                const breaker = recordBreakerFailure(record.breaker, event.category, now, config.breaker);
+                const health = record.health === "healthy" || record.health === "draining" ? "degraded" : record.health;
+                return { ...record, health, breaker: breaker.record, updatedAt: now };
+            }
+            return { ...record, health: "unavailable", updatedAt: now };
+        }
+        default:
+            // context_overflow, content_policy, user_cancelled, unknown:
+            // request-level evidence, not resource health.
+            return touched(record, now);
+    }
+}
+export function applyHealthEvent(record, event, now, config) {
+    switch (event.kind) {
+        case "failure":
+            return failureEvent(record, event, now, config);
+        case "success": {
+            const breaker = recordBreakerSuccess();
+            const health = record.health === "draining" || record.health === "quota_exhausted"
+                ? record.health
+                : "healthy";
+            return {
+                ...record,
+                health,
+                breaker,
+                window: health === record.health ? record.window : undefined,
+                updatedAt: now,
+            };
+        }
+        case "drain": {
+            const health = record.health === "healthy" || record.health === "degraded" ? "draining" : record.health;
+            return { ...record, health, updatedAt: now };
+        }
+        case "capacity": {
+            if (event.exhausted) {
+                if (record.health === "unavailable") {
+                    return touched(record, now);
+                }
+                const retryAfterMs = validRetryAfterMs(event.retryAfterMs);
+                return {
+                    ...record,
+                    health: "quota_exhausted",
+                    window: retryAfterMs === undefined ? undefined : { kind: "quota", until: now + retryAfterMs },
+                    updatedAt: now,
+                };
+            }
+            const health = record.health === "quota_exhausted" ? "healthy" : record.health;
+            return {
+                ...record,
+                health,
+                window: health === record.health ? record.window : undefined,
+                updatedAt: now,
+            };
+        }
+        case "reset":
+            return { key: record.key, health: "healthy", breaker: initialBreaker(), updatedAt: now };
+    }
+}
+//# sourceMappingURL=transitions.js.map

package/dist/health/resource-health/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../../../src/health/resource-health/transitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,GACf,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAGxC,MAAM,UAAU,aAAa,CAAC,GAAgB,EAAE,GAAW;IACzD,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAsB,EAAE,GAAW;IAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;IAC5B,IAAI,MAAM,KAAK,SAAS,IAAI,GAAG,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;QAC/C,OAAO,MAAM,CAAA;IACf,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;AACxF,CAAC;AAED,SAAS,OAAO,CAAC,MAAsB,EAAE,GAAW;IAClD,OAAO,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;AACtC,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,KAAyB;IAClD,OAAO,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACzF,CAAC;AAED,SAAS,YAAY,CACnB,MAAsB,EACtB,KAAgD,EAChD,GAAW,EACX,MAA4B;IAE5B,QAAQ,KAAK,CAAC,QAAQ,EAAE,CAAC;QACvB,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,IAAI,MAAM,CAAC,MAAM,KAAK,iBAAiB,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;gBAC3E,OAAO,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;YAC7B,CAAC;YACD,MAAM,YAAY,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;YAC1D,MAAM,KAAK,GAAG,GAAG,GAAG,CAAC,YAAY,IAAI,MAAM,CAAC,wBAAwB,CAAC,CAAA;YACrE,OAAO;gBACL,GAAG,MAAM;gBACT,MAAM,EAAE,cAAc;gBACtB,MAAM,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE;gBACrC,SAAS,EAAE,GAAG;aACf,CAAA;QACH,CAAC;QACD,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;gBACpC,OAAO,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;YAC7B,CAAC;YACD,MAAM,YAAY,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;YAC1D,OAAO;gBACL,GAAG,MAAM;gBACT,MAAM,EAAE,iBAAiB;gBACzB,MAAM,EACJ,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,YAAY,EAAE;gBACvF,SAAS,EAAE,GAAG;aACf,CAAA;QACH,CAAC;QACD,KAAK,QAAQ,CAAC;QACd,KAAK,UAAU,CAAC;QAChB,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,OAAO,GAAG,oBAAoB,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;YACzF,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAA;YAC1F,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;QACvE,CAAC;QACD,KAAK,cAAc,CAAC;QACpB,KAAK,eAAe,CAAC,CAAC,CAAC;YACrB,oEAAoE;YACpE,iEAAiE;YACjE,IAAI,KAAK,CAAC,QAAQ,KAAK,eAAe,EAAE,CAAC;gBACvC,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBACvC,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBAC7C,OAAO,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;gBAC7B,CAAC;YACH,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;gBACtB,qEAAqE;gBACrE,qEAAqE;gBACrE,iEAAiE;gBACjE,MAAM,OAAO,GAAG,oBAAoB,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;gBACzF,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAA;gBAC1F,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;YACvE,CAAC;YACD,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;QAC7D,CAAC;QACD;YACE,6DAA6D;YAC7D,+CAA+C;YAC/C,OAAO,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC/B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,MAAsB,EACtB,KAAkB,EAClB,GAAW,EACX,MAA4B;IAE5B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,SAAS;YACZ,OAAO,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;QACjD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,OAAO,GAAkB,oBAAoB,EAAE,CAAA;YACrD,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,KAAK,UAAU,IAAI,MAAM,CAAC,MAAM,KAAK,iBAAiB;gBACjE,CAAC,CAAC,MAAM,CAAC,MAAM;gBACf,CAAC,CAAC,SAAS,CAAA;YACf,OAAO;gBACL,GAAG,MAAM;gBACT,MAAM;gBACN,OAAO;gBACP,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;gBAC5D,SAAS,EAAE,GAAG;aACf,CAAA;QACH,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAA;YAC1F,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;QAC9C,CAAC;QACD,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBACpB,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;oBACpC,OAAO,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;gBAC7B,CAAC;gBACD,MAAM,YAAY,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;gBAC1D,OAAO;oBACL,GAAG,MAAM;oBACT,MAAM,EAAE,iBAAiB;oBACzB,MAAM,EACJ,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,YAAY,EAAE;oBACvF,SAAS,EAAE,GAAG;iBACf,CAAA;YACH,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,KAAK,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAA;YAC9E,OAAO;gBACL,GAAG,MAAM;gBACT,MAAM;gBACN,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;gBAC5D,SAAS,EAAE,GAAG;aACf,CAAA;QACH,CAAC;QACD,KAAK,OAAO;YACV,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;IAC5F,CAAC;AACH,CAAC"}

package/dist/health/resource-health/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Resource health types (ADP-007, ADP-012, ADP-021).
+ *
+ * A resource is identified at the narrowest scope the evidence supports:
+ * provider → account → model → variant. Health states are a closed set and
+ * every transition between them is defined by the pure transition layer; the
+ * registry never invents states. The circuit breaker (ADP-019) is an
+ * orthogonal axis stored per resource record.
+ */
+import { type BreakerConfig, type BreakerRecord } from "../circuit-breaker/types.js";
+import type { FailureCategory } from "../classifier/types.js";
+export declare const RESOURCE_SCOPES: readonly ["provider", "account", "model", "variant"];
+export type ResourceScope = (typeof RESOURCE_SCOPES)[number];
+/**
+ * Hierarchical resource identity. The scope is derived from the most specific
+ * field present, so callers attribute evidence at exactly the level they can
+ * prove (e.g. a provider-wide outage without a model id stays at provider
+ * scope; a per-variant failure quarantines only that variant).
+ */
+export interface ResourceKey {
+    readonly providerID: string;
+    readonly accountID?: string | undefined;
+    readonly modelID?: string | undefined;
+    readonly variantID?: string | undefined;
+}
+export declare const HEALTH_STATES: readonly ["healthy", "draining", "degraded", "rate_limited", "quota_exhausted", "unavailable"];
+export type HealthState = (typeof HEALTH_STATES)[number];
+/**
+ * A time-bounded window during which the current state is known to hold
+ * (e.g. until a Retry-After delay or a quota reset elapses). Absent when no
+ * reset time is known — recovery then relies on probes, observed successes,
+ * or explicit resets.
+ */
+export interface ResourceWindow {
+    readonly kind: "rate-limit" | "quota";
+    readonly until: number;
+}
+export interface ResourceRecord {
+    readonly key: ResourceKey;
+    readonly health: HealthState;
+    readonly breaker: BreakerRecord;
+    readonly window?: ResourceWindow | undefined;
+    readonly updatedAt: number;
+}
+/**
+ * Health evidence events. `failure` carries an already-classified category
+ * (from the error classifier, ADP-009) plus the classification's
+ * definitiveness and parsed retry delay. `capacity` carries a CapacitySensor
+ * reading (ADP-020) — `exhausted: false` is positive evidence of capacity.
+ * `reset` is the manual Control-mode recovery op.
+ */
+export type HealthEvent = {
+    readonly kind: "failure";
+    readonly key: ResourceKey;
+    readonly category: FailureCategory;
+    readonly definitive: boolean;
+    readonly retryAfterMs?: number | undefined;
+} | {
+    readonly kind: "success";
+    readonly key: ResourceKey;
+} | {
+    readonly kind: "drain";
+    readonly key: ResourceKey;
+} | {
+    readonly kind: "capacity";
+    readonly key: ResourceKey;
+    readonly exhausted: boolean;
+    readonly retryAfterMs?: number | undefined;
+} | {
+    readonly kind: "reset";
+    readonly key: ResourceKey;
+};
+export interface ResourceHealthConfig {
+    readonly breaker: BreakerConfig;
+    /** Window applied to rate-limited evidence that carries no Retry-After. */
+    readonly defaultRateLimitWindowMs: number;
+}
+export declare const DEFAULT_HEALTH_CONFIG: ResourceHealthConfig;
+/** Injected monotonic clock, milliseconds. */
+export type Clock = () => number;
+/**
+ * Why an assessment blocks new work. Ordered from hardest to softest fact:
+ * hard resource states (unavailable, quota, rate limit) are direct evidence;
+ * breaker reasons are inferred from failure counts; draining is a policy
+ * request, not a health fact.
+ */
+export declare const BLOCKED_REASONS: readonly ["unavailable", "quota-exhausted", "rate-limited", "breaker-open", "probe-in-flight", "draining"];
+export type BlockedReason = (typeof BLOCKED_REASONS)[number];
+/** Opaque single-probe admission token; validated on report. */
+export interface ProbeTicket {
+    readonly id: string;
+    readonly key: ResourceKey;
+}
+export type ProbeOutcome = {
+    readonly success: true;
+} | {
+    readonly success: false;
+    readonly category: FailureCategory;
+};
+/**
+ * Result of assessing whether a resource may take new work right now. The
+ * `blocked` variant reports the winning blocker's key (which may be a wider
+ * scope than the assessed key) and, when known, when the block can lift.
+ */
+export type Assessment = {
+    readonly kind: "available";
+} | {
+    readonly kind: "probe";
+    readonly ticket: ProbeTicket;
+} | {
+    readonly kind: "blocked";
+    readonly reason: BlockedReason;
+    readonly key: ResourceKey;
+    readonly retryAtMs?: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/health/resource-health/types.d.ts.map

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

package/dist/health/resource-health/types.js

@@ -0,0 +1,43 @@
+/**
+ * Resource health types (ADP-007, ADP-012, ADP-021).
+ *
+ * A resource is identified at the narrowest scope the evidence supports:
+ * provider → account → model → variant. Health states are a closed set and
+ * every transition between them is defined by the pure transition layer; the
+ * registry never invents states. The circuit breaker (ADP-019) is an
+ * orthogonal axis stored per resource record.
+ */
+import { DEFAULT_BREAKER_CONFIG, } from "../circuit-breaker/types.js";
+export const RESOURCE_SCOPES = [
+    "provider",
+    "account",
+    "model",
+    "variant",
+];
+export const HEALTH_STATES = [
+    "healthy",
+    "draining",
+    "degraded",
+    "rate_limited",
+    "quota_exhausted",
+    "unavailable",
+];
+export const DEFAULT_HEALTH_CONFIG = {
+    breaker: DEFAULT_BREAKER_CONFIG,
+    defaultRateLimitWindowMs: 30_000,
+};
+/**
+ * Why an assessment blocks new work. Ordered from hardest to softest fact:
+ * hard resource states (unavailable, quota, rate limit) are direct evidence;
+ * breaker reasons are inferred from failure counts; draining is a policy
+ * request, not a health fact.
+ */
+export const BLOCKED_REASONS = [
+    "unavailable",
+    "quota-exhausted",
+    "rate-limited",
+    "breaker-open",
+    "probe-in-flight",
+    "draining",
+];
+//# sourceMappingURL=types.js.map

package/dist/health/resource-health/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/health/resource-health/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,sBAAsB,GAGvB,MAAM,6BAA6B,CAAA;AAGpC,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,UAAU;IACV,SAAS;IACT,OAAO;IACP,SAAS;CAC2B,CAAA;AAiBtC,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,SAAS;IACT,UAAU;IACV,UAAU;IACV,cAAc;IACd,iBAAiB;IACjB,aAAa;CACuB,CAAA;AAsDtC,MAAM,CAAC,MAAM,qBAAqB,GAAyB;IACzD,OAAO,EAAE,sBAAsB;IAC/B,wBAAwB,EAAE,MAAM;CACjC,CAAA;AAKD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,aAAa;IACb,iBAAiB;IACjB,cAAc;IACd,cAAc;IACd,iBAAiB;IACjB,UAAU;CAC0B,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { Plugin } from "@opencode/plugin";
+export { PLUGIN_ID } from "./plugin-id.js";
+/**
+ * Plugin id as required by GOAL.md: must not collide with the `opencode.*`
+ * namespace and must stay stable across releases (referenced by settings
+ * storage keys and receipts).
+ */
+/**
+ * Entry point wired into OpenCode via `opencode.json(c)`. Setup glues the
+ * adapter touchpoints (session hooks, event subscription, storage) to the
+ * supervisor and returns a cleanup that disposes every registration.
+ * All supervision errors are fail-open (ADP-031): the supervisor's public
+ * entry points never throw; the event pump's stream errors are logged.
+ */
+declare const _default: Plugin.Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAezC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C;;;;GAIG;AAEH;;;;;;GAMG;;AACH,wBAyEE"}