@omnicross/core 0.1.0

package/dist/SubscriptionAuthSource-Cr4fVEYY.d.cts

@@ -0,0 +1,264 @@
+import { OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
+import { AuthStrategy } from './pipeline/SubscriptionAuthStrategy.cjs';
+
+/**
+ * AuthSource — unified outbound-authentication strategy for the provider
+ * request pipeline.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3).
+ *
+ * The three consumer paths (the wire-format proxy handler, the host engine
+ * adapter, TransformerHandler) each authenticate differently:
+ *
+ *   - provider-key (+ ApiKeyPool failover)  — LLM-config provider rows
+ *   - subscription `AuthStrategy` (+ 401 refresh + fallback) — code-cli OAuth
+ *   - OAuth pass-through                     — SDK forwards its own Bearer
+ *
+ * `AuthSource` is the single contract that unifies these. THIS PHASE ONLY
+ * DEFINES the interface and provides three behavior-preserving WRAPPERS
+ * (`LlmConfigProviderAuth`, `SubscriptionAuthSource`, `OAuthPassThroughAuth`)
+ * around the existing logic. NO caller is routed through it yet — the core
+ * (`executeProviderCall`) is NOT changed to consume `ctx.auth`, and
+ * the host handler's branch structure is UNCHANGED. Wiring (and
+ * the `onResult` pool-rotation integration) is Phase 3.
+ *
+ * @module pipeline/AuthSource
+ */
+/**
+ * Hints an `AuthSource` may need to vary header formatting per request.
+ *
+ * Mirrors the subscription-side `AuthApplyHints` (which uses optional
+ * `upstreamUrl` / `resolvedModel`) but with REQUIRED fields, since the
+ * pipeline always knows both at the point it applies headers. Adapters that
+ * wrap the looser subscription shape map these across at the boundary.
+ */
+interface AuthApplyHints {
+    /** Resolved upstream URL the request will be sent to. */
+    upstreamUrl: string;
+    /** Resolved model id for the request. */
+    model: string;
+}
+/**
+ * Result of {@link AuthSource.onResult}.
+ *
+ * `rebound` is `true` when the auth source rotated to a different credential
+ * (e.g. ApiKeyPool re-bound the session to a new key after a 429). `newKey`
+ * carries the freshly-resolved key string when a rotation produced one, so a
+ * caller MAY retry the same call once with it. Mirrors the
+ * `{ newKey | null }` contract of `ApiKeyPoolService.reportError` lifted into
+ * a structured shape.
+ */
+interface AuthResultOutcome {
+    /** Whether the credential was rotated/re-bound as a result of this status. */
+    rebound: boolean;
+    /** The new resolved key when a rotation produced one; omitted otherwise. */
+    newKey?: string;
+}
+/**
+ * A pluggable outbound-authentication source for one provider request.
+ *
+ * Implementations OWN exactly the auth concern: which headers carry the
+ * credential, how to recover from a 401, where the request should be sent
+ * (when the credential dictates the endpoint), and how to react to a final
+ * HTTP status (pool rotation / refresh). The pipeline core composes the rest.
+ */
+interface AuthSource {
+    /**
+     * Inject the authentication headers for this request, mutating `headers`
+     * in place. Implementations MAY refresh expiring tokens here.
+     *
+     * NOTE (Phase 2 boundary, see report): exactly WHAT this owns vs what the
+     * ingress assembles (content-type, OpenRouter app headers, proxy auth
+     * stripping) is intentionally left to the caller this phase. The wrappers
+     * preserve their source's CURRENT header behavior verbatim.
+     */
+    applyHeaders(headers: Record<string, string>, hints: AuthApplyHints): Promise<void> | void;
+    /**
+     * Called when the upstream returns 401. Return `true` to ask the caller to
+     * retry once with freshly-applied headers; `false` to surface the 401.
+     * Optional — sources without a refresh notion omit it.
+     */
+    onUnauthorized?(): Promise<boolean>;
+    /**
+     * Resolve the upstream URL the request should target, when the credential
+     * dictates it (e.g. a subscription profile's per-model endpoint). Returns
+     * `undefined` when the source does not override the URL (the ingress keeps
+     * its own URL logic). Optional.
+     */
+    resolveUpstreamUrl?(model: string): string | undefined;
+    /**
+     * React to a final HTTP status (pool participation seam — design D5).
+     *
+     * For the provider-key source this reports the status to the
+     * `ApiKeyPoolService` (cooldown / disable / re-bind) and returns whether it
+     * rotated plus any new key. THIS PHASE ONLY: `onResult` is implemented and
+     * unit-tested in isolation; NO caller invokes it yet. Phase 3 wires it into
+     * `fetchWithRetry`. Optional.
+     *
+     * @param status The final HTTP status, or `null` for non-HTTP failures
+     *   (e.g. network errors). Non-reportable statuses no-op.
+     */
+    onResult?(status: number | null): Promise<AuthResultOutcome>;
+}
+
+/**
+ * SubscriptionAuthSource — `AuthSource` wrapping a subscription `AuthStrategy`.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3, task 4.3).
+ *
+ * Re-expresses the subscription auth used by `SubscriptionDispatcher` behind
+ * the unified `AuthSource` contract, delegating to the existing
+ * `AuthStrategy` so the OAuth refresh / token formatting logic is NOT
+ * rewritten:
+ *
+ *   - `applyHeaders` → `stripAuthHeaders(headers)` then
+ *     `authStrategy.applyHeaders(headers, { upstreamUrl, resolvedModel })`,
+ *     wrapped in the same best-effort try/catch as
+ *     `SubscriptionDispatcher.applyHeadersWithRetry` (a thrown
+ *     `applyHeaders` is logged + swallowed, NOT propagated — preserved
+ *     verbatim).
+ *   - `onUnauthorized` → `authStrategy.onUnauthorized()`.
+ *   - `resolveUpstreamUrl` → `profile.resolveUpstreamUrl?.(model)`.
+ *
+ * IMPORTANT (Phase 2 scope): this WRAPS the strategy + strip behavior but does
+ * NOT re-route `SubscriptionDispatcher` through it. The dispatcher's fragile
+ * 401-refresh + fallback loop is left UNCHANGED (task 4.5 deferred). This
+ * class is unit-tested in isolation only.
+ *
+ * @module pipeline/SubscriptionAuthSource
+ */
+
+/**
+ * Lightweight summary derived from the inbound request body — consumed by a
+ * profile's `modelMapper` (scenario routing). Structural mirror of
+ * `provider-proxy/types.ts`'s `SubscriptionRequestSummary`, declared here so
+ * `SubscriptionAuthProfile.modelMapper` is type-identical WITHOUT a circular
+ * import back into `provider-proxy/types` (which imports THIS module).
+ */
+interface SubscriptionRequestSummary {
+    messageCount: number;
+    estimatedInputTokens: number;
+    /**
+     * OPTIONAL bounded per-message match-text slice — kept structurally identical
+     * to the canonical declaration in `provider-proxy/types.ts` (the two are
+     * deliberate mirrors, not one shared import). Consumed only by the OpenCodeGo
+     * keyword matcher in `@omnicross/subscriptions`; core writes, never reads it.
+     */
+    matchText?: string[];
+}
+/**
+ * The subset of a `SubscriptionDispatchProfile` the subscription paths need.
+ * Kept structural (not the full profile type) so the wrapper does not pull in
+ * the whole registry surface. The full `SubscriptionDispatchProfile` (which IS
+ * what gets passed here) satisfies this shape; the optional `mode` + `modelMapper`
+ * are read by the built-in `/v1/messages` subscription path (RT2.1) to decide the
+ * verbatim-vs-transformer shape and to apply opencodego scenario routing.
+ */
+interface SubscriptionAuthProfile {
+    readonly authStrategy: AuthStrategy;
+    /** Per-model upstream URL resolver (transformer profiles). Optional for
+     *  pass-through profiles that hard-code their endpoint upstream. The OPTIONAL
+     *  2nd `config` arg (opencodego `baseUrl` override, D1) is additive — existing
+     *  one-arg callers compile unchanged; mirrors the full
+     *  `SubscriptionDispatchProfile.resolveUpstreamUrl` so the registry profile
+     *  stays assignable. */
+    readonly resolveUpstreamUrl?: (resolvedModel: string, config?: OpenCodeGoTokenConfig) => string;
+    /**
+     * Names of provider-level transformers (registered in `TransformerService`)
+     * to run on the subscription chain — re-encode Unified → the upstream's wire.
+     * The full `SubscriptionDispatchProfile` (which IS what gets passed here)
+     * carries these; exposing them on the narrow structural type lets the
+     * Responses ingress build the profile's REAL chain (cross-vendor route-to,
+     * task #29) instead of hard-coding `['openai-response']`. Absent/empty →
+     * the ingress falls back to its endpoint transformer (codex byte-identity).
+     */
+    readonly providerTransformerNames?: readonly string[];
+    /** Names of model-specific transformers — usually empty. See above. */
+    readonly modelTransformerNames?: readonly string[];
+    /**
+     * OPTIONAL shape-aware provider transformer-name resolver (opencodego zen).
+     * Type-identical to `SubscriptionDispatchProfile.resolveProviderTransformerNames`
+     * so the registry profile stays assignable. The built-in `/v1/messages`
+     * subscription path (Phase 3) consults it via
+     * `profile.resolveProviderTransformerNames?.(model, route.subscriptionConfig)`
+     * to pick the right zen chain per resolved shape. `config` is `unknown` (core
+     * opaque-config discipline — no `@omnicross/subscriptions` import). When ABSENT
+     * the path reads the static `providerTransformerNames` exactly as today (codex
+     * byte-identity).
+     */
+    readonly resolveProviderTransformerNames?: (model: string, config?: unknown) => readonly string[];
+    /**
+     * Pass-through (claude) vs transformer (codex / opencodego / gemini). The
+     * built-in `/v1/messages` subscription path (RT2.1) reads this for its
+     * core-local same-format signal (pass-through ⇒ always verbatim relay).
+     * Optional on the narrow type — partial profiles built by other route-minting
+     * sites may omit it.
+     */
+    readonly mode?: 'pass-through' | 'transformer';
+    /**
+     * Optional model placeholder rewriter — only set for OpenCodeGo. Type-identical
+     * to `SubscriptionDispatchProfile.modelMapper` so the registry profile stays
+     * assignable. Applied by the built-in `/v1/messages` subscription path BEFORE
+     * resolving the upstream URL (so scenario-based shape routing picks the right
+     * Anthropic-shape vs OpenAI-shape upstream).
+     */
+    readonly modelMapper?: (sdkModel: string, summary: SubscriptionRequestSummary, config: OpenCodeGoTokenConfig | undefined) => {
+        resolvedModel: string;
+        scenario: OpenCodeGoScenario;
+    };
+    /**
+     * Optional fallback resolver — only set for OpenCodeGo. Type-identical to
+     * `SubscriptionDispatchProfile.nextFallback` so the registry profile stays
+     * assignable. Read by the built-in `/v1/messages` fallback loop (D6b) to pick
+     * the next model after an unrecoverable upstream failure; returns `null` when
+     * exhausted (claude / codex / gemini omit it → no fallback attempted).
+     */
+    readonly nextFallback?: (scenario: OpenCodeGoScenario, attempted: readonly string[], config: OpenCodeGoTokenConfig | undefined) => OpenCodeGoModelEntry | null;
+    /**
+     * Optional circuit-breaker admission gate for the PRIMARY (mapped) model (D5
+     * primary-gating). Type-identical to `SubscriptionDispatchProfile.allowModel`.
+     * Only OpenCodeGo sets it; the core `/v1/messages` loop consults it for the
+     * primary before its first attempt and jumps to the first admitting
+     * `nextFallback` candidate when the primary's circuit is open. Absent ⇒ the
+     * primary is always admitted (claude / codex / gemini — no breaker).
+     */
+    readonly allowModel?: (modelId: string) => boolean;
+    /**
+     * Optional record-outcome callback (D5 record seam). Type-identical to
+     * `SubscriptionDispatchProfile.recordModelOutcome`. The core `/v1/messages`
+     * loop calls `profile.recordModelOutcome?.(model, ok)` THROUGH this optional
+     * field after each attempt, so `@omnicross/core` gains NO import of
+     * `@omnicross/subscriptions` (the cross-layer litmus stays 0 — exactly the
+     * `nextFallback` precedent). `ok: true` on `2xx`; `ok: false` on
+     * thrown/`5xx`/`429`; a non-429 `4xx` is NEUTRAL (the loop does NOT call it).
+     * Absent for claude / codex / gemini ⇒ no-op.
+     */
+    readonly recordModelOutcome?: (modelId: string, ok: boolean) => void;
+}
+/**
+ * Drop auth headers the transformer chain may have set so the `AuthStrategy`
+ * is the single source of truth for outbound authentication. Byte-identical
+ * to `SubscriptionDispatcher.stripAuthHeaders`.
+ */
+declare function stripAuthHeaders(headers: Record<string, string>): void;
+declare class SubscriptionAuthSource implements AuthSource {
+    private readonly profile;
+    constructor(profile: SubscriptionAuthProfile);
+    /**
+     * Strip any transformer-set auth headers, then delegate to the bound
+     * strategy. Mirrors `SubscriptionDispatcher`'s
+     * `stripAuthHeaders(...)` + `applyHeadersWithRetry(...)` sequence, including
+     * the best-effort swallow-and-warn around a throwing `applyHeaders`.
+     *
+     * The strategy's looser `AuthApplyHints` (optional `upstreamUrl` /
+     * `resolvedModel`) is fed from the pipeline's required `{ upstreamUrl,
+     * model }` at the boundary.
+     */
+    applyHeaders(headers: Record<string, string>, hints: AuthApplyHints): Promise<void>;
+    /** Delegate the 401-refresh decision to the bound strategy. */
+    onUnauthorized(): Promise<boolean>;
+    /** Resolve the upstream URL from the profile, when it provides one. */
+    resolveUpstreamUrl(model: string): string | undefined;
+}
+
+export { type AuthSource as A, type SubscriptionAuthProfile as S, SubscriptionAuthSource as a, type SubscriptionRequestSummary as b, stripAuthHeaders as s };

package/dist/SubscriptionAuthSource-D89zmiSS.d.ts

@@ -0,0 +1,264 @@
+import { OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
+import { AuthStrategy } from './pipeline/SubscriptionAuthStrategy.js';
+
+/**
+ * AuthSource — unified outbound-authentication strategy for the provider
+ * request pipeline.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3).
+ *
+ * The three consumer paths (the wire-format proxy handler, the host engine
+ * adapter, TransformerHandler) each authenticate differently:
+ *
+ *   - provider-key (+ ApiKeyPool failover)  — LLM-config provider rows
+ *   - subscription `AuthStrategy` (+ 401 refresh + fallback) — code-cli OAuth
+ *   - OAuth pass-through                     — SDK forwards its own Bearer
+ *
+ * `AuthSource` is the single contract that unifies these. THIS PHASE ONLY
+ * DEFINES the interface and provides three behavior-preserving WRAPPERS
+ * (`LlmConfigProviderAuth`, `SubscriptionAuthSource`, `OAuthPassThroughAuth`)
+ * around the existing logic. NO caller is routed through it yet — the core
+ * (`executeProviderCall`) is NOT changed to consume `ctx.auth`, and
+ * the host handler's branch structure is UNCHANGED. Wiring (and
+ * the `onResult` pool-rotation integration) is Phase 3.
+ *
+ * @module pipeline/AuthSource
+ */
+/**
+ * Hints an `AuthSource` may need to vary header formatting per request.
+ *
+ * Mirrors the subscription-side `AuthApplyHints` (which uses optional
+ * `upstreamUrl` / `resolvedModel`) but with REQUIRED fields, since the
+ * pipeline always knows both at the point it applies headers. Adapters that
+ * wrap the looser subscription shape map these across at the boundary.
+ */
+interface AuthApplyHints {
+    /** Resolved upstream URL the request will be sent to. */
+    upstreamUrl: string;
+    /** Resolved model id for the request. */
+    model: string;
+}
+/**
+ * Result of {@link AuthSource.onResult}.
+ *
+ * `rebound` is `true` when the auth source rotated to a different credential
+ * (e.g. ApiKeyPool re-bound the session to a new key after a 429). `newKey`
+ * carries the freshly-resolved key string when a rotation produced one, so a
+ * caller MAY retry the same call once with it. Mirrors the
+ * `{ newKey | null }` contract of `ApiKeyPoolService.reportError` lifted into
+ * a structured shape.
+ */
+interface AuthResultOutcome {
+    /** Whether the credential was rotated/re-bound as a result of this status. */
+    rebound: boolean;
+    /** The new resolved key when a rotation produced one; omitted otherwise. */
+    newKey?: string;
+}
+/**
+ * A pluggable outbound-authentication source for one provider request.
+ *
+ * Implementations OWN exactly the auth concern: which headers carry the
+ * credential, how to recover from a 401, where the request should be sent
+ * (when the credential dictates the endpoint), and how to react to a final
+ * HTTP status (pool rotation / refresh). The pipeline core composes the rest.
+ */
+interface AuthSource {
+    /**
+     * Inject the authentication headers for this request, mutating `headers`
+     * in place. Implementations MAY refresh expiring tokens here.
+     *
+     * NOTE (Phase 2 boundary, see report): exactly WHAT this owns vs what the
+     * ingress assembles (content-type, OpenRouter app headers, proxy auth
+     * stripping) is intentionally left to the caller this phase. The wrappers
+     * preserve their source's CURRENT header behavior verbatim.
+     */
+    applyHeaders(headers: Record<string, string>, hints: AuthApplyHints): Promise<void> | void;
+    /**
+     * Called when the upstream returns 401. Return `true` to ask the caller to
+     * retry once with freshly-applied headers; `false` to surface the 401.
+     * Optional — sources without a refresh notion omit it.
+     */
+    onUnauthorized?(): Promise<boolean>;
+    /**
+     * Resolve the upstream URL the request should target, when the credential
+     * dictates it (e.g. a subscription profile's per-model endpoint). Returns
+     * `undefined` when the source does not override the URL (the ingress keeps
+     * its own URL logic). Optional.
+     */
+    resolveUpstreamUrl?(model: string): string | undefined;
+    /**
+     * React to a final HTTP status (pool participation seam — design D5).
+     *
+     * For the provider-key source this reports the status to the
+     * `ApiKeyPoolService` (cooldown / disable / re-bind) and returns whether it
+     * rotated plus any new key. THIS PHASE ONLY: `onResult` is implemented and
+     * unit-tested in isolation; NO caller invokes it yet. Phase 3 wires it into
+     * `fetchWithRetry`. Optional.
+     *
+     * @param status The final HTTP status, or `null` for non-HTTP failures
+     *   (e.g. network errors). Non-reportable statuses no-op.
+     */
+    onResult?(status: number | null): Promise<AuthResultOutcome>;
+}
+
+/**
+ * SubscriptionAuthSource — `AuthSource` wrapping a subscription `AuthStrategy`.
+ *
+ * Phase 2 of the `provider-request-pipeline` OpenSpec change (design D3, task 4.3).
+ *
+ * Re-expresses the subscription auth used by `SubscriptionDispatcher` behind
+ * the unified `AuthSource` contract, delegating to the existing
+ * `AuthStrategy` so the OAuth refresh / token formatting logic is NOT
+ * rewritten:
+ *
+ *   - `applyHeaders` → `stripAuthHeaders(headers)` then
+ *     `authStrategy.applyHeaders(headers, { upstreamUrl, resolvedModel })`,
+ *     wrapped in the same best-effort try/catch as
+ *     `SubscriptionDispatcher.applyHeadersWithRetry` (a thrown
+ *     `applyHeaders` is logged + swallowed, NOT propagated — preserved
+ *     verbatim).
+ *   - `onUnauthorized` → `authStrategy.onUnauthorized()`.
+ *   - `resolveUpstreamUrl` → `profile.resolveUpstreamUrl?.(model)`.
+ *
+ * IMPORTANT (Phase 2 scope): this WRAPS the strategy + strip behavior but does
+ * NOT re-route `SubscriptionDispatcher` through it. The dispatcher's fragile
+ * 401-refresh + fallback loop is left UNCHANGED (task 4.5 deferred). This
+ * class is unit-tested in isolation only.
+ *
+ * @module pipeline/SubscriptionAuthSource
+ */
+
+/**
+ * Lightweight summary derived from the inbound request body — consumed by a
+ * profile's `modelMapper` (scenario routing). Structural mirror of
+ * `provider-proxy/types.ts`'s `SubscriptionRequestSummary`, declared here so
+ * `SubscriptionAuthProfile.modelMapper` is type-identical WITHOUT a circular
+ * import back into `provider-proxy/types` (which imports THIS module).
+ */
+interface SubscriptionRequestSummary {
+    messageCount: number;
+    estimatedInputTokens: number;
+    /**
+     * OPTIONAL bounded per-message match-text slice — kept structurally identical
+     * to the canonical declaration in `provider-proxy/types.ts` (the two are
+     * deliberate mirrors, not one shared import). Consumed only by the OpenCodeGo
+     * keyword matcher in `@omnicross/subscriptions`; core writes, never reads it.
+     */
+    matchText?: string[];
+}
+/**
+ * The subset of a `SubscriptionDispatchProfile` the subscription paths need.
+ * Kept structural (not the full profile type) so the wrapper does not pull in
+ * the whole registry surface. The full `SubscriptionDispatchProfile` (which IS
+ * what gets passed here) satisfies this shape; the optional `mode` + `modelMapper`
+ * are read by the built-in `/v1/messages` subscription path (RT2.1) to decide the
+ * verbatim-vs-transformer shape and to apply opencodego scenario routing.
+ */
+interface SubscriptionAuthProfile {
+    readonly authStrategy: AuthStrategy;
+    /** Per-model upstream URL resolver (transformer profiles). Optional for
+     *  pass-through profiles that hard-code their endpoint upstream. The OPTIONAL
+     *  2nd `config` arg (opencodego `baseUrl` override, D1) is additive — existing
+     *  one-arg callers compile unchanged; mirrors the full
+     *  `SubscriptionDispatchProfile.resolveUpstreamUrl` so the registry profile
+     *  stays assignable. */
+    readonly resolveUpstreamUrl?: (resolvedModel: string, config?: OpenCodeGoTokenConfig) => string;
+    /**
+     * Names of provider-level transformers (registered in `TransformerService`)
+     * to run on the subscription chain — re-encode Unified → the upstream's wire.
+     * The full `SubscriptionDispatchProfile` (which IS what gets passed here)
+     * carries these; exposing them on the narrow structural type lets the
+     * Responses ingress build the profile's REAL chain (cross-vendor route-to,
+     * task #29) instead of hard-coding `['openai-response']`. Absent/empty →
+     * the ingress falls back to its endpoint transformer (codex byte-identity).
+     */
+    readonly providerTransformerNames?: readonly string[];
+    /** Names of model-specific transformers — usually empty. See above. */
+    readonly modelTransformerNames?: readonly string[];
+    /**
+     * OPTIONAL shape-aware provider transformer-name resolver (opencodego zen).
+     * Type-identical to `SubscriptionDispatchProfile.resolveProviderTransformerNames`
+     * so the registry profile stays assignable. The built-in `/v1/messages`
+     * subscription path (Phase 3) consults it via
+     * `profile.resolveProviderTransformerNames?.(model, route.subscriptionConfig)`
+     * to pick the right zen chain per resolved shape. `config` is `unknown` (core
+     * opaque-config discipline — no `@omnicross/subscriptions` import). When ABSENT
+     * the path reads the static `providerTransformerNames` exactly as today (codex
+     * byte-identity).
+     */
+    readonly resolveProviderTransformerNames?: (model: string, config?: unknown) => readonly string[];
+    /**
+     * Pass-through (claude) vs transformer (codex / opencodego / gemini). The
+     * built-in `/v1/messages` subscription path (RT2.1) reads this for its
+     * core-local same-format signal (pass-through ⇒ always verbatim relay).
+     * Optional on the narrow type — partial profiles built by other route-minting
+     * sites may omit it.
+     */
+    readonly mode?: 'pass-through' | 'transformer';
+    /**
+     * Optional model placeholder rewriter — only set for OpenCodeGo. Type-identical
+     * to `SubscriptionDispatchProfile.modelMapper` so the registry profile stays
+     * assignable. Applied by the built-in `/v1/messages` subscription path BEFORE
+     * resolving the upstream URL (so scenario-based shape routing picks the right
+     * Anthropic-shape vs OpenAI-shape upstream).
+     */
+    readonly modelMapper?: (sdkModel: string, summary: SubscriptionRequestSummary, config: OpenCodeGoTokenConfig | undefined) => {
+        resolvedModel: string;
+        scenario: OpenCodeGoScenario;
+    };
+    /**
+     * Optional fallback resolver — only set for OpenCodeGo. Type-identical to
+     * `SubscriptionDispatchProfile.nextFallback` so the registry profile stays
+     * assignable. Read by the built-in `/v1/messages` fallback loop (D6b) to pick
+     * the next model after an unrecoverable upstream failure; returns `null` when
+     * exhausted (claude / codex / gemini omit it → no fallback attempted).
+     */
+    readonly nextFallback?: (scenario: OpenCodeGoScenario, attempted: readonly string[], config: OpenCodeGoTokenConfig | undefined) => OpenCodeGoModelEntry | null;
+    /**
+     * Optional circuit-breaker admission gate for the PRIMARY (mapped) model (D5
+     * primary-gating). Type-identical to `SubscriptionDispatchProfile.allowModel`.
+     * Only OpenCodeGo sets it; the core `/v1/messages` loop consults it for the
+     * primary before its first attempt and jumps to the first admitting
+     * `nextFallback` candidate when the primary's circuit is open. Absent ⇒ the
+     * primary is always admitted (claude / codex / gemini — no breaker).
+     */
+    readonly allowModel?: (modelId: string) => boolean;
+    /**
+     * Optional record-outcome callback (D5 record seam). Type-identical to
+     * `SubscriptionDispatchProfile.recordModelOutcome`. The core `/v1/messages`
+     * loop calls `profile.recordModelOutcome?.(model, ok)` THROUGH this optional
+     * field after each attempt, so `@omnicross/core` gains NO import of
+     * `@omnicross/subscriptions` (the cross-layer litmus stays 0 — exactly the
+     * `nextFallback` precedent). `ok: true` on `2xx`; `ok: false` on
+     * thrown/`5xx`/`429`; a non-429 `4xx` is NEUTRAL (the loop does NOT call it).
+     * Absent for claude / codex / gemini ⇒ no-op.
+     */
+    readonly recordModelOutcome?: (modelId: string, ok: boolean) => void;
+}
+/**
+ * Drop auth headers the transformer chain may have set so the `AuthStrategy`
+ * is the single source of truth for outbound authentication. Byte-identical
+ * to `SubscriptionDispatcher.stripAuthHeaders`.
+ */
+declare function stripAuthHeaders(headers: Record<string, string>): void;
+declare class SubscriptionAuthSource implements AuthSource {
+    private readonly profile;
+    constructor(profile: SubscriptionAuthProfile);
+    /**
+     * Strip any transformer-set auth headers, then delegate to the bound
+     * strategy. Mirrors `SubscriptionDispatcher`'s
+     * `stripAuthHeaders(...)` + `applyHeadersWithRetry(...)` sequence, including
+     * the best-effort swallow-and-warn around a throwing `applyHeaders`.
+     *
+     * The strategy's looser `AuthApplyHints` (optional `upstreamUrl` /
+     * `resolvedModel`) is fed from the pipeline's required `{ upstreamUrl,
+     * model }` at the boundary.
+     */
+    applyHeaders(headers: Record<string, string>, hints: AuthApplyHints): Promise<void>;
+    /** Delegate the 401-refresh decision to the bound strategy. */
+    onUnauthorized(): Promise<boolean>;
+    /** Resolve the upstream URL from the profile, when it provides one. */
+    resolveUpstreamUrl(model: string): string | undefined;
+}
+
+export { type AuthSource as A, type SubscriptionAuthProfile as S, SubscriptionAuthSource as a, type SubscriptionRequestSummary as b, stripAuthHeaders as s };