audit-tools 0.28.0

package/dist/shared/dispatch/rollingDispatch.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Rolling dispatch engine — packet-type-agnostic.
+ *
+ * Key design invariants:
+ * - No max_concurrent in the public API; quota headroom from `scheduleWave` is the
+ *   sole throttle (INV-S05 / INV-QD-11). `InFlightTokenTracker` is the sole source
+ *   of in-flight token accounting; no external concurrency cap is honoured unless
+ *   `options.maxConcurrentPerPool` is explicitly passed.
+ * - TPacket is fully opaque; the engine never inspects packet payload.
+ * - Terminal hooks (synthesis, ingestion) are NOT inline — consumers supply an
+ *   `onResult` callback and own any terminal logic after `run()` returns.
+ * - `recordWaveOutcome` requires `setQuotaStateDir()` to be called before
+ *   `run()` (existing shared quota contract).
+ * - Transient-exhaustion recovery (INV-QD-07 / ARC-d81a55ab): a `rate_limited`
+ *   result records a `rate_limited` quota outcome (backoff + cooldown), drops the
+ *   exhausted pool from the active routing set, and RE-QUEUES the packet so the
+ *   next pass re-selects a pool still within headroom — a transient 429 never
+ *   permanently strands a packet. Only when NO active pool survives does the
+ *   engine stop and surface a `PartialCompletionTerminal{reason:'empty_pool',
+ *   stranded_ids}` (read via `getTerminal()`); the consumer routes the stranded
+ *   ids (audit → synthesis/uncovered, remediate → blocked → close). Dispatch
+ *   callbacks always resolve, never reject.
+ * - Proactive cross-pool spill (INV-QD-14): selection deprioritises a pool that
+ *   is quota-degraded (live `remaining_pct` below the LOW band, or in an active
+ *   cooldown) so load spills onto a peer WITH headroom BEFORE a 429 — the
+ *   proactive complement to the reactive exhausted-pool re-route above. The
+ *   capability order is preserved WITHIN the healthy and degraded groups; a
+ *   degraded pool stays a fallback so a run never stalls when every pool is
+ *   degraded. Inert when quota management is disabled (selection stays pure
+ *   capability order). This is what makes the real-time quota sources actually
+ *   redistribute load instead of merely throttling a single chosen pool.
+ */
+import type { SessionConfig } from "../types/sessionConfig.js";
+import type { CapacityPool, PartialCompletionTerminal } from "../quota/capacity.js";
+import type { QuotaStateEntry } from "../quota/types.js";
+/** A dispatchable unit of work. TPacket is opaque to the engine. */
+export interface RollingDispatchPacket<TPacket> {
+    /** Stable, unique identifier for this packet within a run. */
+    id: string;
+    /** Consumer-defined payload — never inspected by the engine. */
+    payload: TPacket;
+    /**
+     * Estimated token cost (input tokens) for this packet.
+     * Used for quota headroom checks; over-estimates are safe.
+     */
+    estimatedTokens: number;
+    /**
+     * Complexity score in [0, 1].
+     * 1 = highest complexity — routed to the most-capable pool first.
+     * 0 = lowest complexity — routed to the least-capable pool first.
+     */
+    complexity: number;
+}
+/** Outcome of dispatching a single packet. */
+export interface RollingDispatchResult<TPacket> {
+    packet: RollingDispatchPacket<TPacket>;
+    outcome: "success" | "rate_limited" | "timeout" | "error";
+    /** Actual tokens consumed, if the provider reports it. */
+    actualTokens?: number;
+    error?: unknown;
+}
+/** Identity of the provider/model pool selected for a dispatch. */
+export interface ProviderSlot {
+    providerName: string;
+    hostModel: string | null;
+    poolId: string;
+}
+/** In-flight tracking entry for a dispatched packet. */
+export interface InFlightEntry<TPacket> {
+    slotId: string;
+    packet: RollingDispatchPacket<TPacket>;
+    providerSlot: ProviderSlot;
+    startedAt: number;
+    estimatedTokens: number;
+    promise: Promise<RollingDispatchResult<TPacket>>;
+}
+/** Mutable state of the rolling dispatcher. */
+export interface RollingDispatchState<TPacket> {
+    pendingQueue: RollingDispatchPacket<TPacket>[];
+    inFlight: Map<string, InFlightEntry<TPacket>>;
+    completedIds: Set<string>;
+    /**
+     * Pool ids dropped from the active routing set after a `rate_limited`/
+     * exhaustion result. Monotonic within a run — a pool is never re-added — which
+     * is what bounds the transient-429 re-queue loop (every retry either succeeds
+     * elsewhere or shrinks the active set toward empty).
+     */
+    exhaustedPoolIds: Set<string>;
+    /**
+     * Packet ids that could not be dispatched because every pool was exhausted.
+     * Surfaced via {@link RollingDispatcher.getTerminal} as an `empty_pool`
+     * PartialCompletionTerminal (INV-QD-07).
+     */
+    strandedIds: Set<string>;
+}
+/** Consumer-provided configuration for the rolling dispatcher. */
+export interface RollingDispatchConfig<TPacket> {
+    /** Confirmed provider pools, in preference order. */
+    confirmedPools: CapacityPool[];
+    sessionConfig: SessionConfig;
+    /**
+     * Dispatch a single packet to the given provider slot.
+     * Must resolve (never reject) with a RollingDispatchResult.
+     */
+    dispatchPacket: (packet: RollingDispatchPacket<TPacket>, slot: ProviderSlot) => Promise<RollingDispatchResult<TPacket>>;
+    /** Called synchronously after each packet completes (before the next enqueue pass). */
+    onResult?: (result: RollingDispatchResult<TPacket>) => void;
+    /**
+     * Half-life for decaying empirical quota evidence (hours).
+     * Defaults to DEFAULT_EMPIRICAL_HALF_LIFE_HOURS.
+     */
+    halfLifeHours?: number;
+}
+/** Options for tuning the dispatcher (intentionally minimal per INV-S05). */
+export interface RollingDispatchOptions {
+    /**
+     * Optional cap on concurrent dispatches per pool.
+     * Omit to let quota headroom from scheduleWave be the only throttle (INV-S05).
+     * When set, this acts as an additional hard ceiling AFTER quota calculations.
+     */
+    maxConcurrentPerPool?: number;
+}
+/** Public interface returned by createRollingDispatcher. */
+export interface RollingDispatcher<TPacket> {
+    /**
+     * Add packets to the pending queue.
+     * Safe to call while `run()` is active — newly enqueued packets are picked
+     * up on the next dispatch pass.
+     */
+    enqueue(packets: RollingDispatchPacket<TPacket>[]): void;
+    /**
+     * Drive dispatch to completion.
+     * Resolves once every packet (including those enqueued mid-run) has either
+     * completed or been stranded because no pool survived to dispatch it.
+     */
+    run(): Promise<RollingDispatchResult<TPacket>[]>;
+    /** Read-only snapshot of current dispatcher state. */
+    getState(): Readonly<RollingDispatchState<TPacket>>;
+    /**
+     * After {@link run} resolves, returns an `empty_pool` PartialCompletionTerminal
+     * naming any packets that could not be dispatched because every pool exhausted
+     * (INV-QD-07). Returns `null` when every packet completed. The consumer owns
+     * routing the stranded ids through its terminal handler.
+     */
+    getTerminal(): PartialCompletionTerminal | null;
+}
+/**
+ * Tracks the sum of estimated tokens for all in-flight packets per pool.
+ * Used to subtract from quota headroom before each dispatch decision.
+ */
+export declare class InFlightTokenTracker {
+    private readonly _tokens;
+    recordDispatched(poolId: string, tokens: number): void;
+    recordCompleted(poolId: string, tokens: number): void;
+    getInFlightTokens(poolId: string): number;
+}
+/** Extract the complexity score from a packet (passthrough of the field). */
+export declare function scorePacketComplexity<TPacket>(packet: RollingDispatchPacket<TPacket>): number;
+/**
+ * Select the best available provider slot for a packet.
+ *
+ * Two ordering axes, applied in priority order:
+ *  1. **Quota health (INV-QD-14, proactive spill).** When quota management is
+ *     active, pools that are NOT quota-degraded are tried before degraded ones,
+ *     so load spills off a throttled pool (low `remaining_pct` / in cooldown)
+ *     onto a peer with headroom BEFORE a 429. This is the proactive complement to
+ *     the reactive exhausted-pool re-route (INV-QD-07) and is what lets the
+ *     real-time quota sources actually redistribute load across heterogeneous
+ *     pools rather than merely throttling one chosen pool. Degraded pools remain
+ *     a fallback so a run never stalls when every pool is degraded.
+ *  2. **Capability rank.** WITHIN each health group, high-complexity packets
+ *     (complexity >= 0.5) prefer the most-capable pool; low-complexity packets
+ *     prefer the least-capable pool (preserving expensive capacity for harder
+ *     work — the per-model/cost axis). Pool rank comes from `pool.rank`, never a
+ *     provider-name table (INV-shared-core-02).
+ *
+ * Pools whose id is in `exhaustedPoolIds` are skipped — this is how the
+ * transient-429 recovery re-routes a re-queued packet to a pool still within
+ * headroom (INV-QD-07): the pool that rate-limited is excluded on the next pass.
+ *
+ * Returns null if no eligible pool currently has quota headroom.
+ */
+export declare function selectProvider<TPacket>(packet: RollingDispatchPacket<TPacket>, confirmedPools: CapacityPool[], inFlightTracker: InFlightTokenTracker, quotaStateEntries: Record<string, QuotaStateEntry>, sessionConfig: SessionConfig, exhaustedPoolIds?: ReadonlySet<string>): ProviderSlot | null;
+/**
+ * Create a rolling dispatcher for the given configuration.
+ *
+ * The returned dispatcher drives all packets to completion, dispatching each
+ * packet as soon as quota headroom is available — no wave batching, no
+ * separate concurrency cap unless `options.maxConcurrentPerPool` is set.
+ */
+export declare function createRollingDispatcher<TPacket>(config: RollingDispatchConfig<TPacket>, options?: RollingDispatchOptions): RollingDispatcher<TPacket>;
+//# sourceMappingURL=rollingDispatch.d.ts.map

package/dist/shared/dispatch/rollingDispatch.d.ts.map

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

package/dist/shared/dispatch/rollingDispatch.js

@@ -0,0 +1,389 @@
+/**
+ * Rolling dispatch engine — packet-type-agnostic.
+ *
+ * Key design invariants:
+ * - No max_concurrent in the public API; quota headroom from `scheduleWave` is the
+ *   sole throttle (INV-S05 / INV-QD-11). `InFlightTokenTracker` is the sole source
+ *   of in-flight token accounting; no external concurrency cap is honoured unless
+ *   `options.maxConcurrentPerPool` is explicitly passed.
+ * - TPacket is fully opaque; the engine never inspects packet payload.
+ * - Terminal hooks (synthesis, ingestion) are NOT inline — consumers supply an
+ *   `onResult` callback and own any terminal logic after `run()` returns.
+ * - `recordWaveOutcome` requires `setQuotaStateDir()` to be called before
+ *   `run()` (existing shared quota contract).
+ * - Transient-exhaustion recovery (INV-QD-07 / ARC-d81a55ab): a `rate_limited`
+ *   result records a `rate_limited` quota outcome (backoff + cooldown), drops the
+ *   exhausted pool from the active routing set, and RE-QUEUES the packet so the
+ *   next pass re-selects a pool still within headroom — a transient 429 never
+ *   permanently strands a packet. Only when NO active pool survives does the
+ *   engine stop and surface a `PartialCompletionTerminal{reason:'empty_pool',
+ *   stranded_ids}` (read via `getTerminal()`); the consumer routes the stranded
+ *   ids (audit → synthesis/uncovered, remediate → blocked → close). Dispatch
+ *   callbacks always resolve, never reject.
+ * - Proactive cross-pool spill (INV-QD-14): selection deprioritises a pool that
+ *   is quota-degraded (live `remaining_pct` below the LOW band, or in an active
+ *   cooldown) so load spills onto a peer WITH headroom BEFORE a 429 — the
+ *   proactive complement to the reactive exhausted-pool re-route above. The
+ *   capability order is preserved WITHIN the healthy and degraded groups; a
+ *   degraded pool stays a fallback so a run never stalls when every pool is
+ *   degraded. Inert when quota management is disabled (selection stays pure
+ *   capability order). This is what makes the real-time quota sources actually
+ *   redistribute load instead of merely throttling a single chosen pool.
+ */
+import { scheduleWave, buildProviderModelKey, DEFAULT_EMPIRICAL_HALF_LIFE_HOURS, QUOTA_REMAINING_PCT_LOW, } from "../quota/scheduler.js";
+import { recordWaveOutcome, readQuotaState } from "../quota/state.js";
+import { buildEmptyPoolTerminal } from "../quota/capacity.js";
+import { tierRank } from "./tierRank.js";
+// ---------------------------------------------------------------------------
+// InFlightTokenTracker
+// ---------------------------------------------------------------------------
+/**
+ * Tracks the sum of estimated tokens for all in-flight packets per pool.
+ * Used to subtract from quota headroom before each dispatch decision.
+ */
+export class InFlightTokenTracker {
+    _tokens = new Map();
+    recordDispatched(poolId, tokens) {
+        const current = this._tokens.get(poolId) ?? 0;
+        this._tokens.set(poolId, current + Math.max(0, tokens));
+    }
+    recordCompleted(poolId, tokens) {
+        const current = this._tokens.get(poolId) ?? 0;
+        this._tokens.set(poolId, Math.max(0, current - Math.max(0, tokens)));
+    }
+    getInFlightTokens(poolId) {
+        return this._tokens.get(poolId) ?? 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// scorePacketComplexity
+// ---------------------------------------------------------------------------
+/** Extract the complexity score from a packet (passthrough of the field). */
+export function scorePacketComplexity(packet) {
+    return packet.complexity;
+}
+// ---------------------------------------------------------------------------
+// Capability tier ordering
+// ---------------------------------------------------------------------------
+/**
+ * Numeric rank for a pool's declared DispatchModelTier.
+ *
+ * INV-shared-core-02: pool routing rank must be derived from the pool's
+ * declared `rank` (set at the scheduler handshake from discovered roster
+ * data), never from a hardcoded provider-name → tier lookup table. Absent
+ * rank falls back to the middle tier ("standard"), not to a provider-name
+ * switch, so new providers are neutral rather than silently mis-classified.
+ *
+ * The ordering is the single shared `tierRank` authority (P1) — this module no
+ * longer keeps its own copy of the {small,standard,deep} map.
+ */
+function poolCapabilityRank(pool) {
+    // tierRank() already maps an absent/unknown rank to the neutral middle tier.
+    return tierRank(pool.rank);
+}
+// ---------------------------------------------------------------------------
+// selectProvider
+// ---------------------------------------------------------------------------
+/**
+ * Classify a pool as quota-degraded from its live signals: an active cooldown
+ * (learned 429 backoff, or a critical proactive reset folded in by
+ * `scheduleWave`) or a real-time `remaining_pct` below the LOW band. A degraded
+ * pool is still dispatchable — `scheduleWave` floors the wave at 1 — but it is
+ * deprioritised so load spills to a healthier peer first (INV-QD-14).
+ *
+ * Reads the same `QUOTA_REMAINING_PCT_LOW` threshold the scheduler uses to halve
+ * a wave, so "degraded enough to halve" and "degraded enough to spill off" stay
+ * defined by one constant rather than a second magic number.
+ */
+function isPoolQuotaDegraded(pool, schedule) {
+    if (schedule.cooldown_until)
+        return true;
+    const remainingPct = pool.quotaSourceSnapshot?.remaining_pct;
+    return remainingPct != null && remainingPct < QUOTA_REMAINING_PCT_LOW;
+}
+/**
+ * Select the best available provider slot for a packet.
+ *
+ * Two ordering axes, applied in priority order:
+ *  1. **Quota health (INV-QD-14, proactive spill).** When quota management is
+ *     active, pools that are NOT quota-degraded are tried before degraded ones,
+ *     so load spills off a throttled pool (low `remaining_pct` / in cooldown)
+ *     onto a peer with headroom BEFORE a 429. This is the proactive complement to
+ *     the reactive exhausted-pool re-route (INV-QD-07) and is what lets the
+ *     real-time quota sources actually redistribute load across heterogeneous
+ *     pools rather than merely throttling one chosen pool. Degraded pools remain
+ *     a fallback so a run never stalls when every pool is degraded.
+ *  2. **Capability rank.** WITHIN each health group, high-complexity packets
+ *     (complexity >= 0.5) prefer the most-capable pool; low-complexity packets
+ *     prefer the least-capable pool (preserving expensive capacity for harder
+ *     work — the per-model/cost axis). Pool rank comes from `pool.rank`, never a
+ *     provider-name table (INV-shared-core-02).
+ *
+ * Pools whose id is in `exhaustedPoolIds` are skipped — this is how the
+ * transient-429 recovery re-routes a re-queued packet to a pool still within
+ * headroom (INV-QD-07): the pool that rate-limited is excluded on the next pass.
+ *
+ * Returns null if no eligible pool currently has quota headroom.
+ */
+export function selectProvider(packet, confirmedPools, inFlightTracker, quotaStateEntries, sessionConfig, exhaustedPoolIds = new Set()) {
+    const complexity = scorePacketComplexity(packet);
+    const highComplexity = complexity >= 0.5;
+    // Capability ordering: high-complexity → descending rank, low-complexity → ascending.
+    const sorted = [...confirmedPools]
+        .filter((p) => !exhaustedPoolIds.has(p.id))
+        .sort((a, b) => {
+        const diff = poolCapabilityRank(b) - poolCapabilityRank(a);
+        return highComplexity ? diff : -diff;
+    });
+    // Ask scheduleWave whether each pool can accept one more slot, accounting for
+    // in-flight tokens as additional estimated slot cost. The schedule already
+    // folds in the real-time quota snapshot, learned limits, and any active
+    // cooldown, so it doubles as the health signal for the spill ordering below.
+    const scheduleForPool = (pool) => {
+        const poolKey = buildProviderModelKey(pool.providerName, pool.hostModel);
+        const quotaStateEntry = pool.quotaStateEntry ?? quotaStateEntries[poolKey] ?? null;
+        const inFlightTokens = inFlightTracker.getInFlightTokens(pool.id);
+        return scheduleWave({
+            providerName: pool.providerName,
+            sessionConfig,
+            hostModel: pool.hostModel,
+            requestedConcurrency: 1,
+            estimatedSlotTokens: [packet.estimatedTokens + inFlightTokens],
+            quotaStateEntry,
+            hostConcurrencyLimit: pool.hostConcurrencyLimit,
+            discoveredLimits: pool.discoveredLimits ?? null,
+            quotaSourceSnapshot: pool.quotaSourceSnapshot ?? null,
+        });
+    };
+    const evaluated = sorted.map((pool) => ({ pool, schedule: scheduleForPool(pool) }));
+    // Proactive cross-pool spill (INV-QD-14): healthy pools first, then degraded,
+    // each group keeping the capability order above (a stable partition). When
+    // quota management is disabled the subsystem is inert — selection stays pure
+    // capability order.
+    const quotaManaged = sessionConfig.quota?.enabled !== false;
+    const ordered = quotaManaged
+        ? [
+            ...evaluated.filter((e) => !isPoolQuotaDegraded(e.pool, e.schedule)),
+            ...evaluated.filter((e) => isPoolQuotaDegraded(e.pool, e.schedule)),
+        ]
+        : evaluated;
+    for (const { pool, schedule } of ordered) {
+        if (schedule.max_concurrent > 0) {
+            return {
+                providerName: pool.providerName,
+                hostModel: pool.hostModel,
+                poolId: pool.id,
+            };
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// createRollingDispatcher
+// ---------------------------------------------------------------------------
+/**
+ * Create a rolling dispatcher for the given configuration.
+ *
+ * The returned dispatcher drives all packets to completion, dispatching each
+ * packet as soon as quota headroom is available — no wave batching, no
+ * separate concurrency cap unless `options.maxConcurrentPerPool` is set.
+ */
+export function createRollingDispatcher(config, options = {}) {
+    const { confirmedPools, sessionConfig, dispatchPacket, onResult, halfLifeHours = DEFAULT_EMPIRICAL_HALF_LIFE_HOURS, } = config;
+    const state = {
+        pendingQueue: [],
+        inFlight: new Map(),
+        completedIds: new Set(),
+        exhaustedPoolIds: new Set(),
+        strandedIds: new Set(),
+    };
+    const inFlightTracker = new InFlightTokenTracker();
+    const allResults = [];
+    // Per-pool in-flight count for optional maxConcurrentPerPool cap.
+    const inFlightPerPool = new Map();
+    // Quota state cache — refreshed before each dispatch pass.
+    let quotaStateCache = { version: 2, entries: {} };
+    let quotaStateCacheDirty = true;
+    async function refreshQuotaStateIfNeeded() {
+        if (quotaStateCacheDirty) {
+            try {
+                quotaStateCache = await readQuotaState();
+            }
+            catch {
+                // Non-fatal: fall back to empty state
+                quotaStateCache = { version: 2, entries: {} };
+            }
+            quotaStateCacheDirty = false;
+        }
+    }
+    function getDispatchablePackets() {
+        // Return pending queue items not yet in flight (by id).
+        return state.pendingQueue.filter((p) => !state.inFlight.has(p.id) && !state.completedIds.has(p.id));
+    }
+    function dispatchOnePacket(packet, slot) {
+        // Remove from pending queue.
+        state.pendingQueue = state.pendingQueue.filter((p) => p.id !== packet.id);
+        inFlightTracker.recordDispatched(slot.poolId, packet.estimatedTokens);
+        inFlightPerPool.set(slot.poolId, (inFlightPerPool.get(slot.poolId) ?? 0) + 1);
+        const slotId = `${packet.id}@${slot.poolId}`;
+        const startedAt = Date.now();
+        const promise = dispatchPacket(packet, slot).then((result) => result).catch((err) => ({
+            packet,
+            outcome: "error",
+            error: err,
+        }));
+        const entry = {
+            slotId,
+            packet,
+            providerSlot: slot,
+            startedAt,
+            estimatedTokens: packet.estimatedTokens,
+            promise,
+        };
+        state.inFlight.set(packet.id, entry);
+    }
+    async function handleResult(packetId, result) {
+        const entry = state.inFlight.get(packetId);
+        if (!entry)
+            return;
+        const { providerSlot, estimatedTokens, packet } = entry;
+        // Update in-flight tracking (drains the token accounting regardless of
+        // outcome so headroom reflects the freed slot on the next pass).
+        inFlightTracker.recordCompleted(providerSlot.poolId, estimatedTokens);
+        inFlightPerPool.set(providerSlot.poolId, Math.max(0, (inFlightPerPool.get(providerSlot.poolId) ?? 1) - 1));
+        state.inFlight.delete(packetId);
+        // Record quota outcome. 'error' is a distinct quota outcome (non-quota
+        // failure — no cooldown, only failure weight); 'rate_limited' applies the
+        // backoff cooldown that throttles the exhausted pool's learned limits.
+        const providerModelKey = buildProviderModelKey(providerSlot.providerName, providerSlot.hostModel);
+        const quotaOutcome = result.outcome === "success" ? "success"
+            : result.outcome === "rate_limited" ? "rate_limited"
+                : result.outcome === "error" ? "error"
+                    : "timeout";
+        try {
+            await recordWaveOutcome(providerModelKey, {
+                concurrency: 1,
+                estimated_tokens: estimatedTokens,
+                outcome: quotaOutcome,
+            }, halfLifeHours);
+        }
+        catch {
+            // Non-fatal: quota recording failure should not abort dispatch.
+        }
+        quotaStateCacheDirty = true;
+        // Transient-exhaustion recovery (INV-QD-07 / ARC-d81a55ab): a rate_limited
+        // result is NOT a terminal completion. Drop the exhausted pool from the
+        // active routing set and re-queue the packet so the next dispatch pass
+        // re-selects a pool still within headroom. The packet is therefore neither
+        // marked completed nor recorded as a result — it remains live work.
+        if (result.outcome === "rate_limited") {
+            state.exhaustedPoolIds.add(providerSlot.poolId);
+            // Re-queue at the front so the displaced packet is retried before fresh
+            // pending work (avoids starving an already-attempted packet).
+            if (!state.completedIds.has(packet.id) && !state.pendingQueue.some((q) => q.id === packet.id)) {
+                state.pendingQueue.unshift(packet);
+            }
+            // Observability: a single structured line per exhaustion re-queue.
+            try {
+                process.stderr.write(JSON.stringify({
+                    ts: new Date().toISOString(),
+                    kind: "rolling_dispatch_requeue_rate_limited",
+                    packet_id: packet.id,
+                    exhausted_pool_id: providerSlot.poolId,
+                }) + "\n");
+            }
+            catch {
+                // Observability must never abort a run.
+            }
+            return;
+        }
+        // Terminal completion (success / timeout / error): mark done, store result.
+        state.completedIds.add(packetId);
+        allResults.push(result);
+        onResult?.(result);
+    }
+    function enqueue(packets) {
+        for (const p of packets) {
+            if (!state.completedIds.has(p.id) && !state.inFlight.has(p.id)) {
+                // Avoid duplicate enqueue.
+                if (!state.pendingQueue.some((q) => q.id === p.id)) {
+                    state.pendingQueue.push(p);
+                }
+            }
+        }
+    }
+    /**
+     * True when no confirmed pool is eligible to dispatch (every pool has been
+     * dropped into `exhaustedPoolIds`). Waiting cannot help — the remaining
+     * pending work must be stranded (INV-QD-07 empty-pool terminal).
+     */
+    function allPoolsExhausted() {
+        return confirmedPools.every((p) => state.exhaustedPoolIds.has(p.id));
+    }
+    /** Move every still-pending packet into the stranded set and clear the queue. */
+    function strandPending() {
+        for (const packet of state.pendingQueue) {
+            if (!state.completedIds.has(packet.id))
+                state.strandedIds.add(packet.id);
+        }
+        state.pendingQueue = [];
+    }
+    async function run() {
+        while (state.pendingQueue.length > 0 || state.inFlight.size > 0) {
+            // Dispatch pass: fill quota headroom with pending packets.
+            await refreshQuotaStateIfNeeded();
+            let dispatched = 0;
+            const dispatchable = getDispatchablePackets();
+            for (const packet of dispatchable) {
+                // selectProvider skips pools in exhaustedPoolIds, so a re-queued packet
+                // re-routes to a surviving pool (INV-QD-07).
+                const slot = selectProvider(packet, confirmedPools, inFlightTracker, quotaStateCache.entries, sessionConfig, state.exhaustedPoolIds);
+                if (slot === null)
+                    continue;
+                // Apply optional maxConcurrentPerPool cap.
+                if (options.maxConcurrentPerPool !== undefined &&
+                    (inFlightPerPool.get(slot.poolId) ?? 0) >= options.maxConcurrentPerPool) {
+                    continue;
+                }
+                dispatchOnePacket(packet, slot);
+                dispatched++;
+            }
+            // If nothing is in flight and nothing was dispatched but pending work
+            // remains, decide whether to wait or strand:
+            //  - All pools exhausted → waiting cannot help; strand the remainder and
+            //    surface an empty_pool terminal (INV-QD-07 / SEAM-rolling-stranding).
+            //  - Otherwise this is a transient quota cooldown; yield briefly and retry.
+            if (state.inFlight.size === 0 && dispatched === 0 && state.pendingQueue.length > 0) {
+                if (allPoolsExhausted()) {
+                    strandPending();
+                    break;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 50));
+                continue;
+            }
+            // If nothing is in flight after the dispatch pass, we're done.
+            if (state.inFlight.size === 0) {
+                break;
+            }
+            // Await the earliest in-flight completion (race all in-flight promises).
+            const inFlightEntries = [...state.inFlight.entries()];
+            const firstResult = await Promise.race(inFlightEntries.map(async ([packetId, entry]) => {
+                const result = await entry.promise;
+                return { packetId, result };
+            }));
+            await handleResult(firstResult.packetId, firstResult.result);
+            // Loop immediately to re-run the dispatch pass.
+        }
+        return allResults;
+    }
+    function getState() {
+        return state;
+    }
+    function getTerminal() {
+        if (state.strandedIds.size === 0)
+            return null;
+        return buildEmptyPoolTerminal([...state.strandedIds]);
+    }
+    return { enqueue, run, getState, getTerminal };
+}
+//# sourceMappingURL=rollingDispatch.js.map

package/dist/shared/dispatch/rollingDispatch.js.map

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

package/dist/shared/dispatch/tierRank.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Single shared dispatch tier-rank authority (P1 / drift-consolidation).
+ *
+ * The `DispatchModelTier` *type* (`small | standard | deep`) is single-sourced in
+ * `types/stepContract.ts`; its *ordering* used to be re-declared in at least five
+ * places (audit `tierRouting.TIER_RANK`, audit `quotaPool.rankOrder`, shared
+ * `rollingDispatch.DISPATCH_TIER_RANK`, remediate `dispatch.RANK_ORDER` and the
+ * local `rankOrder` reducer in `buildImplementModelHint`). Every copy used the
+ * same `{small:0,standard:1,deep:2}` mapping, so they could silently drift. This
+ * module is the one ordering authority — all of those sites now import from here.
+ *
+ * Serves the no-hardcoded-models invariant: a "tier" is a RELATIVE capability
+ * label, never a model name, and its ordering lives in exactly one place.
+ *
+ * Pure / synchronous / zero-dependency beyond the type import.
+ */
+import type { DispatchModelTier } from "../types/stepContract.js";
+/**
+ * Canonical relative ordering of the dispatch tiers. Higher number = more
+ * capable. The ONLY place this mapping is declared.
+ */
+export declare const DISPATCH_TIER_RANK: Record<DispatchModelTier, number>;
+/**
+ * Tiers in ascending capability order (`["small", "standard", "deep"]`). Derived
+ * from {@link DISPATCH_TIER_RANK} so it can never disagree with the rank map.
+ */
+export declare const DISPATCH_TIER_ORDER: DispatchModelTier[];
+/**
+ * The neutral fallback rank for an absent/unknown tier: the MIDDLE tier
+ * ("standard"). Used where a pool/packet declares no tier — a new provider is
+ * treated as neutral rather than silently mis-classified (INV-shared-core-02).
+ */
+export declare const DISPATCH_TIER_RANK_FALLBACK: number;
+/**
+ * Numeric rank for a (possibly undefined) tier. An unknown/absent tier maps to
+ * the neutral middle rank, never to the bottom — so a pool with no declared rank
+ * is treated as "standard", matching the rolling-dispatch capability model.
+ */
+export declare function tierRank(tier: DispatchModelTier | null | undefined): number;
+/**
+ * Comparator over tiers: negative when `a` is less capable than `b`, positive
+ * when more capable, zero when equal. `compareTier(a, b)` sorts ascending
+ * (least-capable first); negate it for most-capable-first. Unknown tiers sort as
+ * the neutral middle rank.
+ */
+export declare function compareTier(a: DispatchModelTier | null | undefined, b: DispatchModelTier | null | undefined): number;
+/**
+ * The most-capable tier among `tiers`, or `undefined` when the list is empty.
+ * Replaces the ad-hoc `reduce` that picked the max tier in
+ * `buildImplementModelHint`.
+ */
+export declare function mostCapableTier(tiers: ReadonlyArray<DispatchModelTier>): DispatchModelTier | undefined;
+//# sourceMappingURL=tierRank.d.ts.map