import { DecisionAdmissionRegistry } from '../admission.js'; import type { AdapterObservation, DecisionAdmissionEvidence, DecisionAdmissionLimits, DecisionSchedulerPolicy } from '../types.js'; import { type DecisionLoadManifestV3, type DecisionStagedLoadRecord, type DecisionStagedLoadRecordV1 } from './load-staged.js'; export * from './load-staged.js'; export type DecisionLoadManifest = DecisionLoadManifestV2 | DecisionLoadManifestV3; /** Preregistered D05 load manifest. Bounds are inputs; a changed bound needs a new version. */ export interface DecisionLoadManifestV2 { schema: 'decision-load-manifest/v2'; version: string; mode: 'offline-fake-provider' | 'staged-provider'; profileVersion: string; workspace: DecisionAdmissionLimits; providers: Record; principals: Array<{ id: string; class: 'noisy' | 'quiet'; weight: number; limits: DecisionAdmissionLimits; }>; arrivalModel: { kind: 'seeded-bursty-poisson'; seed: number; averageRequestsPerSecond: number; spikeMultiplier: number; spikeDurationSeconds: number; smallTokens: number; hugeTokens: number; hugeTokenShare: number; serviceTimeMs: { minimum: number; maximum: number; }; retryableFailureRate: number; maxRetries: number; retryBackoffMs: number; cancellationRate: number; cancelAfterMs: number; }; duration: { loadSeconds: number; spikeSeconds: number; soakSeconds: number; evaluatorSampleSeconds: number; }; bounds: { maximumActiveCalls: number; maximumQueuedCalls: number; /** Peak V8 heap of the harness isolate. Process RSS is recorded but shared with the test runner. */ maximumHeapUsedMiB: number; maximumCpuPercentOneCore: number; maximumEligibleLaneWaitMs: number; maximumRetryAmplificationRatio: number; maximumCancellationLatencyMs: number; minimumQuietPrincipalAdmissionRatio: number; }; passFail: { allBoundsMustPass: true; liveServiceRequired: boolean; }; } export interface DecisionLoadArrival { ordinal: number; atMs: number; principalId: string; principalClass: 'noisy' | 'quiet'; providerId: string; tokens: number; serviceMs: number; failsFirstAttempt: boolean; cancelAtMs: number | null; } export interface DecisionLoadClock { now(): number; /** Advance virtual time and run every timer that falls due. */ advance(ms: number): Promise; } export interface DecisionLoadOutcome { attempts: number; outcome: 'completed' | 'failed' | 'shed' | 'cancelled'; admissionReason?: DecisionAdmissionEvidence['reason']; queueDelaysMs: number[]; settledAtMs: number; } export interface DecisionLoadDriverContext { clock: DecisionLoadClock; manifest: DecisionLoadManifest; /** Simulated provider call. Counts active calls and ends early when the signal aborts. */ dispatch(serviceMs: number, signal: AbortSignal): Promise<'completed' | 'aborted'>; } export type DecisionLoadDriver = (arrival: DecisionLoadArrival, signal: AbortSignal, context: DecisionLoadDriverContext) => Promise; /** Deterministic observations: identical for a manifest and seed under fake time on any host. */ export interface DecisionLoadObservations { arrivals: number; attempts: number; completed: number; failed: number; shed: number; cancelled: number; shedReasons: Record; maximumActiveCalls: number; maximumQueuedCalls: number; maximumEligibleLaneWaitMs: number; retryAmplificationRatio: number; maximumCancellationLatencyMs: number; quietPrincipalAdmissionRatio: number; noisyPrincipalAdmissionRatio: number; virtualDurationMs: number; } /** Host-dependent measurements, recorded next to the deterministic observations. */ export interface DecisionLoadResourceObservations { heapUsedMiB: number; /** Informational: process-wide, so it includes the test runner and any sibling workers. */ residentMemoryMiB: number; /** Harness CPU time divided by the manifest's virtual timeline: one-core utilization at the declared arrival rate. */ cpuPercentOneCore: number; /** `thread` CPU time when the runtime exposes it; otherwise harness wall-clock time, an upper bound. */ cpuSource: 'thread' | 'wall-clock-upper-bound'; } export interface DecisionLoadComparison { bound: keyof DecisionLoadManifestV2['bounds']; limit: number; observed: number; pass: boolean; } export interface DecisionLoadResultRecord { schema: 'decision-load-result/v1'; manifest: { schema: DecisionLoadManifest['schema']; version: string; digest: string; }; mode: DecisionLoadManifest['mode']; target: 'admission-controller' | 'evaluator'; window: { seconds: number; }; environment: { node: string; platform: string; arch: string; }; observations: DecisionLoadObservations; resources: DecisionLoadResourceObservations; comparisons: DecisionLoadComparison[]; passed: boolean; /** sha256 over the canonical record without this field. */ digest: string; } export declare function decisionLoadManifestDigest(bytes: Uint8Array | string): string; /** Seeded bursty Poisson arrivals for the manifest's load, spike, and soak phases. */ export declare function decisionLoadArrivals(manifest: DecisionLoadManifest, windowSeconds?: number): DecisionLoadArrival[]; /** Scheduler policy the manifest declares for one principal. */ export declare function decisionLoadPolicy(manifest: DecisionLoadManifest, workspaceId: string, principalId: string): DecisionSchedulerPolicy; /** Drives each arrival straight through a registry-owned `DecisionAdmissionController`. */ export declare function admissionControllerLoadDriver(manifest: DecisionLoadManifest, clock: DecisionLoadClock, registry?: DecisionAdmissionRegistry, hooks?: { onStateChange?: () => void; onDriverError?: () => void; estimateCost?: (arrival: DecisionLoadArrival) => number; backend?: (arrival: DecisionLoadArrival, signal: AbortSignal, context: DecisionLoadDriverContext, attempt: number) => Promise; beforeDispatch?: (arrival: DecisionLoadArrival, attempt: number) => boolean; onAdmission?: (arrival: DecisionLoadArrival, attempt: number, evidence: DecisionAdmissionEvidence) => void; onObservation?: (arrival: DecisionLoadArrival, attempt: number, evidence: DecisionAdmissionEvidence, observation: AdapterObservation) => void; }): { driver: DecisionLoadDriver; sample: () => { active: number; queued: number; }; }; /** * Offline load harness. Arrivals are released on a virtual timeline supplied by * the caller's fake clock. Deterministic observations are separated from * host-dependent memory and CPU measurements. */ export declare function runDecisionLoadHarness(options: { manifest: DecisionLoadManifest; clock: DecisionLoadClock; driver: DecisionLoadDriver; sample: () => { active: number; queued: number; }; windowSeconds?: number; signal?: AbortSignal; /** Preserve the entire declared window, even after the last arrival settles. */ fullWindow?: boolean; }): Promise<{ observations: DecisionLoadObservations; resources: DecisionLoadResourceObservations; }>; export declare function compareDecisionLoadBounds(manifest: DecisionLoadManifest, observations: DecisionLoadObservations, resources: DecisionLoadResourceObservations): DecisionLoadComparison[]; /** Build a digest-bound result record. The manifest digest must be computed from its exact bytes. */ export declare function decisionLoadResultRecord(input: { manifest: DecisionLoadManifest; manifestDigest: string; target: DecisionLoadResultRecord['target']; windowSeconds: number; observations: DecisionLoadObservations; resources: DecisionLoadResourceObservations; }): DecisionLoadResultRecord; export declare function verifyDecisionLoadResultRecord(record: DecisionLoadResultRecord, manifestDigest: string): boolean; /** Historical offline evidence stays separate from verified, exact-commit v3 G5 artifacts. */ export declare function decisionLoadEvidenceFlags(records: readonly (DecisionLoadResultRecord | DecisionStagedLoadRecord | DecisionStagedLoadRecordV1)[], manifestDigest: string, sourceCommit?: string): Record; //# sourceMappingURL=load.d.ts.map