import type { DecisionConfig } from '../../config/decision-config.js'; import { type AdmissionBreakerTransitionRecord, type AdmissionProfileChangeRecord } from '../admission.js'; import type { AdapterObservation, DecisionAdmissionEvidence, DecisionAdmissionLimits, DecisionUsage } from '../types.js'; import { type DecisionLoadArrival, type DecisionLoadClock, type DecisionLoadManifestV2, type DecisionLoadObservations, type DecisionLoadResourceObservations } from './load.js'; export interface DecisionLoadManifestV3 extends Omit { schema: 'decision-load-manifest/v3'; mode: 'staged-provider'; model: string; sampleIntervalMs: number; requestTimeoutMs: number; budget: { maxUsd: number; stopAtFraction: 0.8; maxCalls: number; maxTokens: number; maxWallClockSeconds: number; }; stopConditions: { maximumBreakerOpenMs: number; maximum429StormMs: number; maximumRetryAmplificationRatio: 1.25; maximumCrossPrincipalQuotaViolations: 0; }; bounds: DecisionLoadManifestV2['bounds'] & { maximumResidentMemoryMiB: number; maximumSampleGapMs: number; }; rollout: { previousProfileVersion: string; workspace: DecisionAdmissionLimits; providers: Record; shadowSeconds: number; rollbackSeconds: number; }; } export type DecisionLoadPricing = NonNullable['cost']>; export type DecisionLoadPhase = 'shadow' | 'canary' | 'rollback'; export type DecisionLoadStopReason = 'budget-usd-80-percent' | 'max-calls' | 'max-tokens' | 'max-wall-clock' | 'breaker-open' | 'retry-amplification' | '429-storm' | 'cross-principal-quota' | 'source-drift' | 'usage-exceeds-reservation' | 'invalid-reservation' | 'driver-error'; export interface DecisionLoadResourceSample { atMs: number; residentMemoryMiB: number; heapUsedMiB: number; cpuPercentOneCore: number; active: number; queued: number; } export interface DecisionLoadAttemptReceipt { phase: DecisionLoadPhase; arrivalOrdinal: number; principalId: string; providerId: string; attempt: number; admittedAtMs: number; settledAtMs: number; tokens: number; costUsd: number; admission: DecisionAdmissionEvidence; status: AdapterObservation['status']; reason: AdapterObservation['reason']; usage: DecisionUsage; httpStatus?: number; servedModel?: string; requestId?: string; } export interface DecisionStagedLoadStage { phase: DecisionLoadPhase; profileVersion: string; windowSeconds: number; observations: DecisionLoadObservations; resources: DecisionLoadResourceObservations; scopes: Record; } export interface DecisionStagedLoadComparison { bound: string; limit: number; observed: number; pass: boolean; } export interface DecisionLoadReservedUsage { calls: number; tokens: number; usd: number; } export interface DecisionLoadReportedTotals { inputTokens: number | null; outputTokens: number | null; tokens: number | null; usd: number | null; } export interface DecisionLoadReportedUsage extends DecisionLoadReportedTotals { /** calls counts dispatched attempts, including those with unknown token usage. */ calls: number; /** Calls missing either token dimension or applicable sourced pricing. */ incompleteCalls: number; /** Sum of known reports only; never represents an unknown call as zero. */ knownSubtotal: DecisionLoadReportedTotals; } export interface DecisionStagedLoadRecord { schemaVersion: 'decision-load-result/v2'; kind: 'load-manifest-qualified'; manifest: DecisionLoadManifestV3; manifestBytes: string; manifestDigest: string; mode: 'staged-provider'; execution: 'live' | 'offline-fake-provider'; sourceCommit: string; dirty: boolean; host: { hostname: string; cpuClass: string; memoryGiB: number; networkPath: string; node: string; platform: string; arch: string; }; pricing: DecisionLoadPricing; stages: DecisionStagedLoadStage[]; receipts: DecisionLoadAttemptReceipt[]; samples: DecisionLoadResourceSample[]; profileHistory: AdmissionProfileChangeRecord[]; breakerTransitions: AdmissionBreakerTransitionRecord[]; reservedUsage: DecisionLoadReservedUsage; /** Each total is null if any attempt lacks the corresponding provider usage or applicable pricing. */ reportedUsage: DecisionLoadReportedUsage; stop: { reason: DecisionLoadStopReason; atMs: number; } | null; startedAtMs: number; elapsedMs: number; retries: number; queueWaitDistribution: { count: number; p50: number; p95: number; p99: number; maximum: number; }; comparisons: DecisionStagedLoadComparison[]; passed: boolean; digest: string; } /** Original staged evidence is verified in its original shape and digest domain. */ export interface DecisionStagedLoadRecordV1 extends Omit { schemaVersion: 'decision-load-result/v1'; usage: DecisionLoadReservedUsage; } export declare const DECISION_STAGED_LOAD_RESULT_VERSIONS: readonly ["decision-load-result/v1", "decision-load-result/v2"]; /** Read historical manifests without rewriting them; v3 is the only staged runner input. */ export declare function readDecisionLoadManifest(bytes: string): DecisionLoadManifestV2 | DecisionLoadManifestV3 | { schema: 'decision-load-manifest/v1'; [key: string]: unknown; }; export declare function validateDecisionLoadManifestV3(value: unknown): asserts value is DecisionLoadManifestV3; export declare function validateDecisionLoadPricing(pricing: DecisionLoadPricing, model: string): void; /** Run-wide conservative reservations are never refunded on unknown provider outcomes. */ export declare class DecisionLoadBudgetGuard { readonly manifest: DecisionLoadManifestV3; private readonly now; readonly start: number; private readonly stopped; readonly usage: { calls: number; tokens: number; usd: number; }; stop: DecisionStagedLoadRecord['stop']; private readonly invocations; private readonly open; private readonly storm; constructor(manifest: DecisionLoadManifestV3, now: () => number, start: number, stopped?: () => void); halt(reason: DecisionLoadStopReason): void; reserve(id: string, tokens: number, usd: number): boolean; observe(providerId: string, observation: AdapterObservation, tokens: number, usd: number): void; transition(transition: AdmissionBreakerTransitionRecord): void; tick(): void; quotaViolation(): void; } export declare const realDecisionLoadClock: () => DecisionLoadClock; export declare function runDecisionStagedLoad(options: { manifestBytes: string; live?: boolean; env?: NodeJS.ProcessEnv; credentialEnv?: string; sourceRoot: string; sourceCommit: string; networkPath: string; pricing: DecisionLoadPricing; clock?: DecisionLoadClock; /** Offline test seam. Live always uses the existing Jev adapter. */ fakeBackend?: (arrival: DecisionLoadArrival, signal: AbortSignal) => Promise; /** Read-only exact-source seam for injected-clock tests. */ assertSource?: (root: string, commit: string) => Promise; sampleResources?: () => { rss: number; heapUsed: number; userCPUTime: number; systemCPUTime: number; }; }): Promise; /** Every measurement/stop/budget bound is recomputed from retained evidence, never the record's passed field. */ export declare function compareDecisionStagedLoad(record: Pick): DecisionStagedLoadComparison[]; export declare function decisionStagedLoadResultRecord(input: Omit & { manifestBytes: string; }): DecisionStagedLoadRecord; /** Self digest + exact manifest bytes + recomputed measurements + complete rollout + clean exact commit. */ export declare function verifyDecisionStagedLoadRecord(value: unknown, sourceCommit?: string): boolean; //# sourceMappingURL=load-staged.d.ts.map