@coool/opencode-adaptive 0.0.0-stage → 1.0.1

package/dist/health/classifier/classify.js

@@ -0,0 +1,245 @@
+/**
+ * Text fed to the textual last-resort layer is truncated to this bound before
+ * matching, so adversarial or enormous error bodies cannot dominate
+ * classification cost or smuggle patterns in late bytes (ADP-008).
+ */
+const TEXT_BOUND = 512;
+/**
+ * Retry/failover policy per category (ADP-010, ADP-011).
+ *
+ * - Infrastructure failures (rate limiting, quota, outage, overload, timeout)
+ *   are failover-eligible: horizontal recovery within the tier is exactly
+ *   their remedy.
+ * - Permanent configuration failures (auth, invalid model, content policy)
+ *   and context overflow never retry and never failover: retrying the same
+ *   request cannot help and switching resources would reproduce the failure.
+ * - User cancellation is final: no retry, no failover (ADP-010).
+ * - Unknown failures defer to OpenCode's native handling.
+ */
+const CATEGORY_POLICY = {
+    rate_limited: { retryable: true, failoverEligible: true },
+    quota_exhausted: { retryable: false, failoverEligible: true },
+    outage: { retryable: true, failoverEligible: true },
+    overload: { retryable: true, failoverEligible: true },
+    timeout: { retryable: true, failoverEligible: true },
+    auth_failure: { retryable: false, failoverEligible: false },
+    invalid_model: { retryable: false, failoverEligible: false },
+    context_overflow: { retryable: false, failoverEligible: false },
+    content_policy: { retryable: false, failoverEligible: false },
+    user_cancelled: { retryable: false, failoverEligible: false },
+    unknown: { retryable: false, failoverEligible: false },
+};
+/**
+ * Error tags from the documented @opencode/protocol vocabulary that map
+ * directly to a failure category. Tags absent here (`ProviderRequestError`,
+ * `UnknownError`, anything unrecognized) are structured but not
+ * category-specific: they never guess, and classification falls through to
+ * the refining layers.
+ */
+const STRUCTURED_TYPES = new Map([
+    ["UnauthorizedError", "auth_failure"],
+    ["ForbiddenError", "auth_failure"],
+    ["ModelNotFoundError", "invalid_model"],
+    ["UnsupportedModelError", "invalid_model"],
+    ["ServiceUnavailableError", "outage"],
+]);
+/**
+ * Bounded textual patterns, last resort only (ADP-008). Ordered most
+ * specific first; the first match wins. These encode provider error-message
+ * conventions documented by the research phase, not a general-purpose
+ * keyword classifier.
+ */
+const TEXTUAL_PATTERNS = [
+    {
+        category: "context_overflow",
+        pattern: /context (length|window)|maximum context|input length exceeds|prompt is too long|too many (input )?tokens|exceeds the maximum/i,
+    },
+    { category: "quota_exhausted", pattern: /\bquota\b|credit balance/i },
+    { category: "rate_limited", pattern: /rate ?limit/i },
+    { category: "timeout", pattern: /\btimeout\b|timed? ?out|deadline exceeded|etimedout/i },
+    {
+        category: "auth_failure",
+        pattern: /unauthorized|invalid (api|access) key|api key (expired|invalid)|authentication|permission denied/i,
+    },
+    {
+        category: "invalid_model",
+        pattern: /model.{0,30}(does not exist|not found)|invalid model|unknown model|no such model/i,
+    },
+    {
+        category: "content_policy",
+        pattern: /content (management )?(policy|filter)|safety system|violates?.{0,32}policy|flagged as/i,
+    },
+    { category: "overload", pattern: /overloaded|over capacity|high demand/i },
+    { category: "user_cancelled", pattern: /cancel+(l)?ed|aborted by (the )?user|user abort/i },
+];
+function isHttpStatus(status) {
+    return typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599;
+}
+/**
+ * Upper bound on a provider-claimed retry delay. `Retry-After` and structured
+ * retry metadata are untrusted provider data: a hostile or misconfigured
+ * value ("999999999" seconds) must not convert one response into a
+ * near-permanent resource blacklist. The host's own retry scheduling waits
+ * out the raw header verbatim — this bound only concerns the health window
+ * the supervisor derives from the classification (ADP-011 boundedness).
+ */
+const MAX_RETRY_AFTER_MS = 24 * 60 * 60 * 1000;
+function boundedRetryAfterMs(retryAfterMs) {
+    if (retryAfterMs === undefined) {
+        return undefined;
+    }
+    return Math.min(retryAfterMs, MAX_RETRY_AFTER_MS);
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function lowercasedHeaders(headers) {
+    const lowered = new Map();
+    if (headers === undefined) {
+        return lowered;
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        lowered.set(name.toLowerCase(), value);
+    }
+    return lowered;
+}
+/**
+ * Parses a `Retry-After` header into milliseconds. Only the integer-seconds
+ * form is accepted: the HTTP-date form requires a clock, which the classifier
+ * deliberately does not have (reset-time handling belongs to the capacity
+ * boundary, T-05/T-15).
+ */
+function retryAfterHeaderMs(headers) {
+    const raw = headers.get("retry-after");
+    if (raw === undefined || !/^\d+$/.test(raw)) {
+        return undefined;
+    }
+    return Number(raw) * 1000;
+}
+/**
+ * Standard rate-limit headers (case-insensitive `x-ratelimit-remaining*`).
+ * All-zero remaining capacity indicates a fixed-window quota exhaustion
+ * rather than a short burst limit.
+ */
+function fixedWindowExhausted(headers) {
+    let sawRemaining = false;
+    for (const [name, value] of headers) {
+        if (name.startsWith("x-ratelimit-remaining")) {
+            sawRemaining = true;
+            if (value !== "0") {
+                return false;
+            }
+        }
+    }
+    return sawRemaining;
+}
+function retryAdvice(category, retryAfterMs) {
+    const policy = CATEGORY_POLICY[category];
+    const bounded = boundedRetryAfterMs(retryAfterMs);
+    if (bounded === undefined) {
+        return { retryable: policy.retryable };
+    }
+    return { retryable: policy.retryable, retryAfterMs: bounded };
+}
+function classification(category, layer, definitive, retryAfterMs) {
+    const policy = CATEGORY_POLICY[category];
+    return {
+        category,
+        layer,
+        definitive,
+        retry: retryAdvice(category, retryAfterMs),
+        failoverEligible: policy.failoverEligible,
+    };
+}
+/**
+ * Classifies an HTTP status. 429 consults the standard rate-limit headers in
+ * the same step: status plus documented standard headers are one HTTP
+ * semantics layer, and the quota refinement is more specific evidence than a
+ * bare 429, so it cannot weaken the ADP-008 precedence.
+ */
+function classifyStatus(status, headers) {
+    if (status === 429) {
+        return fixedWindowExhausted(headers) ? "quota_exhausted" : "rate_limited";
+    }
+    if (status === 401 || status === 403) {
+        return "auth_failure";
+    }
+    if (status === 408) {
+        return "timeout";
+    }
+    if (status === 413) {
+        return "context_overflow";
+    }
+    if (status === 502 || status === 503 || status === 504) {
+        return "outage";
+    }
+    return undefined;
+}
+function classifyText(text) {
+    const bounded = text.length > TEXT_BOUND ? text.slice(0, TEXT_BOUND) : text;
+    for (const { category, pattern } of TEXTUAL_PATTERNS) {
+        if (pattern.test(bounded)) {
+            return category;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 function classifyFailure(evidence) {
+    // Layer 0: interruption evidence. Interruptions are host decisions, not
+    // provider failures; a user cancellation is final (ADP-010).
+    if (evidence.interrupted === "user") {
+        return classification("user_cancelled", "interruption", true, undefined);
+    }
+    if (evidence.interrupted !== undefined) {
+        return classification("unknown", "interruption", true, undefined);
+    }
+    // Layer 1: structured OpenCode metadata.
+    const structured = evidence.structured;
+    const structuredRetryAfterMs = isNonNegativeInteger(structured?.retryAfterMs)
+        ? structured.retryAfterMs
+        : undefined;
+    if (structured !== undefined) {
+        const mapped = STRUCTURED_TYPES.get(structured.type);
+        if (mapped !== undefined) {
+            return classification(mapped, "structured", true, structuredRetryAfterMs);
+        }
+        // Unmapped tag: fall through so HTTP semantics can refine the category.
+    }
+    // Layer 2: HTTP status (+ standard headers for the 429 refinement).
+    const headers = lowercasedHeaders(evidence.headers);
+    if (isHttpStatus(evidence.status)) {
+        const category = classifyStatus(evidence.status, headers);
+        if (category !== undefined) {
+            return classification(category, "status", true, structuredRetryAfterMs ?? retryAfterHeaderMs(headers));
+        }
+    }
+    // Layer 3: standard headers alone (Retry-After without a decisive status).
+    const headerRetryAfterMs = retryAfterHeaderMs(headers);
+    if (headerRetryAfterMs !== undefined) {
+        return classification("rate_limited", "headers", false, headerRetryAfterMs);
+    }
+    // Layer 4: documented provider-specific metadata, normalized by our own
+    // adapters after validation (T-15).
+    if (evidence.providerMetadata?.quotaExhausted === true) {
+        return classification("quota_exhausted", "provider-metadata", true, undefined);
+    }
+    if (evidence.providerMetadata?.overloaded === true) {
+        return classification("overload", "provider-metadata", true, structuredRetryAfterMs);
+    }
+    // Layer 5: bounded textual classification, always non-definitive.
+    const text = evidence.text;
+    if (text !== undefined) {
+        const category = classifyText(text);
+        if (category !== undefined) {
+            return classification(category, "textual", false, structuredRetryAfterMs);
+        }
+    }
+    return classification("unknown", "none", false, undefined);
+}
+//# sourceMappingURL=classify.js.map

package/dist/health/classifier/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../../src/health/classifier/classify.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,GAAG,GAAG,CAAA;AAEtB;;;;;;;;;;;GAWG;AACH,MAAM,eAAe,GAEjB;IACF,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE;IACzD,eAAe,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE;IAC7D,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE;IACnD,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE;IACrD,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE;IACpD,YAAY,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE;IAC3D,aAAa,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE;IAC5D,gBAAgB,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE;IAC/D,cAAc,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE;IAC7D,cAAc,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE;IAC7D,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE;CACvD,CAAA;AAED;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAA0B;IACxD,CAAC,mBAAmB,EAAE,cAAc,CAAC;IACrC,CAAC,gBAAgB,EAAE,cAAc,CAAC;IAClC,CAAC,oBAAoB,EAAE,eAAe,CAAC;IACvC,CAAC,uBAAuB,EAAE,eAAe,CAAC;IAC1C,CAAC,yBAAyB,EAAE,QAAQ,CAAC;CACtC,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,gBAAgB,GAGhB;IACJ;QACE,QAAQ,EAAE,kBAAkB;QAC5B,OAAO,EACL,+HAA+H;KAClI;IACD,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,2BAA2B,EAAE;IACrE,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,EAAE;IACrD,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,sDAAsD,EAAE;IACxF;QACE,QAAQ,EAAE,cAAc;QACxB,OAAO,EACL,mGAAmG;KACtG;IACD;QACE,QAAQ,EAAE,eAAe;QACzB,OAAO,EAAE,mFAAmF;KAC7F;IACD;QACE,QAAQ,EAAE,gBAAgB;QAC1B,OAAO,EACL,wFAAwF;KAC3F;IACD,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,uCAAuC,EAAE;IAC1E,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,kDAAkD,EAAE;CAC5F,CAAA;AAED,SAAS,YAAY,CAAC,MAA0B;IAC9C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,IAAI,GAAG,CAAA;AACjG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAE9C,SAAS,mBAAmB,CAAC,YAAgC;IAC3D,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAA;AACnD,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAyB;IACrD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AAC3E,CAAC;AAED,SAAS,iBAAiB,CACxB,OAAqD;IAErD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;IACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAA;IACxC,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,OAAoC;IAC9D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;IACtC,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;AAC3B,CAAC;AAED;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,OAAoC;IAChE,IAAI,YAAY,GAAG,KAAK,CAAA;IACxB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,UAAU,CAAC,uBAAuB,CAAC,EAAE,CAAC;YAC7C,YAAY,GAAG,IAAI,CAAA;YACnB,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;gBAClB,OAAO,KAAK,CAAA;YACd,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,YAAY,CAAA;AACrB,CAAC;AAED,SAAS,WAAW,CAAC,QAAyB,EAAE,YAAgC;IAC9E,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;IACxC,MAAM,OAAO,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAA;IACjD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAA;IACxC,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,CAAA;AAC/D,CAAC;AAED,SAAS,cAAc,CACrB,QAAyB,EACzB,KAAqC,EACrC,UAAmB,EACnB,YAAgC;IAEhC,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;IACxC,OAAO;QACL,QAAQ;QACR,KAAK;QACL,UAAU;QACV,KAAK,EAAE,WAAW,CAAC,QAAQ,EAAE,YAAY,CAAC;QAC1C,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;KAC1C,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CACrB,MAAc,EACd,OAAoC;IAEpC,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,cAAc,CAAA;IAC3E,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACrC,OAAO,cAAc,CAAA;IACvB,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,kBAAkB,CAAA;IAC3B,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACvD,OAAO,QAAQ,CAAA;IACjB,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC3E,KAAK,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,gBAAgB,EAAE,CAAC;QACrD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1B,OAAO,QAAQ,CAAA;QACjB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,QAAuB;IACrD,wEAAwE;IACxE,6DAA6D;IAC7D,IAAI,QAAQ,CAAC,WAAW,KAAK,MAAM,EAAE,CAAC;QACpC,OAAO,cAAc,CAAC,gBAAgB,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;IAC1E,CAAC;IACD,IAAI,QAAQ,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO,cAAc,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;IACnE,CAAC;IAED,yCAAyC;IACzC,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAA;IACtC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC,UAAU,EAAE,YAAY,CAAC;QAC3E,CAAC,CAAC,UAAU,CAAC,YAAY;QACzB,CAAC,CAAC,SAAS,CAAA;IACb,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;QACpD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,sBAAsB,CAAC,CAAA;QAC3E,CAAC;QACD,wEAAwE;IAC1E,CAAC;IAED,oEAAoE;IACpE,MAAM,OAAO,GAAG,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IACnD,IAAI,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACzD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,cAAc,CACnB,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,sBAAsB,IAAI,kBAAkB,CAAC,OAAO,CAAC,CACtD,CAAA;QACH,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IACtD,IAAI,kBAAkB,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,cAAc,CAAC,cAAc,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAA;IAC7E,CAAC;IAED,wEAAwE;IACxE,oCAAoC;IACpC,IAAI,QAAQ,CAAC,gBAAgB,EAAE,cAAc,KAAK,IAAI,EAAE,CAAC;QACvD,OAAO,cAAc,CAAC,iBAAiB,EAAE,mBAAmB,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;IAChF,CAAC;IACD,IAAI,QAAQ,CAAC,gBAAgB,EAAE,UAAU,KAAK,IAAI,EAAE,CAAC;QACnD,OAAO,cAAc,CAAC,UAAU,EAAE,mBAAmB,EAAE,IAAI,EAAE,sBAAsB,CAAC,CAAA;IACtF,CAAC;IAED,kEAAkE;IAClE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAA;IAC1B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,sBAAsB,CAAC,CAAA;QAC3E,CAAC;IACH,CAAC;IAED,OAAO,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;AAC5D,CAAC","sourcesContent":["import type { ErrorEvidence, FailureCategory, FailureClassification, RetryAdvice } from \"./types.js\"\n\n/**\n * Text fed to the textual last-resort layer is truncated to this bound before\n * matching, so adversarial or enormous error bodies cannot dominate\n * classification cost or smuggle patterns in late bytes (ADP-008).\n */\nconst TEXT_BOUND = 512\n\n/**\n * Retry/failover policy per category (ADP-010, ADP-011).\n *\n * - Infrastructure failures (rate limiting, quota, outage, overload, timeout)\n *   are failover-eligible: horizontal recovery within the tier is exactly\n *   their remedy.\n * - Permanent configuration failures (auth, invalid model, content policy)\n *   and context overflow never retry and never failover: retrying the same\n *   request cannot help and switching resources would reproduce the failure.\n * - User cancellation is final: no retry, no failover (ADP-010).\n * - Unknown failures defer to OpenCode's native handling.\n */\nconst CATEGORY_POLICY: Readonly<\n  Record<FailureCategory, { retryable: boolean; failoverEligible: boolean }>\n> = {\n  rate_limited: { retryable: true, failoverEligible: true },\n  quota_exhausted: { retryable: false, failoverEligible: true },\n  outage: { retryable: true, failoverEligible: true },\n  overload: { retryable: true, failoverEligible: true },\n  timeout: { retryable: true, failoverEligible: true },\n  auth_failure: { retryable: false, failoverEligible: false },\n  invalid_model: { retryable: false, failoverEligible: false },\n  context_overflow: { retryable: false, failoverEligible: false },\n  content_policy: { retryable: false, failoverEligible: false },\n  user_cancelled: { retryable: false, failoverEligible: false },\n  unknown: { retryable: false, failoverEligible: false },\n}\n\n/**\n * Error tags from the documented @opencode/protocol vocabulary that map\n * directly to a failure category. Tags absent here (`ProviderRequestError`,\n * `UnknownError`, anything unrecognized) are structured but not\n * category-specific: they never guess, and classification falls through to\n * the refining layers.\n */\nconst STRUCTURED_TYPES = new Map<string, FailureCategory>([\n  [\"UnauthorizedError\", \"auth_failure\"],\n  [\"ForbiddenError\", \"auth_failure\"],\n  [\"ModelNotFoundError\", \"invalid_model\"],\n  [\"UnsupportedModelError\", \"invalid_model\"],\n  [\"ServiceUnavailableError\", \"outage\"],\n])\n\n/**\n * Bounded textual patterns, last resort only (ADP-008). Ordered most\n * specific first; the first match wins. These encode provider error-message\n * conventions documented by the research phase, not a general-purpose\n * keyword classifier.\n */\nconst TEXTUAL_PATTERNS: readonly {\n  readonly category: FailureCategory\n  readonly pattern: RegExp\n}[] = [\n  {\n    category: \"context_overflow\",\n    pattern:\n      /context (length|window)|maximum context|input length exceeds|prompt is too long|too many (input )?tokens|exceeds the maximum/i,\n  },\n  { category: \"quota_exhausted\", pattern: /\\bquota\\b|credit balance/i },\n  { category: \"rate_limited\", pattern: /rate ?limit/i },\n  { category: \"timeout\", pattern: /\\btimeout\\b|timed? ?out|deadline exceeded|etimedout/i },\n  {\n    category: \"auth_failure\",\n    pattern:\n      /unauthorized|invalid (api|access) key|api key (expired|invalid)|authentication|permission denied/i,\n  },\n  {\n    category: \"invalid_model\",\n    pattern: /model.{0,30}(does not exist|not found)|invalid model|unknown model|no such model/i,\n  },\n  {\n    category: \"content_policy\",\n    pattern:\n      /content (management )?(policy|filter)|safety system|violates?.{0,32}policy|flagged as/i,\n  },\n  { category: \"overload\", pattern: /overloaded|over capacity|high demand/i },\n  { category: \"user_cancelled\", pattern: /cancel+(l)?ed|aborted by (the )?user|user abort/i },\n]\n\nfunction isHttpStatus(status: number | undefined): status is number {\n  return typeof status === \"number\" && Number.isInteger(status) && status >= 100 && status <= 599\n}\n\n/**\n * Upper bound on a provider-claimed retry delay. `Retry-After` and structured\n * retry metadata are untrusted provider data: a hostile or misconfigured\n * value (\"999999999\" seconds) must not convert one response into a\n * near-permanent resource blacklist. The host's own retry scheduling waits\n * out the raw header verbatim — this bound only concerns the health window\n * the supervisor derives from the classification (ADP-011 boundedness).\n */\nconst MAX_RETRY_AFTER_MS = 24 * 60 * 60 * 1000\n\nfunction boundedRetryAfterMs(retryAfterMs: number | undefined): number | undefined {\n  if (retryAfterMs === undefined) {\n    return undefined\n  }\n  return Math.min(retryAfterMs, MAX_RETRY_AFTER_MS)\n}\n\nfunction isNonNegativeInteger(value: number | undefined): value is number {\n  return typeof value === \"number\" && Number.isInteger(value) && value >= 0\n}\n\nfunction lowercasedHeaders(\n  headers: Readonly<Record<string, string>> | undefined,\n): ReadonlyMap<string, string> {\n  const lowered = new Map<string, string>()\n  if (headers === undefined) {\n    return lowered\n  }\n  for (const [name, value] of Object.entries(headers)) {\n    lowered.set(name.toLowerCase(), value)\n  }\n  return lowered\n}\n\n/**\n * Parses a `Retry-After` header into milliseconds. Only the integer-seconds\n * form is accepted: the HTTP-date form requires a clock, which the classifier\n * deliberately does not have (reset-time handling belongs to the capacity\n * boundary, T-05/T-15).\n */\nfunction retryAfterHeaderMs(headers: ReadonlyMap<string, string>): number | undefined {\n  const raw = headers.get(\"retry-after\")\n  if (raw === undefined || !/^\\d+$/.test(raw)) {\n    return undefined\n  }\n  return Number(raw) * 1000\n}\n\n/**\n * Standard rate-limit headers (case-insensitive `x-ratelimit-remaining*`).\n * All-zero remaining capacity indicates a fixed-window quota exhaustion\n * rather than a short burst limit.\n */\nfunction fixedWindowExhausted(headers: ReadonlyMap<string, string>): boolean {\n  let sawRemaining = false\n  for (const [name, value] of headers) {\n    if (name.startsWith(\"x-ratelimit-remaining\")) {\n      sawRemaining = true\n      if (value !== \"0\") {\n        return false\n      }\n    }\n  }\n  return sawRemaining\n}\n\nfunction retryAdvice(category: FailureCategory, retryAfterMs: number | undefined): RetryAdvice {\n  const policy = CATEGORY_POLICY[category]\n  const bounded = boundedRetryAfterMs(retryAfterMs)\n  if (bounded === undefined) {\n    return { retryable: policy.retryable }\n  }\n  return { retryable: policy.retryable, retryAfterMs: bounded }\n}\n\nfunction classification(\n  category: FailureCategory,\n  layer: FailureClassification[\"layer\"],\n  definitive: boolean,\n  retryAfterMs: number | undefined,\n): FailureClassification {\n  const policy = CATEGORY_POLICY[category]\n  return {\n    category,\n    layer,\n    definitive,\n    retry: retryAdvice(category, retryAfterMs),\n    failoverEligible: policy.failoverEligible,\n  }\n}\n\n/**\n * Classifies an HTTP status. 429 consults the standard rate-limit headers in\n * the same step: status plus documented standard headers are one HTTP\n * semantics layer, and the quota refinement is more specific evidence than a\n * bare 429, so it cannot weaken the ADP-008 precedence.\n */\nfunction classifyStatus(\n  status: number,\n  headers: ReadonlyMap<string, string>,\n): FailureCategory | undefined {\n  if (status === 429) {\n    return fixedWindowExhausted(headers) ? \"quota_exhausted\" : \"rate_limited\"\n  }\n  if (status === 401 || status === 403) {\n    return \"auth_failure\"\n  }\n  if (status === 408) {\n    return \"timeout\"\n  }\n  if (status === 413) {\n    return \"context_overflow\"\n  }\n  if (status === 502 || status === 503 || status === 504) {\n    return \"outage\"\n  }\n  return undefined\n}\n\nfunction classifyText(text: string): FailureCategory | undefined {\n  const bounded = text.length > TEXT_BOUND ? text.slice(0, TEXT_BOUND) : text\n  for (const { category, pattern } of TEXTUAL_PATTERNS) {\n    if (pattern.test(bounded)) {\n      return category\n    }\n  }\n  return undefined\n}\n\n/**\n * Total classification of layered failure evidence. Never throws and always\n * returns a category: any evidence shape outside the documented vocabularies\n * classifies as `unknown` via the `none` layer, deferring to OpenCode's\n * native failure handling (ADP-009, ADP-012).\n */\nexport function classifyFailure(evidence: ErrorEvidence): FailureClassification {\n  // Layer 0: interruption evidence. Interruptions are host decisions, not\n  // provider failures; a user cancellation is final (ADP-010).\n  if (evidence.interrupted === \"user\") {\n    return classification(\"user_cancelled\", \"interruption\", true, undefined)\n  }\n  if (evidence.interrupted !== undefined) {\n    return classification(\"unknown\", \"interruption\", true, undefined)\n  }\n\n  // Layer 1: structured OpenCode metadata.\n  const structured = evidence.structured\n  const structuredRetryAfterMs = isNonNegativeInteger(structured?.retryAfterMs)\n    ? structured.retryAfterMs\n    : undefined\n  if (structured !== undefined) {\n    const mapped = STRUCTURED_TYPES.get(structured.type)\n    if (mapped !== undefined) {\n      return classification(mapped, \"structured\", true, structuredRetryAfterMs)\n    }\n    // Unmapped tag: fall through so HTTP semantics can refine the category.\n  }\n\n  // Layer 2: HTTP status (+ standard headers for the 429 refinement).\n  const headers = lowercasedHeaders(evidence.headers)\n  if (isHttpStatus(evidence.status)) {\n    const category = classifyStatus(evidence.status, headers)\n    if (category !== undefined) {\n      return classification(\n        category,\n        \"status\",\n        true,\n        structuredRetryAfterMs ?? retryAfterHeaderMs(headers),\n      )\n    }\n  }\n\n  // Layer 3: standard headers alone (Retry-After without a decisive status).\n  const headerRetryAfterMs = retryAfterHeaderMs(headers)\n  if (headerRetryAfterMs !== undefined) {\n    return classification(\"rate_limited\", \"headers\", false, headerRetryAfterMs)\n  }\n\n  // Layer 4: documented provider-specific metadata, normalized by our own\n  // adapters after validation (T-15).\n  if (evidence.providerMetadata?.quotaExhausted === true) {\n    return classification(\"quota_exhausted\", \"provider-metadata\", true, undefined)\n  }\n  if (evidence.providerMetadata?.overloaded === true) {\n    return classification(\"overload\", \"provider-metadata\", true, structuredRetryAfterMs)\n  }\n\n  // Layer 5: bounded textual classification, always non-definitive.\n  const text = evidence.text\n  if (text !== undefined) {\n    const category = classifyText(text)\n    if (category !== undefined) {\n      return classification(category, \"textual\", false, structuredRetryAfterMs)\n    }\n  }\n\n  return classification(\"unknown\", \"none\", false, undefined)\n}\n"]}

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

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

package/dist/health/classifier/index.js

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

package/dist/health/classifier/index.js.map

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

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

@@ -0,0 +1,71 @@
+/**
+ * Failure classification types (ADP-008, ADP-009).
+ *
+ * The classifier consumes a layered evidence record assembled by the OpenCode
+ * adapter. Evidence layers exist so classification can honor the ADP-008
+ * precedence chain: structured metadata beats HTTP status beats standard
+ * headers beats documented provider-specific metadata beats bounded text.
+ */
+import type { InterruptReason } from "../../core/work-unit/interruption.js";
+export declare const FAILURE_CATEGORIES: readonly ["rate_limited", "quota_exhausted", "outage", "overload", "timeout", "auth_failure", "invalid_model", "context_overflow", "content_policy", "user_cancelled", "unknown"];
+export type FailureCategory = (typeof FAILURE_CATEGORIES)[number];
+/**
+ * Where the winning classification came from. Exposed so receipts can show
+ * why a decision was made and so tests can pin the precedence chain.
+ */
+export declare const EVIDENCE_LAYERS: readonly ["interruption", "structured", "status", "headers", "provider-metadata", "textual", "none"];
+export type EvidenceLayer = (typeof EVIDENCE_LAYERS)[number];
+/**
+ * Structured OpenCode evidence (`Session.StructuredError`): a server-assigned
+ * error tag plus, when the provider sent it, a retry delay OpenCode already
+ * parsed from `Retry-After`. `type` is a free-form string on the wire, so the
+ * classifier only interprets types from the documented @opencode/protocol
+ * vocabulary and falls through to lower layers for anything unmapped instead
+ * of guessing.
+ */
+export interface StructuredSignal {
+    readonly type: string;
+    readonly retryAfterMs?: number | undefined;
+}
+/**
+ * Documented provider-specific metadata, already normalized by our own
+ * adapters (e.g. the Codex capacity sensor validates `x-codex-*` headers
+ * before producing these). The classifier never reads raw provider headers
+ * itself.
+ */
+export interface ProviderMetadata {
+    readonly quotaExhausted?: boolean | undefined;
+    readonly overloaded?: boolean | undefined;
+}
+/**
+ * Layered failure evidence. `status` is the merged HTTP status (the adapter
+ * prefers the wire status seen by `http.response` over any status echoed in
+ * structured metadata). `text` is the bounded concatenation of error message
+ * and response body, bounded again defensively inside the classifier.
+ */
+export interface ErrorEvidence {
+    readonly interrupted?: InterruptReason | undefined;
+    readonly structured?: StructuredSignal | undefined;
+    readonly status?: number | undefined;
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    readonly providerMetadata?: ProviderMetadata | undefined;
+    readonly text?: string | undefined;
+}
+/** Advisory retry semantics; the retry policy (T-12) makes final decisions. */
+export interface RetryAdvice {
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+}
+export interface FailureClassification {
+    readonly category: FailureCategory;
+    readonly layer: EvidenceLayer;
+    /**
+     * True when the evidence conclusively identifies the failure. Textual
+     * classifications are always non-definitive; scheduling treats
+     * non-definitive evidence more conservatively (ADP-012).
+     */
+    readonly definitive: boolean;
+    readonly retry: RetryAdvice;
+    /** Horizontal recovery (switch resource within the tier) is allowed. */
+    readonly failoverEligible: boolean;
+}

package/dist/health/classifier/types.js

@@ -0,0 +1,27 @@
+export const FAILURE_CATEGORIES = [
+    "rate_limited",
+    "quota_exhausted",
+    "outage",
+    "overload",
+    "timeout",
+    "auth_failure",
+    "invalid_model",
+    "context_overflow",
+    "content_policy",
+    "user_cancelled",
+    "unknown",
+];
+/**
+ * Where the winning classification came from. Exposed so receipts can show
+ * why a decision was made and so tests can pin the precedence chain.
+ */
+export const EVIDENCE_LAYERS = [
+    "interruption",
+    "structured",
+    "status",
+    "headers",
+    "provider-metadata",
+    "textual",
+    "none",
+];
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/health/classifier/types.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,cAAc;IACd,iBAAiB;IACjB,QAAQ;IACR,UAAU;IACV,SAAS;IACT,cAAc;IACd,eAAe;IACf,kBAAkB;IAClB,gBAAgB;IAChB,gBAAgB;IAChB,SAAS;CAC2B,CAAA;AAItC;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,cAAc;IACd,YAAY;IACZ,QAAQ;IACR,SAAS;IACT,mBAAmB;IACnB,SAAS;IACT,MAAM;CAC8B,CAAA","sourcesContent":["/**\n * Failure classification types (ADP-008, ADP-009).\n *\n * The classifier consumes a layered evidence record assembled by the OpenCode\n * adapter. Evidence layers exist so classification can honor the ADP-008\n * precedence chain: structured metadata beats HTTP status beats standard\n * headers beats documented provider-specific metadata beats bounded text.\n */\nimport type { InterruptReason } from \"../../core/work-unit/interruption.js\"\n\nexport const FAILURE_CATEGORIES = [\n  \"rate_limited\",\n  \"quota_exhausted\",\n  \"outage\",\n  \"overload\",\n  \"timeout\",\n  \"auth_failure\",\n  \"invalid_model\",\n  \"context_overflow\",\n  \"content_policy\",\n  \"user_cancelled\",\n  \"unknown\",\n] as const satisfies readonly string[]\n\nexport type FailureCategory = (typeof FAILURE_CATEGORIES)[number]\n\n/**\n * Where the winning classification came from. Exposed so receipts can show\n * why a decision was made and so tests can pin the precedence chain.\n */\nexport const EVIDENCE_LAYERS = [\n  \"interruption\",\n  \"structured\",\n  \"status\",\n  \"headers\",\n  \"provider-metadata\",\n  \"textual\",\n  \"none\",\n] as const satisfies readonly string[]\n\nexport type EvidenceLayer = (typeof EVIDENCE_LAYERS)[number]\n\n/**\n * Structured OpenCode evidence (`Session.StructuredError`): a server-assigned\n * error tag plus, when the provider sent it, a retry delay OpenCode already\n * parsed from `Retry-After`. `type` is a free-form string on the wire, so the\n * classifier only interprets types from the documented @opencode/protocol\n * vocabulary and falls through to lower layers for anything unmapped instead\n * of guessing.\n */\nexport interface StructuredSignal {\n  readonly type: string\n  readonly retryAfterMs?: number | undefined\n}\n\n/**\n * Documented provider-specific metadata, already normalized by our own\n * adapters (e.g. the Codex capacity sensor validates `x-codex-*` headers\n * before producing these). The classifier never reads raw provider headers\n * itself.\n */\nexport interface ProviderMetadata {\n  readonly quotaExhausted?: boolean | undefined\n  readonly overloaded?: boolean | undefined\n}\n\n/**\n * Layered failure evidence. `status` is the merged HTTP status (the adapter\n * prefers the wire status seen by `http.response` over any status echoed in\n * structured metadata). `text` is the bounded concatenation of error message\n * and response body, bounded again defensively inside the classifier.\n */\nexport interface ErrorEvidence {\n  readonly interrupted?: InterruptReason | undefined\n  readonly structured?: StructuredSignal | undefined\n  readonly status?: number | undefined\n  readonly headers?: Readonly<Record<string, string>> | undefined\n  readonly providerMetadata?: ProviderMetadata | undefined\n  readonly text?: string | undefined\n}\n\n/** Advisory retry semantics; the retry policy (T-12) makes final decisions. */\nexport interface RetryAdvice {\n  readonly retryable: boolean\n  readonly retryAfterMs?: number\n}\n\nexport interface FailureClassification {\n  readonly category: FailureCategory\n  readonly layer: EvidenceLayer\n  /**\n   * True when the evidence conclusively identifies the failure. Textual\n   * classifications are always non-definitive; scheduling treats\n   * non-definitive evidence more conservatively (ADP-012).\n   */\n  readonly definitive: boolean\n  readonly retry: RetryAdvice\n  /** Horizontal recovery (switch resource within the tier) is allowed. */\n  readonly failoverEligible: boolean\n}\n"]}

package/dist/health/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./circuit-breaker/index.js";
+export * from "./capacity/index.js";
+export * from "./classifier/index.js";
+export * from "./resource-health/index.js";

package/dist/health/index.js

@@ -0,0 +1,5 @@
+export * from "./circuit-breaker/index.js";
+export * from "./capacity/index.js";
+export * from "./classifier/index.js";
+export * from "./resource-health/index.js";
+//# sourceMappingURL=index.js.map

package/dist/health/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/health/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,4BAA4B,CAAA","sourcesContent":["export * from \"./circuit-breaker/index.js\"\nexport * from \"./capacity/index.js\"\nexport * from \"./classifier/index.js\"\nexport * from \"./resource-health/index.js\"\n"]}

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

@@ -0,0 +1,4 @@
+export * from "./key.js";
+export * from "./registry.js";
+export * from "./transitions.js";
+export * from "./types.js";

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

@@ -0,0 +1,5 @@
+export * from "./key.js";
+export * from "./registry.js";
+export * from "./transitions.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/health/resource-health/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA","sourcesContent":["export * from \"./key.js\"\nexport * from \"./registry.js\"\nexport * from \"./transitions.js\"\nexport * from \"./types.js\"\n"]}

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

@@ -0,0 +1,18 @@
+/**
+ * Resource key helpers: scope derivation and canonical identity.
+ */
+import type { ResourceKey, ResourceScope } from "./types.js";
+/** The scope a key is attributed at: the most specific present field. */
+export declare function resourceScope(key: ResourceKey): ResourceScope;
+/** Canonical string identity for map keys and receipts. */
+export declare function resourceKeyID(key: ResourceKey): string;
+/**
+ * The chain of scopes implied by `key`, ordered widest → narrowest. Each level
+ * keeps the narrower fields that are present, so a key without an account
+ * (OpenCode model references carry only provider and model) still yields a
+ * model-level entry. Health assessment walks this chain because a blocked
+ * ancestor blocks every descendant (e.g. a provider-wide rate limit skips all
+ * of its models). A variant field without a model field is degenerate and
+ * contributes no level of its own.
+ */
+export declare function resourceChain(key: ResourceKey): ResourceKey[];

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

@@ -0,0 +1,54 @@
+/** The scope a key is attributed at: the most specific present field. */
+export function resourceScope(key) {
+    if (key.variantID !== undefined) {
+        return "variant";
+    }
+    if (key.modelID !== undefined) {
+        return "model";
+    }
+    if (key.accountID !== undefined) {
+        return "account";
+    }
+    return "provider";
+}
+/** Canonical string identity for map keys and receipts. */
+export function resourceKeyID(key) {
+    return JSON.stringify([
+        key.providerID,
+        key.accountID ?? null,
+        key.modelID ?? null,
+        key.variantID ?? null,
+    ]);
+}
+/**
+ * The chain of scopes implied by `key`, ordered widest → narrowest. Each level
+ * keeps the narrower fields that are present, so a key without an account
+ * (OpenCode model references carry only provider and model) still yields a
+ * model-level entry. Health assessment walks this chain because a blocked
+ * ancestor blocks every descendant (e.g. a provider-wide rate limit skips all
+ * of its models). A variant field without a model field is degenerate and
+ * contributes no level of its own.
+ */
+export function resourceChain(key) {
+    const chain = [{ providerID: key.providerID }];
+    if (key.accountID !== undefined) {
+        chain.push({ providerID: key.providerID, accountID: key.accountID });
+    }
+    if (key.modelID !== undefined) {
+        chain.push(key.accountID === undefined
+            ? { providerID: key.providerID, modelID: key.modelID }
+            : { providerID: key.providerID, accountID: key.accountID, modelID: key.modelID });
+    }
+    if (key.modelID !== undefined && key.variantID !== undefined) {
+        chain.push(key.accountID === undefined
+            ? { providerID: key.providerID, modelID: key.modelID, variantID: key.variantID }
+            : {
+                providerID: key.providerID,
+                accountID: key.accountID,
+                modelID: key.modelID,
+                variantID: key.variantID,
+            });
+    }
+    return chain;
+}
+//# sourceMappingURL=key.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../../../src/health/resource-health/key.ts"],"names":[],"mappings":"AAKA,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,GAAG,CAAC,UAAU;QACd,GAAG,CAAC,SAAS,IAAI,IAAI;QACrB,GAAG,CAAC,OAAO,IAAI,IAAI;QACnB,GAAG,CAAC,SAAS,IAAI,IAAI;KACtB,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,MAAM,KAAK,GAAkB,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAA;IAC7D,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAA;IACtE,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CACR,GAAG,CAAC,SAAS,KAAK,SAAS;YACzB,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE;YACtD,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CACnF,CAAA;IACH,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7D,KAAK,CAAC,IAAI,CACR,GAAG,CAAC,SAAS,KAAK,SAAS;YACzB,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE;YAChF,CAAC,CAAC;gBACE,UAAU,EAAE,GAAG,CAAC,UAAU;gBAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,SAAS,EAAE,GAAG,CAAC,SAAS;aACzB,CACN,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC","sourcesContent":["/**\n * Resource key helpers: scope derivation and canonical identity.\n */\nimport type { ResourceKey, ResourceScope } from \"./types.js\"\n\n/** The scope a key is attributed at: the most specific present field. */\nexport function resourceScope(key: ResourceKey): ResourceScope {\n  if (key.variantID !== undefined) {\n    return \"variant\"\n  }\n  if (key.modelID !== undefined) {\n    return \"model\"\n  }\n  if (key.accountID !== undefined) {\n    return \"account\"\n  }\n  return \"provider\"\n}\n\n/** Canonical string identity for map keys and receipts. */\nexport function resourceKeyID(key: ResourceKey): string {\n  return JSON.stringify([\n    key.providerID,\n    key.accountID ?? null,\n    key.modelID ?? null,\n    key.variantID ?? null,\n  ])\n}\n\n/**\n * The chain of scopes implied by `key`, ordered widest → narrowest. Each level\n * keeps the narrower fields that are present, so a key without an account\n * (OpenCode model references carry only provider and model) still yields a\n * model-level entry. Health assessment walks this chain because a blocked\n * ancestor blocks every descendant (e.g. a provider-wide rate limit skips all\n * of its models). A variant field without a model field is degenerate and\n * contributes no level of its own.\n */\nexport function resourceChain(key: ResourceKey): ResourceKey[] {\n  const chain: ResourceKey[] = [{ providerID: key.providerID }]\n  if (key.accountID !== undefined) {\n    chain.push({ providerID: key.providerID, accountID: key.accountID })\n  }\n  if (key.modelID !== undefined) {\n    chain.push(\n      key.accountID === undefined\n        ? { providerID: key.providerID, modelID: key.modelID }\n        : { providerID: key.providerID, accountID: key.accountID, modelID: key.modelID },\n    )\n  }\n  if (key.modelID !== undefined && key.variantID !== undefined) {\n    chain.push(\n      key.accountID === undefined\n        ? { providerID: key.providerID, modelID: key.modelID, variantID: key.variantID }\n        : {\n            providerID: key.providerID,\n            accountID: key.accountID,\n            modelID: key.modelID,\n            variantID: key.variantID,\n          },\n    )\n  }\n  return chain\n}\n"]}

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

@@ -0,0 +1,46 @@
+import { type Assessment, type Clock, type HealthEvent, type ProbeOutcome, type ProbeTicket, type ResourceHealthConfig, type ResourceKey, type ResourceRecord } from "./types.js";
+export declare class ResourceHealthRegistry {
+    #private;
+    constructor(clock: Clock, config?: ResourceHealthConfig);
+    /**
+     * 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: readonly ResourceRecord[]): void;
+    observe(event: HealthEvent): ResourceRecord;
+    /**
+     * 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: ResourceKey): Assessment;
+    /**
+     * 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: ResourceKey): Assessment;
+    /**
+     * 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: ProbeTicket, outcome: ProbeOutcome): boolean;
+    /**
+     * Returns an admitted-but-never-dispatched probe ticket: the breaker
+     * reopens still due, so the next admission can issue a fresh probe. Same
+     * stale-ticket rule as `reportProbe`.
+     */
+    releaseProbe(ticket: ProbeTicket): boolean;
+    /** Current (swept) record for one key, if the registry tracks it. */
+    recordFor(key: ResourceKey): ResourceRecord | undefined;
+    /** All tracked records, swept against the clock. */
+    snapshot(): ResourceRecord[];
+}