@qvac/sdk 0.18.2 → 0.19.1

package/dist/server/bare/runtime/request-registry.js

@@ -1,715 +0,0 @@
-import { AbortController } from 'bare-abort-controller';
-import { createDisposableScope } from '../../../server/bare/runtime/disposable-scope.js';
-import { RequestIdConflictError, RequestRejectedByPolicyError } from '../../../utils/errors-server.js';
-import { getServerLogger } from '../../../logging/index.js';
-/**
- * Tuning knobs for the "cancelled-before-begin" bookkeeping set.
- *
- * The race window is bounded by the client-to-server round-trip: a
- * `cancel({ requestId })` issued by the client at the same time as the
- * matching `completion(...)` either lands first (and we need to remember
- * it long enough for the server's `begin(...)` to follow) or lands
- * second (and we never touch this set). 30 seconds is overkill for a
- * 500ms round-trip but gives slow networks / pause-the-debugger
- * scenarios enough slack while still bounding worst-case retention.
- *
- * The size cap protects against a buggy or malicious client firing a
- * stream of cancels for ids that never get a `begin(...)` follow-up —
- * each `cancel({ requestId })` that doesn't match an in-flight context
- * inserts one entry, so without a cap the worker would grow the map
- * unbounded. At the cap, the oldest entry is evicted.
- *
- * Tweak with care: both bounds appear in the registry race test
- * (`bounded cancel-before-begin set does not grow past its cap`).
- */
-const CANCEL_BEFORE_BEGIN_MAX_ENTRIES = 128;
-const CANCEL_BEFORE_BEGIN_TTL_MS = 30_000;
-/**
- * Default cap on waiters queued per `(lane, modelId)` when a policy uses
- * `onOverflow: "queue"` without an explicit `maxQueueDepthPerModel`.
- * Bounds memory so a misbehaving client firing a flood of same-model
- * requests can't grow the queue without limit — the (depth + 1)th begin
- * rejects with `RequestRejectedByPolicyError` instead of enqueuing.
- */
-const DEFAULT_MAX_QUEUE_DEPTH_PER_MODEL = 64;
-export function createRequestRegistry(options) {
-    const entries = new Map();
-    const policies = new Map();
-    const logger = options?.logger ?? getServerLogger();
-    /**
-     * Per-`(kind, modelId)` admission semaphores. Keyed by
-     * `slotKey(kind, modelId)`. Absent until the first gated `begin(...)`
-     * for that key; removed again the moment the key is idle.
-     */
-    const keyStates = new Map();
-    /**
-     * Reverse index from a queued waiter's `requestId` to its slot so
-     * `cancel({ requestId })` can pull a still-queued request out of the
-     * FIFO in O(1) without scanning every `KeyState`.
-     */
-    const waitersById = new Map();
-    /**
-     * Ids reserved synchronously at `begin(...)` start and cleared once the entry
-     * lands in `entries` (or the begin throws). A same-tick second `begin(...)`
-     * with the same id runs before the first reaches `entries`/`waitersById`, so
-     * without this it would slip past the duplicate check and both would execute.
-     */
-    const reservedIds = new Set();
-    // Models being torn down: a begin(...) for one starts aborted. The barrier
-    // half of cancelAndDrain — catches begins its scan can't see yet.
-    const drainingModels = new Set();
-    // Entries whose disposal has started but not finished. disposeEntry removes
-    // from `entries` before unwinding, so a drain must consult this too or it
-    // would return while a request is still tearing down natively.
-    const disposingEntries = new Set();
-    // Request ids whose entry is mid-disposal. disposeEntry drops the id from
-    // `entries` before its async scope unwinds; without this the id looks free
-    // during that gap, so a same-id begin could activate concurrently with the
-    // still-tearing-down request and a cancel would land as a cancel-before-begin
-    // tripwire that aborts a later reuse. Held until teardown completes.
-    const disposingIds = new Set();
-    function logLifecycle(event, ctx, durationMs) {
-        const modelId = ctx.modelId !== undefined ? ctx.modelId : '-';
-        const base = `[request-lifecycle] ${event} requestId=${ctx.requestId} kind=${ctx.kind} modelId=${modelId} state=${ctx.state}`;
-        const line = durationMs !== undefined ? `${base} durationMs=${durationMs}` : base;
-        // `failed` end emits at `warn` so log shippers can alert on
-        // `level>=warn` for this prefix without parsing `state=failed`
-        // out of the message body. Everything else stays at `info`.
-        if (event === 'end' && ctx.state === 'failed') {
-            logger.warn(line);
-        }
-        else {
-            logger.info(line);
-        }
-    }
-    /**
-     * "Cancelled-before-begin" tripwire. A
-     * `cancel({ requestId })` whose target isn't yet in `entries` records
-     * the id here; the subsequent `begin({ requestId: <same id> })` then
-     * aborts the new controller before returning. Map order is insertion
-     * order — the iterator's first key is the oldest entry, which makes
-     * the size-cap eviction free.
-     *
-     * Invariants:
-     *   - Every read path (`begin`, `cancel`-by-id) calls
-     *     `pruneCancelBeforeBeginExpired()` first so a 30s+ stale entry
-     *     never decides a fresh `begin(...)`.
-     *   - Insertion enforces the size cap by evicting the oldest entry
-     *     when at capacity — a malicious client cannot grow this map
-     *     unbounded.
-     *   - On a successful `begin(...)` match, the entry is consumed
-     *     (removed) so a second `begin(...)` with the same id (which
-     *     would itself throw `RequestIdConflictError`) doesn't see a
-     *     phantom pre-cancel.
-     */
-    const cancelledBeforeBegin = new Map();
-    function pruneCancelBeforeBeginExpired(now = Date.now()) {
-        if (cancelledBeforeBegin.size === 0)
-            return;
-        const cutoff = now - CANCEL_BEFORE_BEGIN_TTL_MS;
-        for (const [id, entry] of cancelledBeforeBegin) {
-            if (entry.at > cutoff)
-                break; // Insertion order ⇒ rest are newer.
-            cancelledBeforeBegin.delete(id);
-        }
-    }
-    function recordCancelBeforeBegin(requestId, reason) {
-        const now = Date.now();
-        pruneCancelBeforeBeginExpired(now);
-        // Re-canceling an id that is already tracked refreshes its TTL but
-        // keeps the original reason — the first cancel "won" the race.
-        if (cancelledBeforeBegin.has(requestId)) {
-            const existing = cancelledBeforeBegin.get(requestId);
-            cancelledBeforeBegin.delete(requestId);
-            cancelledBeforeBegin.set(requestId, { ...existing, at: now });
-            return;
-        }
-        if (cancelledBeforeBegin.size >= CANCEL_BEFORE_BEGIN_MAX_ENTRIES) {
-            const oldest = cancelledBeforeBegin.keys().next().value;
-            if (oldest !== undefined)
-                cancelledBeforeBegin.delete(oldest);
-        }
-        cancelledBeforeBegin.set(requestId, reason !== undefined ? { at: now, reason } : { at: now });
-    }
-    function consumeCancelBeforeBegin(requestId) {
-        pruneCancelBeforeBeginExpired();
-        const entry = cancelledBeforeBegin.get(requestId);
-        if (!entry)
-            return undefined;
-        cancelledBeforeBegin.delete(requestId);
-        return entry;
-    }
-    function slotKey(lane, modelId) {
-        // NUL separator can't appear in a lane (a closed-union kind or an
-        // SDK-controlled `sharedSlotGroup` label) or a modelId (sdkModelId is a
-        // generated handle), so the join is unambiguous.
-        return `${lane}\u0000${modelId}`;
-    }
-    /**
-     * Pull a waiter out of its queue and tidy up: clear its timeout, drop
-     * the reverse index, and delete the `KeyState` if that left it idle.
-     * Does NOT settle the waiter's promise — the caller decides whether the
-     * removal resolves (granted / graceful cancel) or rejects (timeout /
-     * teardown).
-     */
-    function removeWaiter(key, waiter, drainAfter = true) {
-        if (waiter.timer !== undefined) {
-            clearTimeout(waiter.timer);
-            waiter.timer = undefined;
-        }
-        waitersById.delete(waiter.requestId);
-        const st = keyStates.get(key);
-        if (!st)
-            return;
-        const i = st.waiters.indexOf(waiter);
-        if (i >= 0)
-            st.waiters.splice(i, 1);
-        // Removing a queued writer can unblock the readers behind it, so drain
-        // (which also deletes the KeyState once idle). `cancelAll` passes false:
-        // it's tearing every waiter down, so granting one mid-sweep is wrong.
-        if (drainAfter)
-            drain(st, key);
-        else if (st.active <= 0 && !st.exclusiveActive && st.waiters.length === 0) {
-            keyStates.delete(key);
-        }
-    }
-    /**
-     * Admission gate. Resolves to the slot key the caller must release on
-     * dispose, or `undefined` when the request is ungated (no policy, no
-     * `modelId`, an unbounded limit, or an already-aborted parent — which we
-     * let through so the normal abort path produces a clean cancelled
-     * outcome rather than queuing a doomed request).
-     *
-     * When the key is at capacity it either rejects (`onOverflow: "reject"`,
-     * queue-depth cap, or `queueTimeoutMs`) or enqueues a FIFO waiter and
-     * awaits it. The releaser hands a freed slot to the oldest waiter
-     * (`resolve(true)`), so `active` is never decremented and re-incremented
-     * across a hand-off — that's what guarantees FIFO fairness with no
-     * acquire/release race in the single-threaded event loop.
-     */
-    async function acquireSlot(opts) {
-        if (opts.modelId === undefined)
-            return { slotKey: undefined, exclusive: false };
-        const policy = policies.get(opts.kind);
-        if (!policy)
-            return { slotKey: undefined, exclusive: false };
-        // The per-request override (the model's own `parallel`) wins over the
-        // per-kind default. A non-finite effective cap disables gating entirely.
-        const requestedMax = opts.maxConcurrentPerModel ?? policy.maxConcurrent;
-        if (!Number.isFinite(requestedMax)) {
-            return { slotKey: undefined, exclusive: false };
-        }
-        const maxConcurrent = clampSlotCount(requestedMax);
-        // A parent (worker-shutdown) signal that's already aborted: don't
-        // queue behind live work that may never drain — let begin() proceed
-        // and abort immediately via the parentSignal path.
-        if (opts.parentSignal?.aborted)
-            return { slotKey: undefined, exclusive: false };
-        const modelId = opts.modelId;
-        // Lane precedence: the policy's shared group → the kind itself. A shared
-        // lane lets unrelated kinds contend for one slot pool per model.
-        const key = slotKey(policy.slotGroup ?? opts.kind, modelId);
-        let st = keyStates.get(key);
-        if (!st) {
-            st = { active: 0, waiters: [], exclusiveActive: false };
-            keyStates.set(key, st);
-        }
-        const exclusive = policy.exclusive;
-        // A reader admits below the lane's pinned cap (see `readerCap`); an exclusive
-        // writer needs the lane empty. A queued waiter (of any kind) blocks admission
-        // so a writer isn't starved by a steady reader stream. For reader-only lanes
-        // `waiters` is empty whenever `active < cap`, so this guard is a no-op there.
-        const readerCap = st.readerCap ?? maxConcurrent;
-        const canAdmit = st.waiters.length === 0 &&
-            !st.exclusiveActive &&
-            (exclusive ? st.active === 0 : st.active < readerCap);
-        if (canAdmit) {
-            if (exclusive) {
-                st.exclusiveActive = true;
-            }
-            else {
-                st.active++;
-                if (st.readerCap === undefined)
-                    st.readerCap = maxConcurrent;
-            }
-            return { slotKey: key, exclusive };
-        }
-        if (policy.onOverflow === 'reject') {
-            throw new RequestRejectedByPolicyError(opts.requestId, opts.kind, modelId, `another ${opts.kind} request is already running on this model`);
-        }
-        if (st.waiters.length >= policy.maxQueueDepth) {
-            throw new RequestRejectedByPolicyError(opts.requestId, opts.kind, modelId, `request queue for this model is full (${st.waiters.length} waiting)`);
-        }
-        const queue = st;
-        const granted = await new Promise((resolve, reject) => {
-            const waiter = {
-                requestId: opts.requestId,
-                kind: opts.kind,
-                modelId,
-                enqueuedAt: Date.now(),
-                resolve,
-                reject,
-                timer: undefined,
-                exclusive,
-                cap: maxConcurrent
-            };
-            if (policy.queueTimeoutMs !== undefined) {
-                const timeoutMs = policy.queueTimeoutMs;
-                waiter.timer = setTimeout(() => {
-                    removeWaiter(key, waiter);
-                    reject(new RequestRejectedByPolicyError(opts.requestId, opts.kind, modelId, `timed out waiting ${timeoutMs}ms for a slot on this model`));
-                }, timeoutMs);
-            }
-            queue.waiters.push(waiter);
-            waitersById.set(opts.requestId, { key, waiter });
-        });
-        return granted ? { slotKey: key, exclusive } : { slotKey: undefined, exclusive: false };
-    }
-    /**
-     * Grant the lane to as many FIFO-head waiters as now fit: an exclusive writer
-     * only when the lane is idle, readers up to each one's own cap. Stops at the
-     * first head that can't be admitted, so FIFO order holds. Deletes the
-     * `KeyState` once fully idle.
-     */
-    function drain(st, key) {
-        while (st.waiters.length > 0) {
-            const head = st.waiters[0];
-            if (head === undefined)
-                break;
-            if (head.exclusive) {
-                if (st.exclusiveActive || st.active > 0)
-                    break;
-                st.exclusiveActive = true;
-            }
-            else {
-                const readerCap = st.readerCap ?? head.cap;
-                if (st.exclusiveActive || st.active >= readerCap)
-                    break;
-                st.active++;
-                if (st.readerCap === undefined)
-                    st.readerCap = head.cap;
-            }
-            st.waiters.shift();
-            waitersById.delete(head.requestId);
-            if (head.timer !== undefined) {
-                clearTimeout(head.timer);
-                head.timer = undefined;
-            }
-            head.resolve(true);
-        }
-        if (st.active <= 0 && !st.exclusiveActive && st.waiters.length === 0) {
-            keyStates.delete(key);
-        }
-    }
-    /**
-     * Release a held slot, then hand the freed capacity to waiters. Called from
-     * `disposeEntry` after the scope has fully unwound, so its deferred teardown
-     * (for llama.cpp completion, disposing the run response that stops native
-     * decode) has run before the next same-model request is admitted.
-     */
-    function releaseSlot(key, wasExclusive) {
-        const st = keyStates.get(key);
-        if (!st)
-            return;
-        if (wasExclusive)
-            st.exclusiveActive = false;
-        else
-            st.active--;
-        drain(st, key);
-    }
-    function cancelEntry(entry, reason) {
-        if (entry.controller.signal.aborted)
-            return false;
-        entry.ctx.state = 'cancelling';
-        entry.controller.abort(reason);
-        logLifecycle('cancel', entry.ctx);
-        return true;
-    }
-    async function disposeEntry(entry, outcome) {
-        if (entry.scope.disposed || entry.disposing)
-            return;
-        entry.disposing = true;
-        disposingEntries.add(entry);
-        // Keep the id reserved across async teardown so a same-id begin can't
-        // activate concurrently and a cancel can't strand a tripwire for a reuse.
-        disposingIds.add(entry.ctx.requestId);
-        entry.ctx.state = outcome;
-        entry.detachParent();
-        logLifecycle('end', entry.ctx, Date.now() - entry.startedAt);
-        // Pull the entry out before unwinding so observers (e.g. a `cancel(...)`
-        // racing with dispose) don't see a half-disposed context.
-        entries.delete(entry.ctx.requestId);
-        try {
-            await entry.scope[Symbol.asyncDispose]();
-        }
-        finally {
-            // Release the admission slot only after the scope has fully unwound:
-            // the shared llama.cpp context / addon job is torn down in scope
-            // cleanup, so the next queued same-model request must not be admitted
-            // (and start decoding) until this one has actually let go. `finally`
-            // guarantees the slot is freed even if a deferred cleanup throws,
-            // otherwise a throwing teardown would strand the queue forever.
-            if (entry.slotKey !== undefined)
-                releaseSlot(entry.slotKey, entry.exclusive);
-            disposingEntries.delete(entry);
-            // The id is free for reuse only now that native teardown is complete.
-            disposingIds.delete(entry.ctx.requestId);
-            // Signal any `cancelAndDrain` waiting on this request that its native
-            // teardown is complete.
-            entry.resolveDisposed();
-        }
-    }
-    async function begin(opts) {
-        // A request id is reserved for its whole lifecycle: the time it spends
-        // *queued* for an admission slot, while it is active, and while it is
-        // tearing down. `waitersById` holds the still-queued begins (not yet in
-        // `entries`) and `disposingIds` holds the ones whose async teardown hasn't
-        // finished, so a duplicate id must be rejected against all of them —
-        // otherwise a second begin with the same id would enqueue behind the first
-        // and overwrite its `waitersById` index (unreachable by `cancel(...)`), or
-        // activate while the prior request is still releasing its native context.
-        if (entries.has(opts.requestId) ||
-            waitersById.has(opts.requestId) ||
-            reservedIds.has(opts.requestId) ||
-            disposingIds.has(opts.requestId)) {
-            throw new RequestIdConflictError(opts.requestId);
-        }
-        // Reserve synchronously so a same-tick duplicate begin is rejected before
-        // this one reaches `entries`/`waitersById`. Cleared on every exit below.
-        reservedIds.add(opts.requestId);
-        // A request cancelled BEFORE begin must not queue for a slot on a saturated
-        // lane: consume its marker first and skip admission, so it resolves at once
-        // into an aborted context holding no slot instead of waiting for the holder.
-        let preCancel = consumeCancelBeforeBegin(opts.requestId);
-        // Admission control runs before allocation so a rejected begin leaves no
-        // controller / scope behind. This may await: a gated `(kind, modelId)` at
-        // capacity queues the begin FIFO and resolves once a slot frees (or rejects
-        // on overflow / queue-depth cap / timeout).
-        let slotKey;
-        let exclusive = false;
-        if (!preCancel) {
-            // Plain try/catch, not `.catch()`, so admission adds no extra microtask
-            // and observers still see the request registered on the same tick.
-            let acquired;
-            try {
-                acquired = await acquireSlot(opts);
-            }
-            catch (err) {
-                reservedIds.delete(opts.requestId);
-                throw err;
-            }
-            slotKey = acquired.slotKey;
-            exclusive = acquired.exclusive;
-            // The only interleaving point in this otherwise synchronous body is the
-            // await above. A duplicate id could (astronomically unlikely) have landed
-            // while we were queued — re-check and hand the just-acquired slot back
-            // rather than stranding it on the conflicting throw.
-            if (entries.has(opts.requestId)) {
-                if (slotKey !== undefined)
-                    releaseSlot(slotKey, exclusive);
-                reservedIds.delete(opts.requestId);
-                throw new RequestIdConflictError(opts.requestId);
-            }
-            // A cancel that landed WHILE we were queued resolved acquireSlot with no
-            // slot and recorded a marker; consume it so the context starts aborted.
-            preCancel = consumeCancelBeforeBegin(opts.requestId);
-        }
-        // A begin arriving while its model is being torn down starts aborted — no
-        // native work against a model about to be freed.
-        const drainReason = opts.modelId !== undefined && drainingModels.has(opts.modelId) ? 'modelUnload' : undefined;
-        const controller = new AbortController();
-        const scope = createDisposableScope();
-        if (preCancel) {
-            controller.abort(preCancel.reason);
-        }
-        else if (drainReason) {
-            controller.abort(drainReason);
-        }
-        let detachParent = () => { };
-        if (opts.parentSignal) {
-            const parent = opts.parentSignal;
-            if (parent.aborted) {
-                controller.abort(parent.reason);
-            }
-            else {
-                const onParentAbort = () => controller.abort(parent.reason);
-                parent.addEventListener('abort', onParentAbort, { once: true });
-                detachParent = () => parent.removeEventListener('abort', onParentAbort);
-            }
-        }
-        const ctx = {
-            requestId: opts.requestId,
-            kind: opts.kind,
-            modelId: opts.modelId,
-            signal: controller.signal,
-            scope,
-            // Land the context in `cancelling` from the outset whenever the
-            // controller was already aborted by `begin(...)` itself — either
-            // the Stop-button race (`preCancel`) or a `parentSignal` that was
-            // already aborted at begin time. Both branches abort the
-            // controller above, so without this guard observers would see a
-            // momentarily-`running` context with an already-aborted signal.
-            state: preCancel || drainReason || opts.parentSignal?.aborted ? 'cancelling' : 'running'
-        };
-        let resolveDisposed = () => { };
-        const disposed = new Promise((resolve) => {
-            resolveDisposed = resolve;
-        });
-        const entry = {
-            ctx,
-            controller,
-            scope,
-            detachParent,
-            startedAt: Date.now(),
-            slotKey,
-            exclusive,
-            disposing: false,
-            disposed,
-            resolveDisposed
-        };
-        entries.set(opts.requestId, entry);
-        reservedIds.delete(opts.requestId);
-        logLifecycle('begin', ctx);
-        return {
-            get requestId() {
-                return ctx.requestId;
-            },
-            get kind() {
-                return ctx.kind;
-            },
-            get modelId() {
-                return ctx.modelId;
-            },
-            get signal() {
-                return ctx.signal;
-            },
-            get scope() {
-                return ctx.scope;
-            },
-            get state() {
-                return ctx.state;
-            },
-            set state(next) {
-                ctx.state = next;
-            },
-            [Symbol.asyncDispose]: async () => {
-                await disposeEntry(entry, derivedTerminalState(ctx));
-            }
-        };
-    }
-    function get(requestId) {
-        return entries.get(requestId)?.ctx ?? null;
-    }
-    function list() {
-        return Array.from(entries.values(), (e) => e.ctx);
-    }
-    /**
-     * Cancel a still-queued waiter the same way the Stop-button race is
-     * handled: record a cancel-before-begin so its `begin(...)` — which
-     * resumes the instant we `resolve(false)` (without a slot) — observes the
-     * cancel and returns an already-aborted context. The request thus ends in
-     * a clean `cancelled` state rather than throwing.
-     */
-    function cancelQueuedWaiterGracefully(key, waiter, reason) {
-        recordCancelBeforeBegin(waiter.requestId, reason);
-        removeWaiter(key, waiter);
-        waiter.resolve(false);
-    }
-    function cancel(target) {
-        let cancelled = 0;
-        if ('requestId' in target) {
-            const entry = entries.get(target.requestId);
-            if (entry) {
-                if (cancelEntry(entry, target.reason))
-                    cancelled++;
-                return cancelled;
-            }
-            // Queued (still waiting for an admission slot)? It has no controller
-            // yet, so cancel it through the cancel-before-begin tripwire: pull it
-            // from the FIFO and let its begin() resume into an aborted context.
-            // Counted as one — unlike the pure race below, this targets a known
-            // in-flight (queued) begin, so the Stop button feels responsive
-            // instead of waiting for the slot to free first.
-            const queued = waitersById.get(target.requestId);
-            if (queued) {
-                cancelQueuedWaiterGracefully(queued.key, queued.waiter, target.reason);
-                return cancelled + 1;
-            }
-            // Mid-disposal: the request already reached a terminal outcome and is
-            // releasing its native context. There is nothing to cancel, and a
-            // cancel-before-begin marker would wrongly abort a later begin that
-            // reuses this id once teardown frees it.
-            if (disposingIds.has(target.requestId))
-                return cancelled;
-            // Stop-button race: the client beat its own
-            // `begin(...)`. Record the cancel so the next matching `begin`
-            // aborts immediately. The return value stays 0 — no in-flight
-            // request was matched, which is still the truth — but the
-            // *effective* cancel will land when the begin arrives.
-            recordCancelBeforeBegin(target.requestId, target.reason);
-            return cancelled;
-        }
-        for (const entry of entries.values()) {
-            if (entry.ctx.modelId !== target.modelId)
-                continue;
-            if (target.kind && entry.ctx.kind !== target.kind)
-                continue;
-            if (cancelEntry(entry, target.reason))
-                cancelled++;
-        }
-        // Queued waiters aren't in `entries`; drain the ones matching this
-        // model (and optional kind) so a broad `cancel({ modelId })` doesn't
-        // strand them behind a request that's being cancelled out from under
-        // them. Snapshot first — `removeWaiter` mutates `waitersById`.
-        for (const { key, waiter } of Array.from(waitersById.values())) {
-            if (waiter.modelId !== target.modelId)
-                continue;
-            if (target.kind && waiter.kind !== target.kind)
-                continue;
-            cancelQueuedWaiterGracefully(key, waiter, target.reason);
-            cancelled++;
-        }
-        return cancelled;
-    }
-    function cancelAll(reason) {
-        for (const entry of entries.values()) {
-            cancelEntry(entry, reason);
-        }
-        // Drain every queued waiter so a shutdown / model-unload sweep can't
-        // leave a `begin(...)` promise hung forever — which would in turn block
-        // the unload waiting on a request that never resolves. Unlike the
-        // targeted cancels above these *reject* rather than resolve-into-
-        // aborted: the model / worker they queued against is being torn down,
-        // so there is nothing left for them to run. Snapshot first —
-        // `removeWaiter` mutates `waitersById`.
-        for (const { key, waiter } of Array.from(waitersById.values())) {
-            removeWaiter(key, waiter, false);
-            waiter.reject(new RequestRejectedByPolicyError(waiter.requestId, waiter.kind, waiter.modelId, `queued request cancelled (${reason})`));
-        }
-        // Fire-and-forget the abort; each handler unwinds on its own dispose path.
-        return Promise.resolve();
-    }
-    // Cancel and drain every request for a model, then run `teardown` with the
-    // admission barrier held — any begin for the model (including one still
-    // suspended in admission) starts aborted — lifting it afterward. Scoped so the
-    // barrier can't be left raised.
-    async function withModelDraining(modelId, teardown) {
-        drainingModels.add(modelId);
-        try {
-            // Abort each active request and collect its disposal promise, so we wait
-            // for every handler's scope to fully unwind (native context freed, slot
-            // released) before teardown. Snapshot first — `disposeEntry` mutates
-            // `entries`.
-            const draining = [];
-            for (const entry of entries.values()) {
-                if (entry.ctx.modelId !== modelId)
-                    continue;
-                cancelEntry(entry, 'modelUnload');
-                draining.push(entry.disposed);
-            }
-            // Requests already mid-disposal are out of `entries` but may still be
-            // tearing down natively — wait for them too.
-            for (const entry of disposingEntries) {
-                if (entry.ctx.modelId === modelId)
-                    draining.push(entry.disposed);
-            }
-            // Queued waiters never held a slot, so just abort their begins.
-            for (const { key, waiter } of Array.from(waitersById.values())) {
-                if (waiter.modelId === modelId)
-                    cancelQueuedWaiterGracefully(key, waiter, 'modelUnload');
-            }
-            await Promise.all(draining);
-            await teardown();
-        }
-        finally {
-            drainingModels.delete(modelId);
-        }
-    }
-    async function end(requestId, outcome) {
-        const entry = entries.get(requestId);
-        if (!entry)
-            return;
-        await disposeEntry(entry, outcome);
-    }
-    function policy(opts) {
-        policies.set(opts.kind, normalizePolicy(opts));
-    }
-    return {
-        begin,
-        get,
-        list,
-        cancel,
-        cancelAll,
-        withModelDraining,
-        end,
-        policy,
-        // Test-only: lets the registry race tests assert the bound
-        // invariants on the internal "cancelled-before-begin" set without
-        // exposing it as a public surface. Kept off the `RequestRegistry`
-        // interface (typed via the augmented return type below) so handler
-        // code can't depend on it accidentally.
-        __cancelBeforeBeginSize: () => cancelledBeforeBegin.size,
-        // Test-only: the number of live per-`(kind, modelId)` admission
-        // states. Lets the queue tests assert the map empties on drain /
-        // dispose (no `KeyState` leak). Also off the public interface.
-        __keyStateSize: () => keyStates.size
-    };
-}
-// A finite slot count floored to an integer >= 1: a value below 1 would gate
-// every request forever and a fractional one could over-admit. Callers gate on
-// `Number.isFinite` first — Infinity means "ungated" and must stay Infinity.
-function clampSlotCount(count) {
-    return Math.max(1, Math.floor(count));
-}
-/**
- * Resolve a `ConcurrencyPolicy` to concrete numbers, applying defaults and
- * the deprecated `oneAtATimePerModel` alias. Done once at registration so
- * the `begin(...)` hot path reads plain numbers.
- */
-function normalizePolicy(opts) {
-    let maxConcurrent;
-    let onOverflow;
-    if (opts.maxConcurrentPerModel !== undefined) {
-        maxConcurrent = opts.maxConcurrentPerModel;
-        onOverflow = opts.onOverflow ?? 'queue';
-    }
-    else if (opts.oneAtATimePerModel === true) {
-        // Legacy alias: at most one in-flight per model, reject the rest.
-        maxConcurrent = 1;
-        onOverflow = opts.onOverflow ?? 'reject';
-    }
-    else {
-        // Nothing configured (includes `oneAtATimePerModel: false`) ⇒ no gating.
-        maxConcurrent = Infinity;
-        onOverflow = opts.onOverflow ?? 'queue';
-    }
-    if (Number.isFinite(maxConcurrent))
-        maxConcurrent = clampSlotCount(maxConcurrent);
-    return {
-        maxConcurrent,
-        onOverflow,
-        maxQueueDepth: opts.maxQueueDepthPerModel ?? DEFAULT_MAX_QUEUE_DEPTH_PER_MODEL,
-        queueTimeoutMs: opts.queueTimeoutMs,
-        slotGroup: opts.sharedSlotGroup,
-        exclusive: opts.exclusive === true
-    };
-}
-/**
- * Test-only knobs exported for `request-registry.test.ts` so the bound
- * assertions can pin the documented limits without re-reading them via
- * fragile string comparison. **Not part of the public SDK surface.**
- *
- * @internal
- */
-export const __requestRegistryTestHooks = {
-    cancelBeforeBeginMaxEntries: CANCEL_BEFORE_BEGIN_MAX_ENTRIES,
-    cancelBeforeBeginTtlMs: CANCEL_BEFORE_BEGIN_TTL_MS,
-    defaultMaxQueueDepthPerModel: DEFAULT_MAX_QUEUE_DEPTH_PER_MODEL
-};
-function derivedTerminalState(ctx) {
-    if (ctx.state === 'failed')
-        return 'failed';
-    if (ctx.signal.aborted || ctx.state === 'cancelled')
-        return 'cancelled';
-    return 'completed';
-}