audit-tools 0.28.0

package/dist/shared/quota/quotaSource.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export declare const QuotaUsageSnapshotSchema: z.ZodObject<{
+    remaining_pct: z.ZodNullable<z.ZodNumber>;
+    reset_at: z.ZodNullable<z.ZodString>;
+    requests_remaining: z.ZodNullable<z.ZodNumber>;
+    tokens_remaining: z.ZodNullable<z.ZodNumber>;
+    captured_at: z.ZodString;
+    source: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    remaining_pct: number | null;
+    reset_at: string | null;
+    requests_remaining: number | null;
+    tokens_remaining: number | null;
+    captured_at: string;
+    source: string;
+}, {
+    remaining_pct: number | null;
+    reset_at: string | null;
+    requests_remaining: number | null;
+    tokens_remaining: number | null;
+    captured_at: string;
+    source: string;
+}>;
+export type QuotaUsageSnapshot = z.infer<typeof QuotaUsageSnapshotSchema>;
+export interface QuotaSource {
+    readonly name: string;
+    queryCurrentUsage(providerModelKey: string): Promise<QuotaUsageSnapshot | null>;
+}
+//# sourceMappingURL=quotaSource.d.ts.map

package/dist/shared/quota/quotaSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quotaSource.d.ts","sourceRoot":"","sources":["../../../src/shared/quota/quotaSource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;EAS1B,CAAC;AACZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CACjF"}

package/dist/shared/quota/quotaSource.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export const QuotaUsageSnapshotSchema = z
+    .object({
+    remaining_pct: z.number().nullable(),
+    reset_at: z.string().nullable(),
+    requests_remaining: z.number().int().nullable(),
+    tokens_remaining: z.number().int().nullable(),
+    captured_at: z.string(),
+    source: z.string(),
+})
+    .strict();
+//# sourceMappingURL=quotaSource.js.map

package/dist/shared/quota/quotaSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quotaSource.js","sourceRoot":"","sources":["../../../src/shared/quota/quotaSource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC;KACtC,MAAM,CAAC;IACN,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAC/C,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAC7C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/shared/quota/rollingEngine.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Rolling engine — provider-pool-change semantics (drop + re-route).
+ *
+ * Manages a mutable active provider pool across a dispatch run. When a provider
+ * signals quota exhaustion or disappears, the engine drops it from the active
+ * routing set, re-queues any in-flight packets that had been assigned to it, and
+ * re-routes those packets to the remaining active providers.
+ *
+ * NOTE: The empty-pool terminal (active_pools reaches zero → waiting_for_provider)
+ * is NOT handled here — that is N-S09's responsibility. When dropProvider is
+ * called on the last active pool it returns a state with active_pools: [] and
+ * the caller's engine loop detects and handles the empty-pool condition.
+ */
+import type { SessionConfig } from "../types/sessionConfig.js";
+import type { CapacityPool, PartialCompletionTerminal } from "./capacity.js";
+import type { FreshSessionProvider } from "../providers/types.js";
+import { computeDispatchCapacity } from "./capacity.js";
+/** Reason a provider was removed from the active pool. */
+export type ProviderPoolEventKind = "exhausted" | "unavailable";
+/**
+ * A recorded pool-change event: a provider was removed from active routing.
+ * - `exhausted`: quota/rate-limit exhaustion (detectRateLimitError returned a hit).
+ * - `unavailable`: spawn failed with a non-retryable error.
+ */
+export interface ProviderPoolEvent {
+    kind: ProviderPoolEventKind;
+    provider_id: string;
+    timestamp: string;
+    in_flight_count: number;
+    requeued_count: number;
+}
+/**
+ * An active pool entry: the capacity descriptor plus its provider instance.
+ */
+export interface RollingEnginePoolEntry {
+    pool: CapacityPool;
+    provider: FreshSessionProvider;
+}
+/**
+ * Input to the rolling engine: the set of pools available at dispatch start.
+ */
+export type RollingEnginePool = RollingEnginePoolEntry[];
+/**
+ * A packet token tracked by the rolling engine.
+ * The engine is payload-agnostic; only the id and pool assignment matter here.
+ */
+export interface EnginePacketToken {
+    /** Stable unique id for this packet. */
+    id: string;
+    /** The pool_id this packet was assigned to (in-flight or pending). */
+    assigned_pool_id: string;
+    /** Estimated input tokens for this packet. */
+    estimated_tokens: number;
+}
+/**
+ * Mutable state managed by the rolling engine.
+ *
+ * - `active_pools`: providers currently eligible for dispatch.
+ * - `exhausted_pools`: providers removed due to quota/unavailability.
+ * - `in_flight_tokens`: packets currently dispatched and awaiting a result.
+ * - `pending_tokens`: packets queued but not yet dispatched (includes requeued).
+ * - `event_log`: ordered record of pool-change events.
+ */
+export interface RollingEnginePoolState {
+    active_pools: RollingEnginePoolEntry[];
+    exhausted_pools: RollingEnginePoolEntry[];
+    in_flight_tokens: EnginePacketToken[];
+    pending_tokens: EnginePacketToken[];
+    event_log: ProviderPoolEvent[];
+}
+/**
+ * Pure function: remove a provider from the active routing set.
+ *
+ * Given the current engine state and a pool_id to drop:
+ * 1. Moves the named pool from `active_pools` to `exhausted_pools`.
+ * 2. Identifies all in-flight packets assigned to the dropped pool.
+ * 3. Removes those packets from `in_flight_tokens`.
+ * 4. Appends those packets to `pending_tokens` (re-queued for re-routing).
+ * 5. Appends a `ProviderPoolEvent` to `event_log`.
+ *
+ * Returns a new `RollingEnginePoolState` — the input state is never mutated.
+ *
+ * When `active_pools` is already empty or the pool_id is not found in
+ * `active_pools`, the state is returned unchanged (idempotent).
+ *
+ * When this call reduces `active_pools` to `[]`, the caller (N-S09's engine
+ * loop) is responsible for detecting the empty-pool condition.
+ */
+export declare function dropProvider(state: RollingEnginePoolState, pool_id: string, kind: ProviderPoolEventKind): RollingEnginePoolState;
+/** Result of {@link reroutePackets}. */
+export interface ReroutePacketsResult {
+    state: RollingEnginePoolState;
+    /** Dispatch allocation computed over the surviving active pools, or null. */
+    allocation: ReturnType<typeof computeDispatchCapacity> | null;
+    /**
+     * Set when surplus pending packets could not be reassigned to any surviving
+     * active pool — either because no active pool remains, or because pending
+     * demand exceeds the survivors' combined slot capacity. The stranded packet
+     * ids are surfaced here (and removed from `state.pending_tokens`) so the
+     * caller routes them through its consumer-specific terminal handler. `null`
+     * when every pending packet found a surviving active pool. (INV-QD-13)
+     */
+    terminal: PartialCompletionTerminal | null;
+}
+/**
+ * Re-route pending packet tokens across the remaining active pools.
+ *
+ * The no-stranding guarantee (INV-QD-13 / SEAM-rolling-stranding): after ANY
+ * `dropProvider` — including simultaneous multi-pool drops where pending demand
+ * exceeds the survivors' slot capacity — this function leaves ZERO
+ * `pending_tokens` whose `assigned_pool_id` points at a dropped/exhausted (i.e.
+ * non-active) pool. Every pending packet is either reassigned to a pool still in
+ * `active_pools`, or removed from `pending_tokens` and surfaced in
+ * `terminal.stranded_ids`. `reroutePackets` is the SINGLE owner of this
+ * guarantee; consumers (audit-cli-commands, remediate-steps-dispatch) only
+ * consume `stranded_ids` and never implement their own reroute.
+ *
+ * Behaviour:
+ * - No pending tokens → state unchanged, `allocation` and `terminal` null.
+ * - `active_pools` empty but pending tokens exist → every pending packet is
+ *   stranded (state pending cleared) and an `empty_pool` terminal is returned.
+ * - Otherwise → `computeDispatchCapacity` sizes the surviving pools; the largest
+ *   pending packets are assigned to the surviving pools up to their slot counts,
+ *   and any surplus that does not fit is stranded.
+ *
+ * Also returns the `DispatchCapacity` computed by `computeDispatchCapacity` so
+ * callers can inspect the allocation without re-computing it.
+ */
+export declare function reroutePackets(state: RollingEnginePoolState, sessionConfig: SessionConfig): ReroutePacketsResult;
+//# sourceMappingURL=rollingEngine.d.ts.map

package/dist/shared/quota/rollingEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollingEngine.d.ts","sourceRoot":"","sources":["../../../src/shared/quota/rollingEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAA0B,MAAM,eAAe,CAAC;AAMhF,0DAA0D;AAC1D,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,aAAa,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,EAAE,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,gBAAgB,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,sBAAsB,EAAE,CAAC;IACvC,eAAe,EAAE,sBAAsB,EAAE,CAAC;IAC1C,gBAAgB,EAAE,iBAAiB,EAAE,CAAC;IACtC,cAAc,EAAE,iBAAiB,EAAE,CAAC;IACpC,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,qBAAqB,GAC1B,sBAAsB,CAoDxB;AAMD,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,sBAAsB,CAAC;IAC9B,6EAA6E;IAC7E,UAAU,EAAE,UAAU,CAAC,OAAO,uBAAuB,CAAC,GAAG,IAAI,CAAC;IAC9D;;;;;;;OAOG;IACH,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,sBAAsB,EAC7B,aAAa,EAAE,aAAa,GAC3B,oBAAoB,CA0DtB"}

package/dist/shared/quota/rollingEngine.js

@@ -0,0 +1,153 @@
+/**
+ * Rolling engine — provider-pool-change semantics (drop + re-route).
+ *
+ * Manages a mutable active provider pool across a dispatch run. When a provider
+ * signals quota exhaustion or disappears, the engine drops it from the active
+ * routing set, re-queues any in-flight packets that had been assigned to it, and
+ * re-routes those packets to the remaining active providers.
+ *
+ * NOTE: The empty-pool terminal (active_pools reaches zero → waiting_for_provider)
+ * is NOT handled here — that is N-S09's responsibility. When dropProvider is
+ * called on the last active pool it returns a state with active_pools: [] and
+ * the caller's engine loop detects and handles the empty-pool condition.
+ */
+import { computeDispatchCapacity, buildEmptyPoolTerminal } from "./capacity.js";
+// ---------------------------------------------------------------------------
+// dropProvider
+// ---------------------------------------------------------------------------
+/**
+ * Pure function: remove a provider from the active routing set.
+ *
+ * Given the current engine state and a pool_id to drop:
+ * 1. Moves the named pool from `active_pools` to `exhausted_pools`.
+ * 2. Identifies all in-flight packets assigned to the dropped pool.
+ * 3. Removes those packets from `in_flight_tokens`.
+ * 4. Appends those packets to `pending_tokens` (re-queued for re-routing).
+ * 5. Appends a `ProviderPoolEvent` to `event_log`.
+ *
+ * Returns a new `RollingEnginePoolState` — the input state is never mutated.
+ *
+ * When `active_pools` is already empty or the pool_id is not found in
+ * `active_pools`, the state is returned unchanged (idempotent).
+ *
+ * When this call reduces `active_pools` to `[]`, the caller (N-S09's engine
+ * loop) is responsible for detecting the empty-pool condition.
+ */
+export function dropProvider(state, pool_id, kind) {
+    const poolIndex = state.active_pools.findIndex((e) => e.pool.id === pool_id);
+    if (poolIndex === -1) {
+        // Pool not in active set — idempotent, return unchanged.
+        return state;
+    }
+    const dropped = state.active_pools[poolIndex];
+    // Identify in-flight packets assigned to the dropped pool.
+    const requeued = state.in_flight_tokens.filter((t) => t.assigned_pool_id === pool_id);
+    const stillInFlight = state.in_flight_tokens.filter((t) => t.assigned_pool_id !== pool_id);
+    const event = {
+        kind,
+        provider_id: pool_id,
+        timestamp: new Date().toISOString(),
+        in_flight_count: requeued.length,
+        requeued_count: requeued.length,
+    };
+    // Structured observability for pool drops/rerouting (OBS-d81a55ab). Emitted on
+    // its own line and wrapped so a logging failure can never abort a dispatch run.
+    try {
+        process.stderr.write(JSON.stringify({
+            ts: event.timestamp,
+            kind: "rolling_engine_drop_provider",
+            provider_id: pool_id,
+            drop_kind: kind,
+            in_flight_count: event.in_flight_count,
+            requeued_count: event.requeued_count,
+        }) + "\n");
+    }
+    catch {
+        // Observability must never abort a run.
+    }
+    return {
+        active_pools: [
+            ...state.active_pools.slice(0, poolIndex),
+            ...state.active_pools.slice(poolIndex + 1),
+        ],
+        exhausted_pools: [...state.exhausted_pools, dropped],
+        in_flight_tokens: stillInFlight,
+        pending_tokens: [...state.pending_tokens, ...requeued],
+        event_log: [...state.event_log, event],
+    };
+}
+/**
+ * Re-route pending packet tokens across the remaining active pools.
+ *
+ * The no-stranding guarantee (INV-QD-13 / SEAM-rolling-stranding): after ANY
+ * `dropProvider` — including simultaneous multi-pool drops where pending demand
+ * exceeds the survivors' slot capacity — this function leaves ZERO
+ * `pending_tokens` whose `assigned_pool_id` points at a dropped/exhausted (i.e.
+ * non-active) pool. Every pending packet is either reassigned to a pool still in
+ * `active_pools`, or removed from `pending_tokens` and surfaced in
+ * `terminal.stranded_ids`. `reroutePackets` is the SINGLE owner of this
+ * guarantee; consumers (audit-cli-commands, remediate-steps-dispatch) only
+ * consume `stranded_ids` and never implement their own reroute.
+ *
+ * Behaviour:
+ * - No pending tokens → state unchanged, `allocation` and `terminal` null.
+ * - `active_pools` empty but pending tokens exist → every pending packet is
+ *   stranded (state pending cleared) and an `empty_pool` terminal is returned.
+ * - Otherwise → `computeDispatchCapacity` sizes the surviving pools; the largest
+ *   pending packets are assigned to the surviving pools up to their slot counts,
+ *   and any surplus that does not fit is stranded.
+ *
+ * Also returns the `DispatchCapacity` computed by `computeDispatchCapacity` so
+ * callers can inspect the allocation without re-computing it.
+ */
+export function reroutePackets(state, sessionConfig) {
+    if (state.pending_tokens.length === 0) {
+        return { state, allocation: null, terminal: null };
+    }
+    // No surviving pool: every pending packet is stranded. Clearing pending here
+    // is what guarantees ZERO pending_tokens remain pointed at a dead pool.
+    if (state.active_pools.length === 0) {
+        const strandedIds = state.pending_tokens.map((t) => t.id);
+        return {
+            state: { ...state, pending_tokens: [] },
+            allocation: null,
+            terminal: buildEmptyPoolTerminal(strandedIds),
+        };
+    }
+    const pendingItemTokens = state.pending_tokens.map((t) => t.estimated_tokens);
+    const pools = state.active_pools.map((e) => e.pool);
+    const activePoolIds = new Set(pools.map((p) => p.id));
+    const allocation = computeDispatchCapacity({ pools, sessionConfig, pendingItemTokens });
+    // Order pending packets largest-first so the survivors' slots carry the most
+    // expensive work, mirroring computeDispatchCapacity's own descending layout.
+    const ordered = [...state.pending_tokens].sort((a, b) => b.estimated_tokens - a.estimated_tokens);
+    // Re-assign pending tokens to surviving pools based on slot counts.
+    const reassigned = [];
+    let tokenCursor = 0;
+    for (const poolAlloc of allocation.pools) {
+        // Defensive: never assign to a pool that is not in the active set.
+        if (!activePoolIds.has(poolAlloc.pool_id))
+            continue;
+        const assignCount = Math.min(poolAlloc.slots, ordered.length - tokenCursor);
+        for (let i = 0; i < assignCount; i++) {
+            const original = ordered[tokenCursor + i];
+            reassigned.push({ ...original, assigned_pool_id: poolAlloc.pool_id });
+        }
+        tokenCursor += assignCount;
+        if (tokenCursor >= ordered.length)
+            break;
+    }
+    // Any packet beyond the survivors' combined slot capacity cannot be placed on
+    // an active pool. It MUST NOT stay assigned to a dropped/exhausted pool — it is
+    // removed from pending_tokens and surfaced as stranded (INV-QD-13).
+    const stranded = ordered.slice(tokenCursor);
+    const terminal = stranded.length > 0
+        ? buildEmptyPoolTerminal(stranded.map((t) => t.id))
+        : null;
+    return {
+        state: { ...state, pending_tokens: reassigned },
+        allocation,
+        terminal,
+    };
+}
+//# sourceMappingURL=rollingEngine.js.map

package/dist/shared/quota/rollingEngine.js.map

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

package/dist/shared/quota/scheduler.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import type { ResolvedProviderName, SessionConfig } from "../types/sessionConfig.js";
+import type { HostConcurrencyLimit, QuotaStateEntry, WaveSchedule } from "./types.js";
+import type { QuotaUsageSnapshot } from "./quotaSource.js";
+/**
+ * Minimal structural shape of capabilities discovered at runtime — RPM/TPM (e.g.
+ * via response-header extraction) plus, from the dispatch-time capability
+ * handshake, the dispatching model's real context/output window. Declared here
+ * so the scheduler stays decoupled from any package-specific discovery
+ * implementation — callers may pass a richer object (with a `source` field,
+ * etc.); only these fields are read.
+ *
+ * `context_tokens`/`output_tokens`, when present, are the discovered model's
+ * window and take precedence over the static known-model table — they are how
+ * dispatch escapes the conservative 32k default once a host reports its real
+ * capabilities (see docs/audit-workflow-design.md).
+ */
+export interface DiscoveredRateLimitsInput {
+    requests_per_minute?: number | null;
+    input_tokens_per_minute?: number | null;
+    output_tokens_per_minute?: number | null;
+    /** Discovered context window for the dispatching model, if reported. */
+    context_tokens?: number | null;
+    /** Discovered output cap for the dispatching model, if reported. */
+    output_tokens?: number | null;
+}
+/**
+ * One entry of the host's model roster, reported at the dispatch handshake
+ * (lowest rank first). `rank` is a RELATIVE capability label that reuses the
+ * `DispatchModelTier` vocabulary so it lines up with each packet's
+ * `model_hint.tier`; the windows are discovered, never assumed. The host still
+ * never names a model to the backend (no-hardcoded-models invariant).
+ */
+export declare const HostModelRosterEntrySchema: z.ZodObject<{
+    rank: z.ZodEnum<["small", "standard", "deep"]>;
+    /** Context window (input tokens) of the model serving this rank. */
+    context_tokens: z.ZodNumber;
+    /** Output-token cap of the model serving this rank. */
+    output_tokens: z.ZodNumber;
+    /**
+     * Optional OPAQUE identity for the model serving this rank, used ONLY as a
+     * quota-key segment (`provider/<model_id>`) so quota learning stays
+     * per-model. Never a window authority and never compared against a name
+     * table — the no-hardcoded-models invariant holds.
+     */
+    model_id: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    context_tokens: number;
+    output_tokens: number;
+    rank: "deep" | "small" | "standard";
+    model_id?: string | undefined;
+}, {
+    context_tokens: number;
+    output_tokens: number;
+    rank: "deep" | "small" | "standard";
+    model_id?: string | undefined;
+}>;
+export type HostModelRosterEntry = z.infer<typeof HostModelRosterEntrySchema>;
+/**
+ * Parse and validate a `--host-models` handshake value (JSON array, lowest
+ * rank first) into a roster. Single-sourced here so both orchestrators accept
+ * the identical contract. Malformed input throws so a mistyped handshake fails
+ * loudly instead of silently downgrading to the conservative floor.
+ */
+export declare function parseHostModelRoster(raw: string): HostModelRosterEntry[];
+export interface ScheduleWaveOptions {
+    providerName: ResolvedProviderName;
+    sessionConfig: SessionConfig;
+    hostModel: string | null;
+    requestedConcurrency: number;
+    /** Per-slot estimated tokens (one entry per worker slot). Used for TPM budget. */
+    estimatedSlotTokens?: number[];
+    quotaStateEntry?: QuotaStateEntry | null;
+    hostConcurrencyLimit?: HostConcurrencyLimit | null;
+    quotaSourceSnapshot?: QuotaUsageSnapshot | null;
+    /** RPM/TPM discovered from provider queries or response header extraction. */
+    discoveredLimits?: DiscoveredRateLimitsInput | null;
+}
+/** Fraction of a discovered RPM/TPM limit we actually schedule against. */
+export declare const DEFAULT_SAFETY_MARGIN = 0.8;
+/** Half-life (hours) for decaying learned concurrency evidence. */
+export declare const DEFAULT_EMPIRICAL_HALF_LIFE_HOURS = 24;
+/** Conservative ceiling applied on first contact with an unconfigured provider. */
+export declare const DEFAULT_FIRST_CONTACT_CONCURRENCY = 3;
+/**
+ * Real-time quota-source `remaining_pct` thresholds. At/under CRITICAL we throttle
+ * to a single request; at/under LOW we halve the wave.
+ */
+export declare const QUOTA_REMAINING_PCT_CRITICAL = 0.1;
+export declare const QUOTA_REMAINING_PCT_LOW = 0.3;
+export declare function scheduleWave(options: ScheduleWaveOptions): WaveSchedule;
+/** Build the state key used for indexing quota-state.json entries. */
+export declare function buildProviderModelKey(providerName: string, hostModel: string | null | undefined): string;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/shared/quota/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/shared/quota/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAe,oBAAoB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAGlG,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EAGf,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAQ3D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,yBAAyB;IACxC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;IAGnC,oEAAoE;;IAEpE,uDAAuD;;IAEvD;;;;;OAKG;;;;;;;;;;;;EAGI,CAAC;AACZ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAI9E;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAkDxE;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,oBAAoB,CAAC;IACnC,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,oBAAoB,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACnD,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAChD,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAAC;CACrD;AAMD,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,mEAAmE;AACnE,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,mFAAmF;AACnF,eAAO,MAAM,iCAAiC,IAAI,CAAC;AACnD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAmM3C,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA+HvE;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,MAAM,CAER"}