import { type DecisionGraph } from './graph.js'; import { type DecisionGraphTemplate } from './graph-templates.js'; import { type GraphFlowReport } from './graph-run.js'; import { type PairedDifferenceInterval } from './qualification/quality.js'; import { dagLiveDigest, type DagLivePattern, type DagLivePreregistration, type DagLiveTask, type DagLiveWorkload } from './graph-live-workload.js'; import type { DecisionBinding, DecisionDefinition, DecisionRuleset } from './types.js'; export { dagLiveDigest }; /** Hard ceiling from the #2686 assessment; an approval cannot raise it. */ export declare const DAG_LIVE_HARD_CAP_USD = 2; export declare const DAG_LIVE_ENV_GATE = "AIWG_DECISION_DAG_LIVE"; /** Worst-case provider calls per task: flat baseline is always one. */ export declare const DAG_LIVE_MAX_CANDIDATE_CALLS: Record; export interface DagLiveBudgetLimits { usd: number; calls: number; tokens: number; wallClockMs: number; } export interface DagLiveApproval { schemaVersion: 'dag-live-approval/v1'; approved: true; /** Named D12 promotion owner who approved the digests and margin. */ reviewer: string; stagingHost: string; runId: string; sourceCommit: string; exactHeadCi: string; model: string; apiRevision: 'v1'; region: string; secretServiceReference: string; credentialResolverDigest: `sha256:${string}`; workloadDigest: `sha256:${string}`; preregistrationDigest: `sha256:${string}`; budget: DagLiveBudgetLimits & { perPattern: DagLiveBudgetLimits; }; /** * Operator-attested price bound with its evidence. Reservations and charges use the larger of * these prices and DAG_LIVE_RESERVE_FLOOR_USD_PER_MTOK; reported billable cost uses them as attested. */ priceBound: DagLivePriceBound; /** Operator-stated spend of earlier D12 runs. A floor: runs found under the artifact root also count. */ priorSpendUsd: number; /** * Pinned secret service: the exact HTTPS vault origin and the SHA-256 of the KV secret path. * The resolver refuses any other origin or path before a vault token is requested. */ secretService: { origin: string; secretPathDigest: `sha256:${string}`; }; taskDeadlineMs: number; } export interface DagLivePriceBound { inputUsdPerMTok: number; outputUsdPerMTok: number; /** Optional attested minimum price per request; every reservation and charge is at least this. */ perRequestUsd?: number; /** Public pricing pages, live usage receipts or invoices the operator relies on. */ evidenceReferences: string[]; /** Where the operator attested this bound (comment, ticket or signed note). */ approvalReference: string; } /** Hard-coded floor. It never replaces the attestation: a higher attested price always wins. */ export declare const DAG_LIVE_RESERVE_FLOOR_USD_PER_MTOK = 0.1; /** Worst-case reservation for one call: every token at the dearest rate, never below the per-request price. */ export declare function dagLiveReservationMicros(bound: DagLivePriceBound, perCallTokenBound: number): number; /** Charge for reported usage at the reservation rates, never below the per-request price. */ export declare function dagLiveChargeMicros(bound: DagLivePriceBound, inputTokens: number, outputTokens: number): number; /** Digest that pins a KV secret path: SHA-256 of its UTF-8 bytes (the resolver computes the same). */ export declare const dagLiveSecretPathDigest: (path: string) => `sha256:${string}`; export interface DagLiveHost { /** Approved secret-service integration. Receives only the logical reference. */ resolveCredential(reference: string): Promise; } export type FlowExecutor = (manifest: unknown, options: Record) => Promise; /** Fails closed on any unknown field, missing value, digest mismatch or cap violation. */ export declare function validateDagLiveApproval(approval: DagLiveApproval, workload: DagLiveWorkload, preregistration: DagLivePreregistration): void; /** The preregistration must be exactly the one generated from this workload. */ export declare function validateDagLiveInputs(workload: DagLiveWorkload, preregistration: DagLivePreregistration): void; export declare class DagLiveStop extends Error { readonly reason: string; constructor(reason: string); } type Totals = { calls: number; tokens: number; usdMicros: number; }; export interface DagLiveReportedUsage { inputTokens: number | null; outputTokens: number | null; } /** * Pure accounting guard. Every call reserves the full per-call token bound at the larger of * the attested price and the floor before dispatch, and is refused once any global or * per-pattern dimension would pass the stop fraction. Settlement replaces the reservation * with the reported usage, including usage above the reservation. A call reporting more * than its per-call bound records a budget breach: its observed spend is still charged in * full, and every later reservation is refused. A call with missing usage * keeps at least its full reservation. Calls are never refunded. */ export declare class DagLiveBudget { private readonly approval; private readonly bound; private readonly stopFraction; readonly started: number; private readonly now; readonly total: Totals; private readonly patterns; private readonly boundMicros; /** Set when a settled call reports more than its approved per-call bound. */ private breached; constructor(approval: Pick, bound: number, stopFraction: number, started: number, now?: () => number); usd(totals?: Totals): number; pattern(pattern: DagLivePattern): Totals; private exceeds; reserve(pattern: DagLivePattern): (usage: DagLiveReportedUsage | null) => { tokens: number; usdMicros: number; }; } /** One metadata-only provider call record. Provider text and credentials never appear. */ export interface DagLiveCall { pattern: DagLivePattern; taskId: string; arm: 'baseline' | 'candidate'; node: string; ordinal: number; status: string; reason: string; requestId: string | null; servedModel: string | null; inputTokens: number | null; outputTokens: number | null; latencyMs: number; /** Tokens and USD micros charged to spend for this call (reported usage, or the reservation if unknown). */ chargedTokens: number; chargedUsdMicros: number; /** 1 for the first attempt, 2 for the single preregistered retry. */ attempt: number; /** `ok`, a retryable provider outcome, or the immediate-stop reason. */ outcome: string; } interface NodeArtifacts { ruleset: DecisionRuleset; binding: DecisionBinding; definitions: Record; } interface ArmSetup { graph: DecisionGraph; flow: any; requests: Map; template?: DecisionGraphTemplate; } export interface DagLiveArms { baseline: ArmSetup; candidate: ArmSetup & { template: DecisionGraphTemplate; }; resolvedPins: Set; } /** Builds both arms for one task. Pins are resolved from the frozen task before any dispatch. */ export declare function buildDagLiveArms(task: DagLiveTask, options: { model: string; secretServiceReference: string; skillId: `aiwg:skill:${string}`; perCallTokenBound: number; reservationMicros: number; taskDeadlineMs: number; }): DagLiveArms; /** Stop rule: no arm may contain a node able to request an action or permission. */ export declare function speculativeActionViolation(flow: { spec?: { permissions?: unknown[]; nodes?: Array<{ kind?: string; sideEffectMode?: string; permissions?: unknown[]; capabilities?: unknown[]; }>; }; }): boolean; /** Stop rule: a pattern's cumulative candidate calls exceed the multiple of its Flow baseline calls. */ export declare function patternCallRatioExceeded(pairs: readonly DagLivePair[], pattern: DagLivePattern, maxRatio: number): boolean; /** Operator-facing defaults for the dry run and approval template (USD 0.10/1M ceiling, USD 2.00 cap). */ export declare const DAG_LIVE_DEFAULT_LIMITS: Pick; /** Unsigned approval skeleton: every `<...>` value must be filled in and reviewed by the promotion owner. */ export declare function dagLiveApprovalTemplate(workload: DagLiveWorkload, preregistration: DagLivePreregistration): Record; export interface DagLiveArmResult { answer: string | null; correct: boolean; /** First-attempt provider calls (the arm's shape). */ calls: number; /** Charged retry attempts, reported separately. Tokens include every attempt. */ retries?: number; inputTokens: number; outputTokens: number; latencyMs: number; requestIds: string[]; } export interface DagLivePair { pattern: DagLivePattern; taskId: string; slice: string; index: number; order: 'baseline-first' | 'candidate-first'; label: string; baseline: DagLiveArmResult; candidate: DagLiveArmResult & { outcome: string; receiptDigest: string; unusedCalls: number; unusedTokens: number; }; /** Present when a call exhausted its retry: the task is excluded from both arms of the paired analysis. */ measurementFailure?: { arm: 'baseline' | 'candidate'; node: string; reason: string; }; } export interface DagLivePatternAnalysis { /** n counts usable pairs only; measurement failures are excluded from the paired table. */ pattern: DagLivePattern; n: number; attempted: number; measurementFailures: number; measurementFailureTolerance: number; complete: boolean; verdict: 'eligible' | 'not-eligible' | 'insufficient-evidence'; quality: { baselineCorrect: number; candidateCorrect: number; table: { both: number; candidateOnly: number; baselineOnly: number; neither: number; }; baselineAccuracyInterval: readonly [number, number] | null; candidateAccuracyInterval: readonly [number, number] | null; difference: PairedDifferenceInterval | null; nonInferiority: { decision: string; reason: string; }; slices: Record; }; economics: { baseline: { calls: number; inputTokens: number; outputTokens: number; billableUsd: number; p50LatencyMs: number | null; p95LatencyMs: number | null; }; candidate: { calls: number; inputTokens: number; outputTokens: number; billableUsd: number; p50LatencyMs: number | null; p95LatencyMs: number | null; }; net: { calls: number; tokens: number; billableUsd: number; }; callRatio: number | null; p95LatencyRatio: number | null; extraTokensPerTask: PairedDifferenceInterval | null; extraTokensPerTaskUpper: number | null; speculative: { unusedCalls: number; unusedTokens: number; }; outcomes: Record; retries: { baseline: number; candidate: number; }; measurementFailureSpend: { calls: number; retries: number; tokens: number; }; checks: { callRatio: boolean; p95LatencyRatio: boolean; extraTokensPerTask: boolean; }; pass: boolean; }; eligible: boolean; } /** * Paired analysis with the shared helpers at the preregistered level and margin. A pattern is * eligible for the reviewer only with complete pairs, a non-inferior lower bound and every * preregistered economics bound met. Unknown values fail closed. */ export declare function analyzeDagLivePattern(pattern: DagLivePattern, pairs: readonly DagLivePair[], preregistration: DagLivePreregistration, price: Pick): DagLivePatternAnalysis; /** Offline, credential-free worst-case plan against the approval limits. */ export declare function planDagLiveQualification(workload: DagLiveWorkload, preregistration: DagLivePreregistration, limits: Pick): { schemaVersion: string; providerCalls: number; workloadDigest: `sha256:${string}`; preregistrationDigest: `sha256:${string}`; perCallTokenBound: 4000; stopFraction: 0.8; patterns: { pattern: DagLivePattern; tasks: number; worstCase: { baselineCalls: number; candidateCalls: number; firstAttemptCalls: number; retryCalls: number; calls: number; tokens: number; reservedUsd: number; }; estimatedVisibleTokens: number; largestEstimatedCallTokens: number; withinPatternStop: boolean; }[]; totals: { worstCaseFirstAttemptCalls: number; worstCaseCalls: number; worstCaseTokens: number; worstCaseReservedUsd: number; estimatedVisibleTokens: number; estimatedBillableUsdAtAttestedInputPrice: number; reservationUsdPerCall: number; hardCapUsd: number; }; boundCoversLargestEstimate: boolean; withinBudget: boolean; }; /** * Spend of every earlier D12 run anywhere below the artifact root (depth-limited, symlinks not * followed). A run with a summary counts its charged USD. A run with an approval but no summary * (crashed or killed) counts each logged call at its charged amount (the reservation when a line * carries none) plus one call in flight at the reservation. Directories that are not D12 runs are ignored. */ export declare function dagLivePriorSpend(artifactRoot: string): Promise<{ usd: number; runs: string[]; }>; /** The artifact root must BE the canonical AIWG artifact root, never a subdirectory of it. */ export declare function assertDagLiveArtifactRoot(sourceRoot: string, artifactRoot: string): Promise; /** Reads the resolver file once, checks that exact content against both pins, then imports those bytes. */ export declare function loadDagLiveResolver(path: string, expectedDigest: string, approvedDigest: string): Promise>; /** * Runs the approved paired collection and writes digest-bound evidence under * `//`. With `transport` the run is labelled synthetic and never * counts as live evidence. Without it the explicit env gate and the full preregistered * workload are required. */ export declare function runDagLiveQualification(options: { approval: DagLiveApproval; workload: DagLiveWorkload; preregistration: DagLivePreregistration; sourceRoot: string; artifactRoot: string; host: DagLiveHost; executeFlow: FlowExecutor; skillId: `aiwg:skill:${string}`; transport?: typeof fetch; now?: () => number; sourceGoldens?: readonly string[]; }): Promise>; export declare const DAG_LIVE_SOURCE_GOLDENS: readonly ["src/decision/graph-live-qualification.ts", "src/decision/graph-live-workload.ts", "docs/decision/evidence/dag-live-v1/workload.json", "docs/decision/evidence/dag-live-v1/preregistration.json"]; /** * Records the named reviewer's promote-or-hold decision against a finished run directory. * Promotion is refused unless the recorded run was live, unstopped and eligible for every pattern. */ export declare function recordDagLiveDecision(runDirectory: string, decision: 'promote' | 'hold', reviewer: string, rationale: string, at?: Date): Promise<{ schemaVersion: string; issue: string; runId: string; sourceCommit: string; summaryDigest: string; decision: "promote" | "hold"; reviewer: string; rationale: string; recordedAt: string; reviewRecordDigest: `sha256:${string}`; }>; //# sourceMappingURL=graph-live-qualification.d.ts.map