@orkestrel/study 0.0.0-stage → 0.0.2

package/dist/src/core/index.cjs

@@ -0,0 +1,2107 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_contract = require("@orkestrel/contract");
+let _orkestrel_timeout = require("@orkestrel/timeout");
+let _orkestrel_budget = require("@orkestrel/budget");
+let _orkestrel_abort = require("@orkestrel/abort");
+//#region src/core/constants.ts
+/**
+* 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.
+*/
+var STUDY_ERROR_BRAND = Symbol.for("@orkestrel/study.error");
+/** Caps a declared trial population before schedule allocation. */
+var STUDY_TRIALS = 4096;
+/** Caps a declared scenario horizon before execution. */
+var STUDY_GOALS = 4096;
+/** Restricts identifiers to portable path-safe names. */
+var STUDY_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Lists every measured request role in report order. */
+var STUDY_ROLES = Object.freeze([
+	"agent",
+	"judge",
+	"summary",
+	"metadata",
+	"tool"
+]);
+/** Lists every ceiling a run can stop at in report order. */
+var STUDY_LAYERS = Object.freeze([
+	"scope",
+	"window",
+	"custody",
+	"meter",
+	"budget",
+	"model"
+]);
+/** Lists every operational ending in report order. */
+var STUDY_CAUSES = Object.freeze([
+	"capacity",
+	"infrastructure",
+	"deadline",
+	"interrupted",
+	"content"
+]);
+//#endregion
+//#region src/core/helpers.ts
+/**
+* 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 }
+* ```
+*/
+function omitStudyAbsent(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== void 0));
+}
+/**
+* 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
+* ```
+*/
+function normalizeStudyProfile(profile) {
+	const { provider, qualification, settings, room, ...required } = profile;
+	return {
+		...required,
+		room: omitStudyAbsent(room),
+		...provider === void 0 ? {} : { provider: {
+			...omitStudyAbsent(provider),
+			digest: omitStudyAbsent(provider.digest)
+		} },
+		...qualification === void 0 ? {} : { qualification },
+		...settings === void 0 ? {} : { settings }
+	};
+}
+/**
+* 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 }
+* ```
+*/
+function studyStopToJSON(stop) {
+	return {
+		layer: stop.layer,
+		id: stop.id,
+		max: stop.max ?? null,
+		consumed: stop.consumed ?? null
+	};
+}
+/**
+* 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
+* ```
+*/
+function matchesStudyKeys(value, required, optional = []) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+		const keys = Reflect.ownKeys(value);
+		return required.every((key) => Object.hasOwn(value, key)) && keys.every((key) => {
+			if (typeof key !== "string" || !required.includes(key) && !optional.includes(key)) return false;
+			const descriptor = Object.getOwnPropertyDescriptor(value, key);
+			return descriptor !== void 0 && descriptor.enumerable === true && Object.hasOwn(descriptor, "value");
+		});
+	});
+}
+/**
+* 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)
+* ```
+*/
+function buildStudySchedule(definition, scenarios) {
+	if (!isStudyDefinition(definition) || !scenarios.every(isStudyScenario)) throw new StudyError("CONFIG", "Invalid study population");
+	const ids = new Set(scenarios.map((scenario) => scenario.id));
+	if (ids.size !== scenarios.length || ids.size !== definition.scenarios.length || !definition.scenarios.every((id) => ids.has(id))) throw new StudyError("CONFIG", "Scenario declarations must match the population exactly");
+	return Object.freeze([...definition.order.entries()].flatMap(([repetition, row]) => [...definition.scenarios.entries()].flatMap(([scenario, id]) => row.map((arm) => Object.freeze({
+		id: `r${repetition + 1}-s${scenario + 1}-a${definition.arms.indexOf(arm) + 1}`,
+		scenario: id,
+		arm,
+		repetition
+	})))));
+}
+/**
+* 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, or a quality study has no capacity qualification
+* @example
+* ```ts
+* validateStudyInputs(definition, scenarios, rubric, profile)
+* ```
+*/
+function validateStudyInputs(definition, scenarios, rubric, profile) {
+	buildStudySchedule(definition, scenarios);
+	if (!isStudyRubric(rubric) || !isStudyProfile(profile)) throw new StudyError("CONFIG", "Invalid rubric or profile");
+	if (profile.bounds.request.tokens > profile.room.context - profile.room.safety || profile.room.output > profile.bounds.request.tokens) throw new StudyError("CONFIG", "Request allowance does not fit the model room");
+	for (const criterion of rubric.criteria) {
+		const scenario = scenarios.find((entry) => entry.id === criterion.scenario);
+		if (scenario === void 0 || !scenario.goals.some((goal) => goal.id === criterion.goal)) throw new StudyError("CONFIG", "Criterion references an undeclared goal");
+		if (definition.purpose === "mechanism" && criterion.method === "semantic") throw new StudyError("CONFIG", "Mechanism studies cannot establish semantic quality");
+	}
+	const covered = new Set(rubric.criteria.map((criterion) => (0, _orkestrel_contract.canonicalStringify)([criterion.scenario, criterion.goal]) ?? ""));
+	for (const scenario of scenarios) for (const goal of scenario.goals) if (!covered.has((0, _orkestrel_contract.canonicalStringify)([scenario.id, goal.id]) ?? "")) throw new StudyError("CONFIG", "Every declared goal needs a criterion");
+	if (definition.purpose === "quality" && profile.qualification === void 0) throw new StudyError("CONFIG", "Quality studies require a capacity qualification");
+}
+/**
+* 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)
+* ```
+*/
+function computeStudyScores(manifest, rubric, grading) {
+	if (!isStudyRubric(rubric) || !isStudyGrading(grading)) throw new StudyError("EVIDENCE", "Invalid rubric or grading");
+	const expected = buildStudySchedule(manifest.definition, manifest.scenarios);
+	if ((0, _orkestrel_contract.canonicalStringify)(expected) !== (0, _orkestrel_contract.canonicalStringify)(manifest.schedule)) throw new StudyError("EVIDENCE", "Manifest schedule differs from the declared population");
+	const trials = new Map(expected.map((trial) => [trial.id, trial]));
+	if (grading.attempts.length !== expected.length || !grading.attempts.every((id) => trials.has(id))) throw new StudyError("EVIDENCE", "Grading attempts differ from the declared schedule");
+	const criteria = new Map(rubric.criteria.map((criterion) => [criterion.id, criterion]));
+	for (const scenario of manifest.scenarios) for (const goal of scenario.goals) if (!rubric.criteria.some((criterion) => criterion.scenario === scenario.id && criterion.goal === goal.id)) throw new StudyError("EVIDENCE", "Rubric omits a declared goal");
+	for (const criterion of rubric.criteria) if (!manifest.scenarios.some((scenario) => scenario.id === criterion.scenario && scenario.goals.some((goal) => goal.id === criterion.goal)) || manifest.definition.purpose === "mechanism" && criterion.method === "semantic") throw new StudyError("EVIDENCE", "Criterion is incompatible with the study");
+	const keyed = grading.judgments.map((judgment) => ({
+		judgment,
+		key: (0, _orkestrel_contract.canonicalStringify)([judgment.trial, judgment.criterion]) ?? ""
+	}));
+	const firsts = new Map([...keyed.entries()].reverse().map(([index, { key }]) => [key, index]));
+	for (const [index, { judgment, key }] of keyed.entries()) {
+		const trial = trials.get(judgment.trial);
+		const criterion = criteria.get(judgment.criterion);
+		if (trial === void 0 || criterion === void 0 || criterion.scenario !== trial.scenario || firsts.get(key) !== index) throw new StudyError("EVIDENCE", "Duplicate or foreign trial criterion judgment");
+		if (criterion.method === "semantic" ? judgment.method !== "human" && judgment.method !== "model" : judgment.method !== criterion.method) throw new StudyError("EVIDENCE", "Judgment method differs from the criterion");
+	}
+	const judgments = new Map(keyed.map(({ key, judgment }) => [key, judgment]));
+	return Object.freeze(manifest.definition.arms.map((arm) => {
+		const pairs = expected.filter((trial) => trial.arm === arm).flatMap((trial) => rubric.criteria.filter((criterion) => criterion.scenario === trial.scenario).map((criterion) => ({
+			criterion,
+			judgment: judgments.get((0, _orkestrel_contract.canonicalStringify)([trial.id, criterion.id]) ?? "")
+		})));
+		const refuted = pairs.filter(({ judgment }) => judgment?.verdict === "unsuccessful");
+		const total = pairs.length;
+		const achieved = pairs.filter(({ judgment }) => judgment?.verdict === "achieved").length;
+		const unsuccessful = refuted.length;
+		const critical = refuted.filter(({ criterion }) => criterion.critical).length;
+		const unknown = total - achieved - unsuccessful;
+		return Object.freeze({
+			arm,
+			total,
+			achieved,
+			unsuccessful,
+			unknown,
+			critical,
+			lower: achieved / total,
+			upper: (achieved + unknown) / total,
+			coverage: (achieved + unsuccessful) / total
+		});
+	}));
+}
+//#endregion
+//#region src/core/validators.ts
+/** Checks whether a value names a measured request role. */
+var isStudyRole = (0, _orkestrel_contract.literalOf)(STUDY_ROLES);
+/** Checks whether a value names an operational ending. */
+var isStudyCause = (0, _orkestrel_contract.literalOf)(STUDY_CAUSES);
+/** Checks whether a value names a ceiling a run can stop at. */
+var isStudyLayer = (0, _orkestrel_contract.literalOf)(STUDY_LAYERS);
+/**
+* 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
+* ```
+*/
+function isStudyStop(value) {
+	return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, ["layer", "id"], ["max", "consumed"]) && isStudyLayer(value.layer) && (0, _orkestrel_contract.isNonEmptyString)(value.id) && ["max", "consumed"].every((key) => value[key] === void 0 || (0, _orkestrel_contract.isFiniteNumber)(value[key])));
+}
+/**
+* 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
+* ```
+*/
+function isStudyName(value) {
+	return typeof value === "string" && value.length <= 128 && STUDY_NAME.test(value);
+}
+/**
+* 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
+* ```
+*/
+function isStudyLimit(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value) || !matchesStudyKeys(value, [
+			"duration",
+			"calls",
+			"tokens",
+			"bytes"
+		])) return false;
+		return [
+			"duration",
+			"calls",
+			"tokens",
+			"bytes"
+		].every((key) => typeof value[key] === "number" && Number.isSafeInteger(value[key]) && value[key] > 0) && typeof value.duration === "number" && value.duration <= _orkestrel_timeout.MAX_TIMEOUT_MS;
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyBounds(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value) || !matchesStudyKeys(value, [
+			"request",
+			"goal",
+			"trial",
+			"series"
+		]) || !isStudyLimit(value.request) || !isStudyLimit(value.goal) || !isStudyLimit(value.trial) || !isStudyLimit(value.series)) return false;
+		const limits = [
+			value.request,
+			value.goal,
+			value.trial,
+			value.series
+		];
+		for (const [index, limit] of limits.entries()) {
+			const next = limits[index + 1];
+			if (next === void 0) continue;
+			if (limit.duration > next.duration || limit.calls > next.calls || limit.tokens > next.tokens || limit.bytes > next.bytes) return false;
+		}
+		return value.request.calls === 1;
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyGoal(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		return (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, ["id", "input"]) && isStudyName(value.id) && (0, _orkestrel_contract.isJSONValue)(value.input);
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyScenario(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value) || !matchesStudyKeys(value, ["id", "goals"]) || !isStudyName(value.id) || !(0, _orkestrel_contract.isArray)(value.goals)) return false;
+		return value.goals.length > 0 && value.goals.length <= 4096 && value.goals.every(isStudyGoal) && new Set(value.goals.map((goal) => goal.id)).size === value.goals.length && (0, _orkestrel_contract.isJSONValue)(value.goals);
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyDefinition(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value) || !(0, _orkestrel_contract.isJSONValue)(value) || !matchesStudyKeys(value, [
+			"name",
+			"version",
+			"question",
+			"purpose",
+			"driver",
+			"arms",
+			"scenarios",
+			"order",
+			"retries",
+			"rubric"
+		]) || !isStudyName(value.name) || !isStudyName(value.driver) || !(0, _orkestrel_contract.isNonEmptyString)(value.version) || !(0, _orkestrel_contract.isNonEmptyString)(value.question) || value.purpose !== "mechanism" && value.purpose !== "quality" && value.purpose !== "capacity" || !(0, _orkestrel_contract.isArray)(value.arms) || value.arms.length === 0 || !value.arms.every(isStudyName) || new Set(value.arms).size !== value.arms.length || !(0, _orkestrel_contract.isArray)(value.scenarios) || value.scenarios.length === 0 || !value.scenarios.every(isStudyName) || new Set(value.scenarios).size !== value.scenarios.length || !(0, _orkestrel_contract.isArray)(value.order) || !(0, _orkestrel_contract.isJSONValue)(value.order) || value.order.length === 0 || value.retries !== 0 || !(0, _orkestrel_contract.isNonEmptyString)(value.rubric)) return false;
+		const arms = value.arms;
+		if (arms.length * value.scenarios.length * value.order.length > 4096) return false;
+		return value.order.every((order) => (0, _orkestrel_contract.isArray)(order) && order.length === arms.length && new Set(order).size === arms.length && order.every((arm) => typeof arm === "string" && arms.includes(arm)));
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyRoom(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value) || !matchesStudyKeys(value, [
+			"context",
+			"output",
+			"safety",
+			"think"
+		], ["recap"]) || typeof value.think !== "boolean") return false;
+		if (![
+			"context",
+			"output",
+			"safety",
+			...value.recap === void 0 ? [] : ["recap"]
+		].every((key) => typeof value[key] === "number" && Number.isSafeInteger(value[key]) && value[key] > 0)) return false;
+		return typeof value.context === "number" && typeof value.output === "number" && typeof value.safety === "number" && value.output + value.safety < value.context && (value.recap === void 0 || typeof value.recap === "number" && value.recap + value.safety < value.context);
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyProvider(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value) || !matchesStudyKeys(value, [
+			"entry",
+			"url",
+			"model",
+			"digest"
+		], ["judge"]) || ![
+			"entry",
+			"url",
+			"model"
+		].every((key) => (0, _orkestrel_contract.isNonEmptyString)(value[key])) || typeof value.url !== "string" || !(0, _orkestrel_contract.isRecord)(value.digest) || !matchesStudyKeys(value.digest, ["model"], ["judge"]) || !isStudyDigest(value.digest.model) || value.judge === void 0 !== (value.digest.judge === void 0) || value.judge !== void 0 && (!(0, _orkestrel_contract.isNonEmptyString)(value.judge) || !isStudyDigest(value.digest.judge))) return false;
+		const url = new URL(value.url);
+		return ["http:", "https:"].includes(url.protocol) && url.username === "" && url.password === "" && url.search === "" && url.hash === "" && url.pathname === "/";
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyProfile(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		return (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, [
+			"name",
+			"agent",
+			"subject",
+			"roots",
+			"bounds",
+			"room"
+		], [
+			"provider",
+			"qualification",
+			"settings"
+		]) && isStudyName(value.name) && (0, _orkestrel_contract.isNonEmptyString)(value.agent) && (0, _orkestrel_contract.isArray)(value.roots) && (0, _orkestrel_contract.isJSONValue)(value.roots) && value.roots.length > 0 && value.roots.every((root) => typeof root === "string" && root.trim().length > 0) && new Set(value.roots).size === value.roots.length && (0, _orkestrel_contract.isNonEmptyString)(value.subject) && isStudyBounds(value.bounds) && isStudyRoom(value.room) && (value.provider === void 0 || isStudyProvider(value.provider)) && (value.qualification === void 0 || (0, _orkestrel_contract.isNonEmptyString)(value.qualification)) && (value.settings === void 0 || (0, _orkestrel_contract.isRecord)(value.settings) && (0, _orkestrel_contract.isJSONValue)(value.settings));
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyDigest(value) {
+	return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+/**
+* 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
+* ```
+*/
+function isStudyTimestamp(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value) && new Date(value).toISOString() === value;
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyUsage(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		return (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, [
+			"role",
+			"calls",
+			"duration"
+		], ["tokens", "bytes"]) && isStudyRole(value.role) && ["calls", "duration"].every((key) => typeof value[key] === "number" && Number.isSafeInteger(value[key]) && value[key] >= 0) && (value.bytes === void 0 || typeof value.bytes === "number" && Number.isSafeInteger(value.bytes) && value.bytes >= 0) && (value.tokens === void 0 || typeof value.tokens === "number" && Number.isSafeInteger(value.tokens) && value.tokens >= 0);
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyProduct(value) {
+	return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isRecord)(value) && typeof value.partial === "boolean" && (0, _orkestrel_contract.isJSONValue)(value.value));
+}
+/**
+* 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
+* ```
+*/
+function isStudyCriterion(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		return (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, [
+			"id",
+			"scenario",
+			"goal",
+			"method",
+			"critical",
+			"assertion"
+		]) && isStudyName(value.id) && isStudyName(value.scenario) && isStudyName(value.goal) && (value.method === "state" || value.method === "trace" || value.method === "semantic") && typeof value.critical === "boolean" && (0, _orkestrel_contract.isJSONValue)(value.assertion);
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyRubric(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		return (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, ["version", "criteria"]) && typeof value.version === "string" && value.version.trim().length > 0 && (0, _orkestrel_contract.isArray)(value.criteria) && value.criteria.length > 0 && value.criteria.every(isStudyCriterion) && new Set(value.criteria.map((criterion) => criterion.id)).size === value.criteria.length && (0, _orkestrel_contract.isJSONValue)(value.criteria);
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyJudgment(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		return (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, [
+			"trial",
+			"criterion",
+			"verdict",
+			"method",
+			"reason",
+			"references"
+		]) && isStudyName(value.trial) && isStudyName(value.criterion) && (value.verdict === "achieved" || value.verdict === "unsuccessful" || value.verdict === "unknown") && (value.method === "state" || value.method === "trace" || value.method === "human" || value.method === "model") && typeof value.reason === "string" && value.reason.trim().length > 0 && (0, _orkestrel_contract.isArray)(value.references) && (0, _orkestrel_contract.isJSONValue)(value.references) && value.references.every((reference) => typeof reference === "string" && reference.trim().length > 0) && new Set(value.references).size === value.references.length && (value.verdict === "unknown" || value.references.length > 0);
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyLabeling(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		return (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, [
+			"packet",
+			"labeler",
+			"version",
+			"created",
+			"usage",
+			"judgments"
+		]) && isStudyDigest(value.packet) && typeof value.labeler === "string" && value.labeler.trim().length > 0 && typeof value.version === "string" && value.version.trim().length > 0 && isStudyTimestamp(value.created) && (0, _orkestrel_contract.isArray)(value.usage) && Reflect.ownKeys(value.usage).length === value.usage.length + 1 && Array.from(value.usage).every(isStudyUsage) && (0, _orkestrel_contract.isArray)(value.judgments) && value.judgments.every(isStudyJudgment) && value.judgments.every((judgment) => judgment.method === "human" || judgment.method === "model") && new Set(value.judgments.map((judgment) => (0, _orkestrel_contract.canonicalStringify)([judgment.trial, judgment.criterion]))).size === value.judgments.length && (0, _orkestrel_contract.isJSONValue)(value.judgments);
+	});
+}
+/**
+* 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
+* ```
+*/
+function isStudyErrorCode(value) {
+	return value === "CONFIG" || value === "EVIDENCE" || value === "CUSTODY" || value === "CAPACITY" || value === "FAULT" || value === "DEADLINE";
+}
+/**
+* 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
+* ```
+*/
+function isStudyGrading(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		return (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, [
+			"result",
+			"rubric",
+			"grader",
+			"instrument",
+			"attempts",
+			"judgments"
+		], ["labels", "packet"]) && isStudyDigest(value.result) && isStudyDigest(value.rubric) && isStudyDigest(value.instrument) && typeof value.grader === "string" && value.grader.trim().length > 0 && (value.labels === void 0 || isStudyDigest(value.labels)) && (value.packet === void 0 || isStudyDigest(value.packet)) && (0, _orkestrel_contract.isArray)(value.attempts) && (0, _orkestrel_contract.isJSONValue)(value.attempts) && value.attempts.every(isStudyName) && new Set(value.attempts).size === value.attempts.length && (0, _orkestrel_contract.isArray)(value.judgments) && value.judgments.every(isStudyJudgment) && new Set(value.judgments.map((judgment) => (0, _orkestrel_contract.canonicalStringify)([judgment.trial, judgment.criterion]))).size === value.judgments.length && (0, _orkestrel_contract.isJSONValue)(value.judgments);
+	});
+}
+//#endregion
+//#region src/core/errors.ts
+/** Reports a study contract or operational failure with a stable code. */
+var StudyError = class extends Error {
+	code;
+	failure;
+	/**
+	* 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, message, failure) {
+		super(message);
+		_orkestrel_contract.INTRINSICS.define(this, STUDY_ERROR_BRAND, {
+			value: this,
+			enumerable: false,
+			writable: false,
+			configurable: true
+		});
+		this.name = "StudyError";
+		this.code = code;
+		this.failure = failure;
+	}
+};
+/**
+* Narrows a caught value to a branded study error with valid failure attribution.
+* @remarks
+* Recognition combines the native `Error` base, a subclass prototype, a declared study code,
+* valid optional failure members, and an own {@link STUDY_ERROR_BRAND} descriptor whose value is
+* the error itself. Subclasses can replace the name.
+* 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
+* ```
+*/
+function isStudyError(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isError)(value) || _orkestrel_contract.INTRINSICS.prototype(value) === _orkestrel_contract.INTRINSICS.error.prototype) return false;
+		const brand = _orkestrel_contract.INTRINSICS.describe(value, STUDY_ERROR_BRAND)?.value;
+		const code = _orkestrel_contract.INTRINSICS.reflect.read(value, "code");
+		const failure = _orkestrel_contract.INTRINSICS.reflect.read(value, "failure");
+		if (brand !== value || !isStudyErrorCode(code) || typeof _orkestrel_contract.INTRINSICS.reflect.read(value, "name") !== "string" || typeof _orkestrel_contract.INTRINSICS.reflect.read(value, "message") !== "string") return false;
+		if (failure === void 0) return true;
+		if (!(0, _orkestrel_contract.isObject)(failure)) return false;
+		const cause = _orkestrel_contract.INTRINSICS.reflect.read(failure, "cause");
+		const message = _orkestrel_contract.INTRINSICS.reflect.read(failure, "message");
+		const role = _orkestrel_contract.INTRINSICS.reflect.read(failure, "role");
+		const stop = _orkestrel_contract.INTRINSICS.reflect.read(failure, "stop");
+		if (!isStudyCause(cause) || typeof message !== "string" || role !== void 0 && !isStudyRole(role)) return false;
+		if (stop === void 0) return true;
+		if (!(0, _orkestrel_contract.isObject)(stop)) return false;
+		const layer = _orkestrel_contract.INTRINSICS.reflect.read(stop, "layer");
+		const id = _orkestrel_contract.INTRINSICS.reflect.read(stop, "id");
+		const max = _orkestrel_contract.INTRINSICS.reflect.read(stop, "max");
+		const consumed = _orkestrel_contract.INTRINSICS.reflect.read(stop, "consumed");
+		return isStudyLayer(layer) && typeof id === "string" && (max === void 0 || (0, _orkestrel_contract.isFiniteNumber)(max)) && (consumed === void 0 || (0, _orkestrel_contract.isFiniteNumber)(consumed));
+	});
+}
+//#endregion
+//#region src/core/parsers.ts
+/**
+* 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
+* ```
+*/
+function parseStudyReading(value) {
+	return (0, _orkestrel_contract.isFiniteNumber)(value) ? value : void 0;
+}
+/**
+* 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)
+* ```
+*/
+function parseStudyDefinition(value) {
+	try {
+		if (!isStudyDefinition(value)) throw new StudyError("CONFIG", "Invalid study definition");
+		const snapshot = (0, _orkestrel_contract.cloneJSONValue)(value);
+		if (isStudyDefinition(snapshot)) return snapshot;
+	} catch {
+		throw new StudyError("CONFIG", "Invalid or unreadable study definition");
+	}
+	throw new StudyError("CONFIG", "Invalid study definition snapshot");
+}
+/**
+* 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: {} }] })
+* ```
+*/
+function parseStudyScenario(value) {
+	try {
+		if (!isStudyScenario(value)) throw new StudyError("CONFIG", "Invalid study scenario");
+		const snapshot = (0, _orkestrel_contract.cloneJSONValue)(value);
+		if (isStudyScenario(snapshot)) return snapshot;
+	} catch {
+		throw new StudyError("CONFIG", "Invalid or unreadable study scenario");
+	}
+	throw new StudyError("CONFIG", "Invalid study scenario snapshot");
+}
+/**
+* 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)
+* ```
+*/
+function parseStudyProfile(value) {
+	try {
+		if (!isStudyProfile(value)) throw new StudyError("CONFIG", "Invalid study profile");
+		const snapshot = (0, _orkestrel_contract.cloneJSONValue)(normalizeStudyProfile(value));
+		if (isStudyProfile(snapshot)) return snapshot;
+	} catch {
+		throw new StudyError("CONFIG", "Invalid or unreadable study profile");
+	}
+	throw new StudyError("CONFIG", "Invalid study profile snapshot");
+}
+/**
+* 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)
+* ```
+*/
+function parseStudyRubric(value) {
+	try {
+		if (!isStudyRubric(value)) throw new StudyError("CONFIG", "Invalid study rubric");
+		const snapshot = (0, _orkestrel_contract.cloneJSONValue)(value);
+		if (isStudyRubric(snapshot)) return snapshot;
+	} catch {
+		throw new StudyError("CONFIG", "Invalid or unreadable study rubric");
+	}
+	throw new StudyError("CONFIG", "Invalid study rubric snapshot");
+}
+/**
+* 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)
+* ```
+*/
+function parseStudyGrading(value) {
+	try {
+		if (!isStudyGrading(value)) throw new StudyError("EVIDENCE", "Invalid study grading");
+		const { labels, packet, ...required } = value;
+		const snapshot = (0, _orkestrel_contract.cloneJSONValue)({
+			...required,
+			...labels === void 0 ? {} : { labels },
+			...packet === void 0 ? {} : { packet }
+		});
+		if (isStudyGrading(snapshot)) return snapshot;
+	} catch {
+		throw new StudyError("EVIDENCE", "Invalid or unreadable study grading");
+	}
+	throw new StudyError("EVIDENCE", "Invalid study grading snapshot");
+}
+/**
+* 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)
+* ```
+*/
+function parseStudyLabeling(value) {
+	try {
+		if (!isStudyLabeling(value)) throw new StudyError("EVIDENCE", "Invalid study labels");
+		const snapshot = (0, _orkestrel_contract.cloneJSONValue)({
+			...value,
+			usage: value.usage.map(({ tokens, bytes, ...usage }) => ({
+				...usage,
+				...tokens === void 0 ? {} : { tokens },
+				...bytes === void 0 ? {} : { bytes }
+			}))
+		});
+		if (isStudyLabeling(snapshot)) return snapshot;
+	} catch {
+		throw new StudyError("EVIDENCE", "Invalid or unreadable study labels");
+	}
+	throw new StudyError("EVIDENCE", "Invalid study labels snapshot");
+}
+//#endregion
+//#region src/core/engines/helpers.ts
+/** Converts an operational reading to its throwable boundary.
+* @param failure - The retained operational reading.
+* @returns An error preserving the reading's cause and responsibility.
+*/
+function failureToStudyError(failure) {
+	return new StudyError(failure.cause === "capacity" ? "CAPACITY" : failure.cause === "deadline" ? "DEADLINE" : "FAULT", failure.message, failure);
+}
+/** 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.
+*/
+function readStudyFailure(error) {
+	if (isStudyError(error)) {
+		const { failure, code, message } = error;
+		if (failure !== void 0) return failure;
+		if (code === "CAPACITY") return {
+			cause: "capacity",
+			message,
+			role: void 0,
+			stop: void 0
+		};
+		if (code === "DEADLINE") return {
+			cause: "deadline",
+			message,
+			role: void 0,
+			stop: void 0
+		};
+	}
+	if ((0, _orkestrel_budget.isBudgetError)(error)) {
+		const reading = (0, _orkestrel_contract.attempt)(() => {
+			const context = error.context;
+			return {
+				id: context.id,
+				max: context.max,
+				consumed: context.consumed,
+				message: error.message
+			};
+		});
+		if (reading.success) return {
+			cause: "capacity",
+			message: reading.value.message,
+			role: void 0,
+			stop: {
+				layer: "budget",
+				id: (0, _orkestrel_contract.isNonEmptyString)(reading.value.id) ? reading.value.id : "Agent budget",
+				max: parseStudyReading(reading.value.max),
+				consumed: parseStudyReading(reading.value.consumed)
+			}
+		};
+	}
+	return {
+		cause: "infrastructure",
+		message: (0, _orkestrel_contract.isError)(error) ? error.message : "Study operation rejected without an Error",
+		role: void 0,
+		stop: void 0
+	};
+}
+/**
+* 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 }
+* ```
+*/
+function computeStudyAdmittedStop(charge, usage) {
+	if (usage.tokens !== void 0 && usage.tokens > charge.tokens) return {
+		layer: "scope",
+		id: "Admitted tokens",
+		max: charge.tokens,
+		consumed: usage.tokens
+	};
+	if (usage.bytes !== void 0 && usage.bytes > charge.bytes) return {
+		layer: "scope",
+		id: "Admitted bytes",
+		max: charge.bytes,
+		consumed: usage.bytes
+	};
+}
+/**
+* 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 }
+* ```
+*/
+function computeStudyOutputStop(bytes, limit, outputs) {
+	if (bytes > limit) return {
+		layer: "scope",
+		id: "Goal bytes",
+		max: limit,
+		consumed: bytes
+	};
+	const refusal = outputs.find((budget) => bytes > budget.remaining);
+	return refusal === void 0 ? void 0 : {
+		layer: "scope",
+		id: refusal.id,
+		max: refusal.max,
+		consumed: refusal.consumed + bytes
+	};
+}
+/**
+* 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')
+* ```
+*/
+function failStudyTicket(ticket, error, role) {
+	if (ticket.settled || ticket.signal.aborted) return;
+	const failure = readStudyFailure(error);
+	ticket.fail(role === void 0 ? failure : {
+		...failure,
+		role
+	});
+}
+//#endregion
+//#region src/core/engines/StudyControl.ts
+/** Retains the first operational failure while bounding asynchronous waits. */
+var StudyControl = class {
+	#abort;
+	#listeners = new _orkestrel_abort.Abort();
+	#failure;
+	/** Links cancellation to the caller without assigning it a task verdict.
+	* @param signal - Optional parent cancellation.
+	*/
+	constructor(signal) {
+		this.#abort = new _orkestrel_abort.Abort(signal === void 0 ? void 0 : { signal });
+		if (this.#abort.aborted) this.#interrupt();
+		else this.#abort.signal.addEventListener("abort", () => this.#interrupt(), {
+			once: true,
+			signal: this.#listeners.signal
+		});
+	}
+	get signal() {
+		return this.#abort.signal;
+	}
+	get failure() {
+		return this.#failure;
+	}
+	/** Latches an operational failure and cancels all linked work.
+	* @param failure - The first attribution to preserve.
+	*/
+	fail(failure) {
+		if (this.#failure !== void 0) return;
+		this.#failure = Object.freeze({
+			...failure,
+			stop: failure.stop === void 0 ? void 0 : Object.freeze({ ...failure.stop })
+		});
+		this.#abort.abort(failureToStudyError(this.#failure));
+	}
+	/** 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(work) {
+		const listeners = new _orkestrel_abort.Abort();
+		return new Promise((resolve, reject) => {
+			Promise.resolve(work).then(resolve, reject);
+			if (this.#abort.aborted) reject(this.#reason());
+			else this.#abort.signal.addEventListener("abort", () => reject(this.#reason()), {
+				once: true,
+				signal: listeners.signal
+			});
+		}).finally(() => listeners.abort());
+	}
+	/** Removes the lifecycle listener without changing the retained failure. */
+	close() {
+		this.#listeners.abort();
+	}
+	#reason() {
+		return failureToStudyError(this.#failure ?? {
+			cause: "interrupted",
+			message: "Study interrupted",
+			role: void 0,
+			stop: void 0
+		});
+	}
+	#interrupt() {
+		if (this.#failure === void 0) this.fail({
+			cause: "interrupted",
+			message: "Study interrupted by parent cancellation",
+			role: void 0,
+			stop: void 0
+		});
+	}
+};
+//#endregion
+//#region src/core/engines/StudyScope.ts
+/** Reserves finite request ceilings around cumulative actual budgets and one deadline. */
+var StudyScope = class {
+	#options;
+	#calls;
+	#tokens;
+	#bytes;
+	#timeout;
+	#listeners = new _orkestrel_abort.Abort();
+	#pending = /* @__PURE__ */ new Map();
+	#started = performance.now();
+	#closed = false;
+	/** Starts a timed scope with independent counters.
+	* @param options - Finite limit, shared failure owner, and diagnostic label.
+	*/
+	constructor(options) {
+		if (!isStudyLimit(options.limit)) throw new StudyError("CONFIG", "Invalid study scope limit");
+		this.#options = {
+			...options,
+			limit: { ...options.limit }
+		};
+		this.#calls = new _orkestrel_budget.Budget({
+			max: options.limit.calls,
+			consumer: (value) => value
+		});
+		this.#tokens = new _orkestrel_budget.Budget({
+			max: options.limit.tokens,
+			consumer: (value) => value
+		});
+		this.#bytes = new _orkestrel_budget.Budget({
+			max: options.limit.bytes,
+			consumer: (value) => value
+		});
+		this.#timeout = new _orkestrel_timeout.Timeout({ ms: options.limit.duration });
+		this.#timeout.signal.addEventListener("abort", () => this.#expire(), {
+			once: true,
+			signal: this.#listeners.signal
+		});
+		this.#timeout.start();
+	}
+	/** 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) {
+		this.#checkTime();
+		if (this.#closed) throw new StudyError("FAULT", "Study scope is closed");
+		const prior = this.#options.control.failure;
+		if (prior !== void 0) throw failureToStudyError(prior);
+		if (charge === void 0) return;
+		const pending = [...this.#pending.values()];
+		const tokens = pending.reduce((total, entry) => total + entry.tokens, 0);
+		const bytes = pending.reduce((total, entry) => total + entry.bytes, 0);
+		const { label, limit } = this.#options;
+		const refusal = [
+			{
+				id: `${label} calls`,
+				refused: this.#calls.remaining - this.#pending.size < 1,
+				max: limit.calls,
+				consumed: this.#calls.consumed + this.#pending.size + 1
+			},
+			{
+				id: `${label} tokens`,
+				refused: this.#tokens.remaining - tokens < charge.tokens,
+				max: limit.tokens,
+				consumed: this.#tokens.consumed + tokens + charge.tokens
+			},
+			{
+				id: `${label} bytes`,
+				refused: this.#bytes.remaining - bytes < charge.bytes,
+				max: limit.bytes,
+				consumed: this.#bytes.consumed + bytes + charge.bytes
+			}
+		].find((entry) => entry.refused);
+		if (refusal !== void 0) {
+			const failure = {
+				cause: "capacity",
+				message: `${label} allowance cannot admit the request`,
+				role: charge.role,
+				stop: {
+					layer: "scope",
+					id: refusal.id,
+					max: refusal.max,
+					consumed: refusal.consumed
+				}
+			};
+			this.#options.control.fail(failure);
+			throw failureToStudyError(failure);
+		}
+	}
+	/** 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, charge) {
+		if (this.#pending.has(id)) throw new StudyError("FAULT", "Duplicate study reservation");
+		this.#pending.set(id, { ...charge });
+	}
+	/** 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, usage) {
+		const charge = this.#pending.get(id);
+		if (charge === void 0) throw new StudyError("FAULT", "Study reservation is not pending");
+		this.#pending.delete(id);
+		this.#calls.consume(1);
+		this.#tokens.consume(Math.min(charge.tokens, usage.tokens ?? charge.tokens));
+		this.#bytes.consume(Math.min(charge.bytes, usage.bytes ?? charge.bytes));
+	}
+	/** Checks deadline attribution before clearing the timer. */
+	close() {
+		if (this.#closed) return;
+		this.#checkTime();
+		this.#closed = true;
+		this.#listeners.abort();
+		this.#timeout.clear();
+	}
+	#checkTime() {
+		if (!this.#closed && (this.#timeout.expired || performance.now() - this.#started >= this.#options.limit.duration)) this.#expire();
+	}
+	#expire() {
+		this.#options.control.fail({
+			cause: "deadline",
+			message: `${this.#options.label} deadline expired`,
+			role: void 0,
+			stop: {
+				layer: "scope",
+				id: `${this.#options.label} duration`,
+				max: this.#options.limit.duration,
+				consumed: Math.ceil(performance.now() - this.#started)
+			}
+		});
+	}
+};
+//#endregion
+//#region src/core/engines/StudyDeadline.ts
+/** Bounds each independent operation with a fresh failure owner and deadline. */
+var StudyDeadline = class {
+	#options;
+	/** Retains the deadline without starting a timer.
+	* @param options - Finite duration in milliseconds and diagnostic label.
+	*/
+	constructor(options) {
+		this.#options = { ...options };
+	}
+	/** 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.
+	*/
+	async wait(work) {
+		const control = new StudyControl();
+		const scope = this.#open(control, work);
+		try {
+			const result = await control.wait(work);
+			scope.check();
+			return result;
+		} finally {
+			scope.close();
+			control.close();
+		}
+	}
+	#open(control, work) {
+		try {
+			return new StudyScope({
+				limit: {
+					duration: this.#options.duration,
+					calls: 1,
+					tokens: 1,
+					bytes: 1
+				},
+				control,
+				label: this.#options.label
+			});
+		} catch (error) {
+			Promise.resolve(work).catch(() => void 0);
+			control.close();
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/core/engines/StudyRequest.ts
+/** Settles an admitted request once and propagates operational failure to its owner. */
+var StudyRequest = class {
+	#options;
+	#timeout;
+	#signal;
+	#listeners = new _orkestrel_abort.Abort();
+	#started = performance.now();
+	#settled = false;
+	/** Starts the request deadline after its enclosing scopes reserve capacity.
+	* @param options - Admitted ceilings, request deadline, and settlement callback.
+	*/
+	constructor(options) {
+		this.#options = {
+			...options,
+			charge: { ...options.charge }
+		};
+		this.#timeout = new _orkestrel_timeout.Timeout({ ms: options.duration });
+		this.#signal = (0, _orkestrel_abort.linkSignal)(this.#timeout.signal, options.control.signal);
+		this.#signal.addEventListener("abort", () => this.#abort(), {
+			once: true,
+			signal: this.#listeners.signal
+		});
+		this.#timeout.start();
+		if (this.#signal.aborted) this.#abort();
+	}
+	get signal() {
+		return this.#signal;
+	}
+	get settled() {
+		return this.#settled;
+	}
+	/** 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) {
+		this.#checkPending();
+		if (!isStudyUsage(usage) || usage.role !== this.#options.charge.role || usage.calls !== 1) {
+			const failure = {
+				cause: "infrastructure",
+				message: "Request usage is invalid or misattributed",
+				role: this.#options.charge.role,
+				stop: void 0
+			};
+			this.fail(failure);
+			throw failureToStudyError(failure);
+		}
+		const elapsed = performance.now() - this.#started;
+		const admitted = computeStudyAdmittedStop(this.#options.charge, usage);
+		const failure = this.#timeout.expired || elapsed >= this.#options.duration || usage.duration > this.#options.duration ? {
+			cause: "deadline",
+			message: "Request deadline expired",
+			role: usage.role,
+			stop: {
+				layer: "scope",
+				id: "Request duration",
+				max: this.#options.duration,
+				consumed: Math.ceil(Math.max(elapsed, usage.duration))
+			}
+		} : admitted !== void 0 ? {
+			cause: "capacity",
+			message: "Request usage exceeded its admitted ceiling",
+			role: usage.role,
+			stop: admitted
+		} : void 0;
+		this.#complete(usage);
+		if (failure !== void 0) {
+			this.#options.control.fail(failure);
+			throw failureToStudyError(failure);
+		}
+	}
+	/** 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) {
+		this.#checkPending();
+		this.#complete({
+			role: this.#options.charge.role,
+			calls: 1,
+			tokens: void 0,
+			bytes: void 0,
+			duration: Math.ceil(performance.now() - this.#started)
+		});
+		this.#options.control.fail({
+			...failure,
+			role: failure.role ?? this.#options.charge.role
+		});
+	}
+	#complete(usage) {
+		this.#settled = true;
+		this.#listeners.abort();
+		this.#timeout.clear();
+		this.#options.settle(Object.freeze({ ...usage }));
+	}
+	#checkPending() {
+		if (this.#settled) {
+			this.#options.control.fail({
+				cause: "infrastructure",
+				message: "Request settlement is late or repeated",
+				role: this.#options.charge.role,
+				stop: void 0
+			});
+			throw new StudyError("FAULT", "Request settlement is late or repeated", this.#options.control.failure);
+		}
+	}
+	#abort() {
+		if (this.#settled) return;
+		const expired = this.#timeout.expired;
+		this.fail(this.#options.control.failure ?? {
+			cause: expired ? "deadline" : "interrupted",
+			message: expired ? "Request deadline expired" : "Request interrupted",
+			role: this.#options.charge.role,
+			stop: expired ? {
+				layer: "scope",
+				id: "Request duration",
+				max: this.#options.duration,
+				consumed: Math.ceil(performance.now() - this.#started)
+			} : void 0
+		});
+	}
+};
+//#endregion
+//#region src/core/engines/StudyMeter.ts
+/** Admits request ceilings across every enclosing scope before dispatch. */
+var StudyMeter = class {
+	#options;
+	#pending = /* @__PURE__ */ new Set();
+	#usage = [];
+	#closed = false;
+	/** Holds the goal's shared admission scopes.
+	* @param options - Request bound, enclosing scopes, and shared failure owner.
+	*/
+	constructor(options) {
+		if (!isStudyLimit(options.request) || options.request.calls !== 1 || options.scopes.length === 0) throw new StudyError("CONFIG", "Invalid request admission bounds");
+		this.#options = {
+			...options,
+			request: { ...options.request },
+			scopes: [...options.scopes]
+		};
+	}
+	get signal() {
+		return this.#options.control.signal;
+	}
+	get usage() {
+		return Object.freeze([...this.#usage]);
+	}
+	/** 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) {
+		if (this.#closed) throw new StudyError("FAULT", "Study meter is closed");
+		if (this.#options.control.failure !== void 0) throw failureToStudyError(this.#options.control.failure);
+		if (!isStudyRole(charge.role) || !Number.isSafeInteger(charge.tokens) || charge.tokens < 0 || !Number.isSafeInteger(charge.bytes) || charge.bytes < 0) {
+			const failure = {
+				cause: "infrastructure",
+				message: "Request admission requires safe nonnegative ceilings",
+				role: void 0,
+				stop: void 0
+			};
+			this.#options.control.fail(failure);
+			throw failureToStudyError(failure);
+		}
+		const { request } = this.#options;
+		if (charge.tokens > request.tokens || charge.bytes > request.bytes) {
+			const tokens = charge.tokens > request.tokens;
+			const failure = {
+				cause: "capacity",
+				message: "Request ceiling exceeds the request allowance",
+				role: charge.role,
+				stop: {
+					layer: "scope",
+					id: tokens ? "Request tokens" : "Request bytes",
+					max: tokens ? request.tokens : request.bytes,
+					consumed: tokens ? charge.tokens : charge.bytes
+				}
+			};
+			this.#options.control.fail(failure);
+			throw failureToStudyError(failure);
+		}
+		for (const scope of this.#options.scopes) scope.check(charge);
+		const id = Symbol("request");
+		for (const scope of this.#options.scopes) scope.reserve(id, charge);
+		this.#pending.add(id);
+		return new StudyRequest({
+			charge,
+			duration: this.#options.request.duration,
+			control: this.#options.control,
+			settle: (usage) => {
+				for (const scope of this.#options.scopes) scope.settle(id, usage);
+				this.#pending.delete(id);
+				this.#usage = [...this.#usage, usage];
+			}
+		});
+	}
+	/** Refuses unfinished requests before closing a goal's admission boundary. */
+	close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		if (this.#pending.size > 0) this.#options.control.fail({
+			cause: "infrastructure",
+			message: "Goal completed with unsettled requests",
+			role: void 0,
+			stop: void 0
+		});
+	}
+};
+//#endregion
+//#region src/core/engines/StudyTrialLease.ts
+/** Holds one trial's evidence custody, admission scope and driver session from opening to cleanup. */
+var StudyTrialLease = class {
+	#trial;
+	#options;
+	#control;
+	#series;
+	#deadline;
+	#scope;
+	#evidence;
+	#opening;
+	#session;
+	/** Binds one scheduled trial to the series' owned inputs, failure owner, series scope and cleanup deadline.
+	* @param trial - The scheduled trial.
+	* @param options - The series' owned manifest, driver and store.
+	* @param control - The series failure owner.
+	* @param series - The series admission scope.
+	* @param deadline - The custody and cleanup deadline.
+	*/
+	constructor(trial, options, control, series, deadline) {
+		this.#trial = trial;
+		this.#options = options;
+		this.#control = control;
+		this.#series = series;
+		this.#deadline = deadline;
+	}
+	/** Reports the trial scope once opened; undefined when the trial inherited a failure. */
+	get scope() {
+		return this.#scope;
+	}
+	/** Reports the trial's evidence sink once custody started. */
+	get evidence() {
+		return this.#evidence;
+	}
+	/** Reports the driver session once it opened. */
+	get session() {
+		return this.#session;
+	}
+	/** Starts evidence custody and, unless a failure is latched, opens the trial scope and driver session.
+	* @returns Nothing after the session opened, or after custody alone started under a latched failure.
+	* @throws StudyError - Thrown with code `CUSTODY` when custody refuses the trial; thrown for a series or trial limit or an opening failure.
+	*/
+	async open() {
+		const control = this.#control;
+		if (control.failure !== void 0) {
+			this.#evidence = await this.#start();
+			return;
+		}
+		this.#series.check();
+		const scope = new StudyScope({
+			limit: this.#options.manifest.bounds.trial,
+			control,
+			label: "Trial"
+		});
+		this.#scope = scope;
+		this.#evidence = await this.#start();
+		this.#series.check();
+		scope.check();
+		const opening = this.#launch();
+		this.#opening = opening;
+		this.#session = await control.wait(opening);
+	}
+	/** Closes the opened session, or a session that opened late, then the trial scope.
+	* @returns The cleanup failure, or undefined when cleanup succeeded or repeated the latched failure.
+	*/
+	async close() {
+		const cleanup = await this.#release();
+		this.#scope?.close();
+		return cleanup;
+	}
+	async #release() {
+		const session = this.#session;
+		const opening = this.#opening;
+		if (session !== void 0) try {
+			await this.#deadline.wait(session.close());
+			return;
+		} catch (error) {
+			const cleanup = readStudyFailure(error);
+			this.#control.fail(cleanup);
+			return cleanup;
+		}
+		if (opening === void 0) return void 0;
+		try {
+			const late = await this.#deadline.wait(opening);
+			await this.#deadline.wait(late.close());
+			return;
+		} catch (error) {
+			const late = readStudyFailure(error);
+			return late.message !== this.#control.failure?.message ? late : void 0;
+		}
+	}
+	async #launch() {
+		const control = this.#control;
+		const session = await this.#options.driver.open(this.#trial, control.signal);
+		if (control.failure !== void 0) {
+			await this.#deadline.wait(session.close());
+			throw failureToStudyError(control.failure);
+		}
+		return session;
+	}
+	async #start() {
+		const control = this.#control;
+		try {
+			const pending = this.#options.store.start(this.#trial);
+			return control.failure === void 0 ? await control.wait(pending) : await this.#deadline.wait(pending);
+		} catch (error) {
+			control.fail(readStudyFailure(error));
+			const failure = control.failure ?? readStudyFailure(error);
+			throw new StudyError("CUSTODY", failure.message, failure);
+		}
+	}
+};
+//#endregion
+//#region src/core/engines/StudySeries.ts
+/** Executes a frozen serial study schedule with finite admission and sticky failures. */
+var StudySeries = class {
+	#options;
+	#executed = false;
+	/** Owns the declared inputs while retaining the concrete driver and custody store.
+	* @param options - Frozen manifest, concrete adapters, and parent cancellation.
+	*/
+	constructor(options) {
+		this.#options = {
+			...options,
+			manifest: structuredClone(options.manifest)
+		};
+	}
+	/** 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.
+	*/
+	async execute() {
+		if (this.#executed) throw new StudyError("CONFIG", "Study series can execute only once");
+		this.#executed = true;
+		const manifest = this.#options.manifest;
+		const expected = buildStudySchedule(manifest.definition, manifest.scenarios);
+		if (!isStudyBounds(manifest.bounds) || (0, _orkestrel_contract.canonicalStringify)(expected) !== (0, _orkestrel_contract.canonicalStringify)(manifest.schedule)) throw new StudyError("CONFIG", "Study manifest schedule or bounds are invalid");
+		const control = new StudyControl(this.#options.signal);
+		const scope = new StudyScope({
+			limit: manifest.bounds.series,
+			control,
+			label: "Series"
+		});
+		const deadline = new StudyDeadline({
+			duration: manifest.bounds.request.duration,
+			label: "Custody or cleanup"
+		});
+		const output = new _orkestrel_budget.Budget({
+			id: "Series output",
+			max: manifest.bounds.series.bytes,
+			consumer: (bytes) => bytes
+		});
+		const attempts = [];
+		try {
+			for (const trial of manifest.schedule) attempts.push(await this.#executeTrial(trial, control, scope, output, deadline));
+		} finally {
+			scope.close();
+			control.close();
+		}
+		return Object.freeze(attempts);
+	}
+	async #executeTrial(trial, control, series, output, deadline) {
+		const started = performance.now();
+		const scenario = this.#options.manifest.scenarios.find((entry) => entry.id === trial.scenario);
+		if (scenario === void 0) throw new StudyError("CONFIG", "Scheduled scenario is absent");
+		const prior = control.failure;
+		const lease = new StudyTrialLease(trial, this.#options, control, series, deadline);
+		const executed = await this.#executeGoals(scenario, lease, control, series, output);
+		const cleanup = await this.#release(lease, control, series);
+		const failure = control.failure;
+		const observations = [...executed, ...scenario.goals.slice(executed.length).map((goal) => {
+			const unexecuted = failure === void 0 ? {
+				cause: "infrastructure",
+				message: "Goal unexecuted because the trial did not open",
+				role: void 0,
+				stop: void 0
+			} : {
+				...failure,
+				message: `Goal unexecuted: ${failure.message}`
+			};
+			return Object.freeze({
+				goal: goal.id,
+				product: void 0,
+				failure: unexecuted,
+				usage: Object.freeze([]),
+				duration: 0,
+				executed: false
+			});
+		})];
+		const attempt = Object.freeze({
+			trial,
+			observations: Object.freeze(observations),
+			failure: cleanup !== void 0 && failure !== void 0 && (prior !== void 0 || failure.message !== cleanup.message) ? {
+				...failure,
+				message: `${failure.message}; cleanup: ${cleanup.message}`
+			} : failure,
+			duration: Math.ceil(performance.now() - started),
+			executed: prior === void 0
+		});
+		try {
+			await deadline.wait(this.#options.store.finish(attempt));
+			if (attempt.failure === void 0) series.check();
+		} catch (error) {
+			control.fail(readStudyFailure(error));
+			const custody = control.failure ?? readStudyFailure(error);
+			throw new StudyError("CUSTODY", custody.message, custody);
+		}
+		return attempt;
+	}
+	async #executeGoals(scenario, lease, control, series, output) {
+		const observations = [];
+		try {
+			await lease.open();
+			const trialOutput = new _orkestrel_budget.Budget({
+				id: "Trial output",
+				max: this.#options.manifest.bounds.trial.bytes,
+				consumer: (bytes) => bytes
+			});
+			for (const goal of scenario.goals) {
+				const { session, scope, evidence } = lease;
+				if (control.failure !== void 0 || session === void 0 || scope === void 0 || evidence === void 0) break;
+				series.check();
+				scope.check();
+				observations.push(await this.#executeGoal(goal, session, evidence, control, [scope, series], [trialOutput, output]));
+			}
+		} catch (error) {
+			if (isStudyError(error) && error.code === "CUSTODY") {
+				await this.#release(lease, control, series);
+				throw error;
+			}
+			control.fail(readStudyFailure(error));
+		}
+		return observations;
+	}
+	async #release(lease, control, series) {
+		const cleanup = await lease.close();
+		try {
+			series.check();
+		} catch (error) {
+			control.fail(readStudyFailure(error));
+		}
+		return cleanup;
+	}
+	async #executeGoal(goal, session, evidence, control, parents, outputs) {
+		const started = performance.now();
+		const bounds = this.#options.manifest.bounds;
+		const scope = new StudyScope({
+			limit: bounds.goal,
+			control,
+			label: "Goal"
+		});
+		const meter = new StudyMeter({
+			request: bounds.request,
+			scopes: [scope, ...parents],
+			control
+		});
+		const product = await this.#produce(goal, session, evidence, control, scope, meter, parents, outputs);
+		return Object.freeze({
+			goal: goal.id,
+			product,
+			failure: control.failure,
+			usage: meter.usage,
+			duration: Math.ceil(performance.now() - started),
+			executed: true
+		});
+	}
+	async #produce(goal, session, evidence, control, scope, meter, parents, outputs) {
+		const bounds = this.#options.manifest.bounds;
+		try {
+			const value = await control.wait(session.execute(goal, {
+				signal: control.signal,
+				meter,
+				evidence
+			}));
+			if (!isStudyProduct(value)) throw new StudyError("FAULT", "Driver returned no valid study product");
+			const candidate = Object.freeze({
+				value: (0, _orkestrel_contract.cloneJSONValue)(value.value),
+				partial: value.partial
+			});
+			const bytes = new TextEncoder().encode(JSON.stringify(candidate.value)).byteLength;
+			const stop = computeStudyOutputStop(bytes, bounds.goal.bytes, outputs);
+			const product = stop === void 0 ? candidate : void 0;
+			try {
+				for (const parent of parents) parent.check();
+				scope.check();
+				if (stop !== void 0) control.fail({
+					cause: "capacity",
+					message: "Study product exceeded its output allowance",
+					role: void 0,
+					stop
+				});
+				else for (const budget of outputs) budget.consume(bytes);
+			} catch (error) {
+				control.fail(readStudyFailure(error));
+			}
+			return product;
+		} catch (error) {
+			control.fail(readStudyFailure(error));
+			return;
+		} finally {
+			meter.close();
+			scope.close();
+		}
+	}
+};
+//#endregion
+//#region src/core/agents/helpers.ts
+/**
+* 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
+*/
+function projectStudyAgentRequest(gauge, estimate) {
+	return Math.ceil(gauge.overhead + gauge.scale * estimate);
+}
+/**
+* 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
+*/
+function validateStudyAgentUsage(usage, role) {
+	const prompt = usage?.prompt;
+	if (typeof prompt !== "number" || !Number.isFinite(prompt) || prompt <= 0) {
+		const message = "Gauged request returned no usable prompt count";
+		throw new StudyError("FAULT", message, {
+			cause: "infrastructure",
+			message,
+			role,
+			stop: void 0
+		});
+	}
+}
+/**
+* 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
+*/
+function translateStudyAgentError(error, runtime) {
+	if (!runtime.isAgentError(error) || error.code !== "WINDOW") return error;
+	const context = error.context;
+	return new StudyError("CAPACITY", error.message, {
+		cause: "capacity",
+		message: error.message,
+		role: "agent",
+		stop: {
+			layer: "window",
+			id: "Agent window",
+			max: parseStudyReading(context?.max),
+			consumed: parseStudyReading(context?.consumed)
+		}
+	});
+}
+/**
+* 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 }
+* ```
+*/
+function translateStudyAgentStop(stop) {
+	if (stop === void 0) return void 0;
+	const reading = (0, _orkestrel_contract.attempt)(() => {
+		if (!(0, _orkestrel_contract.isObject)(stop)) return void 0;
+		const layer = Reflect.get(stop, "layer");
+		const id = Reflect.get(stop, "id");
+		if (!(0, _orkestrel_contract.isNonEmptyString)(id)) return void 0;
+		if (layer === "meter" || layer === "budget") {
+			const max = Reflect.get(stop, "max");
+			const consumed = Reflect.get(stop, "consumed");
+			const limit = parseStudyReading(max);
+			const used = parseStudyReading(consumed);
+			return limit === void 0 || used === void 0 ? void 0 : {
+				layer,
+				id,
+				max: limit,
+				consumed: used
+			};
+		}
+		if (layer === "model") {
+			const usage = Reflect.get(stop, "usage");
+			return {
+				layer,
+				id,
+				max: void 0,
+				consumed: (0, _orkestrel_contract.isObject)(usage) ? parseStudyReading(Reflect.get(usage, "completion")) : void 0
+			};
+		}
+	});
+	const parsed = reading.success ? reading.value : void 0;
+	if (parsed === void 0) {
+		const message = "Agent stop record is malformed";
+		return new StudyError("FAULT", message, {
+			cause: "infrastructure",
+			message,
+			role: "agent",
+			stop: void 0
+		});
+	}
+	const message = parsed.layer === "meter" ? "Agent meter allowance reached its ceiling" : parsed.layer === "budget" ? "Agent budget reached its ceiling" : "Agent model reached its own token limit";
+	return new StudyError("CAPACITY", message, {
+		cause: "capacity",
+		message,
+		role: "agent",
+		stop: parsed
+	});
+}
+/**
+* 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
+*/
+function buildStudyAgentParts(measure) {
+	return {
+		messages: measure.messages.map((message) => ({
+			id: message.id,
+			role: message.role,
+			content: message.content,
+			framing: message.framing,
+			calls: message.calls,
+			thinking: message.thinking,
+			images: message.images
+		})),
+		tools: measure.tools,
+		schema: measure.schema
+	};
+}
+/**
+* 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
+*/
+function buildStudyAgentDispatch(dispatch) {
+	return {
+		canonical: dispatch?.id ?? null,
+		revision: dispatch?.revision ?? null
+	};
+}
+//#endregion
+//#region src/core/agents/validators.ts
+/**
+* Checks whether a value is a gauge with a finite positive scale and a finite nonnegative overhead.
+* @param value - The candidate gauge; additional members are admitted
+* @returns True if the gauge readings are finite and within their bounds; false otherwise
+* @example
+* ```ts
+* isStudyAgentGauge({ scale: 1, overhead: 0 }) // true
+* ```
+*/
+function isStudyAgentGauge(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isObject)(value) || !("scale" in value) || !("overhead" in value)) return false;
+		const { scale, overhead } = value;
+		return (0, _orkestrel_contract.isFiniteNumber)(scale) && scale > 0 && (0, _orkestrel_contract.isFiniteNumber)(overhead) && overhead >= 0;
+	});
+}
+/**
+* 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
+*/
+function isStudyAgentRuntime(value) {
+	return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isObject)(value) && "estimateRequest" in value && typeof value.estimateRequest === "function" && "measureRequest" in value && typeof value.measureRequest === "function" && "isAgentError" in value && typeof value.isAgentError === "function");
+}
+//#endregion
+//#region src/core/agents/StudyAgentObserver.ts
+/** Reads each Agent request's size before delegating it unchanged to the real provider. */
+var StudyAgentObserver = class {
+	#options;
+	/** 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) {
+		this.#options = { ...options };
+	}
+	/** Reports the delegate's trace label. */
+	get id() {
+		return this.#options.provider.id;
+	}
+	/** Reports the delegate's backend name. */
+	get name() {
+		return this.#options.provider.name;
+	}
+	/** Reports the delegate's thinking replay policy; an absent policy is the declared `none`. */
+	get replay() {
+		return this.#options.provider.replay ?? "none";
+	}
+	/** 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.
+	*/
+	async generate(messages, signal, tools, options) {
+		this.#measure(messages, tools, options);
+		const result = await this.#options.provider.generate(messages, signal, tools, options);
+		if (this.#options.enforced && !signal.aborted) validateStudyAgentUsage(result.usage, "agent");
+		return result;
+	}
+	/** 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, signal, tools, options) {
+		this.#measure(messages, tools, options);
+		return this.#relay(this.#options.provider.stream(messages, signal, tools, options), signal);
+	}
+	#measure(messages, tools, options) {
+		const request = {
+			messages,
+			...tools === void 0 ? {} : { tools },
+			...options === void 0 ? {} : { options }
+		};
+		const estimate = this.#options.runtime.estimateRequest(request);
+		const gauge = this.#options.gauge;
+		const projected = gauge === void 0 ? void 0 : projectStudyAgentRequest(gauge, estimate);
+		this.#options.record({
+			estimate,
+			projected
+		}, request);
+	}
+	async *#relay(source, signal) {
+		const result = yield* source;
+		if (this.#options.enforced && !signal.aborted) validateStudyAgentUsage(result.usage, "agent");
+		return result;
+	}
+};
+//#endregion
+//#region src/core/agents/StudyAgentJudge.ts
+/** Latches a real judge's failure before an enclosing runtime can treat it as absent. */
+var StudyAgentJudge = class {
+	#judge;
+	#latch;
+	/** 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, latch) {
+		this.#judge = judge;
+		this.#latch = latch;
+	}
+	/** Reports the delegate's trace label. */
+	get id() {
+		return this.#judge.id;
+	}
+	/** Reports the delegate's backend name. */
+	get name() {
+		return this.#judge.name;
+	}
+	/** Reports the delegate's model identity. */
+	get model() {
+		return this.#judge.model;
+	}
+	/** 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.
+	*/
+	async ask(request, signal) {
+		this.#latch.check();
+		try {
+			return await this.#judge.ask(request, signal);
+		} catch (error) {
+			this.#latch.fail(error);
+			throw error;
+		}
+	}
+};
+//#endregion
+exports.STUDY_CAUSES = STUDY_CAUSES;
+exports.STUDY_ERROR_BRAND = STUDY_ERROR_BRAND;
+exports.STUDY_GOALS = STUDY_GOALS;
+exports.STUDY_LAYERS = STUDY_LAYERS;
+exports.STUDY_NAME = STUDY_NAME;
+exports.STUDY_ROLES = STUDY_ROLES;
+exports.STUDY_TRIALS = STUDY_TRIALS;
+exports.StudyAgentJudge = StudyAgentJudge;
+exports.StudyAgentObserver = StudyAgentObserver;
+exports.StudyControl = StudyControl;
+exports.StudyDeadline = StudyDeadline;
+exports.StudyError = StudyError;
+exports.StudyMeter = StudyMeter;
+exports.StudyRequest = StudyRequest;
+exports.StudyScope = StudyScope;
+exports.StudySeries = StudySeries;
+exports.buildStudyAgentDispatch = buildStudyAgentDispatch;
+exports.buildStudyAgentParts = buildStudyAgentParts;
+exports.buildStudySchedule = buildStudySchedule;
+exports.computeStudyAdmittedStop = computeStudyAdmittedStop;
+exports.computeStudyOutputStop = computeStudyOutputStop;
+exports.computeStudyScores = computeStudyScores;
+exports.failStudyTicket = failStudyTicket;
+exports.failureToStudyError = failureToStudyError;
+exports.isStudyAgentGauge = isStudyAgentGauge;
+exports.isStudyAgentRuntime = isStudyAgentRuntime;
+exports.isStudyBounds = isStudyBounds;
+exports.isStudyCause = isStudyCause;
+exports.isStudyCriterion = isStudyCriterion;
+exports.isStudyDefinition = isStudyDefinition;
+exports.isStudyDigest = isStudyDigest;
+exports.isStudyError = isStudyError;
+exports.isStudyErrorCode = isStudyErrorCode;
+exports.isStudyGoal = isStudyGoal;
+exports.isStudyGrading = isStudyGrading;
+exports.isStudyJudgment = isStudyJudgment;
+exports.isStudyLabeling = isStudyLabeling;
+exports.isStudyLayer = isStudyLayer;
+exports.isStudyLimit = isStudyLimit;
+exports.isStudyName = isStudyName;
+exports.isStudyProduct = isStudyProduct;
+exports.isStudyProfile = isStudyProfile;
+exports.isStudyProvider = isStudyProvider;
+exports.isStudyRole = isStudyRole;
+exports.isStudyRoom = isStudyRoom;
+exports.isStudyRubric = isStudyRubric;
+exports.isStudyScenario = isStudyScenario;
+exports.isStudyStop = isStudyStop;
+exports.isStudyTimestamp = isStudyTimestamp;
+exports.isStudyUsage = isStudyUsage;
+exports.matchesStudyKeys = matchesStudyKeys;
+exports.normalizeStudyProfile = normalizeStudyProfile;
+exports.omitStudyAbsent = omitStudyAbsent;
+exports.parseStudyDefinition = parseStudyDefinition;
+exports.parseStudyGrading = parseStudyGrading;
+exports.parseStudyLabeling = parseStudyLabeling;
+exports.parseStudyProfile = parseStudyProfile;
+exports.parseStudyReading = parseStudyReading;
+exports.parseStudyRubric = parseStudyRubric;
+exports.parseStudyScenario = parseStudyScenario;
+exports.projectStudyAgentRequest = projectStudyAgentRequest;
+exports.readStudyFailure = readStudyFailure;
+exports.studyStopToJSON = studyStopToJSON;
+exports.translateStudyAgentError = translateStudyAgentError;
+exports.translateStudyAgentStop = translateStudyAgentStop;
+exports.validateStudyAgentUsage = validateStudyAgentUsage;
+exports.validateStudyInputs = validateStudyInputs;
+
+//# sourceMappingURL=index.cjs.map