@orkestrel/study 0.0.1 → 0.0.3

package/dist/src/core/index.cjs

@@ -8,8 +8,8 @@ let _orkestrel_abort = require("@orkestrel/abort");
 * 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.
+* key. The registry makes the key discoverable; it recognizes the contract without proving
+* its origin.
 */
 var STUDY_ERROR_BRAND = Symbol.for("@orkestrel/study.error");
 /** Caps a declared trial population before schedule allocation. */
@@ -24,6 +24,7 @@ var STUDY_ROLES = Object.freeze([
 	"judge",
 	"summary",
 	"metadata",
+	"maintenance",
 	"tool"
 ]);
 /** Lists every ceiling a run can stop at in report order. */
@@ -67,16 +68,18 @@ function omitStudyAbsent(value) {
 * ```
 */
 function normalizeStudyProfile(profile) {
-	const { provider, qualification, settings, room, ...required } = profile;
+	const { provider, qualification, settings, record, room, ...required } = profile;
 	return {
 		...required,
 		room: omitStudyAbsent(room),
 		...provider === void 0 ? {} : { provider: {
 			...omitStudyAbsent(provider),
-			digest: omitStudyAbsent(provider.digest)
+			digest: omitStudyAbsent(provider.digest),
+			...provider.daemon === void 0 ? {} : { daemon: omitStudyAbsent(provider.daemon) }
 		} },
 		...qualification === void 0 ? {} : { qualification },
-		...settings === void 0 ? {} : { settings }
+		...settings === void 0 ? {} : { settings },
+		...record === void 0 ? {} : { record }
 	};
 }
 /**
@@ -150,7 +153,7 @@ function buildStudySchedule(definition, scenarios) {
 * @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
+* @throws StudyError - Thrown when any input or cross-reference is invalid, or a quality study has no capacity qualification
 * @example
 * ```ts
 * validateStudyInputs(definition, scenarios, rubric, profile)
@@ -167,6 +170,7 @@ function validateStudyInputs(definition, scenarios, rubric, profile) {
 	}
 	const covered = new Set(rubric.criteria.map((criterion) => (0, _orkestrel_contract.canonicalStringify)([criterion.scenario, criterion.goal]) ?? ""));
 	for (const scenario of scenarios) for (const goal of scenario.goals) if (!covered.has((0, _orkestrel_contract.canonicalStringify)([scenario.id, goal.id]) ?? "")) throw new StudyError("CONFIG", "Every declared goal needs a criterion");
+	if (definition.purpose === "quality" && profile.qualification === void 0) throw new StudyError("CONFIG", "Quality studies require a capacity qualification");
 }
 /**
 * Computes arm intervals over the complete declared criterion horizon.
@@ -417,15 +421,46 @@ function isStudyProvider(value) {
 			"url",
 			"model",
 			"digest"
-		], ["judge"]) || ![
+		], ["judge", "daemon"]) || ![
 			"entry",
 			"url",
 			"model"
 		].every((key) => (0, _orkestrel_contract.isNonEmptyString)(value[key])) || typeof value.url !== "string" || !(0, _orkestrel_contract.isRecord)(value.digest) || !matchesStudyKeys(value.digest, ["model"], ["judge"]) || !isStudyDigest(value.digest.model) || value.judge === void 0 !== (value.digest.judge === void 0) || value.judge !== void 0 && (!(0, _orkestrel_contract.isNonEmptyString)(value.judge) || !isStudyDigest(value.digest.judge))) return false;
 		const url = new URL(value.url);
+		if (value.daemon !== void 0) {
+			if (!isStudyDaemon(value.daemon) || !/^http:\/\/127\.0\.0\.1:[0-9]+\/?$/.test(value.url) || Number(url.port) <= 0 || Number(url.port) === 11434) return false;
+			const daemon = value.daemon;
+			const digest = value.digest;
+			if (!daemon.models.every((model) => model.name === value.model && model.digest === digest.model || value.judge !== void 0 && model.name === value.judge && model.digest === digest.judge) || !daemon.models.some((model) => model.name === value.model && model.digest === digest.model) || value.judge !== void 0 && !daemon.models.some((model) => model.name === value.judge && model.digest === digest.judge)) return false;
+		}
 		return ["http:", "https:"].includes(url.protocol) && url.username === "" && url.password === "" && url.search === "" && url.hash === "" && url.pathname === "/";
 	});
 }
+/** Checks whether an owned daemon declaration pins an absolute executable and distinct models.
+* @param value - The candidate declaration.
+* @returns True if executable, version, environment, and model identities are valid; false otherwise.
+* @example
+* ```ts
+* isStudyDaemon({ executable: 'ollama' }) // false
+* ```
+*/
+function isStudyDaemon(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value) || !matchesStudyKeys(value, [
+			"executable",
+			"digest",
+			"version",
+			"models"
+		], ["environment"]) || typeof value.executable !== "string" || !/^(?:[A-Za-z]:[\\/]|\/(?!\/)|\\\\[^\\]+\\[^\\]+\\)/.test(value.executable) || value.executable.includes("\0") || value.executable.split(/[\\/]/).some((part) => part === "." || part === "..") || !isStudyDigest(value.digest) || !(0, _orkestrel_contract.isNonEmptyString)(value.version) || value.version.trim().length === 0 || value.version.includes("\0") || !(0, _orkestrel_contract.isArray)(value.models) || value.models.length === 0 || !value.models.every((model) => (0, _orkestrel_contract.isRecord)(model) && matchesStudyKeys(model, ["name", "digest"]) && (0, _orkestrel_contract.isNonEmptyString)(model.name) && model.name.trim().length > 0 && !model.name.includes("\0") && isStudyDigest(model.digest))) return false;
+		if (new Set(value.models.map((model) => (0, _orkestrel_contract.isRecord)(model) ? model.name : void 0)).size !== value.models.length) return false;
+		if (value.environment !== void 0) {
+			if (!(0, _orkestrel_contract.isRecord)(value.environment) || !matchesStudyKeys(value.environment, [], Object.keys(value.environment))) return false;
+			const entries = Object.entries(value.environment);
+			if (new Set(entries.map(([name]) => name.toLowerCase())).size !== entries.length || entries.some(([name, entry]) => name.length === 0 || /[=\0]/.test(name) || typeof entry !== "string" || entry.includes("\0"))) return false;
+		}
+		return true;
+	});
+}
 /**
 * Checks whether a profile carries finite bounds and an optional explicit provider.
 * @param value - The candidate profile
@@ -447,10 +482,18 @@ function isStudyProfile(value) {
 		], [
 			"provider",
 			"qualification",
-			"settings"
-		]) && isStudyName(value.name) && (0, _orkestrel_contract.isNonEmptyString)(value.agent) && (0, _orkestrel_contract.isArray)(value.roots) && (0, _orkestrel_contract.isJSONValue)(value.roots) && value.roots.length > 0 && value.roots.every((root) => typeof root === "string" && root.trim().length > 0) && new Set(value.roots).size === value.roots.length && (0, _orkestrel_contract.isNonEmptyString)(value.subject) && isStudyBounds(value.bounds) && isStudyRoom(value.room) && (value.provider === void 0 || isStudyProvider(value.provider)) && (value.qualification === void 0 || (0, _orkestrel_contract.isNonEmptyString)(value.qualification)) && (value.settings === void 0 || (0, _orkestrel_contract.isRecord)(value.settings) && (0, _orkestrel_contract.isJSONValue)(value.settings));
+			"settings",
+			"record"
+		]) && isStudyName(value.name) && (0, _orkestrel_contract.isNonEmptyString)(value.agent) && (0, _orkestrel_contract.isArray)(value.roots) && (0, _orkestrel_contract.isJSONValue)(value.roots) && value.roots.length > 0 && value.roots.every((root) => typeof root === "string" && root.trim().length > 0) && new Set(value.roots).size === value.roots.length && (0, _orkestrel_contract.isNonEmptyString)(value.subject) && isStudyBounds(value.bounds) && isStudyRoom(value.room) && (value.provider === void 0 || isStudyProvider(value.provider)) && (value.record === void 0 || isStudyRecord(value.record)) && (value.qualification === void 0 || (0, _orkestrel_contract.isNonEmptyString)(value.qualification)) && (value.settings === void 0 || (0, _orkestrel_contract.isRecord)(value.settings) && (0, _orkestrel_contract.isJSONValue)(value.settings));
 	});
 }
+/** Checks whether a recording declaration bounds every serialized sidecar byte.
+* @param value - The candidate declaration.
+* @returns True if its byte allowance is a positive safe integer; false otherwise.
+*/
+function isStudyRecord(value) {
+	return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isRecord)(value) && matchesStudyKeys(value, ["bytes"]) && typeof value.bytes === "number" && Number.isSafeInteger(value.bytes) && value.bytes > 0);
+}
 /**
 * Checks whether a byte identity is a lowercase SHA-256 digest.
 * @param value - The candidate identity
@@ -631,8 +674,10 @@ var StudyError = class extends Error {
 	*/
 	constructor(code, message, failure) {
 		super(message);
-		Object.defineProperty(this, STUDY_ERROR_BRAND, {
+		_orkestrel_contract.INTRINSICS.define(this, STUDY_ERROR_BRAND, {
 			value: this,
+			enumerable: false,
+			writable: false,
 			configurable: true
 		});
 		this.name = "StudyError";
@@ -641,14 +686,15 @@ var StudyError = class extends Error {
 	}
 };
 /**
-* Narrows a caught value to an attributable study error.
+* Narrows a caught value to a branded study error with valid failure attribution.
 * @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.
+* Recognition combines the native `Error` base, a subclass prototype, a declared study code,
+* valid optional failure members, and an own {@link STUDY_ERROR_BRAND} descriptor whose value is
+* the error itself. Subclasses can replace the name.
 * The global key is recognized across package, ESM, CommonJS and captured module copies; it is
-* not unforgeable provenance. A transparent proxy is refused because its forwarded descriptor
+* not proof of origin. 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.
+* stays outside the type. Throwing property access returns false instead of throwing.
 * @param value - The caught value
 * @returns True if the value is a study error; false otherwise
 * @example
@@ -657,7 +703,28 @@ var StudyError = class extends Error {
 * ```
 */
 function isStudyError(value) {
-	return (0, _orkestrel_contract.isError)(value) && (0, _orkestrel_contract.holds)(() => Object.getPrototypeOf(value) !== Error.prototype && value.name === "StudyError" && Object.getOwnPropertyDescriptor(value, STUDY_ERROR_BRAND)?.value === value && "code" in value && isStudyErrorCode(value.code));
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(value instanceof _orkestrel_contract.INTRINSICS.error) || _orkestrel_contract.INTRINSICS.prototype(value) === _orkestrel_contract.INTRINSICS.error.prototype) return false;
+		const brand = _orkestrel_contract.INTRINSICS.describe(value, STUDY_ERROR_BRAND)?.value;
+		const code = _orkestrel_contract.INTRINSICS.reflect.read(value, "code");
+		const failure = _orkestrel_contract.INTRINSICS.reflect.read(value, "failure");
+		const stack = _orkestrel_contract.INTRINSICS.reflect.read(value, "stack");
+		if (brand !== value || !isStudyErrorCode(code) || typeof _orkestrel_contract.INTRINSICS.reflect.read(value, "name") !== "string" || typeof _orkestrel_contract.INTRINSICS.reflect.read(value, "message") !== "string" || stack !== void 0 && typeof stack !== "string") return false;
+		if (failure === void 0) return true;
+		if (!(0, _orkestrel_contract.isObject)(failure)) return false;
+		const cause = _orkestrel_contract.INTRINSICS.reflect.read(failure, "cause");
+		const message = _orkestrel_contract.INTRINSICS.reflect.read(failure, "message");
+		const role = _orkestrel_contract.INTRINSICS.reflect.read(failure, "role");
+		const stop = _orkestrel_contract.INTRINSICS.reflect.read(failure, "stop");
+		if (!isStudyCause(cause) || typeof message !== "string" || role !== void 0 && !isStudyRole(role)) return false;
+		if (stop === void 0) return true;
+		if (!(0, _orkestrel_contract.isObject)(stop)) return false;
+		const layer = _orkestrel_contract.INTRINSICS.reflect.read(stop, "layer");
+		const id = _orkestrel_contract.INTRINSICS.reflect.read(stop, "id");
+		const max = _orkestrel_contract.INTRINSICS.reflect.read(stop, "max");
+		const consumed = _orkestrel_contract.INTRINSICS.reflect.read(stop, "consumed");
+		return isStudyLayer(layer) && typeof id === "string" && (max === void 0 || (0, _orkestrel_contract.isNumber)(max)) && (consumed === void 0 || (0, _orkestrel_contract.isNumber)(consumed));
+	});
 }
 //#endregion
 //#region src/core/parsers.ts
@@ -921,8 +988,8 @@ function computeStudyOutputStop(bytes, limit, outputs) {
 	};
 }
 /**
-* Records an error that escaped admitted work as the failure of its ticket.
-* @param ticket - The admitted request whose work escaped
+* Records an error thrown by admitted work as the failure of its ticket.
+* @param ticket - The admitted request whose work threw
 * @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
@@ -931,7 +998,7 @@ function computeStudyOutputStop(bytes, limit, outputs) {
 * 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
+* @example Fail an admitted request
 * ```ts
 * import type { StudyTicket } from '@orkestrel/study'
 * import { failStudyTicket } from '@orkestrel/study'
@@ -1877,6 +1944,22 @@ function buildStudyAgentDispatch(dispatch) {
 //#endregion
 //#region src/core/agents/validators.ts
 /**
+* Checks whether a value is a gauge with a finite positive scale and a finite nonnegative overhead.
+* @param value - The candidate gauge; additional members are admitted
+* @returns True if the gauge readings are finite and within their bounds; false otherwise
+* @example
+* ```ts
+* isStudyAgentGauge({ scale: 1, overhead: 0 }) // true
+* ```
+*/
+function isStudyAgentGauge(value) {
+	return (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isObject)(value) || !("scale" in value) || !("overhead" in value)) return false;
+		const { scale, overhead } = value;
+		return (0, _orkestrel_contract.isFiniteNumber)(scale) && scale > 0 && (0, _orkestrel_contract.isFiniteNumber)(overhead) && overhead >= 0;
+	});
+}
+/**
 * Checks whether a namespace exposes the Agent capabilities the instrumentation invokes.
 * @remarks
 * The guard reads only `estimateRequest`, `measureRequest`, and `isAgentError`, so a namespace
@@ -2020,10 +2103,12 @@ exports.computeStudyOutputStop = computeStudyOutputStop;
 exports.computeStudyScores = computeStudyScores;
 exports.failStudyTicket = failStudyTicket;
 exports.failureToStudyError = failureToStudyError;
+exports.isStudyAgentGauge = isStudyAgentGauge;
 exports.isStudyAgentRuntime = isStudyAgentRuntime;
 exports.isStudyBounds = isStudyBounds;
 exports.isStudyCause = isStudyCause;
 exports.isStudyCriterion = isStudyCriterion;
+exports.isStudyDaemon = isStudyDaemon;
 exports.isStudyDefinition = isStudyDefinition;
 exports.isStudyDigest = isStudyDigest;
 exports.isStudyError = isStudyError;
@@ -2038,6 +2123,7 @@ exports.isStudyName = isStudyName;
 exports.isStudyProduct = isStudyProduct;
 exports.isStudyProfile = isStudyProfile;
 exports.isStudyProvider = isStudyProvider;
+exports.isStudyRecord = isStudyRecord;
 exports.isStudyRole = isStudyRole;
 exports.isStudyRoom = isStudyRoom;
 exports.isStudyRubric = isStudyRubric;