@aiwg/cli 2026.9.20 → 2026.9.21

package/dist/src/decision/admission.js

@@ -0,0 +1,550 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../security/artifact-trust.js';
+export class AdmissionError extends Error {
+    evidence;
+    retryable;
+    constructor(evidence, retryable) {
+        super(`decision admission ${evidence.decision}: ${evidence.reason}`);
+        this.evidence = evidence;
+        this.retryable = retryable;
+    }
+}
+const MAX_BREAKER_HISTORY = 64;
+const shareCap = (share, capacity) => Math.max(1, Math.floor(share * capacity));
+/** Shared, in-process controller. Hosts may share one instance across invocations. */
+export class DecisionAdmissionController {
+    limits;
+    now;
+    options;
+    active = 0;
+    activePrincipal = new Map();
+    activeWorkspace = new Map();
+    activeProvider = new Map();
+    activePrincipalProvider = new Map();
+    seenReservations = new Map();
+    /** Oldest waiter deferred on each token bucket; later work cannot drain its share. */
+    tokenReservations = new Map();
+    breakerHistory = [];
+    requestBuckets = new Map();
+    tokenBuckets = new Map();
+    costSpent = new Map();
+    tokensReserved = new Map();
+    attempts = new Map();
+    breakers = new Map();
+    providerPausedUntil = new Map();
+    queues = new Map();
+    laneCursor = 0;
+    retryPressure = 0;
+    timer;
+    constructor(
+    /** Returns null when the trusted profile has no limits for the request's provider. */
+    limits, now = Date.now, options = {}) {
+        this.limits = limits;
+        this.now = now;
+        this.options = options;
+    }
+    /** Aggregate counts only; suitable for load harness sampling. */
+    snapshot() {
+        return { active: this.active, queued: this.queuedCount() };
+    }
+    /** Bounded, metadata-only breaker transition history, oldest first. */
+    breakerTransitions() {
+        return structuredClone(this.breakerHistory);
+    }
+    /** True when no lease is active and no request is queued, optionally for one principal. */
+    idle(principalId) {
+        if (principalId === undefined)
+            return this.active === 0 && this.queuedCount() === 0;
+        return !this.activePrincipal.get(principalId) && this.queuedCount(request => request.principalId === principalId) === 0;
+    }
+    async acquire(request) {
+        const checked = this.preflight(request);
+        if (checked)
+            throw checked;
+        const lane = `${request.providerId}\u0000${request.workspaceId}\u0000${request.principalId}`;
+        const limits = this.limits(request);
+        const queueCounts = [this.queuedCount(candidate => candidate.principalId === request.principalId),
+            this.queuedCount(candidate => candidate.workspaceId === request.workspaceId),
+            this.queuedCount(candidate => candidate.providerId === request.providerId)];
+        const queueLimits = [limits.principal.maxQueueLength, limits.workspace.maxQueueLength, limits.provider.maxQueueLength];
+        if (queueLimits.some((limit, index) => limit !== undefined && queueCounts[index] >= limit)) {
+            throw this.error('queue-full', 'reject', request, true, this.jitterHint(250));
+        }
+        // A principal's share of a shared queue is capped so one noisy scope cannot
+        // fill it and turn other principals' requests into queue-full rejections.
+        const ownQueued = [
+            this.queuedCount(candidate => candidate.principalId === request.principalId && candidate.workspaceId === request.workspaceId),
+            this.queuedCount(candidate => candidate.principalId === request.principalId && candidate.providerId === request.providerId),
+        ];
+        if ([limits.workspace, limits.provider].some((limit, index) => limit.maxPrincipalShare !== undefined
+            && limit.maxQueueLength !== undefined && ownQueued[index] >= shareCap(limit.maxPrincipalShare, limit.maxQueueLength))) {
+            throw this.error('queue-full', 'reject', request, true, this.jitterHint(250));
+        }
+        if (!this.options.principals && limits.principal.reservedConcurrency)
+            this.seenReservations.set(request.principalId, limits.principal);
+        return await new Promise((resolve, reject) => {
+            const queue = this.queues.get(lane) ?? [];
+            const cancelled = () => { this.remove(request, 'cancelled'); };
+            request.signal.addEventListener('abort', cancelled, { once: true });
+            queue.push({ request, resolve, reject, enqueuedAt: this.now(),
+                cleanup: () => {
+                    request.signal.removeEventListener('abort', cancelled);
+                    for (const [key, holder] of this.tokenReservations)
+                        if (holder.request === request)
+                            this.tokenReservations.delete(key);
+                } });
+            this.queues.set(lane, queue);
+            this.pump();
+        });
+    }
+    coordinateRetryAfter(providerId, retryAfterMs) {
+        this.providerPausedUntil.set(providerId, Math.max(this.providerPausedUntil.get(providerId) ?? 0, this.now() + Math.max(0, retryAfterMs)));
+        this.retryPressure += 1;
+        this.schedulePump(Math.max(1, retryAfterMs));
+    }
+    /** Release invocation-scoped counters once every active lease has settled. */
+    releaseBudget(budgetId) {
+        const prefix = `${budgetId}:`;
+        for (const key of this.attempts.keys())
+            if (key.startsWith(prefix))
+                this.attempts.delete(key);
+        for (const key of this.costSpent.keys())
+            if (key.startsWith(prefix))
+                this.costSpent.delete(key);
+        for (const key of this.tokensReserved.keys())
+            if (key.startsWith(prefix))
+                this.tokensReserved.delete(key);
+    }
+    preflight(request) {
+        const scoped = this.limits(request);
+        const estimate = request.estimate;
+        if (request.signal.aborted)
+            return this.error('cancelled', 'reject', request, false);
+        if (!scoped)
+            return this.error('unconfigured-provider', 'reject', request, false);
+        const all = Object.values(scoped);
+        if (this.now() >= request.deadlineEpochMs)
+            return this.error('deadline-exceeded', 'reject', request, false);
+        for (const count of [estimate.tokens, estimate.requestBytes, estimate.items, estimate.attempts, estimate.batchSize, estimate.retainedWork]) {
+            if (count !== undefined && (!Number.isSafeInteger(count) || count < 0)) {
+                return this.error('invalid-estimate', 'reject', request, false);
+            }
+        }
+        if (estimate.costUsd !== undefined && estimate.costUsd !== null
+            && (!Number.isFinite(estimate.costUsd) || estimate.costUsd < 0)) {
+            return this.error('invalid-estimate', 'reject', request, false);
+        }
+        for (const limit of all) {
+            if (estimate.batchSize !== undefined && limit.maxBatchSize !== undefined && estimate.batchSize > limit.maxBatchSize)
+                return this.error('batch-size', 'reject', request, false);
+            if (estimate.requestBytes !== undefined && limit.maxRequestBytes !== undefined && estimate.requestBytes > limit.maxRequestBytes)
+                return this.error('request-too-large', 'reject', request, false);
+            if (estimate.items !== undefined && limit.maxItems !== undefined && estimate.items > limit.maxItems)
+                return this.error('too-many-items', 'reject', request, false);
+            if (limit.maxRetainedWork !== undefined && estimate.retainedWork === undefined)
+                return this.error('unknown-retained-work', 'reject', request, false);
+            if (estimate.retainedWork !== undefined && limit.maxRetainedWork !== undefined && estimate.retainedWork > limit.maxRetainedWork)
+                return this.error('retained-work', 'reject', request, false);
+            if (estimate.costUsd == null && limit.maxCostUsd !== undefined && !limit.allowUnknownCost)
+                return this.error('unknown-cost', 'reject', request, false);
+            if (estimate.tokens === undefined && limit.maxTokens !== undefined)
+                return this.error('unknown-tokens', 'reject', request, false);
+        }
+        return null;
+    }
+    pump() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        const lanes = [...this.queues.keys()].filter(lane => this.queues.get(lane)?.length);
+        if (!lanes.length)
+            return;
+        let nearest = Number.POSITIVE_INFINITY;
+        let progressed = true;
+        while (progressed) {
+            progressed = false;
+            for (let offset = 0; offset < lanes.length; offset += 1) {
+                const position = (this.laneCursor + offset) % lanes.length;
+                const queue = this.queues.get(lanes[position]);
+                const waiter = queue[0];
+                if (!waiter)
+                    continue;
+                const waitLimit = Math.min(...Object.values(this.limits(waiter.request) ?? {}).map(limit => limit.maxQueueWaitMs ?? Number.POSITIVE_INFINITY));
+                if (waiter.request.signal.aborted || this.now() >= waiter.request.deadlineEpochMs || this.now() - waiter.enqueuedAt >= waitLimit) {
+                    queue.shift();
+                    waiter.cleanup();
+                    waiter.reject(this.error(waiter.request.signal.aborted ? 'cancelled' : this.now() >= waiter.request.deadlineEpochMs ? 'deadline-exceeded' : 'queue-timeout', 'reject', waiter.request, false));
+                    progressed = true;
+                    continue;
+                }
+                // A profile may tighten while a client is queued. Recheck non-concurrency
+                // limits at dispatch, not only when the waiter first enters the queue.
+                const admitted = this.preflight(waiter.request) ?? this.tryAdmit(waiter);
+                if (admitted instanceof AdmissionError) {
+                    if (!admitted.retryable) {
+                        queue.shift();
+                        waiter.cleanup();
+                        waiter.reject(admitted);
+                        progressed = true;
+                    }
+                    else
+                        nearest = Math.min(nearest, admitted.evidence.retryAfterMs ?? 25, Math.max(1, waiter.request.deadlineEpochMs - this.now()), Math.max(1, waitLimit - (this.now() - waiter.enqueuedAt)));
+                    continue;
+                }
+                queue.shift();
+                waiter.cleanup();
+                this.laneCursor = (position + 1) % lanes.length;
+                waiter.resolve(admitted);
+                progressed = true;
+            }
+        }
+        for (const [lane, queue] of this.queues)
+            if (!queue.length)
+                this.queues.delete(lane);
+        if (this.queuedCount())
+            this.schedulePump(Number.isFinite(nearest) ? nearest : 25);
+    }
+    tryAdmit(waiter) {
+        const request = waiter.request;
+        const { principal, workspace, provider } = this.limits(request);
+        const limits = [principal, workspace, provider];
+        const counts = [this.activePrincipal.get(request.principalId) ?? 0, this.activeWorkspace.get(request.workspaceId) ?? 0, this.activeProvider.get(request.providerId) ?? 0];
+        if (limits.some((limit, index) => counts[index] >= limit.concurrency))
+            return this.error('concurrency', 'defer', request, true, 10);
+        const ownProvider = this.activePrincipalProvider.get(`${request.providerId}\u0000${request.principalId}`) ?? 0;
+        if ((workspace.maxPrincipalShare !== undefined && counts[0] >= shareCap(workspace.maxPrincipalShare, workspace.concurrency))
+            || (provider.maxPrincipalShare !== undefined && ownProvider >= shareCap(provider.maxPrincipalShare, provider.concurrency))
+            || !this.withinReservations(request, principal, workspace.concurrency, counts[1], counts[0], id => this.activePrincipal.get(id) ?? 0)
+            || !this.withinReservations(request, principal, provider.concurrency, counts[2], ownProvider, id => this.activePrincipalProvider.get(`${request.providerId}\u0000${id}`) ?? 0)) {
+            return this.error('concurrency', 'defer', request, true, 10);
+        }
+        const breaker = this.breaker(request.providerId);
+        const breakerConfig = provider.circuitBreaker;
+        const transitions = [];
+        const pausedUntil = this.providerPausedUntil.get(request.providerId) ?? 0;
+        if (this.now() < pausedUntil)
+            return this.error('retry-after', 'defer', request, true, pausedUntil - this.now());
+        if (breaker.state === 'open') {
+            const readyAt = breaker.openedAt + (breakerConfig?.openMs ?? 30_000);
+            if (this.now() < readyAt)
+                return this.error('circuit-open', 'defer', request, true, readyAt - this.now());
+            this.transition(request.providerId, breaker, 'half-open', transitions);
+            breaker.halfOpenActive = 0;
+        }
+        if (breaker.state === 'half-open' && breaker.halfOpenActive >= (breakerConfig?.halfOpenMaxCalls ?? 1))
+            return this.error('circuit-open', 'defer', request, true, 25);
+        const keys = [[`p:${request.principalId}`, principal], [`w:${request.workspaceId}`, workspace], [`v:${request.providerId}`, provider]];
+        for (const [key, limit] of keys) {
+            const budgetKey = `${request.budgetId}:${key}`;
+            if (limit.maxAttempts !== undefined && (this.attempts.get(budgetKey) ?? 0) + (request.estimate.attempts ?? 1) > limit.maxAttempts)
+                return this.error('attempts', 'reject', request, false);
+            if (limit.maxCostUsd !== undefined && request.estimate.costUsd != null && (this.costSpent.get(budgetKey) ?? 0) + request.estimate.costUsd > limit.maxCostUsd)
+                return this.error('cost', 'reject', request, false);
+            if (limit.maxTokens !== undefined && (this.tokensReserved.get(budgetKey) ?? 0) + (request.estimate.tokens ?? 0) > limit.maxTokens)
+                return this.error('tokens', 'reject', request, false);
+            // A bucket can never refill beyond its capacity. Fail permanently rather
+            // than retaining an impossible waiter until its deadline or queue timeout.
+            if (limit.requestsPerMinute === 0)
+                return this.error('requests-per-minute', 'reject', request, false);
+            if (limit.tokensPerSecond !== undefined && (request.estimate.tokens ?? 0) > limit.tokensPerSecond)
+                return this.error('tokens-per-second', 'reject', request, false);
+            if (limit.requestsPerMinute !== undefined && !this.canConsume(this.requestBuckets, key, limit.requestsPerMinute, limit.requestsPerMinute / 60_000, 1))
+                return this.error('requests-per-minute', 'defer', request, true, 100);
+            if (limit.tokensPerSecond !== undefined) {
+                const holder = this.tokenReservations.get(key);
+                const reserved = holder && holder !== waiter ? holder.request.estimate.tokens ?? 0 : 0;
+                if (!this.canConsume(this.tokenBuckets, key, limit.tokensPerSecond, limit.tokensPerSecond / 1000, (request.estimate.tokens ?? 0) + reserved)) {
+                    if (!holder)
+                        this.tokenReservations.set(key, waiter);
+                    return this.error('tokens-per-second', 'defer', request, true, 100);
+                }
+            }
+        }
+        keys.forEach(([key, limit]) => {
+            this.consume(this.requestBuckets, key, limit.requestsPerMinute, limit.requestsPerMinute === undefined ? 0 : limit.requestsPerMinute / 60_000, 1);
+            this.consume(this.tokenBuckets, key, limit.tokensPerSecond, limit.tokensPerSecond === undefined ? 0 : limit.tokensPerSecond / 1000, request.estimate.tokens ?? 0);
+            const budgetKey = `${request.budgetId}:${key}`;
+            this.attempts.set(budgetKey, (this.attempts.get(budgetKey) ?? 0) + (request.estimate.attempts ?? 1));
+            if (request.estimate.costUsd != null)
+                this.costSpent.set(budgetKey, (this.costSpent.get(budgetKey) ?? 0) + request.estimate.costUsd);
+            if (request.estimate.tokens !== undefined)
+                this.tokensReserved.set(budgetKey, (this.tokensReserved.get(budgetKey) ?? 0) + request.estimate.tokens);
+        });
+        this.active += 1;
+        this.increment(this.activePrincipal, request.principalId);
+        this.increment(this.activeWorkspace, request.workspaceId);
+        this.increment(this.activeProvider, request.providerId);
+        this.increment(this.activePrincipalProvider, `${request.providerId}\u0000${request.principalId}`);
+        for (const [key, holder] of this.tokenReservations)
+            if (holder === waiter)
+                this.tokenReservations.delete(key);
+        if (breaker.state === 'half-open')
+            breaker.halfOpenActive += 1;
+        let released = false;
+        const evidence = this.evidence('admitted', 'admit', request, this.now() - waiter.enqueuedAt);
+        if (transitions.length)
+            evidence.breakerTransitions = transitions;
+        return { evidence, release: outcome => {
+                if (released)
+                    return;
+                released = true;
+                this.active -= 1;
+                this.decrement(this.activePrincipal, request.principalId);
+                this.decrement(this.activeWorkspace, request.workspaceId);
+                this.decrement(this.activeProvider, request.providerId);
+                this.decrement(this.activePrincipalProvider, `${request.providerId}\u0000${request.principalId}`);
+                if (breaker.state === 'half-open')
+                    breaker.halfOpenActive = Math.max(0, breaker.halfOpenActive - 1);
+                // Transitions after release are appended to this lease's evidence so the
+                // attempt that caused them carries them into receipts and telemetry.
+                const after = evidence.breakerTransitions ?? [];
+                if (outcome?.retryAfterMs !== undefined)
+                    this.coordinateRetryAfter(request.providerId, outcome.retryAfterMs);
+                else if (outcome?.success) {
+                    breaker.failures = 0;
+                    if (breaker.state !== 'closed')
+                        this.transition(request.providerId, breaker, 'closed', after);
+                }
+                else if (outcome && breakerConfig && ++breaker.failures >= breakerConfig.failureThreshold && breaker.state !== 'open') {
+                    breaker.openedAt = this.now();
+                    this.transition(request.providerId, breaker, 'open', after);
+                }
+                if (after.length)
+                    evidence.breakerTransitions = after;
+                this.pump();
+            } };
+    }
+    transition(providerId, breaker, to, into) {
+        const change = { from: breaker.state, to };
+        breaker.state = to;
+        into.push(change);
+        const record = { providerId, ...change, atEpochMs: this.now(), failures: breaker.failures };
+        this.breakerHistory.push(record);
+        if (this.breakerHistory.length > MAX_BREAKER_HISTORY)
+            this.breakerHistory.shift();
+        try {
+            this.options.onBreakerTransition?.(structuredClone(record));
+        }
+        catch { /* observers cannot change admission */ }
+    }
+    /**
+     * Other principals' unused `reservedConcurrency` is held back from a shared
+     * pool. A principal still inside its own reservation needs one free permit.
+     */
+    withinReservations(request, principal, capacity, active, ownActive, activeOf) {
+        const free = capacity - active;
+        if (ownActive < Math.min(principal.reservedConcurrency ?? 0, capacity))
+            return free >= 1;
+        let held = 0;
+        for (const [principalId, limits] of this.options.principals?.() ?? this.seenReservations) {
+            if (principalId === request.principalId || !limits.reservedConcurrency)
+                continue;
+            held += Math.max(0, Math.min(limits.reservedConcurrency, capacity) - activeOf(principalId));
+        }
+        return free - held >= 1;
+    }
+    breaker(provider) { let value = this.breakers.get(provider); if (!value) {
+        value = { state: 'closed', failures: 0, openedAt: 0, halfOpenActive: 0 };
+        this.breakers.set(provider, value);
+    } return value; }
+    queuedCount(predicate = () => true) {
+        return [...this.queues.values()].reduce((sum, queue) => sum + queue.filter(waiter => predicate(waiter.request)).length, 0);
+    }
+    increment(map, key) { map.set(key, (map.get(key) ?? 0) + 1); }
+    decrement(map, key) { const next = (map.get(key) ?? 1) - 1; if (next)
+        map.set(key, next);
+    else
+        map.delete(key); }
+    canConsume(map, key, capacity, rate, amount) { const bucket = this.refill(map, key, capacity, rate); return bucket.value >= amount; }
+    consume(map, key, capacity, rate, amount) { if (capacity === undefined)
+        return; const bucket = this.refill(map, key, capacity, rate); bucket.value -= amount; }
+    refill(map, key, capacity, rate) { const at = this.now(); let bucket = map.get(key); if (!bucket) {
+        bucket = { value: capacity, updatedAt: at };
+        map.set(key, bucket);
+    }
+    else {
+        bucket.value = Math.min(capacity, bucket.value + Math.max(0, at - bucket.updatedAt) * rate);
+        bucket.updatedAt = at;
+    } return bucket; }
+    remove(request, reason) { for (const queue of this.queues.values()) {
+        const index = queue.findIndex(waiter => waiter.request === request);
+        if (index >= 0) {
+            const [waiter] = queue.splice(index, 1);
+            waiter.cleanup();
+            waiter.reject(this.error(reason, 'reject', request, false));
+            break;
+        }
+    } this.pump(); }
+    evidence(reason, decision, request, queueDelayMs = 0, retryAfterMs) { const breaker = this.breaker(request.providerId); return { decision, reason, queueDelayMs: Math.max(0, queueDelayMs), active: this.activePrincipal.get(request.principalId) ?? 0, queued: Math.max(0, this.queuedCount(candidate => candidate.principalId === request.principalId) - ([...this.queues.values()].some(queue => queue.some(waiter => waiter.request === request)) ? 1 : 0)), estimatedTokens: Number.isSafeInteger(request.estimate.tokens) && request.estimate.tokens >= 0 ? request.estimate.tokens : null, estimatedCostUsd: request.estimate.costUsd != null && Number.isFinite(request.estimate.costUsd) && request.estimate.costUsd >= 0 ? request.estimate.costUsd : null, retryPressure: this.retryPressure, breakerState: breaker.state, ...(retryAfterMs === undefined ? {} : { retryAfterMs: this.jitterHint(retryAfterMs) }) }; }
+    error(reason, decision, request, retryable, retryAfterMs) { return new AdmissionError(this.evidence(reason, decision, request, 0, retryAfterMs), retryable); }
+    jitterHint(value) { return Math.max(1, Math.min(30_000, Math.round(value * 0.875))); }
+    schedulePump(delay) { if (this.timer)
+        return; this.timer = setTimeout(() => { this.timer = undefined; this.pump(); }, Math.max(1, Math.min(delay, 30_000))); }
+}
+/** A scheduler profile the registry refuses; the evaluator reports it as an invalid definition. */
+export class AdmissionProfileError extends Error {
+}
+export class AdmissionProfileConflictError extends AdmissionProfileError {
+    constructor() { super('scheduler profile revision conflicts with the registered revision'); }
+}
+const MAX_TRACKED_REVISIONS = 4096;
+const MAX_TRACKED_PRINCIPALS = 4096;
+const MAX_PROFILE_HISTORY = 64;
+/**
+ * Trusted-scope controller registry. Admission state is keyed by the host's
+ * workspace ID, not by the identity of the policy object, so structurally equal
+ * policies built per request share principal, workspace, and provider ceilings.
+ *
+ * The most recently registered `profileVersion` supplies the current limits for
+ * a workspace (queued work is revalidated against it). Registering different
+ * limits under a revision already seen for the same scope fails closed: a
+ * changed profile must carry a new `profileVersion`. Every change of revision
+ * produces an audit record.
+ */
+export class DecisionAdmissionRegistry {
+    maxIdleScopes;
+    scopes = new Map();
+    profileListeners = new Set();
+    breakerListeners = new Set();
+    constructor(maxIdleScopes = 1024) {
+        this.maxIdleScopes = maxIdleScopes;
+    }
+    /** Record the policy as the workspace's current profile and return its controller. */
+    register(policy, now = Date.now) {
+        validateShares(policy);
+        const scope = this.scopeFor(policy, now);
+        const workspaceDigest = canonicalJson({ workspace: policy.workspace.limits, providers: policy.providers });
+        const principalDigest = canonicalJson(policy.principal.limits);
+        const workspaceKey = `w\u0000${policy.profileVersion}`;
+        const principalKey = `p\u0000${policy.principal.id}\u0000${policy.profileVersion}`;
+        const knownWorkspace = scope.revisions.get(workspaceKey);
+        const knownPrincipal = scope.revisions.get(principalKey);
+        if ((knownWorkspace !== undefined && knownWorkspace !== workspaceDigest)
+            || (knownPrincipal !== undefined && knownPrincipal !== principalDigest))
+            throw new AdmissionProfileConflictError();
+        const reserved = [...scope.principals].reduce((sum, [principalId, limits]) => principalId === policy.principal.id ? sum : sum + (limits.reservedConcurrency ?? 0), policy.principal.limits.reservedConcurrency ?? 0);
+        const pools = [policy.workspace.limits, ...Object.values(policy.providers)];
+        if (reserved > 0 && pools.some(limit => reserved > limit.concurrency)) {
+            throw new AdmissionProfileError('scheduler principal reservations exceed shared workspace or provider concurrency');
+        }
+        const changed = scope.history.length === 0 || scope.profileVersion !== policy.profileVersion;
+        const rollback = changed && knownWorkspace !== undefined;
+        this.remember(scope.revisions, workspaceKey, workspaceDigest, MAX_TRACKED_REVISIONS);
+        this.remember(scope.revisions, principalKey, principalDigest, MAX_TRACKED_REVISIONS);
+        const previousProfileVersion = scope.history.length ? scope.profileVersion : null;
+        scope.profileVersion = policy.profileVersion;
+        scope.workspace = structuredClone(policy.workspace.limits);
+        scope.providers = structuredClone(policy.providers);
+        scope.principals.delete(policy.principal.id);
+        scope.principals.set(policy.principal.id, structuredClone(policy.principal.limits));
+        for (const principalId of scope.principals.keys()) {
+            if (scope.principals.size <= MAX_TRACKED_PRINCIPALS)
+                break;
+            if (principalId !== policy.principal.id && scope.controller.idle(principalId))
+                scope.principals.delete(principalId);
+        }
+        if (changed) {
+            const record = {
+                schema: 'decision-admission-profile-change/v1', workspaceId: policy.workspace.id,
+                kind: previousProfileVersion === null ? 'initial' : rollback ? 'rollback' : 'change',
+                previousProfileVersion, profileVersion: policy.profileVersion,
+                digest: `sha256:${createHash('sha256').update(workspaceDigest).digest('hex')}`, atEpochMs: scope.now(),
+            };
+            scope.history.push(record);
+            if (scope.history.length > MAX_PROFILE_HISTORY)
+                scope.history.shift();
+            for (const listener of this.profileListeners) {
+                try {
+                    listener(structuredClone(record));
+                }
+                catch { /* audit sinks cannot change admission */ }
+            }
+        }
+        return scope.controller;
+    }
+    /** The workspace's controller, registering the policy only when the scope is unknown. */
+    controllerFor(policy, now = Date.now) {
+        const scope = this.scopes.get(policy.workspace.id);
+        return scope?.principals.has(policy.principal.id) ? scope.controller : this.register(policy, now);
+    }
+    controller(workspaceId) {
+        return this.scopes.get(workspaceId)?.controller;
+    }
+    /** Bounded audit history of profile revisions for one workspace, oldest first. */
+    profileHistory(workspaceId) {
+        return structuredClone(this.scopes.get(workspaceId)?.history ?? []);
+    }
+    /** Subscribe to profile-change audit records. Returns an unsubscribe function. */
+    onProfileChange(listener) {
+        this.profileListeners.add(listener);
+        return () => { this.profileListeners.delete(listener); };
+    }
+    /** Subscribe to breaker transitions in every workspace scope. Returns an unsubscribe function. */
+    onBreakerTransition(listener) {
+        this.breakerListeners.add(listener);
+        return () => { this.breakerListeners.delete(listener); };
+    }
+    scopeFor(policy, now) {
+        let scope = this.scopes.get(policy.workspace.id);
+        if (!scope) {
+            const created = { controller: undefined, now,
+                profileVersion: policy.profileVersion, workspace: policy.workspace.limits, providers: policy.providers,
+                principals: new Map(), revisions: new Map(), history: [] };
+            created.controller = this.controllerOf(created);
+            this.scopes.set(policy.workspace.id, created);
+            for (const [workspaceId, candidate] of this.scopes) {
+                if (this.scopes.size <= this.maxIdleScopes)
+                    break;
+                if (candidate !== created && candidate.controller.idle())
+                    this.scopes.delete(workspaceId);
+            }
+            scope = created;
+        }
+        else if (scope.now !== now && scope.controller.idle()) {
+            // An injected clock is a test seam. Switching clocks restarts idle state;
+            // a busy scope keeps its clock so live counters are never discarded.
+            scope.now = now;
+            scope.controller = this.controllerOf(scope);
+        }
+        return scope;
+    }
+    controllerOf(scope) {
+        return new DecisionAdmissionController(request => {
+            const principal = scope.principals.get(request.principalId);
+            const provider = scope.providers[request.providerId];
+            return principal && provider ? { principal, workspace: scope.workspace, provider } : null;
+        }, scope.now, {
+            principals: () => scope.principals,
+            onBreakerTransition: transition => {
+                for (const listener of this.breakerListeners) {
+                    try {
+                        listener(structuredClone(transition));
+                    }
+                    catch { /* observers cannot change admission */ }
+                }
+            },
+        });
+    }
+    remember(map, key, value, maximum) {
+        map.delete(key);
+        map.set(key, value);
+        while (map.size > maximum)
+            map.delete(map.keys().next().value);
+    }
+}
+function validateShares(policy) {
+    const reserved = policy.principal.limits.reservedConcurrency;
+    if (reserved !== undefined && (!Number.isSafeInteger(reserved) || reserved < 0 || reserved > policy.principal.limits.concurrency)) {
+        throw new AdmissionProfileError('scheduler reserved concurrency must be an integer within the principal concurrency');
+    }
+    for (const limit of [policy.workspace.limits, policy.principal.limits, ...Object.values(policy.providers)]) {
+        const share = limit.maxPrincipalShare;
+        if (share !== undefined && (!Number.isFinite(share) || share <= 0 || share > 1)) {
+            throw new AdmissionProfileError('scheduler principal share must be greater than 0 and at most 1');
+        }
+    }
+}
+/** Process-wide registry used by the evaluator. */
+export const decisionAdmissionRegistry = new DecisionAdmissionRegistry();
+//# sourceMappingURL=admission.js.map

package/dist/src/decision/batch-benchmark.js

@@ -0,0 +1,47 @@
+function finiteNonNegative(value, label) {
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error(`${label} must be finite and non-negative`);
+}
+function sumKnown(values) {
+    return values.some(value => value === null) ? null : values.reduce((sum, value) => sum + value, 0);
+}
+function summarize(samples) {
+    return {
+        samples: samples.length,
+        providerCalls: samples.reduce((sum, value) => sum + value.providerCalls, 0),
+        inputTokens: sumKnown(samples.map(value => value.inputTokens)),
+        outputTokens: sumKnown(samples.map(value => value.outputTokens)),
+        latencyMs: samples.reduce((sum, value) => sum + value.latencyMs, 0),
+    };
+}
+/**
+ * Produces workload-pinned comparative evidence without asserting that a
+ * synthetic improvement generalizes to another provider, model, or workload.
+ */
+export function decisionBatchBenchmarkReport(workloadDigest, samples) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(workloadDigest))
+        throw new Error('invalid workload digest');
+    for (const sample of samples) {
+        if (!Number.isSafeInteger(sample.providerCalls) || sample.providerCalls < 1) {
+            throw new Error('providerCalls must be a positive integer');
+        }
+        finiteNonNegative(sample.latencyMs, 'latencyMs');
+        if (sample.inputTokens !== null)
+            finiteNonNegative(sample.inputTokens, 'inputTokens');
+        if (sample.outputTokens !== null)
+            finiteNonNegative(sample.outputTokens, 'outputTokens');
+    }
+    const nativeBatch = samples.filter(sample => sample.mode === 'native-batch');
+    const singleCall = samples.filter(sample => sample.mode === 'single-call');
+    if (nativeBatch.length === 0 || nativeBatch.length !== singleCall.length) {
+        throw new Error('paired batch benchmark requires equal non-empty mode samples');
+    }
+    return {
+        schemaVersion: 'decision-batch-benchmark/v1',
+        workloadDigest,
+        repetitions: nativeBatch.length,
+        nativeBatch: summarize(nativeBatch),
+        singleCall: summarize(singleCall),
+    };
+}
+//# sourceMappingURL=batch-benchmark.js.map