spawnfile 0.1.25 → 0.1.27

package/dist/training/contracts/evaluation.d.ts

@@ -0,0 +1,256 @@
+import type { AtomicRuntime, AtomicGradeResult } from '../graders/atomic/index.js';
+import type { DecisionAccounting } from './grading.js';
+import type { GradingRuntime, GradeResult } from '../graders/index.js';
+import type { CheckNode, EvaluatorDefinition, DataMap } from './dataset.js';
+import type { Observation, ObservationCoverage, InferenceProvider, Usage, InferenceFailureKind, InferenceDiagnostic } from './execution.js';
+export type Verdict = 'pass' | 'fail' | 'unknown' | 'error' | 'skipped';
+export type Finality = 'provisional' | 'final';
+export interface EvidenceReference {
+    kind: 'event' | 'artifact' | 'input' | 'output' | 'sidecar';
+    id: string;
+    digest?: string;
+}
+export interface JudgeCall {
+    /** One actual provider.generate attempt; references retain this ID for deduplication. */
+    id: string;
+    judge: string;
+    providerId: string;
+    requestedModel: string;
+    /** Must be a provider-reported identity; requested-model fallbacks and missing identities are null. */
+    responseModel: string | null;
+    responseRoute: string | null;
+    outcome: 'completed' | 'invalid-response' | 'generation-error' | 'refused';
+    usage: Usage | null;
+    /** Configured maximum, including when no repair was needed. Omitted only in legacy captures. */
+    citationRepairs?: 0 | 1;
+    /** A citation-only protocol repair of this earlier actual attempt. */
+    repairOf?: string;
+    /**
+     * Historical retry provenance, retained for cache/replay compatibility.
+     * Older evaluations retried generic protocol failures without proof that no
+     * judgment existed. Current evaluations do not emit retries; this field alone
+     * must not be treated as proof of a pre-judgment abort or a same-route retry.
+     */
+    retryOf?: string;
+    /** Historical cause attributed to the prior failed attempt; present only beside `retryOf`. */
+    retryCause?: JudgeFailureCause;
+    failureKind?: InferenceFailureKind;
+    /** Typed containment rejection; never provider diagnostic prose. */
+    failureDetail?: 'tool-call';
+    fallbackOf?: string;
+    wallMs?: number;
+    billing?: 'local' | 'subscription' | 'api' | 'mixed';
+}
+export interface CachedJudgment {
+    response: string;
+    sourceCallId: string;
+    /** Historical inference provenance, never current inference or billable usage. */
+    sourceCalls?: JudgeCall[];
+}
+/** Host-owned, bounded evaluation cache; no subject access and no infrastructure errors. */
+export interface JudgeCache {
+    readonly persistent?: boolean;
+    get(key: string): CachedJudgment | undefined | Promise<CachedJudgment | undefined>;
+    put(key: string, value: CachedJudgment): void | Promise<void>;
+}
+export interface JudgeRoute {
+    provider: InferenceProvider;
+    model: string;
+    citationRepairs?: 0 | 1;
+    protocol?: 'citations' | 'evidence-ids';
+    identity?: string;
+    template?: {
+        language: 'jinja';
+        text: string;
+    };
+    cache?: JudgeCache;
+    /** Host-frozen dataset and phase identity, required for persistent reuse. */
+    cacheScope?: string;
+}
+/**
+ * Why a judge produced no usable judgment, as a closed vocabulary rather than prose.
+ *
+ * A judge error used to publish a bare `status: 'error'` and nothing else: the
+ * reason string can quote the prompt, the article or a provider body, so nothing
+ * carried it, and a live run left an operator unable to tell a refused grant from
+ * an unreadable answer. These values name the FIRST thing that did not hold, and
+ * never carry a prompt, subject text, a response body, a bearer or a grant token.
+ *
+ * Absence is not one of them. A judge with no input to read stays `unknown` with
+ * no failure at all, which is a different claim from one that ran and refused.
+ */
+export declare const judgeFailureCauses: readonly ["grant-refused", "grant-expired", "provider-error", "response-unparseable", "response-schema", "response-citations", "timeout", "cancelled", "route-unusable", "evidence-unusable", "cache-unusable", "evidence-unpersisted", "unclassified"];
+export type JudgeFailureCause = (typeof judgeFailureCauses)[number];
+/**
+ * The published, prose-free account of one failed judge: the cause, which judge,
+ * and which model and route actually answered. An unrequested provider or route
+ * appearing here is how a silent judge fallback stops being silent.
+ */
+export interface JudgeFailure {
+    cause: JudgeFailureCause;
+    judge: string;
+    providerId: string | null;
+    requestedModel: string | null;
+    /** Provider-reported; null when no provider identity was returned. Never a requested alias. */
+    responseModel: string | null;
+    responseRoute: string | null;
+    kind?: InferenceFailureKind;
+    /** Only a provider-reported response status, as a number. */
+    status?: number;
+}
+export interface JudgeProtocolViolation {
+    code: 'invalid-json' | 'invalid-judgment' | 'invalid-citations' | 'invalid-citation-repair' | 'invalid-evidence-ids';
+    citations?: {
+        index: number;
+        source: string;
+        reason: 'unknown-source' | 'quote-not-found';
+    }[];
+}
+/** Protected evaluator evidence, never part of optimizer feedback or viewer projections. */
+export interface JudgeAttemptObservation {
+    call: JudgeCall;
+    response: string;
+    violation?: JudgeProtocolViolation;
+    diagnostic?: InferenceDiagnostic;
+}
+export interface EvaluationResult {
+    id?: string;
+    status: Verdict;
+    finality: Finality;
+    reason: string;
+    /** Set on every `error` a judge produces; absent on any other verdict. */
+    judgeFailure?: JudgeFailure;
+    score?: number;
+    evidence: EvidenceReference[];
+    /** Deterministic measurements over the referenced text bytes. */
+    mechanicalEvidence?: {
+        count?: number;
+        found?: number;
+        total?: number;
+        missing?: string[];
+    };
+    children?: EvaluationResult[];
+    grading?: GradeResult;
+    atomicGrading?: AtomicGradeResult;
+    /** Infrastructure stopped atomic grading before extraction; no grade was produced. */
+    atomicFailure?: {
+        cause: 'acceptance-gate';
+        gateId: string;
+    };
+    /** Paid grader attempts retained even when no grade was produced. */
+    decisionAccounting?: DecisionAccounting;
+    usage?: Usage[];
+    judgeCalls?: JudgeCall[];
+    cache?: {
+        key: string;
+        sourceCallId: string;
+        sourceCalls?: JudgeCall[];
+    };
+}
+export interface ArtifactSnapshot {
+    name: string;
+    checkpointId: string;
+    digest: string;
+    bytes: string;
+    value: unknown;
+    provenance: string;
+    acceptedCallId?: string;
+}
+/** Authoritative subject-only returned turn totals; never reconstructed from observations. */
+export interface SubjectUsageSnapshot {
+    status: 'complete' | 'incomplete';
+    usage: Usage | null;
+    /**
+     * The subject execution closed completed, host-settled and stop-proven, whether or not every
+     * token was accounted for. Absent means not attested (legacy capture or uncertain run). It certifies an
+     * observed artifact absence; it never certifies usage, which only `status` does.
+     */
+    settled?: boolean;
+}
+export interface EvaluationSnapshot {
+    trialId: string;
+    recordId: string;
+    closed: boolean;
+    /** Missing in legacy captures means unknown, never zero cost. */
+    subjectUsage?: SubjectUsageSnapshot;
+    events: readonly Observation[];
+    coverage: readonly ObservationCoverage[];
+    artifacts: Readonly<Record<string, ArtifactSnapshot>>;
+    output: string;
+    inputFiles: Readonly<Record<string, string>>;
+    context: Readonly<DataMap>;
+}
+export interface EmbeddingProvider {
+    id: string;
+    version: string;
+    embed(texts: readonly string[], model: string, signal?: AbortSignal): Promise<{
+        vectors: number[][];
+        usage: Usage | null;
+    }>;
+}
+export interface EvaluationContext {
+    snapshot: EvaluationSnapshot;
+    results: Readonly<Record<string, EvaluationResult>>;
+    scores: Readonly<Record<string, WeightedScore>>;
+    judges: Readonly<Record<string, JudgeRoute>>;
+    embeddings: Readonly<Record<string, EmbeddingProvider>>;
+    /** Host-built grader routes keyed by resolved grader filename. */
+    graders?: Readonly<Record<string, GradingRuntime | AtomicRuntime>>;
+    /** Engine-owned nested gate execution against the same immutable trial snapshot. */
+    evaluateCheck?: (check: CheckNode, artifact?: ArtifactSnapshot) => Promise<EvaluationResult>;
+    /** Artifact whose acceptance a nested grader gate must establish. */
+    gradedArtifact?: ArtifactSnapshot;
+    /** The host confines sidecars to protected evaluator resources. */
+    readText: (path: string) => Promise<string>;
+    /** Trusted host sink, awaited before accepting a judgment or making its one permitted repair. */
+    observeJudgeAttempt?: (attempt: JudgeAttemptObservation) => void | Promise<void>;
+    /** Trusted persisted measurement sink; never receives prompt text or judge reasons. */
+    observeMeasurement?: (measurement: EvaluationMeasurement) => void | Promise<void>;
+    signal?: AbortSignal;
+    /** Maximum slotted (inference-capable) stage checks in flight; built-in mechanical checks take no slot. Defaults to 2. */
+    checkConcurrency?: number;
+}
+export interface EvaluationMeasurement {
+    stageId: string;
+    criterionId: string;
+    kind: 'criterion' | 'gate' | 'score';
+    status: Verdict;
+    score: number | null;
+    weight?: number;
+    weightedContribution?: number | null;
+    /** Named cause of an errored judge criterion; the weight still counts against the denominator. */
+    judgeFailure?: JudgeFailure;
+}
+export interface RegisteredEvaluator {
+    definition: EvaluatorDefinition;
+    evaluate(check: CheckNode, context: EvaluationContext): Promise<EvaluationResult>;
+    /**
+     * Opt-in stage concurrency. Declare only when the result never reads context.results or
+     * context.scores; return the stateful resources it uses (for example a judge cache).
+     * Checks sharing a resource never overlap. Results and measurements still commit in order.
+     */
+    concurrency?(check: CheckNode, context: EvaluationContext): readonly object[] | undefined;
+}
+export type EvaluationRegistry = Readonly<Record<string, RegisteredEvaluator>>;
+export interface WeightedScore {
+    finality: Finality;
+    lower: number;
+    upper: number;
+    assessedWeight: number;
+    missingWeight: number;
+}
+export interface StageEvaluation {
+    id: string;
+    checks: EvaluationResult[];
+    gate: EvaluationResult;
+    score?: WeightedScore;
+    /** Authored relative weights; normalize against the complete declared denominator. */
+    weights?: Record<string, number>;
+}
+export interface PlanEvaluation {
+    status: Verdict;
+    stages: StageEvaluation[];
+    checks: Record<string, EvaluationResult>;
+    scores: Record<string, WeightedScore>;
+    judgeCalls?: JudgeCall[];
+}

package/dist/training/contracts/evaluation.js

@@ -0,0 +1,41 @@
+/**
+ * Why a judge produced no usable judgment, as a closed vocabulary rather than prose.
+ *
+ * A judge error used to publish a bare `status: 'error'` and nothing else: the
+ * reason string can quote the prompt, the article or a provider body, so nothing
+ * carried it, and a live run left an operator unable to tell a refused grant from
+ * an unreadable answer. These values name the FIRST thing that did not hold, and
+ * never carry a prompt, subject text, a response body, a bearer or a grant token.
+ *
+ * Absence is not one of them. A judge with no input to read stays `unknown` with
+ * no failure at all, which is a different claim from one that ran and refused.
+ */
+export const judgeFailureCauses = [
+    /** The grant broker declined to lend a grant for this call. */
+    'grant-refused',
+    /** A grant, or the credential realm behind it, was no longer valid. */
+    'grant-expired',
+    /** The provider itself failed; `status` carries its reported status when it reported one. */
+    'provider-error',
+    /** The answer was not JSON at all. */
+    'response-unparseable',
+    /** The answer parsed but was not a judgment of the requested shape. */
+    'response-schema',
+    /** The judgment's citations were not present in the evidence it was given. */
+    'response-citations',
+    /** A deadline passed before an answer arrived. */
+    'timeout',
+    /** The caller cancelled the trial before the judge settled. */
+    'cancelled',
+    /** The judge route is absent or its declared policy is unusable; nothing was asked. */
+    'route-unusable',
+    /** The selected evidence could not be prepared for the judge; nothing was asked. */
+    'evidence-unusable',
+    /** A persisted judgment could not be read back as one. */
+    'cache-unusable',
+    /** The attempt could not be recorded, so its answer may not be accepted. */
+    'evidence-unpersisted',
+    /** The provider failed with no typed discriminator at all; naming that is still a finding. */
+    'unclassified',
+];
+//# sourceMappingURL=evaluation.js.map

package/dist/training/contracts/evaluation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluation.js","sourceRoot":"","sources":["../../../src/training/contracts/evaluation.ts"],"names":[],"mappings":"AA+DA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,+DAA+D;IAC/D,eAAe;IACf,uEAAuE;IACvE,eAAe;IACf,6FAA6F;IAC7F,gBAAgB;IAChB,sCAAsC;IACtC,sBAAsB;IACtB,uEAAuE;IACvE,iBAAiB;IACjB,8EAA8E;IAC9E,oBAAoB;IACpB,kDAAkD;IAClD,SAAS;IACT,+DAA+D;IAC/D,WAAW;IACX,uFAAuF;IACvF,gBAAgB;IAChB,oFAAoF;IACpF,mBAAmB;IACnB,0DAA0D;IAC1D,gBAAgB;IAChB,4EAA4E;IAC5E,sBAAsB;IACtB,8FAA8F;IAC9F,cAAc;CACN,CAAC"}

package/dist/training/contracts/execution.d.ts

@@ -0,0 +1,363 @@
+import type { TrialSlot } from './trial-slot.js';
+/** Native execution is independent of the dataset language and evaluator registry. */
+export interface Usage {
+    inputTokens: number | null;
+    cachedInputTokens: number | null;
+    /** Cache reads and writes are disjoint subsets of total inputTokens. Missing means unknown. */
+    cacheWriteInputTokens?: number | null;
+    cacheWrite5mInputTokens?: number | null;
+    cacheWrite1hInputTokens?: number | null;
+    outputTokens: number | null;
+    reasoningTokens: number | null;
+    /** Runtime-reported notional API-equivalent USD for exactly these tokens, labelled by `source`. Missing means unreported. */
+    notionalUsd?: number | null;
+    source: string;
+}
+export interface ObservationCoverage {
+    channel: 'tools' | 'output' | 'usage';
+    completeness: 'complete' | 'partial' | 'absent';
+    ordering: 'source' | 'causal' | 'none';
+}
+export interface Observation {
+    id: string;
+    source: string;
+    /** Monotonic within this source; never a global causal-order claim. */
+    seq: number;
+    type: 'tool.dispatch' | 'tool.complete' | 'output' | 'usage' | 'diagnostic' | 'input';
+    timestamp: string;
+    trialId: string;
+    wakeId: string;
+    callId?: string;
+    tool?: string;
+    args?: unknown;
+    result?: unknown;
+    success?: boolean;
+    text?: string;
+    usage?: Usage;
+    causalParents?: string[];
+    native?: unknown;
+}
+export interface SubjectCapabilities {
+    toolTrace: 'none' | 'partial' | 'complete';
+    /** A fixture journal never implies observation of every native built-in tool. */
+    liveObservations: boolean;
+    cancellation: 'none' | 'process-group' | 'native-handle';
+    multiTurn: boolean;
+    resources: readonly ('instructions' | 'supporting-files' | 'native-skills')[];
+    isolation: string;
+    readIsolation: 'none' | 'declared-paths';
+    protectedPaths: boolean;
+}
+/**
+ * Why a CLOSURE proof did not settle, as a closed vocabulary rather than prose.
+ *
+ * Closure answers one question — is anything still running or still spending? —
+ * and it is the conjunction of three independent proofs: the owned child process
+ * exited, the runtime sealed its own stop and acknowledged it, and the runtime's
+ * own activity projection admits no execution. For as long as the failing proof
+ * was swallowed, every unscorable run looked identical: two sessions in a row had
+ * to guess which one was missing from a control root that dies with its
+ * container. Absent means closure was proven; the value names the FIRST proof
+ * that did not hold, and never carries a path, a token, a body or an error
+ * string.
+ *
+ * What a trial can be SCORED from is a separate question with its own vocabulary
+ * (`TerminalEvidenceMissing`). Four members below are retired: they were scoring
+ * facts that had been placed inside this predicate, where each one demoted a
+ * healthy run to an infrastructure failure. They are kept so a sealed report that
+ * carries one still replays; nothing produces them.
+ */
+export type StopUnconfirmed = 'worker-unavailable'
+/**
+ * Retired as closure causes, and reported as `unevidenced` instead. A terminal
+ * frame that never arrived, or that did not bind to this trial, says nothing
+ * about whether a worker is still spending: it is a fact about the last
+ * delivery's paperwork, read out of another service's inbox bookkeeping over
+ * HTTP. The live proofs beside it — no admitted execution, a sealed
+ * acknowledged stop, an exited child — are what that claim rests on.
+ */
+ | 'terminal-absent' | 'terminal-unbound'
+/**
+ * Retired as a closure cause. The delivery's disposition is a SCORING fact:
+ * reading it here demoted a scorable turn to an infrastructure failure, and the
+ * live proofs beside it already establish that no worker is still spending. A
+ * recurrence is an upstream regression and fails on the worker's own evidence
+ * instead.
+ */
+ | 'delivery-undisposed' | 'activity-unreadable' | 'activity-busy'
+/** The activity projection omitted its execution authority or listed another agent's execution. */
+ | 'execution-unbound' | 'native-stop-unacknowledged' | 'child-running' | 'child-exit';
+/**
+ * Why a trial has no terminal evidence to be scored from — which is NOT a closure
+ * fault and must never read as one.
+ *
+ * "The runtime might still be spending" and "this turn cannot be scored" call for
+ * fixes in different places, and collapsing them sent seven investigations after
+ * the wrong layer: a healthy, closed, idle, exited run kept publishing as unproven
+ * containment because its frame did not bind. A trial carrying one of these is
+ * unscorable for want of evidence, on a runtime that is provably quiet.
+ *
+ * `terminal-absent` is no frame at all for the last delivery; `terminal-unbound`
+ * is a frame whose identity, closed trace or resolved execution disagreed —
+ * including a frame belonging to a different trial, which is never accepted as
+ * this one's evidence.
+ *
+ * `terminal-ambiguous` is the third, and it is not a weaker `terminal-unbound`:
+ * the frame named an execution and the trial carries MORE THAN ONE closed trace
+ * for that same id, so nothing here can say which one the frame accounts for. A
+ * trial that legitimately ran several wakes resolves the one its frame names and
+ * is scored; two traces answering to one name is a runtime defect and fails
+ * closed under its own word, because the fix it calls for is not in Training.
+ */
+export type TerminalEvidenceMissing = 'terminal-absent' | 'terminal-unbound' | 'terminal-ambiguous';
+export interface StopReceipt {
+    state: 'requested' | 'acknowledged' | 'unknown';
+    scope: 'process' | 'process-group' | 'native-handle';
+    quiescence: 'confirmed' | 'unknown';
+    remoteWork: 'unknown';
+    reason: string;
+    detail: string;
+    /** Set only on an unconfirmed stop, and only by an adapter that knows which proof failed. */
+    unconfirmed?: StopUnconfirmed;
+    /**
+     * Set when this trial has no terminal evidence to be scored from. It is
+     * independent of `quiescence`: a run can be provably closed and still
+     * unscorable, and that pair is the whole point of keeping two names.
+     */
+    unevidenced?: TerminalEvidenceMissing;
+    /**
+     * The wake whose terminal frame this trial is scored from, when one bound.
+     *
+     * A trial that defers runs several wakes and each publishes its own frame, so
+     * "this trial has evidence" is a selection and not the newest answer: a
+     * continuation that did not bind must not erase a wake that did, and a scored
+     * report has to be able to say which wake it read. Absent exactly when
+     * `unevidenced` is present.
+     */
+    evidenced?: string;
+    /**
+     * Every delivery this trial made, in order, with why each one's own frame
+     * cannot be scored from. Selection is not suppression: the wake that carried
+     * the trial and the wake that failed are both real accounts, and an adapter
+     * whose own per-wake artifacts live on storage that dies with the runtime
+     * publishes them here, where the report keeps them.
+     */
+    wakes?: readonly {
+        wakeId: string;
+        unevidenced?: TerminalEvidenceMissing;
+    }[];
+}
+/**
+ * What an adapter publishes about a subject that never became ready.
+ *
+ * The failure class has to survive the runtime it happened in: an adapter may
+ * keep its full capture on storage that dies with the container, so this is the
+ * redacted record that reaches the durable run output. `reason` is the runtime's
+ * own stated failure and is safe to show an operator. `streams` are redacted
+ * captures; an adapter that cannot prove a secret was removed omits them and
+ * reports `redaction: 'withheld'`, so the defect class still lands even when the
+ * bytes cannot. `protectedArtifact` names the adapter-private full copy.
+ */
+export interface SubjectStartupDiagnostic {
+    schema: string;
+    trialId: string;
+    reason: string;
+    exitCode: number | null;
+    exitSignal: string | null;
+    redaction: 'applied' | 'withheld';
+    streams?: {
+        stdout: string;
+        stderr: string;
+        truncated: {
+            stdout: boolean;
+            stderr: boolean;
+        };
+    };
+    /** Structured frames the runtime printed. A frame's schema publishes even when its message cannot. */
+    frames?: {
+        stream: 'stdout' | 'stderr';
+        schema: string;
+        message?: string;
+        withheldBy?: readonly string[];
+    }[];
+    /** Why a stream could not be published, in enough detail to tell one failure class from another. */
+    withheld?: {
+        stream: 'stdout' | 'stderr';
+        bytes: number;
+        lines: number;
+        frame: string | null;
+        detectors: readonly string[];
+    }[];
+    protectedArtifact?: string;
+    /** Operator-only full capture on the operator's own run output, written by the caller. Never shipped to a viewer or report. */
+    operatorCapture?: string;
+}
+/**
+ * The unredacted capture an adapter hands its caller exactly once.
+ *
+ * It never enters the durable event stream, a report or a viewer projection: the
+ * caller writes it to the operator's own run output as an operator-only file and
+ * then keeps only its path. `basename` is adapter-suggested and caller-validated.
+ */
+export interface SubjectStartupCapture {
+    basename: string;
+    content: string;
+}
+export interface FixtureTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute(args: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+export interface SubjectStart {
+    slot?: TrialSlot;
+    trialId: string;
+    workspacePath: string;
+    runtimeHomePath: string;
+    /** Evaluator-owned roots denied by adapters with native path protections. */
+    protectedPaths?: readonly string[];
+    instructions: string;
+    model?: string;
+    tools?: readonly FixtureTool[];
+    onObservation: (observation: Observation) => void | Promise<void>;
+    signal?: AbortSignal;
+}
+export interface SubjectEvidence {
+    adapterId: string;
+    /** Adapter-owned typed payload; core consumers must not interpret runtime identities. */
+    payload: unknown;
+}
+/** A subject-declared budget a runtime may report as exhausted. */
+export type DeclaredLimit = 'tokens' | 'requests' | 'timeout';
+export interface SubjectTurnResult {
+    /** Only evidence admitted by the adapter, never unbound frames. */
+    evidence?: SubjectEvidence;
+    status: 'completed' | 'failed' | 'cancelled';
+    /** Adapter-bound terminal admission evidence. Null means unobserved, never zero. */
+    admission?: {
+        executionRecords: number | null;
+        executionsUsed: number | null;
+        agentExecutionsUsed: number | null;
+        tokensUsed: number | null;
+        agentTokensUsed: number | null;
+        toolEvents: number | null;
+        outputEvents: number | null;
+    };
+    /**
+     * The subject's own execution closed while its delivery stayed accepted and
+     * deferred awaiting external input. The turn is never `completed`: confirming
+     * closure changes no task outcome and makes no unanswered delivery eligible as
+     * completed training evidence. An adapter sets it only with that explicit
+     * blocked receipt and the identity, idle, stop and exit proofs behind it, so a
+     * hang, crash, abort or deadline never carries it.
+     */
+    blocked?: 'awaiting-external-input';
+    /**
+     * The subject's execution closed because it exhausted a budget it declared
+     * itself, sealed by the runtime's declared-limit stop contract on the failed
+     * execution's own usage row. The turn is still
+     * `failed`; an adapter sets it only for a closed, bound execution, so an
+     * unconfirmed closure, crash, credential fault, refusal or unknown stop never
+     * carries it.
+     */
+    limit?: DeclaredLimit;
+    text: string;
+    coverage: ObservationCoverage[];
+    usage: Usage | null;
+    error?: string;
+    stop?: StopReceipt;
+}
+export interface SubjectSession {
+    run(turn: {
+        id: string;
+        text: string;
+    }, signal?: AbortSignal): Promise<SubjectTurnResult>;
+    stop(reason: string): Promise<StopReceipt>;
+}
+export interface SubjectAdapter {
+    id: string;
+    capabilities: SubjectCapabilities;
+    start(input: SubjectStart): Promise<SubjectSession>;
+}
+export interface InferenceRequest {
+    prompt: string;
+    system?: string;
+    /** Optional JSON Schema; supported providers constrain and validate the completed text. */
+    responseSchema?: Readonly<Record<string, unknown>>;
+    /** Subscription extraction compatibility: permit one surrounding json fence before schema validation. */
+    responseJsonFence?: boolean;
+    /** Trusted evaluator-only sink; never serialize into prompts, results or checkpoints. */
+    observeFailure?: (observation: {
+        attempt: Readonly<InferenceAttempt>;
+        fallbackOf?: string;
+        diagnostic: InferenceDiagnostic;
+    }) => void | Promise<void>;
+    model: string;
+    signal?: AbortSignal;
+    /** Controls must be rejected if unsupported, never silently discarded. */
+    temperature?: number;
+    seed?: number;
+}
+export type InferenceModelBasis = 'provider-reported' | 'requested-assumption';
+/** `auth-stale`: a shared credential authority (a broker realm) is stale; routes on that authority fail fast. */
+export type InferenceFailureKind = 'quota' | 'transport' | 'unavailable' | 'authentication' | 'auth-stale' | 'protocol' | 'invalid-response' | 'cancelled' | 'timeout' | 'unsupported' | 'unknown';
+/**
+ * What `kind` alone cannot express, as a closed vocabulary rather than prose.
+ *
+ * A borrowed inference grant has three different ways to stop working and `kind`
+ * collapsed all of them onto `unavailable`: the broker refusing to lend one, the
+ * lent grant outliving its own expiry, and the broker simply being down. A judge
+ * that reports only `unavailable` cannot tell an operator which of those to fix,
+ * so the adapter that knows names it here. Absent means the adapter had nothing
+ * more specific than `kind`; it never carries a token, a URL, a body or prose.
+ */
+export declare const inferenceFailureDetails: readonly ["grant-refused", "grant-expired", "provider-status", "tool-call"];
+export type InferenceFailureDetail = (typeof inferenceFailureDetails)[number];
+export declare const inferenceDiagnosticCodes: readonly ["initialization", "tool-isolation", "subscription", "transport-framing", "native-process", "terminal-error", "unfinished-response", "empty-response", "response-mismatch", "session-mismatch", "stop-mismatch", "model-missing", "content-shape", "response-envelope", "response-schema"];
+/** Protected provider evidence. Codes never contain arbitrary native error prose. */
+export interface InferenceDiagnostic {
+    code: (typeof inferenceDiagnosticCodes)[number];
+    /** Only an attested completed schema-rejected answer; oversized text is explicitly omitted. */
+    response?: {
+        bytes: number;
+        sha256: string;
+        text?: string;
+        omitted: boolean;
+    };
+}
+/** One settled or interrupted inference attempt, without prompts or provider diagnostics. */
+export interface InferenceAttempt {
+    id: string;
+    ordinal: number;
+    providerId: string;
+    requestedModel: string;
+    responseModel: string | null;
+    responseRoute: string | null;
+    outcome: 'completed' | 'failed';
+    failureKind: InferenceFailureKind | null;
+    startedAt: string;
+    completedAt: string;
+    usage: Usage | null;
+}
+export interface InferenceResult {
+    text: string;
+    model: string;
+    /** Omitted means provider-reported for existing providers. Requested fallback is never actual-model evidence. */
+    modelBasis?: InferenceModelBasis;
+    usage: Usage | null;
+    route: string;
+    /** All attempted declared routes, including failures. Omitted by unrouted legacy providers. */
+    attempts?: readonly InferenceAttempt[];
+}
+export interface InferenceProvider {
+    id: string;
+    capabilities: {
+        tools: 'disabled' | 'contained';
+        billing: 'subscription' | 'api' | 'local' | 'mixed';
+        temperature: boolean;
+        seed: boolean;
+        /** Shared credential authority; after `auth-stale` routing skips every later route naming the same authority. */
+        credentialAuthority?: string;
+    };
+    generate(request: InferenceRequest): Promise<InferenceResult>;
+}

package/dist/training/contracts/execution.js

@@ -0,0 +1,15 @@
+/**
+ * What `kind` alone cannot express, as a closed vocabulary rather than prose.
+ *
+ * A borrowed inference grant has three different ways to stop working and `kind`
+ * collapsed all of them onto `unavailable`: the broker refusing to lend one, the
+ * lent grant outliving its own expiry, and the broker simply being down. A judge
+ * that reports only `unavailable` cannot tell an operator which of those to fix,
+ * so the adapter that knows names it here. Absent means the adapter had nothing
+ * more specific than `kind`; it never carries a token, a URL, a body or prose.
+ */
+export const inferenceFailureDetails = ['grant-refused', 'grant-expired', 'provider-status', 'tool-call'];
+export const inferenceDiagnosticCodes = ['initialization', 'tool-isolation', 'subscription', 'transport-framing', 'native-process',
+    'terminal-error', 'unfinished-response', 'empty-response', 'response-mismatch', 'session-mismatch',
+    'stop-mismatch', 'model-missing', 'content-shape', 'response-envelope', 'response-schema'];
+//# sourceMappingURL=execution.js.map