@orkestrel/study 0.0.0-stage → 0.0.1

package/dist/src/core/index.d.ts

@@ -0,0 +1,1319 @@
+import type { BudgetInterface } from '@orkestrel/budget';
+import type { estimateRequest } from '@orkestrel/agent';
+import type { Guard } from '@orkestrel/contract';
+import type { isAgentError } from '@orkestrel/agent';
+import type { JSONValue } from '@orkestrel/contract';
+import type { JudgeInterface } from '@orkestrel/agent';
+import type { JudgeRequest } from '@orkestrel/agent';
+import type { JudgeResult } from '@orkestrel/agent';
+import type { LedgerGauge } from '@orkestrel/agent';
+import type { measureRequest } from '@orkestrel/agent';
+import type { Message } from '@orkestrel/agent';
+import type { ProviderDelta } from '@orkestrel/agent';
+import type { ProviderInterface } from '@orkestrel/agent';
+import type { ProviderRequest } from '@orkestrel/agent';
+import type { ProviderResult } from '@orkestrel/agent';
+import type { ProviderStreamOptions } from '@orkestrel/agent';
+import type { RequestMeasure } from '@orkestrel/agent';
+import type { ThinkingReplay } from '@orkestrel/agent';
+
+/**
+ * Builds the evidence join of a wire request to its canonical dispatch.
+ * @param dispatch - The measured dispatch, or undefined when the caller measured none
+ * @returns The dispatch id and revision, each null when unknown
+ */
+export declare function buildStudyAgentDispatch(dispatch: StudyAgentDispatch | undefined): Readonly<Record<string, JSONValue>>;
+
+/**
+ * Projects a request's structural components onto plain JSON without storing a total.
+ * @param measure - The runtime's disjoint per-message, tools and schema estimates
+ * @returns The same components in request order
+ */
+export declare function buildStudyAgentParts(measure: RequestMeasure): JSONValue;
+
+/**
+ * Builds a bounded schedule from explicit repetition rows and declared scenarios.
+ * @param definition - The frozen population declaration
+ * @param scenarios - The complete scenario declarations
+ * @returns Owned trials in repetition, scenario and row-arm order
+ * @throws StudyError - Thrown when the population or scenario set is invalid
+ * @example
+ * ```ts
+ * buildStudySchedule(definition, scenarios)
+ * ```
+ */
+export declare function buildStudySchedule(definition: StudyDefinition, scenarios: readonly StudyScenario[]): readonly StudyTrial[];
+
+/**
+ * Computes the stop of a request whose actual usage crossed the ceiling it was admitted under.
+ * @param charge - The request's admitted ceilings
+ * @param usage - The request's measured usage
+ * @returns The `scope` stop for the first quantity, tokens then bytes, whose known usage exceeds its admitted ceiling; undefined when none does
+ * @example
+ * ```ts
+ * computeStudyAdmittedStop({ role: 'agent', tokens: 10, bytes: 100 }, usage) // { layer: 'scope', id: 'Admitted tokens', max: 10, consumed: 12 }
+ * ```
+ */
+export declare function computeStudyAdmittedStop(charge: StudyCharge, usage: StudyUsage): StudyStop | undefined;
+
+/**
+ * Computes the stop of a product the output allowances cannot hold.
+ * @param bytes - The encoded size of the product's value
+ * @param limit - The goal's byte allowance
+ * @param outputs - The trial and series output budgets, in the order they refuse
+ * @returns The `Goal bytes` stop when the goal allowance refuses, else the stop of the first budget whose remaining room is below the product, with its tally including the refused product; undefined when every allowance holds it
+ * @example
+ * ```ts
+ * computeStudyOutputStop(2048, 1024, []) // { layer: 'scope', id: 'Goal bytes', max: 1024, consumed: 2048 }
+ * ```
+ */
+export declare function computeStudyOutputStop(bytes: number, limit: number, outputs: ReadonlyArray<BudgetInterface<number>>): StudyStop | undefined;
+
+/**
+ * Computes arm intervals over the complete declared criterion horizon.
+ * @param manifest - The sealed population and schedule
+ * @param rubric - The criterion declaration
+ * @param grading - Judgments bound to the complete scheduled attempt set
+ * @returns Whole-horizon scores in declared arm order
+ * @throws StudyError - Thrown when schedule, attempts or judgments are incompatible
+ * @example
+ * ```ts
+ * computeStudyScores(manifest, rubric, grading)
+ * ```
+ */
+export declare function computeStudyScores(manifest: StudyManifest, rubric: StudyRubric, grading: StudyGrading): readonly StudyScore[];
+
+/**
+ * Records an error that escaped admitted work as the failure of its ticket.
+ * @param ticket - The admitted request whose work escaped
+ * @param error - The caught value, read through `readStudyFailure`
+ * @param role - The responsibility that replaces any role the reading carries; Default: the carried role, else the ticket's admitted role
+ * @remarks
+ * A ticket that already settled or whose signal aborted is left untouched, because its owner
+ * already holds the failure. A remote ticket's aborted signal does not mean it settled locally,
+ * so the parent's ownership is respected rather than inferred as local settlement. A refusal
+ * thrown by the ticket's own settlement propagates.
+ * @throws Thrown when the ticket's settlement refuses the failure.
+ * @example Fail an escaped request
+ * ```ts
+ * import type { StudyTicket } from '@orkestrel/study'
+ * import { failStudyTicket } from '@orkestrel/study'
+ *
+ * declare const ticket: StudyTicket
+ *
+ * failStudyTicket(ticket, new Error('Provider refused'), 'tool')
+ * ```
+ */
+export declare function failStudyTicket(ticket: StudyTicket, error: unknown, role?: StudyRole): void;
+
+/** Converts an operational reading to its throwable boundary.
+ * @param failure - The retained operational reading.
+ * @returns An error preserving the reading's cause and responsibility.
+ */
+export declare function failureToStudyError(failure: StudyFailure): StudyError;
+
+/**
+ * Checks whether a namespace exposes the Agent capabilities the instrumentation invokes.
+ * @remarks
+ * The guard reads only `estimateRequest`, `measureRequest`, and `isAgentError`, so a namespace
+ * without Ledger or conversation factories passes. A throwing accessor returns false.
+ * @param value - The admitted namespace
+ * @returns True if every required capability is a function; false otherwise
+ */
+export declare function isStudyAgentRuntime(value: unknown): value is StudyAgentRuntime;
+
+/**
+ * Checks whether nested scopes admit no larger allowance than their parent.
+ * @param value - The candidate bounds
+ * @returns True if every nested allowance is ordered; false otherwise
+ * @example
+ * ```ts
+ * isStudyBounds({}) // false
+ * ```
+ */
+export declare function isStudyBounds(value: unknown): value is StudyBounds;
+
+/** Checks whether a value names an operational ending. */
+export declare const isStudyCause: Guard<StudyCause>;
+
+/**
+ * Checks whether a criterion declares exact grading inputs and references.
+ * @param value - The candidate criterion
+ * @returns True if its structural grading declaration is valid; false otherwise
+ * @example
+ * ```ts
+ * isStudyCriterion({ id: 'saved', scenario: 'shift', goal: 'write', method: 'state', critical: true, assertion: true }) // true
+ * ```
+ */
+export declare function isStudyCriterion(value: unknown): value is StudyCriterion;
+
+/**
+ * Checks whether a study freezes a complete arm order for every repetition.
+ * @param value - The candidate definition
+ * @returns True if its population and repetition orders are valid; false otherwise
+ * @example
+ * ```ts
+ * isStudyDefinition({ name: 'tools' }) // false
+ * ```
+ */
+export declare function isStudyDefinition(value: unknown): value is StudyDefinition;
+
+/**
+ * Checks whether a byte identity is a lowercase SHA-256 digest.
+ * @param value - The candidate identity
+ * @returns True if it has exactly 64 hexadecimal digits; false otherwise
+ * @example
+ * ```ts
+ * isStudyDigest('a'.repeat(64)) // true
+ * ```
+ */
+export declare function isStudyDigest(value: unknown): value is string;
+
+/**
+ * Narrows a caught value to an attributable study error.
+ * @remarks
+ * Recognition combines the native `Error` base, a subclass prototype, the fixed name, a declared
+ * study code, and an own {@link STUDY_ERROR_BRAND} descriptor whose value is the error itself.
+ * The global key is recognized across package, ESM, CommonJS and captured module copies; it is
+ * not unforgeable provenance. A transparent proxy is refused because its forwarded descriptor
+ * stores the target, and an unbranded copy, an inherited brand, or a property-only lookalike
+ * stays outside the type. Hostile property access returns false instead of throwing.
+ * @param value - The caught value
+ * @returns True if the value is a study error; false otherwise
+ * @example
+ * ```ts
+ * isStudyError(new StudyError('CONFIG', 'missing definition')) // true
+ * ```
+ */
+export declare function isStudyError(value: unknown): value is StudyError;
+
+/**
+ * Checks whether a value names a supported study error code.
+ * @param value - The candidate code
+ * @returns True if it is a declared study error code; false otherwise
+ * @example
+ * ```ts
+ * isStudyErrorCode('CONFIG') // true
+ * ```
+ */
+export declare function isStudyErrorCode(value: unknown): value is StudyErrorCode;
+
+/**
+ * Checks whether a goal has a bounded identifier and exact JSON input.
+ * @param value - The candidate goal
+ * @returns True if the goal is valid; false otherwise
+ * @example
+ * ```ts
+ * isStudyGoal({ id: 'write', input: { text: 'hello' } }) // true
+ * ```
+ */
+export declare function isStudyGoal(value: unknown): value is StudyGoal;
+
+/**
+ * Checks whether grading binds accountable judgments to unique attempt identities.
+ * @param value - The candidate grading
+ * @returns True if its identities, attempts and judgments are valid; false otherwise
+ * @example
+ * ```ts
+ * isStudyGrading({}) // false
+ * ```
+ */
+export declare function isStudyGrading(value: unknown): value is StudyGrading;
+
+/**
+ * Checks whether a judgment carries a supported verdict and evidence references.
+ * @param value - The candidate judgment
+ * @returns True if the judgment is attributable and structurally valid; false otherwise
+ * @example
+ * ```ts
+ * isStudyJudgment({ trial: 'r1-s1-a1', criterion: 'saved', verdict: 'unknown', method: 'state', reason: 'No evidence', references: [] }) // true
+ * ```
+ */
+export declare function isStudyJudgment(value: unknown): value is StudyJudgment;
+
+/**
+ * Checks whether imported semantic labels have accountable packet provenance.
+ * @param value - The candidate labels
+ * @returns True if provenance, usage and semantic judgments are valid; false otherwise
+ * @example
+ * ```ts
+ * isStudyLabeling({}) // false
+ * ```
+ */
+export declare function isStudyLabeling(value: unknown): value is StudyLabeling;
+
+/** Checks whether a value names a ceiling a run can stop at. */
+export declare const isStudyLayer: Guard<StudyLayer>;
+
+/**
+ * Checks whether all allowances are positive safe integers within timer bounds.
+ * @param value - The candidate limit
+ * @returns True if it defines finite positive allowances; false otherwise
+ * @example
+ * ```ts
+ * isStudyLimit({ duration: 1000, calls: 1, tokens: 100, bytes: 1024 }) // true
+ * ```
+ */
+export declare function isStudyLimit(value: unknown): value is StudyLimit;
+
+/**
+ * Checks whether an identifier is portable and bounded.
+ * @param value - The candidate identifier
+ * @returns True if it is a portable study identifier; false otherwise
+ * @example
+ * ```ts
+ * isStudyName('memory') // true
+ * ```
+ */
+export declare function isStudyName(value: unknown): value is string;
+
+/**
+ * Checks a retained public product without awarding task achievement.
+ * @param value - The candidate product
+ * @returns True if the product carries JSON output and partial status; false otherwise
+ * @example
+ * ```ts
+ * isStudyProduct({ value: { answer: 1 }, partial: true }) // true
+ * ```
+ */
+export declare function isStudyProduct(value: unknown): value is StudyProduct;
+
+/**
+ * Checks whether a profile carries finite bounds and an optional explicit provider.
+ * @param value - The candidate profile
+ * @returns True if the profile is structurally valid; false otherwise
+ * @example
+ * ```ts
+ * isStudyProfile({ name: 'local' }) // false
+ * ```
+ */
+export declare function isStudyProfile(value: unknown): value is StudyProfile;
+
+/**
+ * Checks whether a provider declaration names artifacts, an HTTP origin and models.
+ * @param value - The candidate provider declaration
+ * @returns True if the declaration has a supported origin, nonempty names, and a judge declared with its digest or not at all; false otherwise
+ * @example
+ * ```ts
+ * isStudyProvider({ entry: 'dist/index.js' }) // false
+ * ```
+ */
+export declare function isStudyProvider(value: unknown): value is StudyProvider;
+
+/** Checks whether a value names a measured request role. */
+export declare const isStudyRole: Guard<StudyRole>;
+
+/**
+ * Checks whether generation room leaves positive context for input.
+ * @param value - The candidate room
+ * @returns True if input, output and safety allowances fit and any declared recap fits; false otherwise
+ * @example
+ * ```ts
+ * isStudyRoom({ context: 20480, output: 8192, safety: 512, recap: 2048, think: true }) // true
+ * isStudyRoom({ context: 20480, output: 8192, safety: 512, think: true }) // true
+ * ```
+ */
+export declare function isStudyRoom(value: unknown): value is StudyRoom;
+
+/**
+ * Checks whether a rubric declares nonempty criteria with unique identities.
+ * @param value - The candidate rubric
+ * @returns True if its version and criteria are valid; false otherwise
+ * @example
+ * ```ts
+ * isStudyRubric({ version: '1', criteria: [] }) // false
+ * ```
+ */
+export declare function isStudyRubric(value: unknown): value is StudyRubric;
+
+/**
+ * Checks whether a scenario declares a nonempty horizon with unique goal ids.
+ * @param value - The candidate scenario
+ * @returns True if the scenario has a valid horizon; false otherwise
+ * @example
+ * ```ts
+ * isStudyScenario({ id: 'shift', goals: [{ id: 'handoff', input: 'Prepare handoff' }] }) // true
+ * ```
+ */
+export declare function isStudyScenario(value: unknown): value is StudyScenario;
+
+/**
+ * Checks whether a value is the exact record of a ceiling that stopped a run.
+ * @remarks
+ * The guard accepts exact own data keys: `layer` and `id` are required and `max` and `consumed` are
+ * optional. `max` and `consumed` are each undefined or a finite number. Finite foreign readings,
+ * including negative and fractional values, retain the source's measurement unchanged.
+ * @param value - The candidate stop
+ * @returns True if the layer is known, the id is nonempty, and every reading is absent or finite; false otherwise
+ * @example
+ * ```ts
+ * isStudyStop({ layer: 'scope', id: 'Goal tokens', max: 100, consumed: 120 }) // true
+ * ```
+ */
+export declare function isStudyStop(value: unknown): value is StudyStop;
+
+/**
+ * Checks whether a timestamp is a canonical UTC millisecond instant.
+ * @param value - The candidate timestamp
+ * @returns True if it is a valid canonical timestamp; false otherwise
+ * @example
+ * ```ts
+ * isStudyTimestamp('2026-10-14T12:00:00.000Z') // true
+ * ```
+ */
+export declare function isStudyTimestamp(value: unknown): value is string;
+
+/**
+ * Checks whether request usage contains nonnegative safe measurements.
+ * @param value - The candidate usage
+ * @returns True if the role and every known measurement are valid; false otherwise
+ * @example
+ * ```ts
+ * isStudyUsage({ role: 'tool', calls: 0, bytes: 0, duration: 0 }) // true
+ * ```
+ */
+export declare function isStudyUsage(value: unknown): value is StudyUsage;
+
+/**
+ * Matches exact own enumerable data keys without evaluating accessors.
+ * @param value - The candidate record
+ * @param required - Required keys
+ * @param optional - Allowed optional keys
+ * @returns True if the record has exactly the allowed data keys; false otherwise
+ * @example Check exact keys
+ * ```ts
+ * import { matchesStudyKeys } from '@orkestrel/study'
+ *
+ * matchesStudyKeys({ id: 'one' }, ['id']) // true
+ * ```
+ */
+export declare function matchesStudyKeys(value: unknown, required: readonly string[], optional?: readonly string[]): boolean;
+
+/**
+ * Omits every undefined optional declaration so the profile has one JSON form.
+ * @param profile - The validated profile whose optional leaves may be undefined
+ * @returns The profile fields with absent qualification, settings, provider, judge and recap removed
+ * @example
+ * ```ts
+ * normalizeStudyProfile(profile) // no `recap` key when the room declares none
+ * ```
+ */
+export declare function normalizeStudyProfile(profile: StudyProfile): Readonly<Record<string, unknown>>;
+
+/**
+ * Copies the own entries of a record that hold a value, in their original order.
+ * @param value - The record whose undefined entries are absent declarations
+ * @returns A new record without the undefined entries
+ * @example
+ * ```ts
+ * omitStudyAbsent({ context: 512, recap: undefined }) // { context: 512 }
+ * ```
+ */
+export declare function omitStudyAbsent(value: object): Readonly<Record<string, unknown>>;
+
+/**
+ * Parses a definition into an independent frozen validated snapshot.
+ * @param value - The unknown configuration
+ * @returns The owned study definition
+ * @throws StudyError - Thrown when configuration is invalid or cannot be owned
+ * @example
+ * ```ts
+ * parseStudyDefinition(configuration)
+ * ```
+ */
+export declare function parseStudyDefinition(value: unknown): StudyDefinition;
+
+/**
+ * Parses grading into an independent frozen validated evidence snapshot.
+ * @param value - The unknown grading evidence
+ * @returns The owned grading identity and judgments
+ * @throws StudyError - Thrown when evidence is invalid or cannot be owned
+ * @example
+ * ```ts
+ * parseStudyGrading(evidence)
+ * ```
+ */
+export declare function parseStudyGrading(value: unknown): StudyGrading;
+
+/**
+ * Parses semantic labels into an independent frozen validated evidence snapshot.
+ * @param value - The unknown imported labels
+ * @returns The owned packet provenance, usage and judgments
+ * @throws StudyError - Thrown when evidence is invalid or cannot be owned
+ * @example
+ * ```ts
+ * parseStudyLabeling(evidence)
+ * ```
+ */
+export declare function parseStudyLabeling(value: unknown): StudyLabeling;
+
+/**
+ * Parses a profile into an independent frozen validated snapshot.
+ * @param value - The unknown configuration
+ * @returns The owned profile with absent optional settings preserved
+ * @throws StudyError - Thrown when configuration is invalid or cannot be owned
+ * @example
+ * ```ts
+ * parseStudyProfile(configuration)
+ * ```
+ */
+export declare function parseStudyProfile(value: unknown): StudyProfile;
+
+/**
+ * Parses a foreign reading into a number a stop can retain.
+ * @param value - The unknown reading a source reports
+ * @returns The value when it is a finite number; undefined otherwise
+ * @example
+ * ```ts
+ * parseStudyReading(2048) // 2048
+ * parseStudyReading(Number.NaN) // undefined
+ * ```
+ */
+export declare function parseStudyReading(value: unknown): number | undefined;
+
+/**
+ * Parses a rubric into an independent frozen validated snapshot.
+ * @param value - The unknown grading declaration
+ * @returns The owned rubric and assertion inputs
+ * @throws StudyError - Thrown when configuration is invalid or cannot be owned
+ * @example
+ * ```ts
+ * parseStudyRubric(configuration)
+ * ```
+ */
+export declare function parseStudyRubric(value: unknown): StudyRubric;
+
+/**
+ * Parses a scenario into an independent frozen validated snapshot.
+ * @param value - The unknown configuration
+ * @returns The owned scenario and goal inputs
+ * @throws StudyError - Thrown when configuration is invalid or cannot be owned
+ * @example
+ * ```ts
+ * parseStudyScenario({ id: 'shift', goals: [{ id: 'write', input: {} }] })
+ * ```
+ */
+export declare function parseStudyScenario(value: unknown): StudyScenario;
+
+/**
+ * Prices a runtime estimate through an explicit gauge.
+ * @param gauge - The declared scale and overhead
+ * @param estimate - The runtime's estimate of one complete request
+ * @returns The projected prompt tokens, rounded up
+ */
+export declare function projectStudyAgentRequest(gauge: LedgerGauge, estimate: number): number;
+
+/** Reads an operational error without inventing a task verdict.
+ * @remarks
+ * A branded `BudgetError` from any copy of the budget package reads as a `budget` stop, because the
+ * error alone does not prove which budget object raised it; the Agent record names a `meter` stop.
+ * An unbranded lookalike reads as an infrastructure failure.
+ * @param error - The caught error.
+ * @returns Existing attribution, the capacity a branded budget error names, the cause a bare
+ * capacity or deadline code names, or an infrastructure failure.
+ */
+export declare function readStudyFailure(error: unknown): StudyFailure;
+
+/** Lists every operational ending in report order. */
+export declare const STUDY_CAUSES: readonly StudyCause[];
+
+/**
+ * Keys the own self-identity every study error stamps on itself.
+ * @remarks
+ * The global symbol registry lets every package, ESM, CommonJS and captured copy read the same
+ * key. The registry makes the key discoverable; it is a recognition mechanism, not an
+ * unforgeable provenance marker.
+ */
+export declare const STUDY_ERROR_BRAND: unique symbol;
+
+/** Caps a declared scenario horizon before execution. */
+export declare const STUDY_GOALS = 4096;
+
+/** Lists every ceiling a run can stop at in report order. */
+export declare const STUDY_LAYERS: readonly StudyLayer[];
+
+/** Restricts identifiers to portable path-safe names. */
+export declare const STUDY_NAME: RegExp;
+
+/** Lists every measured request role in report order. */
+export declare const STUDY_ROLES: readonly StudyRole[];
+
+/** Caps a declared trial population before schedule allocation. */
+export declare const STUDY_TRIALS = 4096;
+
+/** Admits requests against enclosing limits before an adapter dispatches them. */
+export declare interface StudyAdmissionInterface {
+    readonly signal: AbortSignal;
+    readonly usage: readonly StudyUsage[];
+    /** Resolves admission before dispatch; local meters may return the ticket synchronously. */
+    admit(charge: StudyCharge): StudyTicket | Promise<StudyTicket>;
+}
+
+/** Holds the trial-local canonical dispatch identity a wire request joins to. */
+export declare interface StudyAgentDispatch {
+    readonly id: number;
+    /** Holds the SHA-256 revision of the canonical request, or undefined when it could not be rendered. */
+    readonly revision: string | undefined;
+}
+
+/** Latches a real judge's failure before an enclosing runtime can treat it as absent. */
+export declare class StudyAgentJudge implements JudgeInterface {
+    #private;
+    /** Binds a real public judge to the trial's failure owner.
+     * @param judge - The admitted judge every question is delegated to.
+     * @param latch - The owner that retains the first operational failure.
+     */
+    constructor(judge: JudgeInterface, latch: StudyLatchInterface);
+    /** Reports the delegate's trace label. */
+    get id(): string;
+    /** Reports the delegate's backend name. */
+    get name(): string;
+    /** Reports the delegate's model identity. */
+    get model(): string;
+    /** Refuses dispatch after a retained failure and retains a thrown failure with its identity.
+     * @param request - The real classification request.
+     * @param signal - The caller's cancellation.
+     * @returns The unmodified judge result.
+     */
+    ask(request: JudgeRequest, signal: AbortSignal): Promise<JudgeResult>;
+}
+
+/** Reads each Agent request's size before delegating it unchanged to the real provider. */
+export declare class StudyAgentObserver implements ProviderInterface {
+    #private;
+    /** Binds the real provider, the measuring runtime, the explicit gauge and usage policy, and the reading recorder.
+     * @param options - Delegate, measurement seam, and policies.
+     */
+    constructor(options: StudyAgentObserverOptions);
+    /** Reports the delegate's trace label. */
+    get id(): string;
+    /** Reports the delegate's backend name. */
+    get name(): string;
+    /** Reports the delegate's thinking replay policy; an absent policy is the declared `none`. */
+    get replay(): ThinkingReplay;
+    /** Records one reading, then awaits the real generation.
+     * @param messages - The conversation sent.
+     * @param signal - Bounds the request.
+     * @param tools - The tools advertised this turn.
+     * @param options - The per-call options.
+     * @returns The real provider's result.
+     */
+    generate(messages: readonly Message[], signal: AbortSignal, tools?: ProviderRequest['tools'], options?: ProviderStreamOptions): Promise<ProviderResult>;
+    /** Records one reading, then relays the real stream.
+     * @param messages - The conversation sent.
+     * @param signal - Bounds the request.
+     * @param tools - The tools advertised this turn.
+     * @param options - The per-call options.
+     * @returns The real deltas and result.
+     */
+    stream(messages: readonly Message[], signal: AbortSignal, tools?: ProviderRequest['tools'], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
+}
+
+/**
+ * Holds the observing provider's delegate, measurement seam and explicit policies.
+ * @remarks
+ * `provider` receives every call unchanged. `runtime` measures each request. `gauge` prices each
+ * reading; undefined prices nothing. `enforced` selects the usage policy: if `true`, a successful,
+ * unaborted return must report a usable actual prompt count; if `false`, the observer reads usage
+ * passively and refuses nothing. `record` receives exactly one reading, synchronously, before
+ * each delegated call.
+ */
+export declare interface StudyAgentObserverOptions {
+    readonly provider: ProviderInterface;
+    readonly runtime: Pick<StudyAgentRuntime, 'estimateRequest'>;
+    readonly gauge: LedgerGauge | undefined;
+    readonly enforced: boolean;
+    readonly record: StudyAgentRecordHandler;
+}
+
+/** Holds one dispatched request's explicit size reading. */
+export declare interface StudyAgentReading {
+    /** Holds the runtime's estimate of the complete pre-encoding request. */
+    readonly estimate: number;
+    /** Holds the gauge projection of that estimate; undefined when no gauge applies. */
+    readonly projected: number | undefined;
+}
+
+/** Receives one reading and the exact pre-encoding request it measured. */
+export declare type StudyAgentRecordHandler = (reading: StudyAgentReading, request: ProviderRequest) => void;
+
+/**
+ * Holds the admitted Agent namespace capabilities the shared instrumentation invokes.
+ * @remarks
+ * Each member has the exact signature of the export of the same name in the selected Agent
+ * runtime. The consumer supplies the admitted namespace; the instrumentation never imports a
+ * runtime value from an installed Agent copy. No Ledger capability is required.
+ */
+export declare interface StudyAgentRuntime {
+    readonly estimateRequest: typeof estimateRequest;
+    readonly measureRequest: typeof measureRequest;
+    readonly isAgentError: typeof isAgentError;
+}
+
+/** Holds a terminal trial record, including goals never dispatched. */
+export declare interface StudyAttempt {
+    readonly trial: StudyTrial;
+    readonly observations: readonly StudyObservation[];
+    readonly failure: StudyFailure | undefined;
+    readonly duration: number;
+    /** Records whether the trial entered execution without an inherited terminal series failure, including failures before the driver opened; not a claim that the driver was opened. */
+    readonly executed: boolean;
+}
+
+/** Holds nested execution allowances; each request also has a deadline. */
+export declare interface StudyBounds {
+    readonly request: StudyLimit;
+    readonly goal: StudyLimit;
+    readonly trial: StudyLimit;
+    readonly series: StudyLimit;
+}
+
+/**
+ * Names an operational ending separately from task achievement.
+ * @remarks
+ * `content` means a request completed but its consumer refused the content as unusable. It
+ * claims no model or decoder cause and grades no semantic quality.
+ */
+export declare type StudyCause = 'capacity' | 'infrastructure' | 'deadline' | 'interrupted' | 'content';
+
+/** Holds a request's pre-dispatch upper bounds. */
+export declare interface StudyCharge {
+    readonly role: StudyRole;
+    readonly tokens: number;
+    readonly bytes: number;
+}
+
+/** Holds the resources visible to one running goal. */
+export declare interface StudyContext {
+    readonly signal: AbortSignal;
+    readonly meter: StudyAdmissionInterface;
+    readonly evidence: StudySinkInterface;
+}
+
+/** Retains the first operational failure while bounding asynchronous waits. */
+export declare class StudyControl implements StudyControlInterface {
+    #private;
+    /** Links cancellation to the caller without assigning it a task verdict.
+     * @param signal - Optional parent cancellation.
+     */
+    constructor(signal?: AbortSignal);
+    get signal(): AbortSignal;
+    get failure(): StudyFailure | undefined;
+    /** Latches an operational failure and cancels all linked work.
+     * @param failure - The first attribution to preserve.
+     */
+    fail(failure: StudyFailure): void;
+    /** Races work against cancellation and removes its listener after either ending.
+     * @param work - Already-started work whose rejection remains observed after cancellation.
+     * @returns The work's result if it settles before cancellation.
+     * @throws Thrown with the retained operational attribution when cancelled.
+     */
+    wait<T>(work: PromiseLike<T>): Promise<T>;
+    /** Removes the lifecycle listener without changing the retained failure. */
+    close(): void;
+}
+
+/** Owns the first operational failure and cancellation of enclosing work. */
+export declare interface StudyControlInterface {
+    readonly signal: AbortSignal;
+    readonly failure: StudyFailure | undefined;
+    /** Latches an operational failure and cancels all linked work.
+     * @param failure - The first attribution to preserve.
+     * @returns Nothing after failure propagation.
+     */
+    fail(failure: StudyFailure): void;
+    /** Races work against cancellation and removes its listener after either ending.
+     * @param work - Work whose late rejection remains observed.
+     * @returns The result when work settles before cancellation.
+     */
+    wait<T>(work: PromiseLike<T>): Promise<T>;
+    /** Removes the lifecycle listener without changing the retained failure.
+     * @returns Nothing after listener release.
+     */
+    close(): void;
+}
+
+/** Holds a grader-owned criterion outside the driver's public input. */
+export declare interface StudyCriterion {
+    readonly id: string;
+    readonly scenario: string;
+    readonly goal: string;
+    readonly method: 'state' | 'trace' | 'semantic';
+    readonly critical: boolean;
+    readonly assertion: JSONValue;
+}
+
+/** Bounds each independent operation with a fresh failure owner and deadline. */
+export declare class StudyDeadline implements StudyDeadlineInterface {
+    #private;
+    /** Retains the deadline without starting a timer.
+     * @param options - Finite duration in milliseconds and diagnostic label.
+     */
+    constructor(options: StudyDeadlineOptions);
+    /** Waits for work under a fresh failure owner and releases its timer and listener.
+     * @param work - Already-started work whose late rejection remains observed.
+     * @returns The work's result when it settles before the deadline.
+     * @throws Thrown for an invalid duration, the work's own rejection, or the labelled deadline.
+     */
+    wait<T>(work: PromiseLike<T>): Promise<T>;
+}
+
+/** Bounds one independent asynchronous operation under its own deadline. */
+export declare interface StudyDeadlineInterface {
+    /** Waits for work under a fresh failure owner and releases its timer and listener.
+     * @param work - Already-started work whose late rejection remains observed.
+     * @returns The work's result when it settles before the deadline.
+     */
+    wait<T>(work: PromiseLike<T>): Promise<T>;
+}
+
+/** Supplies one bounded operation's finite deadline and diagnostic label. */
+export declare interface StudyDeadlineOptions {
+    readonly duration: number;
+    readonly label: string;
+}
+
+/** Holds the frozen study question, population and explicit repetition orders. */
+export declare interface StudyDefinition {
+    readonly name: string;
+    readonly version: string;
+    readonly question: string;
+    readonly purpose: StudyPurpose;
+    readonly driver: string;
+    readonly arms: readonly string[];
+    readonly scenarios: readonly string[];
+    readonly order: ReadonlyArray<readonly string[]>;
+    readonly retries: 0;
+    readonly rubric: string;
+}
+
+/** Creates isolated domain state through a concrete package consumer. */
+export declare interface StudyDriverInterface {
+    /** Creates fresh domain state for one scheduled trial.
+     * @param trial - The scheduled scenario, arm, and repetition.
+     * @param signal - The caller's cancellation.
+     * @returns The isolated session for this trial.
+     */
+    open(trial: StudyTrial, signal: AbortSignal): Promise<StudySessionInterface>;
+}
+
+/** Reports a study contract or operational failure with a stable code. */
+export declare class StudyError extends Error {
+    readonly code: StudyErrorCode;
+    readonly failure: StudyFailure | undefined;
+    /**
+     * Records the failing boundary and optional operational attribution.
+     * @param code - The machine-readable boundary
+     * @param message - The specific failure
+     * @param failure - The optional operational reading
+     */
+    constructor(code: StudyErrorCode, message: string, failure?: StudyFailure);
+}
+
+/** Names malformed configuration, evidence, custody and operational failures. */
+export declare type StudyErrorCode = 'CONFIG' | 'EVIDENCE' | 'CUSTODY' | 'CAPACITY' | 'FAULT' | 'DEADLINE';
+
+/** Holds append-only domain evidence in a JSON-compatible form. */
+export declare interface StudyEvidence {
+    readonly event: string;
+    readonly goal: string;
+    readonly value: JSONValue;
+}
+
+/** Holds an attributable operational fault without awarding a task verdict. */
+export declare interface StudyFailure {
+    readonly cause: StudyCause;
+    readonly message: string;
+    readonly role: StudyRole | undefined;
+    /** Names the ceiling that stopped the run; undefined for a failure no ceiling caused, and for a record sealed before this member existed. */
+    readonly stop: StudyStop | undefined;
+}
+
+/** Holds a declared goal's public input without its grading truth. */
+export declare interface StudyGoal {
+    readonly id: string;
+    readonly input: JSONValue;
+}
+
+/** Holds a grading identity that cannot replace or mutate execution bytes. */
+export declare interface StudyGrading {
+    readonly result: string;
+    readonly rubric: string;
+    readonly grader: string;
+    readonly instrument: string;
+    readonly attempts: readonly string[];
+    readonly labels: string | undefined;
+    /** Binds the retained public packet and private mapping when semantic criteria exist. */
+    readonly packet?: string;
+    readonly judgments: readonly StudyJudgment[];
+}
+
+/** Holds byte identities that qualification and comparisons must agree on. */
+export declare interface StudyIdentity {
+    readonly agent: string;
+    readonly subject: string;
+    readonly provider: string | undefined;
+    readonly instrument: string;
+    readonly fixtures: string;
+    readonly profile: string;
+}
+
+/** Holds an evidence-backed verdict; missing evidence stays unknown. */
+export declare interface StudyJudgment {
+    readonly trial: string;
+    readonly criterion: string;
+    readonly verdict: 'achieved' | 'unsuccessful' | 'unknown';
+    readonly method: 'state' | 'trace' | 'human' | 'model';
+    readonly reason: string;
+    readonly references: readonly string[];
+}
+
+/** Holds imported semantic judgments and their accountable origin. */
+export declare interface StudyLabeling {
+    readonly packet: string;
+    readonly labeler: string;
+    readonly version: string;
+    readonly created: string;
+    readonly usage: readonly StudyUsage[];
+    readonly judgments: readonly StudyJudgment[];
+}
+
+/** Retains the first operational failure of instrumented work and refuses work after it. */
+export declare interface StudyLatchInterface {
+    /** Refuses work after a retained failure or cancellation.
+     * @returns Nothing when work may continue.
+     */
+    check(): void;
+    /** Retains an operational failure even when an enclosing runtime catches it.
+     * @param error - The observed failure; an earlier retained failure keeps its identity, and a branded `BudgetError` can retain nothing because Agent reports that stop in its own result.
+     * @returns Nothing after retention.
+     */
+    fail(error: unknown): void;
+}
+
+/**
+ * Names the ceiling that stopped a run.
+ * @remarks
+ * `scope` is a limit Study declares: the calls, tokens, bytes, or duration of a request, goal,
+ * trial, series, or operation, the product output allowance, and a provider's declared byte bound.
+ * `window` is a prompt room. `custody` is an evidence allowance. `meter`, `budget`, and `model`
+ * mirror the `layer` of the `AgentStop` type from `@orkestrel/agent`: the run's estimate allowance,
+ * any other budget, and the model's own token limit, which also names the daemon's context and
+ * output caps.
+ */
+export declare type StudyLayer = 'scope' | 'window' | 'custody' | 'meter' | 'budget' | 'model';
+
+/** Holds finite allowances in milliseconds, calls, tokens and bytes. */
+export declare interface StudyLimit {
+    readonly duration: number;
+    readonly calls: number;
+    readonly tokens: number;
+    readonly bytes: number;
+}
+
+/** Holds the execution declaration sealed before any trial begins. */
+export declare interface StudyManifest {
+    readonly id: string;
+    readonly created: string;
+    readonly definition: StudyDefinition;
+    readonly scenarios: readonly StudyScenario[];
+    readonly identity: StudyIdentity;
+    readonly schedule: readonly StudyTrial[];
+    readonly bounds: StudyBounds;
+    readonly qualification: string | undefined;
+    readonly host: Readonly<Record<string, string>>;
+}
+
+/** Admits request ceilings across every enclosing scope before dispatch. */
+export declare class StudyMeter implements StudyMeterInterface {
+    #private;
+    /** Holds the goal's shared admission scopes.
+     * @param options - Request bound, enclosing scopes, and shared failure owner.
+     */
+    constructor(options: StudyMeterOptions);
+    get signal(): AbortSignal;
+    get usage(): readonly StudyUsage[];
+    /** Reserves one request atomically across all enclosing allowances.
+     * @param charge - Safe integer token and byte ceilings with the request's role.
+     * @returns A request ticket that must settle before the goal completes.
+     * @throws Thrown before dispatch if the request exceeds available capacity.
+     */
+    admit(charge: StudyCharge): StudyTicket;
+    /** Refuses unfinished requests before closing a goal's admission boundary. */
+    close(): void;
+}
+
+/** Owns request admission and the goal's terminal lifecycle. */
+export declare interface StudyMeterInterface extends StudyAdmissionInterface {
+    /** Refuses unfinished requests before closing a goal's admission boundary.
+     * @returns Nothing after admission closes.
+     */
+    close(): void;
+}
+
+/** Supplies the request allowance and all enclosing admission scopes. */
+export declare interface StudyMeterOptions {
+    readonly request: StudyLimit;
+    readonly scopes: readonly StudyScopeInterface[];
+    readonly control: StudyControlInterface;
+}
+
+/** Holds the retained outcome of a scheduled goal. */
+export declare interface StudyObservation {
+    readonly goal: string;
+    readonly product: StudyProduct | undefined;
+    readonly failure: StudyFailure | undefined;
+    readonly usage: readonly StudyUsage[];
+    readonly duration: number;
+    /** Records whether the engine dispatched the goal to the session; never inferred from product, usage, duration or failure. */
+    readonly executed: boolean;
+}
+
+/** Holds observed output and partial completion, never self-awarded success. */
+export declare interface StudyProduct {
+    readonly value: JSONValue;
+    readonly partial: boolean;
+}
+
+/** Holds execution settings independently of scenario and grading declarations. */
+export declare interface StudyProfile {
+    readonly name: string;
+    /** Selects the Agent runtime entry, independently of the package under study. */
+    readonly agent: string;
+    /** Selects the entry of the package under study; it can equal the Agent entry. */
+    readonly subject: string;
+    readonly roots: readonly string[];
+    readonly bounds: StudyBounds;
+    readonly room: StudyRoom;
+    readonly provider: StudyProvider | undefined;
+    readonly qualification: string | undefined;
+    /** Holds driver-owned JSON; the driver owns its interpretation and Study only validates and owns the object. */
+    readonly settings: Readonly<Record<string, JSONValue>> | undefined;
+}
+
+/** Holds caller-selected provider artifacts and model identities. */
+export declare interface StudyProvider {
+    readonly entry: string;
+    readonly url: string;
+    readonly model: string;
+    /** Names the judge model; declared together with its digest or both absent. */
+    readonly judge: string | undefined;
+    /** Pins the serving inventory independently of mutable model names. */
+    readonly digest: {
+        readonly model: string;
+        /** Pins the judge model; declared together with its name or both absent. */
+        readonly judge: string | undefined;
+    };
+}
+
+/** Names the evidence a study can establish. */
+export declare type StudyPurpose = 'mechanism' | 'quality' | 'capacity';
+
+/** Settles an admitted request once and propagates operational failure to its owner. */
+export declare class StudyRequest implements StudyTicket {
+    #private;
+    /** Starts the request deadline after its enclosing scopes reserve capacity.
+     * @param options - Admitted ceilings, request deadline, and settlement callback.
+     */
+    constructor(options: StudyRequestOptions);
+    get signal(): AbortSignal;
+    get settled(): boolean;
+    /** Retains actual measurements and refuses invalid or excessive charges.
+     * @param usage - Measurements attributed to exactly this request.
+     * @throws Thrown when settlement is late, repeated, invalid, or beyond admission.
+     */
+    finish(usage: StudyUsage): void;
+    /** Retains unknown cost conservatively and latches the first operational failure.
+     * @param failure - The operational request failure.
+     * @throws Thrown when this request was already settled.
+     */
+    fail(failure: StudyFailure): void;
+}
+
+/** Supplies one admitted request with its shared failure owner and settlement sink. */
+export declare interface StudyRequestOptions {
+    readonly charge: StudyCharge;
+    readonly duration: number;
+    readonly control: StudyControlInterface;
+    readonly settle: StudySettlementHandler;
+}
+
+/** Names a request's measured responsibility. */
+export declare type StudyRole = 'agent' | 'judge' | 'summary' | 'metadata' | 'tool';
+
+/** Holds the model context and generation allowance as separate measurements. */
+export declare interface StudyRoom {
+    readonly context: number;
+    readonly output: number;
+    readonly safety: number;
+    /** Declares the recap allowance; absent when the workflow produces no recap. */
+    readonly recap: number | undefined;
+    readonly think: boolean;
+}
+
+/** Holds a versioned grading declaration independently of execution. */
+export declare interface StudyRubric {
+    readonly version: string;
+    readonly criteria: readonly StudyCriterion[];
+}
+
+/** Holds ordered goals sharing state within an isolated trial. */
+export declare interface StudyScenario {
+    readonly id: string;
+    readonly goals: readonly StudyGoal[];
+}
+
+/** Reserves finite request ceilings around cumulative actual budgets and one deadline. */
+export declare class StudyScope implements StudyScopeInterface {
+    #private;
+    /** Starts a timed scope with independent counters.
+     * @param options - Finite limit, shared failure owner, and diagnostic label.
+     */
+    constructor(options: StudyScopeOptions);
+    /** Checks cumulative consumption and every pending ceiling before admission.
+     * @param charge - One prospective request's ceilings.
+     * @throws Thrown when this scope cannot admit the request.
+     */
+    check(charge?: StudyCharge): void;
+    /** Reserves one request after the enclosing meter checked all scopes.
+     * @param id - The request's unique reservation identity.
+     * @param charge - Its admitted ceilings.
+     */
+    reserve(id: symbol, charge: StudyCharge): void;
+    /** Commits known charges while retaining ceilings for missing measurements.
+     * @param id - The pending reservation identity.
+     * @param usage - The request's retained public measurements.
+     */
+    settle(id: symbol, usage: StudyUsage): void;
+    /** Checks deadline attribution before clearing the timer. */
+    close(): void;
+}
+
+/** Holds cumulative admission ceilings for one timed execution scope. */
+export declare interface StudyScopeInterface {
+    /** Checks cumulative consumption and every pending ceiling before admission.
+     * @param charge - The prospective request's ceilings, when supplied.
+     * @returns Nothing when admission remains possible.
+     */
+    check(charge?: StudyCharge): void;
+    /** Reserves one request after the enclosing meter checked all scopes.
+     * @param id - The reservation identity.
+     * @param charge - The admitted ceilings.
+     * @returns Nothing after reservation.
+     */
+    reserve(id: symbol, charge: StudyCharge): void;
+    /** Commits known charges while retaining ceilings for missing measurements.
+     * @param id - The pending reservation identity.
+     * @param usage - The retained public measurements.
+     * @returns Nothing after settlement.
+     */
+    settle(id: symbol, usage: StudyUsage): void;
+    /** Checks deadline attribution before clearing the timer.
+     * @returns Nothing after resource release.
+     */
+    close(): void;
+}
+
+/** Supplies one deadline and its shared failure owner. */
+export declare interface StudyScopeOptions {
+    readonly limit: StudyLimit;
+    readonly control: StudyControlInterface;
+    readonly label: string;
+}
+
+/** Holds an arm's whole-horizon counts without hiding unresolved criteria. */
+export declare interface StudyScore {
+    readonly arm: string;
+    readonly total: number;
+    readonly achieved: number;
+    readonly unsuccessful: number;
+    readonly unknown: number;
+    readonly critical: number;
+    readonly lower: number;
+    readonly upper: number;
+    readonly coverage: number;
+}
+
+/** Executes a frozen serial study schedule with finite admission and sticky failures. */
+export declare class StudySeries {
+    #private;
+    /** Owns the declared inputs while retaining the concrete driver and custody store.
+     * @param options - Frozen manifest, concrete adapters, and parent cancellation.
+     */
+    constructor(options: StudySeriesOptions);
+    /** Runs every declared trial once and retains explicit unexecuted observations after failure.
+     * Custody rejection leaves the run unsealed; callers must seal only a fulfilled execution.
+     * @returns Ordered terminal attempts without task success labels.
+     * @throws Thrown for invalid configuration or failed or timed out custody operations.
+     */
+    execute(): Promise<readonly StudyAttempt[]>;
+}
+
+/** Holds the common engine's fixed execution inputs. */
+export declare interface StudySeriesOptions {
+    readonly manifest: StudyManifest;
+    readonly driver: StudyDriverInterface;
+    readonly store: StudyStoreInterface;
+    readonly signal: AbortSignal;
+}
+
+/** Owns domain state across a trial and releases it before the next trial. */
+export declare interface StudySessionInterface {
+    /** Executes one public goal against the trial's retained domain state.
+     * @param goal - The declared public input.
+     * @param context - Cancellation, borrowed admission, and evidence custody.
+     * @returns The observed product without a task verdict.
+     */
+    execute(goal: StudyGoal, context: StudyContext): Promise<StudyProduct>;
+    /** Releases the trial's domain resources.
+     * @returns A promise that resolves after release.
+     */
+    close(): Promise<void>;
+}
+
+/** Records the settlement of one admitted request. */
+export declare type StudySettlementHandler = (usage: StudyUsage) => void;
+
+/** Holds an evidence sink whose implementation owns byte limits and custody. */
+export declare interface StudySinkInterface {
+    /** Appends bounded domain evidence to the owned execution record.
+     * @param evidence - The public evidence for a declared goal.
+     * @returns A promise that resolves when custody accepts the bytes.
+     */
+    append(evidence: StudyEvidence): Promise<void>;
+}
+
+/**
+ * Holds the ceiling that stopped a run and the readings it crossed.
+ * @remarks
+ * `id` names the ceiling: a Study label and quantity such as `Goal tokens`, an Agent budget's trace
+ * id, or the provider option that capped the model such as `num_predict`. `max` is the ceiling and
+ * `consumed` the tally at the crossing, the refused charge included; each is undefined when its
+ * source reports none. On the `model` layer `max` is the cap and `consumed` the completion or prompt.
+ * Finite foreign readings retain their source values, including negative and fractional values.
+ */
+export declare interface StudyStop {
+    readonly layer: StudyLayer;
+    readonly id: string;
+    readonly max: number | undefined;
+    readonly consumed: number | undefined;
+}
+
+/**
+ * Projects a stop onto JSON with every unreported reading as null.
+ * @param stop - The ceiling that stopped a run
+ * @returns The stop's layer, id, and readings, with an undefined `max` or `consumed` as null
+ * @example
+ * ```ts
+ * studyStopToJSON({ layer: 'model', id: 'num_predict', max: 2048, consumed: undefined })
+ * // { layer: 'model', id: 'num_predict', max: 2048, consumed: null }
+ * ```
+ */
+export declare function studyStopToJSON(stop: StudyStop): JSONValue;
+
+/** Appends terminal records without overwriting a prior attempt. */
+export declare interface StudyStoreInterface {
+    /** Opens append-only evidence custody for one scheduled trial.
+     * @param trial - The exact scheduled trial.
+     * @returns The borrowed evidence sink.
+     */
+    start(trial: StudyTrial): Promise<StudySinkInterface>;
+    /** Retains the terminal record for one scheduled trial.
+     * @param attempt - The complete scheduled goal horizon.
+     * @returns A promise that resolves after custody retains the record.
+     */
+    finish(attempt: StudyAttempt): Promise<void>;
+}
+
+/** Holds one admitted request until its actual charge is recorded. */
+export declare interface StudyTicket {
+    readonly signal: AbortSignal;
+    /** Reports whether this ticket already recorded its own settlement; an aborted signal does not establish it. */
+    readonly settled: boolean;
+    /** Records actual measurements for one admitted request.
+     * @param usage - The request's measured charges.
+     * @returns Nothing after settlement.
+     */
+    finish(usage: StudyUsage): void;
+    /** Records an attributable failure for one admitted request.
+     * @param failure - The retained operational attribution.
+     * @returns Nothing after failure propagation.
+     */
+    fail(failure: StudyFailure): void;
+}
+
+/** Holds a scheduled trajectory, with a fresh state for each repetition and arm. */
+export declare interface StudyTrial {
+    readonly id: string;
+    readonly scenario: string;
+    readonly arm: string;
+    readonly repetition: number;
+}
+
+/** Holds actual request measurements; absent token usage remains unknown. */
+export declare interface StudyUsage {
+    readonly role: StudyRole;
+    readonly calls: number;
+    readonly tokens: number | undefined;
+    readonly bytes: number | undefined;
+    readonly duration: number;
+}
+
+/**
+ * Translates only a nominal Agent window refusal into the attributable capacity failure.
+ * @remarks
+ * The failure's stop is the `window` layer with the id `Agent window`; its `max` is the window and
+ * its `consumed` the measured request, each read from the error's context when it is a finite
+ * number.
+ * @param error - The caught or reported value
+ * @param runtime - The admitted Agent namespace owning the nominal guard
+ * @returns A capacity StudyError for an Agent `WINDOW` error; every other value with its identity
+ */
+export declare function translateStudyAgentError(error: unknown, runtime: Pick<StudyAgentRuntime, 'isAgentError'>): unknown;
+
+/**
+ * Translates an Agent run's stop record into the attributable capacity failure of the layer that stopped it.
+ * @remarks
+ * The record is foreign data from the admitted runtime, so the helper reads it once, each member
+ * once, inside one contained boundary, and validates only the members it dereferences. A `meter`
+ * or `budget` stop always leaves the run partial; a `model` stop is a complete answer, so a
+ * consumer whose role admits a `length` finish keeps it. The consumer throws the returned error
+ * when its policy refuses the stop. A `model` stop reports no cap because the Agent does not see
+ * one; its `consumed` is the completion the stopped call reported, when finite.
+ * @param stop - The `stop` member of an Agent or Ledger result
+ * @returns Undefined when `stop` is undefined; a `CAPACITY` StudyError with role `agent` and the Agent layer for a meter, budget, or model stop; a `FAULT` StudyError with role `agent` for a malformed record
+ * @example
+ * ```ts
+ * translateStudyAgentStop({ layer: 'meter', id: 'meter', max: 2000, consumed: 2001 })
+ * // a CAPACITY StudyError whose failure.stop is { layer: 'meter', id: 'meter', max: 2000, consumed: 2001 }
+ * ```
+ */
+export declare function translateStudyAgentStop(stop: unknown): StudyError | undefined;
+
+/**
+ * Checks that a successful provider call reported a usable actual prompt count.
+ * @remarks
+ * The check compares nothing with a forecast; room enforcement stays with the transport.
+ * @param usage - The usage a successful provider call reported
+ * @param role - The responsibility whose request was dispatched; the failure retains it
+ * @returns Nothing when the prompt count is finite and positive
+ * @throws StudyError - Thrown with code `FAULT` when the prompt count is missing, not finite, or not positive
+ */
+export declare function validateStudyAgentUsage(usage: ProviderResult['usage'], role: StudyRole): void;
+
+/**
+ * Validates grading coverage and request room against the declared study inputs.
+ * @param definition - The population declaration
+ * @param scenarios - The complete scenario declarations
+ * @param rubric - The independently held grading declaration
+ * @param profile - The execution bounds and model room
+ * @returns Nothing when every cross-input invariant holds
+ * @throws StudyError - Thrown when any input or cross-reference is invalid
+ * @example
+ * ```ts
+ * validateStudyInputs(definition, scenarios, rubric, profile)
+ * ```
+ */
+export declare function validateStudyInputs(definition: StudyDefinition, scenarios: readonly StudyScenario[], rubric: StudyRubric, profile: StudyProfile): void;
+
+export { }