@orkestrel/study 0.0.1 → 0.0.2

package/dist/src/server/index.js

@@ -1,670 +1,34 @@
 import { createRequire, isBuiltin, registerHooks, stripTypeScriptTypes } from "node:module";
-import { arrayOf, attempt, canonicalStringify, cloneJSONValue, holds, isArray, isError, isFiniteNumber, isInstance, isInteger, isJSONValue, isNonEmptyString, isObject, isRecord, isString, literalOf, parseJSON } from "@orkestrel/contract";
+import { STUDY_CAUSES, STUDY_LAYERS, STUDY_ROLES, StudyControl, StudyDeadline, StudyError, StudySeries, buildStudyAgentDispatch, buildStudyAgentParts, buildStudySchedule, computeStudyScores, failStudyTicket, failureToStudyError, isStudyAgentGauge, isStudyBounds, isStudyCause, isStudyDefinition, isStudyDigest, isStudyError, isStudyGoal, isStudyJudgment, isStudyName, isStudyProduct, isStudyProfile, isStudyRole, isStudyRubric, isStudyScenario, isStudyStop, isStudyTimestamp, isStudyUsage, matchesStudyKeys, parseStudyDefinition, parseStudyGrading, parseStudyLabeling, parseStudyProfile, parseStudyReading, parseStudyRubric, parseStudyScenario, projectStudyAgentRequest, readStudyFailure, studyStopToJSON, translateStudyAgentError, validateStudyAgentUsage, validateStudyInputs } from "../core/index.js";
+import { arrayOf, attempt, canonicalStringify, cloneJSONValue, holds, isArray, isError, isInstance, isInteger, isJSONValue, isNonEmptyString, isObject, isRecord, isString, parseJSON } from "@orkestrel/contract";
 import { createHash, randomUUID } from "node:crypto";
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
-import { MAX_TIMEOUT_MS, Timeout } from "@orkestrel/timeout";
 import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, opendirSync, readFileSync, readSync, realpathSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { lstat, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
-import { Budget, isBudgetError } from "@orkestrel/budget";
-import { Abort, linkSignal } from "@orkestrel/abort";
 import { execFile, execFileSync, fork, spawn } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { isToolCall } from "@orkestrel/tool";
-//#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");
-/** 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
+import { isBudgetError } from "@orkestrel/budget";
+//#region src/server/helpers.ts
+/** Reports whether a caught value is a Node error carrying the given system code.
+* @remarks Requires an `Error` from this realm. Structured cloning, such as a worker's `postMessage`,
+* drops a Node error's system code, so the cloned error does not match.
+* @param value - The caught value.
+* @param code - The system error code to match.
+* @returns True if the value is an Error from this realm carrying the code; false otherwise.
+* @example Match a system error
 * ```ts
-* import { matchesStudyKeys } from '@orkestrel/study'
+* import { matchesSystemError } from '@orkestrel/study/server'
 *
-* matchesStudyKeys({ id: 'one' }, ['id']) // true
-* ```
-*/
-function matchesStudyKeys(value, required, optional = []) {
-	return holds(() => {
-		if (!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
-* @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) => canonicalStringify([criterion.scenario, criterion.goal]) ?? ""));
-	for (const scenario of scenarios) for (const goal of scenario.goals) if (!covered.has(canonicalStringify([scenario.id, goal.id]) ?? "")) throw new StudyError("CONFIG", "Every declared goal needs a criterion");
-}
-/**
-* 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 (canonicalStringify(expected) !== 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: 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(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 = literalOf(STUDY_ROLES);
-/** Checks whether a value names an operational ending. */
-var isStudyCause = literalOf(STUDY_CAUSES);
-/** Checks whether a value names a ceiling a run can stop at. */
-var isStudyLayer = 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 holds(() => isRecord(value) && matchesStudyKeys(value, ["layer", "id"], ["max", "consumed"]) && isStudyLayer(value.layer) && isNonEmptyString(value.id) && ["max", "consumed"].every((key) => value[key] === void 0 || 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 holds(() => {
-		if (!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 <= 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 holds(() => {
-		if (!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 holds(() => {
-		return isRecord(value) && matchesStudyKeys(value, ["id", "input"]) && isStudyName(value.id) && 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 holds(() => {
-		if (!isRecord(value) || !matchesStudyKeys(value, ["id", "goals"]) || !isStudyName(value.id) || !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 && 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 holds(() => {
-		if (!isRecord(value) || !isJSONValue(value) || !matchesStudyKeys(value, [
-			"name",
-			"version",
-			"question",
-			"purpose",
-			"driver",
-			"arms",
-			"scenarios",
-			"order",
-			"retries",
-			"rubric"
-		]) || !isStudyName(value.name) || !isStudyName(value.driver) || !isNonEmptyString(value.version) || !isNonEmptyString(value.question) || value.purpose !== "mechanism" && value.purpose !== "quality" && value.purpose !== "capacity" || !isArray(value.arms) || value.arms.length === 0 || !value.arms.every(isStudyName) || new Set(value.arms).size !== value.arms.length || !isArray(value.scenarios) || value.scenarios.length === 0 || !value.scenarios.every(isStudyName) || new Set(value.scenarios).size !== value.scenarios.length || !isArray(value.order) || !isJSONValue(value.order) || value.order.length === 0 || value.retries !== 0 || !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) => 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 holds(() => {
-		if (!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 holds(() => {
-		if (!isRecord(value) || !matchesStudyKeys(value, [
-			"entry",
-			"url",
-			"model",
-			"digest"
-		], ["judge"]) || ![
-			"entry",
-			"url",
-			"model"
-		].every((key) => isNonEmptyString(value[key])) || typeof value.url !== "string" || !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 && (!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 holds(() => {
-		return isRecord(value) && matchesStudyKeys(value, [
-			"name",
-			"agent",
-			"subject",
-			"roots",
-			"bounds",
-			"room"
-		], [
-			"provider",
-			"qualification",
-			"settings"
-		]) && isStudyName(value.name) && isNonEmptyString(value.agent) && isArray(value.roots) && 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 && isNonEmptyString(value.subject) && isStudyBounds(value.bounds) && isStudyRoom(value.room) && (value.provider === void 0 || isStudyProvider(value.provider)) && (value.qualification === void 0 || isNonEmptyString(value.qualification)) && (value.settings === void 0 || isRecord(value.settings) && 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 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 holds(() => {
-		return 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 holds(() => isRecord(value) && typeof value.partial === "boolean" && 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 holds(() => {
-		return 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" && 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 holds(() => {
-		return isRecord(value) && matchesStudyKeys(value, ["version", "criteria"]) && typeof value.version === "string" && value.version.trim().length > 0 && isArray(value.criteria) && value.criteria.length > 0 && value.criteria.every(isStudyCriterion) && new Set(value.criteria.map((criterion) => criterion.id)).size === value.criteria.length && 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 holds(() => {
-		return 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 && isArray(value.references) && 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 holds(() => {
-		return 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) && isArray(value.usage) && Reflect.ownKeys(value.usage).length === value.usage.length + 1 && Array.from(value.usage).every(isStudyUsage) && isArray(value.judgments) && value.judgments.every(isStudyJudgment) && value.judgments.every((judgment) => judgment.method === "human" || judgment.method === "model") && new Set(value.judgments.map((judgment) => canonicalStringify([judgment.trial, judgment.criterion]))).size === value.judgments.length && 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 holds(() => {
-		return 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)) && isArray(value.attempts) && isJSONValue(value.attempts) && value.attempts.every(isStudyName) && new Set(value.attempts).size === value.attempts.length && isArray(value.judgments) && value.judgments.every(isStudyJudgment) && new Set(value.judgments.map((judgment) => canonicalStringify([judgment.trial, judgment.criterion]))).size === value.judgments.length && 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);
-		Object.defineProperty(this, STUDY_ERROR_BRAND, {
-			value: this,
-			configurable: true
-		});
-		this.name = "StudyError";
-		this.code = code;
-		this.failure = failure;
-	}
-};
-/**
-* 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
+* const error = Object.assign(new Error('Missing declaration'), { code: 'ENOENT' })
+* matchesSystemError(error, 'ENOENT') // true
+* matchesSystemError({ code: 'ENOENT' }, 'ENOENT') // false
 * ```
 */
-function isStudyError(value) {
-	return isError(value) && holds(() => Object.getPrototypeOf(value) !== Error.prototype && value.name === "StudyError" && Object.getOwnPropertyDescriptor(value, STUDY_ERROR_BRAND)?.value === value && "code" in value && isStudyErrorCode(value.code));
+function matchesSystemError(value, code) {
+	return holds(() => isError(value) && "code" in value && value.code === code);
 }
-//#endregion
-//#region src/server/helpers.ts
 /** Checks strict lexical containment under a selected directory.
 * @param root - The canonical directory.
 * @param path - The candidate absolute file.
@@ -2076,153 +1440,6 @@ var StudyResultStore = class {
 	}
 };
 //#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 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 = 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 = 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 = 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 = 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 = 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 = 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/server/stores/StudyGradingStore.ts
 /** Retains immutable deterministic grading versions independently of execution bytes. */
 var StudyGradingStore = class {
@@ -2290,7 +1507,7 @@ var StudyGradingStore = class {
 		try {
 			await lstat(directory);
 		} catch (error) {
-			if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+			if (matchesSystemError(error, "ENOENT")) return void 0;
 			throw error;
 		}
 		await checkStudyDirectory(directory);
@@ -2331,14 +1548,14 @@ var StudyGradingStore = class {
 		try {
 			await mkdir(root);
 		} catch (error) {
-			if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+			if (!matchesSystemError(error, "EEXIST")) throw error;
 		}
 		await checkStudyDirectory(root);
 		const directory = join(root, id);
 		try {
 			await mkdir(directory);
 		} catch (error) {
-			if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+			if (!matchesSystemError(error, "EEXIST")) throw error;
 			const existing = await this.read(id);
 			if (existing === void 0 || canonicalStringify(existing) !== canonicalStringify(grading) || hashStudyBytes(await readStudyBytes(join(directory, "grading.json"), 16777216)) !== id) throw new StudyError("CUSTODY", "Existing grading version is incompatible");
 			return id;
@@ -2390,6 +1607,7 @@ study grade <result> --rubric <path>
 study label <result> --grading <sha256> --labels <path>
 study report <result> --grading <sha256>
 study --help
+study --version
 
 Profiles default to local. Flags require values and may appear only once.
 Results default to tmp/studies/<result>; scratch also uses tmp/studies.
@@ -2405,6 +1623,81 @@ Exit codes: 0 success, 64 invalid input, 124 deadline, 130 interruption, 1 opera
 `;
 //#endregion
 //#region src/server/commands/helpers.ts
+/** Reads one declaration file and refuses a missing or linked path with its root-relative path.
+* @param root - The consumer root used to describe a missing or linked declaration.
+* @param path - The already resolved and contained declaration path.
+* @returns The exact declaration bytes under the custody metadata allowance.
+* @throws StudyError - Thrown with code `CONFIG` when the path is missing or linked; other custody refusals retain their codes.
+* @example Read declaration bytes
+* ```ts
+* import { readStudyDeclarationBytes } from '@orkestrel/study/server'
+*
+* declare const root: string
+* declare const path: string
+* await readStudyDeclarationBytes(root, path)
+* ```
+*/
+async function readStudyDeclarationBytes(root, path) {
+	try {
+		const absolute = resolve(path);
+		const origin = parse(absolute).root;
+		const names = relative(origin, absolute).split(sep).filter(Boolean);
+		for (const [index] of names.entries()) {
+			const candidate = join(origin, ...names.slice(0, index + 1));
+			const stat = await lstat(candidate);
+			if (stat.isSymbolicLink()) throw new StudyError("CONFIG", `Declaration path is linked: ${relative(root, candidate).split(sep).join("/")}`);
+			if (!stat.isDirectory()) break;
+		}
+		return await readStudyBytes(path, STUDY_CUSTODY_BYTES);
+	} catch (error) {
+		if (matchesSystemError(error, "ENOENT")) throw new StudyError("CONFIG", `Declaration is missing: ${relative(root, path).split(sep).join("/")}`);
+		throw error;
+	}
+}
+/** Reads a study declaration, its driver's scenarios, and its rubric as the command resolves them.
+* @param root - The consumer root containing the studies directory.
+* @param study - The selected study name.
+* @param signal - Optional cancellation checked between scenario reads.
+* @returns The parsed declaration, driver bundle, ordered scenarios, fixtures, and selected rubric.
+* @throws StudyError - Thrown when declarations are missing, invalid, or incompatible.
+* @example Read a study declaration
+* ```ts
+* import type { StudyDeclaration } from '@orkestrel/study/server'
+* import { readStudyDeclaration } from '@orkestrel/study/server'
+*
+* declare const root: string
+* const declaration: StudyDeclaration = await readStudyDeclaration(root, 'assessment')
+* ```
+*/
+async function readStudyDeclaration(root, study, signal) {
+	const directory = resolveStudyPath(join(root, "studies"), study);
+	const definition = parseStudyDefinition(decodeStudyJSON(await readStudyDeclarationBytes(root, resolveStudyPath(directory, "study.json"))));
+	if (definition.name !== study) throw new StudyError("CONFIG", "Study name differs from its selected directory");
+	const bundle = resolveStudyPath(join(root, "studies"), definition.driver);
+	const steps = [];
+	for (const id of definition.scenarios) {
+		signal?.throwIfAborted();
+		const path = `scenarios/${id}.json`;
+		const bytes = await readStudyDeclarationBytes(root, resolveStudyPath(bundle, path));
+		const scenario = parseStudyScenario(decodeStudyJSON(bytes));
+		if (scenario.id !== id) throw new StudyError("CONFIG", "Scenario identity is incompatible");
+		steps.push({
+			scenario,
+			fixture: {
+				path,
+				digest: hashStudyBytes(bytes)
+			}
+		});
+	}
+	const rubric = parseStudyRubric(decodeStudyJSON(await readStudyDeclarationBytes(root, resolveStudyPath(directory, definition.rubric))));
+	return {
+		bundle,
+		definition,
+		scenarios: Object.freeze(steps.map((step) => step.scenario)),
+		fixtures: Object.freeze(steps.map((step) => step.fixture)),
+		rubric
+	};
+}
 /**
 * Resolves a portable relative artifact path strictly inside its selected directory.
 * @param directory - The selected custody or study directory
@@ -2616,1083 +1909,167 @@ function computeStudyReport(result, rubric, grading) {
 	const identity = result.manifest.identity;
 	return {
 		command: "report",
-		result: result.manifest.id,
-		seal: result.seal.id,
-		identity: {
-			agent: identity.agent,
-			subject: identity.subject,
-			instrument: identity.instrument,
-			fixtures: identity.fixtures,
-			profile: identity.profile,
-			...identity.provider === void 0 ? {} : { provider: identity.provider }
-		},
-		purpose: result.manifest.definition.purpose,
-		population: "Complete declared trial and criterion horizon",
-		uncertainty: repetitions.length === 1 ? "One repetition is descriptive and does not establish replicated capacity or quality." : "Repetitions are retained separately; intervals represent unresolved grading, not statistical confidence.",
-		scores: scores.map((score) => ({ ...score })),
-		repetitions,
-		operations: {
-			trials: {
-				scheduled: result.manifest.schedule.length,
-				terminal: result.attempts.length,
-				...computeStudyPartition(result.attempts),
-				completed: result.attempts.filter((attempt) => attempt.failure === void 0 && attempt.observations.every((observation) => completed.has(observation))).length,
-				faults: STUDY_CAUSES.map((cause) => ({
-					cause,
-					...computeStudyPartition(result.attempts.filter((attempt) => attempt.failure?.cause === cause))
-				})),
-				attributions: computeStudyAttributions(result.attempts.flatMap((attempt) => attempt.failure === void 0 ? [] : [{
-					trial: attempt.trial.id,
-					goal: void 0,
-					failure: attempt.failure,
-					executed: attempt.executed
-				}]))
-			},
-			goals: {
-				scheduled: observations.length,
-				...computeStudyPartition(observations),
-				products: observations.filter((observation) => observation.product !== void 0).length,
-				partial: observations.filter((observation) => observation.product?.partial === true).length,
-				completed: observations.filter((observation) => completed.has(observation)).length,
-				faults: STUDY_CAUSES.map((cause) => ({
-					cause,
-					...computeStudyPartition(observations.filter((observation) => observation.failure?.cause === cause))
-				})),
-				attributions: computeStudyAttributions(result.attempts.flatMap((attempt) => attempt.observations.flatMap((observation) => observation.failure === void 0 ? [] : [{
-					trial: attempt.trial.id,
-					goal: observation.goal,
-					failure: observation.failure,
-					executed: observation.executed
-				}])))
-			}
-		},
-		costs: {
-			duration: result.attempts.reduce((total, attempt) => total + attempt.duration, 0),
-			roles: STUDY_ROLES.map((role) => {
-				const charges = usage.filter((entry) => entry.role === role);
-				return {
-					role,
-					measurements: charges.length,
-					calls: charges.reduce((total, entry) => total + entry.calls, 0),
-					duration: charges.reduce((total, entry) => total + entry.duration, 0),
-					tokens: {
-						known: charges.reduce((total, entry) => total + (entry.tokens ?? 0), 0),
-						unknown: charges.filter((entry) => entry.tokens === void 0).length
-					},
-					bytes: {
-						known: charges.reduce((total, entry) => total + (entry.bytes ?? 0), 0),
-						unknown: charges.filter((entry) => entry.bytes === void 0).length
-					}
-				};
-			})
-		}
-	};
-}
-//#endregion
-//#region src/server/commands/parsers.ts
-/** Parses public command tokens with operation-specific grammar diagnostics.
-* @param arguments_ - Exact command tokens, after the CLI help boundary.
-* @returns The independent operation request.
-* @throws StudyError when a token, required flag, or portable path is invalid.
-* @example Parse a study command
-* ```ts
-* import { parseStudyArguments } from '@orkestrel/study/server'
-*
-* parseStudyArguments(['check', 'files', '--profile', 'local'])
-* ```
-*/
-function parseStudyArguments(arguments_) {
-	const command = arguments_[0];
-	const target = arguments_[1];
-	const usage = "study check <study> [--profile <name>]\nstudy execute <study> [--profile <name>] [--out <path>] [--expected <sha256>]\nstudy grade <result> --rubric <path>\nstudy label <result> --grading <sha256> --labels <path>\nstudy report <result> --grading <sha256>\nstudy --help\n\nProfiles default to local. Flags require values and may appear only once.\nResults default to tmp/studies/<result>; scratch also uses tmp/studies.\nA result is its id under tmp/studies, a root-relative path, or an absolute path.\nRelative paths, including --out, must stay inside the consumer working directory.\nOutput directories must be new; existing results are never overwritten.\n--expected pins the fingerprint returned by check. --grading selects an exact grading.\n--rubric selects independent criteria. --labels imports caller-supplied semantic labels.\nSuccess writes one JSON document; next contains suggested argv, never executed automatically.\ncheck, grade, label and report have a fixed allowance of 60 seconds.\nexecute checks first, then uses the declared series duration plus 15 seconds for cleanup.\nExit codes: 0 success, 64 invalid input, 124 deadline, 130 interruption, 1 operational failure.\n".split("\n").find((line) => line.startsWith("study " + command + " ")) ?? "Expected study check, execute, grade, label, or report; use study --help.";
-	if (![
-		"check",
-		"execute",
-		"grade",
-		"label",
-		"report"
-	].includes(command ?? "")) throw new StudyError("CONFIG", "Unknown or missing command " + JSON.stringify(command ?? "<command>") + ". " + usage);
-	if (target === void 0 || target === "" || target.startsWith("-")) throw new StudyError("CONFIG", "Missing <" + (command === "check" || command === "execute" ? "study" : "result") + "> before " + JSON.stringify(target ?? "<end>") + ". " + usage);
-	const allowed = command === "check" ? ["--profile"] : command === "execute" ? [
-		"--profile",
-		"--out",
-		"--expected"
-	] : command === "grade" ? ["--rubric"] : command === "label" ? ["--grading", "--labels"] : ["--grading"];
-	const tokens = arguments_.slice(2);
-	const pairs = [...tokens.entries()].flatMap(([index, flag]) => index % 2 === 0 ? [{
-		flag,
-		value: tokens[index + 1]
-	}] : []);
-	const firsts = new Map(pairs.map(({ flag }, index) => [flag, index]).reverse());
-	for (const [index, { flag, value }] of pairs.entries()) {
-		if (flag === void 0 || !allowed.includes(flag)) throw new StudyError("CONFIG", JSON.stringify(flag ?? "<end>") + " is not a " + command + " flag; accepts " + allowed.join(", ") + ". " + usage);
-		if (firsts.get(flag) !== index) throw new StudyError("CONFIG", flag + " is duplicate. " + usage);
-		if (value === void 0 || value === "" || value.startsWith("-")) throw new StudyError("CONFIG", flag + " requires a value before " + JSON.stringify(value ?? "<end>") + ". " + usage);
-	}
-	const flags = new Map(pairs.flatMap(({ flag, value }) => flag === void 0 || value === void 0 ? [] : [[flag, value]]));
-	if (command === "check" || command === "execute") {
-		if (!isStudyCustodyName(target)) throw new StudyError("CONFIG", "Invalid study token " + JSON.stringify(target) + "; use a portable study name. " + usage);
-		const profile = flags.get("--profile") ?? "local";
-		const out = flags.get("--out");
-		const expected = flags.get("--expected");
-		if (!isStudyCustodyName(profile)) throw new StudyError("CONFIG", "--profile " + JSON.stringify(profile) + " must be a portable name. " + usage);
-		if (out !== void 0 && !isAbsolute(out)) try {
-			resolveStudyPath(resolve("."), out);
-		} catch {
-			throw new StudyError("CONFIG", "--out " + JSON.stringify(out) + " must be a portable contained path and cannot escape the consumer root. " + usage);
-		}
-		if (expected !== void 0 && !isStudyDigest(expected)) throw new StudyError("CONFIG", "--expected " + JSON.stringify(expected) + " must be a SHA-256 fingerprint. " + usage);
-		return {
-			command,
-			target,
-			profile,
-			out,
-			expected
-		};
-	}
-	if (command === "grade") {
-		const rubric = flags.get("--rubric");
-		if (rubric === void 0) throw new StudyError("CONFIG", "Missing --rubric. " + usage);
-		return {
-			command,
-			target,
-			rubric
-		};
-	}
-	const grading = flags.get("--grading");
-	if (!isStudyDigest(grading)) throw new StudyError("CONFIG", "--grading " + JSON.stringify(grading ?? "<missing>") + " must be an exact SHA-256 grading identity. " + usage);
-	if (command === "label") {
-		const labels = flags.get("--labels");
-		if (labels === void 0) throw new StudyError("CONFIG", "Missing --labels. " + usage);
-		return {
-			command,
-			target,
-			grading,
-			labels
-		};
-	}
-	return {
-		command: "report",
-		target,
-		grading
-	};
-}
-//#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 (isBudgetError(error)) {
-		const reading = 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: isNonEmptyString(reading.value.id) ? reading.value.id : "Agent budget",
-				max: parseStudyReading(reading.value.max),
-				consumed: parseStudyReading(reading.value.consumed)
-			}
-		};
-	}
-	return {
-		cause: "infrastructure",
-		message: 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 Abort();
-	#failure;
-	/** Links cancellation to the caller without assigning it a task verdict.
-	* @param signal - Optional parent cancellation.
-	*/
-	constructor(signal) {
-		this.#abort = new 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 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 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 Budget({
-			max: options.limit.calls,
-			consumer: (value) => value
-		});
-		this.#tokens = new Budget({
-			max: options.limit.tokens,
-			consumer: (value) => value
-		});
-		this.#bytes = new Budget({
-			max: options.limit.bytes,
-			consumer: (value) => value
-		});
-		this.#timeout = new 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 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 Timeout({ ms: options.duration });
-		this.#signal = 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) || canonicalStringify(expected) !== 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 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 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;
+		result: result.manifest.id,
+		seal: result.seal.id,
+		identity: {
+			agent: identity.agent,
+			subject: identity.subject,
+			instrument: identity.instrument,
+			fixtures: identity.fixtures,
+			profile: identity.profile,
+			...identity.provider === void 0 ? {} : { provider: identity.provider }
+		},
+		purpose: result.manifest.definition.purpose,
+		population: "Complete declared trial and criterion horizon",
+		uncertainty: repetitions.length === 1 ? "One repetition is descriptive and does not establish replicated capacity or quality." : "Repetitions are retained separately; intervals represent unresolved grading, not statistical confidence.",
+		scores: scores.map((score) => ({ ...score })),
+		repetitions,
+		operations: {
+			trials: {
+				scheduled: result.manifest.schedule.length,
+				terminal: result.attempts.length,
+				...computeStudyPartition(result.attempts),
+				completed: result.attempts.filter((attempt) => attempt.failure === void 0 && attempt.observations.every((observation) => completed.has(observation))).length,
+				faults: STUDY_CAUSES.map((cause) => ({
+					cause,
+					...computeStudyPartition(result.attempts.filter((attempt) => attempt.failure?.cause === cause))
+				})),
+				attributions: computeStudyAttributions(result.attempts.flatMap((attempt) => attempt.failure === void 0 ? [] : [{
+					trial: attempt.trial.id,
+					goal: void 0,
+					failure: attempt.failure,
+					executed: attempt.executed
+				}]))
+			},
+			goals: {
+				scheduled: observations.length,
+				...computeStudyPartition(observations),
+				products: observations.filter((observation) => observation.product !== void 0).length,
+				partial: observations.filter((observation) => observation.product?.partial === true).length,
+				completed: observations.filter((observation) => completed.has(observation)).length,
+				faults: STUDY_CAUSES.map((cause) => ({
+					cause,
+					...computeStudyPartition(observations.filter((observation) => observation.failure?.cause === cause))
+				})),
+				attributions: computeStudyAttributions(result.attempts.flatMap((attempt) => attempt.observations.flatMap((observation) => observation.failure === void 0 ? [] : [{
+					trial: attempt.trial.id,
+					goal: observation.goal,
+					failure: observation.failure,
+					executed: observation.executed
+				}])))
 			}
-			control.fail(readStudyFailure(error));
+		},
+		costs: {
+			duration: result.attempts.reduce((total, attempt) => total + attempt.duration, 0),
+			roles: STUDY_ROLES.map((role) => {
+				const charges = usage.filter((entry) => entry.role === role);
+				return {
+					role,
+					measurements: charges.length,
+					calls: charges.reduce((total, entry) => total + entry.calls, 0),
+					duration: charges.reduce((total, entry) => total + entry.duration, 0),
+					tokens: {
+						known: charges.reduce((total, entry) => total + (entry.tokens ?? 0), 0),
+						unknown: charges.filter((entry) => entry.tokens === void 0).length
+					},
+					bytes: {
+						known: charges.reduce((total, entry) => total + (entry.bytes ?? 0), 0),
+						unknown: charges.filter((entry) => entry.bytes === void 0).length
+					}
+				};
+			})
 		}
-		return observations;
+	};
+}
+//#endregion
+//#region src/server/commands/parsers.ts
+/** Parses public command tokens with operation-specific grammar diagnostics.
+* @param arguments_ - Exact command tokens, after the CLI help boundary.
+* @returns The independent operation request.
+* @throws StudyError when a token, required flag, or portable path is invalid.
+* @example Parse a study command
+* ```ts
+* import { parseStudyArguments } from '@orkestrel/study/server'
+*
+* parseStudyArguments(['check', 'files', '--profile', 'local'])
+* ```
+*/
+function parseStudyArguments(arguments_) {
+	const command = arguments_[0];
+	const target = arguments_[1];
+	const usage = "study check <study> [--profile <name>]\nstudy execute <study> [--profile <name>] [--out <path>] [--expected <sha256>]\nstudy grade <result> --rubric <path>\nstudy label <result> --grading <sha256> --labels <path>\nstudy report <result> --grading <sha256>\nstudy --help\nstudy --version\n\nProfiles default to local. Flags require values and may appear only once.\nResults default to tmp/studies/<result>; scratch also uses tmp/studies.\nA result is its id under tmp/studies, a root-relative path, or an absolute path.\nRelative paths, including --out, must stay inside the consumer working directory.\nOutput directories must be new; existing results are never overwritten.\n--expected pins the fingerprint returned by check. --grading selects an exact grading.\n--rubric selects independent criteria. --labels imports caller-supplied semantic labels.\nSuccess writes one JSON document; next contains suggested argv, never executed automatically.\ncheck, grade, label and report have a fixed allowance of 60 seconds.\nexecute checks first, then uses the declared series duration plus 15 seconds for cleanup.\nExit codes: 0 success, 64 invalid input, 124 deadline, 130 interruption, 1 operational failure.\n".split("\n").find((line) => line.startsWith("study " + command + " ")) ?? "Expected study check, execute, grade, label, or report; use study --help.";
+	if (![
+		"check",
+		"execute",
+		"grade",
+		"label",
+		"report"
+	].includes(command ?? "")) throw new StudyError("CONFIG", "Unknown or missing command " + JSON.stringify(command ?? "<command>") + ". " + usage);
+	if (target === void 0 || target === "" || target.startsWith("-")) throw new StudyError("CONFIG", "Missing <" + (command === "check" || command === "execute" ? "study" : "result") + "> before " + JSON.stringify(target ?? "<end>") + ". " + usage);
+	const allowed = command === "check" ? ["--profile"] : command === "execute" ? [
+		"--profile",
+		"--out",
+		"--expected"
+	] : command === "grade" ? ["--rubric"] : command === "label" ? ["--grading", "--labels"] : ["--grading"];
+	const tokens = arguments_.slice(2);
+	const pairs = [...tokens.entries()].flatMap(([index, flag]) => index % 2 === 0 ? [{
+		flag,
+		value: tokens[index + 1]
+	}] : []);
+	const firsts = new Map(pairs.map(({ flag }, index) => [flag, index]).reverse());
+	for (const [index, { flag, value }] of pairs.entries()) {
+		if (flag === void 0 || !allowed.includes(flag)) throw new StudyError("CONFIG", JSON.stringify(flag ?? "<end>") + " is not a " + command + " flag; accepts " + allowed.join(", ") + ". " + usage);
+		if (firsts.get(flag) !== index) throw new StudyError("CONFIG", flag + " is duplicate. " + usage);
+		if (value === void 0 || value === "" || value.startsWith("-")) throw new StudyError("CONFIG", flag + " requires a value before " + JSON.stringify(value ?? "<end>") + ". " + usage);
 	}
-	async #release(lease, control, series) {
-		const cleanup = await lease.close();
-		try {
-			series.check();
-		} catch (error) {
-			control.fail(readStudyFailure(error));
+	const flags = new Map(pairs.flatMap(({ flag, value }) => flag === void 0 || value === void 0 ? [] : [[flag, value]]));
+	if (command === "check" || command === "execute") {
+		if (!isStudyCustodyName(target)) throw new StudyError("CONFIG", "Invalid study token " + JSON.stringify(target) + "; use a portable study name. " + usage);
+		const profile = flags.get("--profile") ?? "local";
+		const out = flags.get("--out");
+		const expected = flags.get("--expected");
+		if (!isStudyCustodyName(profile)) throw new StudyError("CONFIG", "--profile " + JSON.stringify(profile) + " must be a portable name. " + usage);
+		if (out !== void 0 && !isAbsolute(out)) try {
+			resolveStudyPath(resolve("."), out);
+		} catch {
+			throw new StudyError("CONFIG", "--out " + JSON.stringify(out) + " must be a portable contained path and cannot escape the consumer root. " + usage);
 		}
-		return cleanup;
+		if (expected !== void 0 && !isStudyDigest(expected)) throw new StudyError("CONFIG", "--expected " + JSON.stringify(expected) + " must be a SHA-256 fingerprint. " + usage);
+		return {
+			command,
+			target,
+			profile,
+			out,
+			expected
+		};
 	}
-	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
-		});
+	if (command === "grade") {
+		const rubric = flags.get("--rubric");
+		if (rubric === void 0) throw new StudyError("CONFIG", "Missing --rubric. " + usage);
+		return {
+			command,
+			target,
+			rubric
+		};
 	}
-	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: 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();
-		}
+	const grading = flags.get("--grading");
+	if (!isStudyDigest(grading)) throw new StudyError("CONFIG", "--grading " + JSON.stringify(grading ?? "<missing>") + " must be an exact SHA-256 grading identity. " + usage);
+	if (command === "label") {
+		const labels = flags.get("--labels");
+		if (labels === void 0) throw new StudyError("CONFIG", "Missing --labels. " + usage);
+		return {
+			command,
+			target,
+			grading,
+			labels
+		};
 	}
-};
+	return {
+		command: "report",
+		target,
+		grading
+	};
+}
 //#endregion
 //#region src/server/processes/constants.ts
 /** Limits each serialized IPC envelope, including its JSON framing. */
@@ -3785,6 +2162,23 @@ function resolveStudyInstrument(entry) {
 	if (root === void 0) throw new StudyError("CONFIG", "Cannot locate the study runtime package");
 	return root;
 }
+/** Reads the version of the study package that owns an executable entry.
+* @param entry - The installed runtime's executable entry.
+* @returns The non-empty version declared by the owning study package.
+* @throws StudyError - Thrown when no study package owns the entry or its version is absent or empty.
+* @example Read the installed version
+* ```ts
+* import { readStudyVersion } from '@orkestrel/study/server'
+*
+* declare const entry: string
+* readStudyVersion(entry)
+* ```
+*/
+function readStudyVersion(entry) {
+	const value = JSON.parse(readFileSync(join(resolveStudyInstrument(entry), "package.json"), "utf8"));
+	if (!isRecord(value) || typeof value.version !== "string" || value.version.length === 0) throw new StudyError("CONFIG", "Study runtime package declares no version");
+	return value.version;
+}
 /** Collects a directory and each of its ancestors up to the filesystem root, nearest first.
 * @param directory - The absolute directory to start from.
 * @returns The directory followed by every parent directory, ending at the root.
@@ -3856,14 +2250,14 @@ function terminateStudyChild(child) {
 			for (const pid of [...descendants].reverse()) try {
 				process.kill(pid, "SIGKILL");
 			} catch (error) {
-				if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) throw error;
+				if (!matchesSystemError(error, "ESRCH")) throw error;
 			}
 		}
 	} catch (error) {
 		try {
 			process.kill(child.pid, 0);
 		} catch (status) {
-			if (status instanceof Error && "code" in status && status.code === "ESRCH") return;
+			if (matchesSystemError(status, "ESRCH")) return;
 			throw status;
 		}
 		if (child.exitCode === null && child.signalCode === null) {
@@ -4631,35 +3025,13 @@ var StudyCommand = class {
 		throw new StudyError("CONFIG", "Unsupported study operation");
 	}
 	async #prepare(request, signal) {
-		const directory = resolveStudyPath(join(this.#root, "studies"), request.target);
-		const definition = parseStudyDefinition(decodeStudyJSON(await readStudyBytes(resolveStudyPath(directory, "study.json"), STUDY_CUSTODY_BYTES)));
-		if (definition.name !== request.target) throw new StudyError("CONFIG", "Study name differs from its selected directory");
-		const bundle = resolveStudyPath(join(this.#root, "studies"), definition.driver);
-		const steps = [];
-		for (const id of definition.scenarios) {
-			signal.throwIfAborted();
-			const path = `scenarios/${id}.json`;
-			const bytes = await readStudyBytes(resolveStudyPath(bundle, path), STUDY_CUSTODY_BYTES);
-			const scenario = parseStudyScenario(decodeStudyJSON(bytes));
-			if (scenario.id !== id) throw new StudyError("CONFIG", "Scenario identity is incompatible");
-			steps.push({
-				scenario,
-				fixture: {
-					path,
-					digest: hashStudyBytes(bytes)
-				}
-			});
-		}
-		const scenarios = steps.map((step) => step.scenario);
-		const fixtures = steps.map((step) => step.fixture);
-		const profileBytes = await readStudyBytes(resolveStudyPath(bundle, `profiles/${request.profile}.json`), STUDY_CUSTODY_BYTES);
+		const { bundle, definition, scenarios, fixtures, rubric } = await readStudyDeclaration(this.#root, request.target, signal);
+		const profileBytes = await readStudyDeclarationBytes(this.#root, resolveStudyPath(bundle, `profiles/${request.profile}.json`));
 		const source = parseStudyProfile(decodeStudyJSON(profileBytes));
 		if (source.name !== request.profile) throw new StudyError("CONFIG", "Profile name differs from its selected file");
 		if (source.bounds.series.duration > 864e5) throw new StudyError("CONFIG", "Series duration exceeds the 24-hour host ceiling");
 		const profile = resolveStudyProfile(this.#root, source);
-		const rubric = parseStudyRubric(decodeStudyJSON(await readStudyBytes(resolveStudyPath(directory, definition.rubric), STUDY_CUSTODY_BYTES)));
 		validateStudyInputs(definition, scenarios, rubric, profile);
-		if (definition.purpose === "quality" && profile.qualification === void 0) throw new StudyError("CONFIG", "Quality studies require a capacity qualification");
 		signal.throwIfAborted();
 		const artifacts = new StudyArtifactLoader({
 			root: this.#root,
@@ -4685,7 +3057,7 @@ var StudyCommand = class {
 		if (validation.value !== true || validation.instrument !== selected.instrument) throw new StudyError("FAULT", "Adapter validation identity differs");
 		artifacts.verify();
 		return {
-			directory: bundle,
+			bundle,
 			definition,
 			scenarios: Object.freeze(scenarios),
 			rubric,
@@ -4757,17 +3129,18 @@ var StudyCommand = class {
 		await store.create();
 		const scratch = await mkdtemp(join(parent, "scratch-"));
 		try {
+			const driver = new StudyProcessDriver({
+				root: this.#root,
+				entry: this.#entry,
+				profile: preparation.profile,
+				identity: preparation.identity,
+				driver: preparation.definition.driver,
+				adapter: join(preparation.bundle, "index.ts"),
+				directory: scratch
+			});
 			const attempts = await new StudySeries({
 				manifest,
-				driver: new StudyProcessDriver({
-					root: this.#root,
-					entry: this.#entry,
-					profile: preparation.profile,
-					identity: preparation.identity,
-					driver: preparation.definition.driver,
-					adapter: join(preparation.directory, "index.ts"),
-					directory: scratch
-				}),
+				driver,
 				store,
 				signal
 			}).execute();
@@ -4915,14 +3288,17 @@ var StudyCommand = class {
 		});
 	}
 	async #result(target) {
-		const result = await readStudyResult(isAbsolute(target) ? resolve(target) : target.includes("/") ? resolveStudyPath(this.#root, target) : resolveStudyPath(join(this.#root, "tmp", "studies"), target));
+		const result = await readStudyResult(isAbsolute(target) ? resolve(target) : target.includes("/") ? resolveStudyPath(this.#root, target) : resolveStudyPath(join(this.#root, "tmp", "studies"), target)).catch((error) => {
+			if (matchesSystemError(error, "ENOENT")) throw new StudyError("CUSTODY", `Selected result is missing: ${target}`);
+			throw error;
+		});
 		if (result.status !== "sealed") throw new StudyError("CUSTODY", "Interrupted execution cannot be graded or reported");
 		return result;
 	}
 	async #grading(result, id) {
 		const directory = join(result.directory, "grades", id);
 		const raw = await readStudyBytes(join(directory, "grading.json"), STUDY_CUSTODY_BYTES).catch((error) => {
-			if (error instanceof Error && "code" in error && error.code === "ENOENT") throw new StudyError("CUSTODY", `Selected grading is missing: ${join(directory, "grading.json")}`);
+			if (matchesSystemError(error, "ENOENT")) throw new StudyError("CUSTODY", `Selected grading is missing: ${join(directory, "grading.json")}`);
 			throw error;
 		});
 		if (hashStudyBytes(raw) !== id) throw new StudyError("CUSTODY", "Selected grading differs from its byte identity");
@@ -4957,7 +3333,7 @@ var StudyCommand = class {
 			try {
 				await mkdir(directory);
 			} catch (error) {
-				if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+				if (!matchesSystemError(error, "EEXIST")) throw error;
 			}
 			return checkStudyDirectory(directory);
 		}, checkStudyDirectory(this.#root));
@@ -4969,7 +3345,10 @@ var StudyCommand = class {
 		return result.seal.id;
 	}
 	async #instrument() {
-		return hashStudyBytes(await readStudyBytes(this.#entry, STUDY_CUSTODY_BYTES));
+		return computeStudyInstrumentDigest(hashStudyBytes(await readStudyBytes(this.#entry, STUDY_CUSTODY_BYTES)), new ArtifactLoader({
+			entries: [this.#entry],
+			roots: [resolveStudyInstrument(this.#entry)]
+		}).inspect().digest);
 	}
 };
 //#endregion
@@ -5520,6 +3899,10 @@ var StudyCLI = class {
 					process.stdout.write(STUDY_COMMAND_HELP);
 					return 0;
 				}
+				if (arguments_.length === 1 && arguments_[0] === "--version") {
+					process.stdout.write(`${readStudyVersion(this.#options.entry)}\n`);
+					return 0;
+				}
 				if (arguments_.length === 0) {
 					process.stderr.write(STUDY_COMMAND_HELP);
 					return 64;
@@ -5548,6 +3931,98 @@ var StudyCLI = class {
 //#endregion
 //#region src/server/agents/helpers.ts
 /**
+* Reads an Agent tool call into a validated envelope from one read of each foreign field.
+* @remarks The returned envelope owns its fields; arguments retain their original record identity.
+* JSON validation and copying belong to the executed-result projection.
+* @param call - The call received from the admitted Agent
+* @returns A fresh ToolCall envelope with the original arguments record
+* @throws StudyError - Thrown with code `FAULT` when a field cannot be read or the envelope is malformed
+* @example Read an Agent tool call
+* ```ts
+* import { readStudyAgentToolCall } from '@orkestrel/study/server'
+*
+* const call = readStudyAgentToolCall({ id: 'c1', name: 'write', arguments: { path: 'note.txt' } })
+* // { id: 'c1', name: 'write', arguments: { path: 'note.txt' } }
+* ```
+*/
+function readStudyAgentToolCall(call) {
+	const observed = attempt(() => isRecord(call) ? {
+		id: "id" in call ? call.id : void 0,
+		name: "name" in call ? call.name : void 0,
+		arguments: "arguments" in call ? call.arguments : void 0
+	} : void 0);
+	if (!observed.success || !isToolCall(observed.value)) throw new StudyError("FAULT", "Admitted Agent supplied invalid tool observation");
+	return observed.value;
+}
+/**
+* Builds the JSON evidence form of an Agent tool call and its executed result.
+* @param call - The call received from the admitted Agent
+* @param result - The executed tool result
+* @returns The call identity, owned arguments, success, and owned value or error text
+* @throws StudyError - Thrown with code `FAULT` when the call, result, arguments, or value is malformed
+* @example
+* ```ts
+* buildStudyAgentToolResult(call, { success: true, value: 'stored' })
+* ```
+*/
+function buildStudyAgentToolResult(call, result) {
+	const { id, name, arguments: arguments_ } = readStudyAgentToolCall(call);
+	const returned = attempt(() => {
+		if (!isObject(result)) return void 0;
+		const success = "success" in result ? result.success : void 0;
+		if (typeof success !== "boolean") return void 0;
+		return success ? {
+			success,
+			value: "value" in result ? result.value : void 0
+		} : {
+			success,
+			error: "error" in result ? result.error : void 0
+		};
+	});
+	if (!returned.success || returned.value === void 0) throw new StudyError("FAULT", "Admitted Agent supplied invalid tool result");
+	const argumentsCopy = attempt(() => cloneJSONValue(arguments_));
+	if (!argumentsCopy.success) throw new StudyError("FAULT", "Admitted Agent supplied non-JSON tool arguments");
+	const outcome = returned.value;
+	if (outcome.success) {
+		const valueCopy = attempt(() => cloneJSONValue(outcome.value));
+		if (!valueCopy.success) throw new StudyError("FAULT", "Admitted Agent supplied non-JSON tool value");
+		return {
+			id,
+			name,
+			arguments: argumentsCopy.value,
+			success: true,
+			value: valueCopy.value
+		};
+	}
+	if (typeof outcome.error !== "string") throw new StudyError("FAULT", "Admitted Agent supplied invalid tool error");
+	return {
+		id,
+		name,
+		arguments: argumentsCopy.value,
+		success: false,
+		error: outcome.error
+	};
+}
+/**
+* Builds the JSON evidence form of an Agent tool call the Agent denied before dispatch.
+* @param call - The call received from the admitted Agent
+* @param reason - The denial reason, retained only when it is a string
+* @returns The call identity with the optional string reason
+* @throws StudyError - Thrown with code `FAULT` when the call is malformed
+* @example
+* ```ts
+* buildStudyAgentToolDenial(call, 'refused')
+* ```
+*/
+function buildStudyAgentToolDenial(call, reason) {
+	const { id, name } = readStudyAgentToolCall(call);
+	return {
+		id,
+		name,
+		...typeof reason === "string" ? { reason } : {}
+	};
+}
+/**
 * Builds a request revision by hashing its canonical rendering exactly as rendered.
 * @remarks
 * The request is rendered once with key-sorted canonical JSON and hashed as rendered; no
@@ -5650,94 +4125,6 @@ function isStudyAgentResponse(value) {
 	]) && typeof value.content === "string" && isArray(value.calls) && value.calls.every(isToolCall) && isJSONValue(value.calls) && (value.consume === void 0 || typeof value.consume === "string" && value.consume.length > 0) && (value.abort === void 0 || typeof value.abort === "boolean") && (value.truncated === void 0 || typeof value.truncated === "boolean") && ["tokens", "bytes"].every((key) => value[key] === void 0 || typeof value[key] === "number" && Number.isSafeInteger(value[key]) && value[key] >= 0));
 }
 //#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)
-		}
-	});
-}
-/**
-* 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/server/agents/StudyAgentTraceGoal.ts
 /** Holds one goal's retained trace rows, its latest admission and its last refused identity. */
 var StudyAgentTraceGoal = class {
@@ -5966,15 +4353,16 @@ var StudyAgentSummary = class {
 	constructor(options) {
 		const { limit } = options;
 		const { scale, overhead } = options.gauge;
+		const gauge = {
+			scale,
+			overhead
+		};
 		if (!Number.isSafeInteger(limit) || limit <= 0) throw new StudyError("CONFIG", "Summary limit must be a positive safe integer");
-		if (!isFiniteNumber(scale) || scale <= 0 || !isFiniteNumber(overhead) || overhead < 0) throw new StudyError("CONFIG", "Summary gauge scale must be finite and positive and its overhead finite and nonnegative");
+		if (!isStudyAgentGauge(gauge)) throw new StudyError("CONFIG", "Summary gauge scale must be finite and positive and its overhead finite and nonnegative");
 		this.#options = {
 			...options,
 			limit,
-			gauge: {
-				scale,
-				overhead
-			}
+			gauge
 		};
 	}
 	/** Measures one canonical request, refuses it at the limit, and sends the very same array to the provider.
@@ -7276,6 +5664,6 @@ var StudyOllamaTransport = class {
 	}
 };
 //#endregion
-export { ARTIFACT_BYTES, ARTIFACT_DEPTH, ARTIFACT_FILES, ARTIFACT_FILE_BYTES, ARTIFACT_ROOTS, ARTIFACT_VISITS, ArtifactError, ArtifactLoader, Resolution, STUDY_COMMAND_DURATION, STUDY_COMMAND_GRADER, STUDY_COMMAND_HELP, STUDY_COMMAND_OPERATION, STUDY_CUSTODY_BYTES, STUDY_DRAIN_DURATION, STUDY_FRAME_BYTES, STUDY_LAUNCH_BYTES, STUDY_LAUNCH_CLEANUP, STUDY_LAUNCH_DURATION, STUDY_LOG_BYTES, STUDY_PACKET_DISCLOSURE, STUDY_PENDING_LIMIT, STUDY_PROCESS_LABEL, STUDY_RESERVED_NAME, STUDY_TASK_DURATION, STUDY_TASK_OPERATION, STUDY_WORKER_OPERATION, StudyAgentScript, StudyAgentSummary, StudyAgentTrace, StudyArtifactLoader, StudyCLI, StudyChannel, StudyCommand, StudyEvidenceSink, StudyGradingStore, StudyLauncher, StudyOllamaTransport, StudyProcessDriver, StudyProcessGoal, StudyProcessSession, StudyRemoteMeter, StudyRemoteTicket, StudyResultStore, StudyTask, StudyTaskWorker, StudyWorker, buildStudyAgentReadings, buildStudyAgentRevision, buildStudyOllamaModels, buildStudyOllamaOptions, buildStudyOllamaRaw, buildStudyOllamaSnapshot, buildStudyOllamaTiming, buildStudyOllamaTransportOptions, buildStudyPacket, buildStudyPacketLinks, buildStudyReference, checkStudyDirectory, collectStudyAncestors, collectStudyEntries, collectStudyEvidence, computeStudyAttributions, computeStudyCommandFingerprint, computeStudyFixtureDigest, computeStudyInstrumentDigest, computeStudyPacketDigest, computeStudyPartition, computeStudyProfileDigest, computeStudyReport, computeStudySealId, containsArtifact, createStudyProcessFailure, decodeStudyJSON, drainStudyChild, encodeStudyJSON, gradeStudyEvidence, hashStudyBytes, isArtifactError, isStudyAdapter, isStudyAgentResponse, isStudyCharge, isStudyCustodyAttempt, isStudyCustodyEvidence, isStudyCustodyFailure, isStudyCustodyFile, isStudyCustodyManifest, isStudyCustodyName, isStudyCustodyObservation, isStudyCustodySeal, isStudyCustodyTrial, isStudyEvidence, isStudyFrame, isStudyIdentity, isStudyProcessFailure, isStudyTrial, iterateArtifactEntries, parseStudyArguments, readArtifact, readArtifactBytes, readStudyAdapter, readStudyAgentMessages, readStudyAgentResult, readStudyBytes, readStudyHandle, readStudyOllamaDigest, readStudyOllamaFailure, readStudyOllamaRequest, readStudyOllamaSupport, readStudyOllamaTerminal, readStudyOllamaTiming, readStudyResult, resolveStudyAgentContent, resolveStudyInstrument, resolveStudyPath, resolveStudyProfile, scanStudyExecution, scanStudyTree, terminateStudyChild, translateStudyPacketLabeling, validateStudyEvidenceBytes, validateStudyOllamaCompletion, validateStudyOllamaInventory, validateStudyOllamaRoles, validateStudyRuntime, valueToWire, writeStudyBytes };
+export { ARTIFACT_BYTES, ARTIFACT_DEPTH, ARTIFACT_FILES, ARTIFACT_FILE_BYTES, ARTIFACT_ROOTS, ARTIFACT_VISITS, ArtifactError, ArtifactLoader, Resolution, STUDY_COMMAND_DURATION, STUDY_COMMAND_GRADER, STUDY_COMMAND_HELP, STUDY_COMMAND_OPERATION, STUDY_CUSTODY_BYTES, STUDY_DRAIN_DURATION, STUDY_FRAME_BYTES, STUDY_LAUNCH_BYTES, STUDY_LAUNCH_CLEANUP, STUDY_LAUNCH_DURATION, STUDY_LOG_BYTES, STUDY_PACKET_DISCLOSURE, STUDY_PENDING_LIMIT, STUDY_PROCESS_LABEL, STUDY_RESERVED_NAME, STUDY_TASK_DURATION, STUDY_TASK_OPERATION, STUDY_WORKER_OPERATION, StudyAgentScript, StudyAgentSummary, StudyAgentTrace, StudyArtifactLoader, StudyCLI, StudyChannel, StudyCommand, StudyEvidenceSink, StudyGradingStore, StudyLauncher, StudyOllamaTransport, StudyProcessDriver, StudyProcessGoal, StudyProcessSession, StudyRemoteMeter, StudyRemoteTicket, StudyResultStore, StudyTask, StudyTaskWorker, StudyWorker, buildStudyAgentReadings, buildStudyAgentRevision, buildStudyAgentToolDenial, buildStudyAgentToolResult, buildStudyOllamaModels, buildStudyOllamaOptions, buildStudyOllamaRaw, buildStudyOllamaSnapshot, buildStudyOllamaTiming, buildStudyOllamaTransportOptions, buildStudyPacket, buildStudyPacketLinks, buildStudyReference, checkStudyDirectory, collectStudyAncestors, collectStudyEntries, collectStudyEvidence, computeStudyAttributions, computeStudyCommandFingerprint, computeStudyFixtureDigest, computeStudyInstrumentDigest, computeStudyPacketDigest, computeStudyPartition, computeStudyProfileDigest, computeStudyReport, computeStudySealId, containsArtifact, createStudyProcessFailure, decodeStudyJSON, drainStudyChild, encodeStudyJSON, gradeStudyEvidence, hashStudyBytes, isArtifactError, isStudyAdapter, isStudyAgentResponse, isStudyCharge, isStudyCustodyAttempt, isStudyCustodyEvidence, isStudyCustodyFailure, isStudyCustodyFile, isStudyCustodyManifest, isStudyCustodyName, isStudyCustodyObservation, isStudyCustodySeal, isStudyCustodyTrial, isStudyEvidence, isStudyFrame, isStudyIdentity, isStudyProcessFailure, isStudyTrial, iterateArtifactEntries, matchesSystemError, parseStudyArguments, readArtifact, readArtifactBytes, readStudyAdapter, readStudyAgentMessages, readStudyAgentResult, readStudyAgentToolCall, readStudyBytes, readStudyDeclaration, readStudyDeclarationBytes, readStudyHandle, readStudyOllamaDigest, readStudyOllamaFailure, readStudyOllamaRequest, readStudyOllamaSupport, readStudyOllamaTerminal, readStudyOllamaTiming, readStudyResult, readStudyVersion, resolveStudyAgentContent, resolveStudyInstrument, resolveStudyPath, resolveStudyProfile, scanStudyExecution, scanStudyTree, terminateStudyChild, translateStudyPacketLabeling, validateStudyEvidenceBytes, validateStudyOllamaCompletion, validateStudyOllamaInventory, validateStudyOllamaRoles, validateStudyRuntime, valueToWire, writeStudyBytes };
 
 //# sourceMappingURL=index.js.map