@orkestrel/study 0.0.1 → 0.0.2

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

@@ -112,6 +112,17 @@ export declare function failStudyTicket(ticket: StudyTicket, error: unknown, rol
  */
 export declare function failureToStudyError(failure: StudyFailure): StudyError;
 
+/**
+ * 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
+ * ```
+ */
+export declare function isStudyAgentGauge(value: unknown): value is LedgerGauge;
+
 /**
  * Checks whether a namespace exposes the Agent capabilities the instrumentation invokes.
  * @remarks
@@ -170,10 +181,11 @@ export declare function isStudyDefinition(value: unknown): value is StudyDefinit
 export declare function isStudyDigest(value: unknown): value is string;
 
 /**
- * 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
  * stores the target, and an unbranded copy, an inherited brand, or a property-only lookalike
@@ -1308,7 +1320,7 @@ export declare function validateStudyAgentUsage(usage: ProviderResult['usage'],
  * @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)

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

@@ -112,6 +112,17 @@ export declare function failStudyTicket(ticket: StudyTicket, error: unknown, rol
  */
 export declare function failureToStudyError(failure: StudyFailure): StudyError;
 
+/**
+ * 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
+ * ```
+ */
+export declare function isStudyAgentGauge(value: unknown): value is LedgerGauge;
+
 /**
  * Checks whether a namespace exposes the Agent capabilities the instrumentation invokes.
  * @remarks
@@ -170,10 +181,11 @@ export declare function isStudyDefinition(value: unknown): value is StudyDefinit
 export declare function isStudyDigest(value: unknown): value is string;
 
 /**
- * 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
  * stores the target, and an unbranded copy, an inherited brand, or a property-only lookalike
@@ -1308,7 +1320,7 @@ export declare function validateStudyAgentUsage(usage: ProviderResult['usage'],
  * @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)

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { attempt, canonicalStringify, cloneJSONValue, holds, isArray, isError, isFiniteNumber, isJSONValue, isNonEmptyString, isObject, isRecord, literalOf } from "@orkestrel/contract";
+import { INTRINSICS, attempt, canonicalStringify, cloneJSONValue, holds, isArray, isError, isFiniteNumber, isJSONValue, isNonEmptyString, isObject, isRecord, literalOf } from "@orkestrel/contract";
 import { MAX_TIMEOUT_MS, Timeout } from "@orkestrel/timeout";
 import { Budget, isBudgetError } from "@orkestrel/budget";
 import { Abort, linkSignal } from "@orkestrel/abort";
@@ -149,7 +149,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)
@@ -166,6 +166,7 @@ function validateStudyInputs(definition, scenarios, rubric, profile) {
 	}
 	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");
+	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.
@@ -630,8 +631,10 @@ var StudyError = class extends Error {
 	*/
 	constructor(code, message, failure) {
 		super(message);
-		Object.defineProperty(this, STUDY_ERROR_BRAND, {
+		INTRINSICS.define(this, STUDY_ERROR_BRAND, {
 			value: this,
+			enumerable: false,
+			writable: false,
 			configurable: true
 		});
 		this.name = "StudyError";
@@ -640,10 +643,11 @@ 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
 * stores the target, and an unbranded copy, an inherited brand, or a property-only lookalike
@@ -656,7 +660,27 @@ var StudyError = class extends Error {
 * ```
 */
 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));
+	return holds(() => {
+		if (!isError(value) || INTRINSICS.prototype(value) === INTRINSICS.error.prototype) return false;
+		const brand = INTRINSICS.describe(value, STUDY_ERROR_BRAND)?.value;
+		const code = INTRINSICS.reflect.read(value, "code");
+		const failure = INTRINSICS.reflect.read(value, "failure");
+		if (brand !== value || !isStudyErrorCode(code) || typeof INTRINSICS.reflect.read(value, "name") !== "string" || typeof INTRINSICS.reflect.read(value, "message") !== "string") return false;
+		if (failure === void 0) return true;
+		if (!isObject(failure)) return false;
+		const cause = INTRINSICS.reflect.read(failure, "cause");
+		const message = INTRINSICS.reflect.read(failure, "message");
+		const role = INTRINSICS.reflect.read(failure, "role");
+		const stop = 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 (!isObject(stop)) return false;
+		const layer = INTRINSICS.reflect.read(stop, "layer");
+		const id = INTRINSICS.reflect.read(stop, "id");
+		const max = INTRINSICS.reflect.read(stop, "max");
+		const consumed = INTRINSICS.reflect.read(stop, "consumed");
+		return isStudyLayer(layer) && typeof id === "string" && (max === void 0 || isFiniteNumber(max)) && (consumed === void 0 || isFiniteNumber(consumed));
+	});
 }
 //#endregion
 //#region src/core/parsers.ts
@@ -1876,6 +1900,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 holds(() => {
+		if (!isObject(value) || !("scale" in value) || !("overhead" in value)) return false;
+		const { scale, overhead } = value;
+		return isFiniteNumber(scale) && scale > 0 && 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
@@ -1995,6 +2035,6 @@ var StudyAgentJudge = class {
 	}
 };
 //#endregion
-export { STUDY_CAUSES, STUDY_ERROR_BRAND, STUDY_GOALS, STUDY_LAYERS, STUDY_NAME, STUDY_ROLES, STUDY_TRIALS, StudyAgentJudge, StudyAgentObserver, StudyControl, StudyDeadline, StudyError, StudyMeter, StudyRequest, StudyScope, StudySeries, buildStudyAgentDispatch, buildStudyAgentParts, buildStudySchedule, computeStudyAdmittedStop, computeStudyOutputStop, computeStudyScores, failStudyTicket, failureToStudyError, isStudyAgentRuntime, isStudyBounds, isStudyCause, isStudyCriterion, isStudyDefinition, isStudyDigest, isStudyError, isStudyErrorCode, isStudyGoal, isStudyGrading, isStudyJudgment, isStudyLabeling, isStudyLayer, isStudyLimit, isStudyName, isStudyProduct, isStudyProfile, isStudyProvider, isStudyRole, isStudyRoom, isStudyRubric, isStudyScenario, isStudyStop, isStudyTimestamp, isStudyUsage, matchesStudyKeys, normalizeStudyProfile, omitStudyAbsent, parseStudyDefinition, parseStudyGrading, parseStudyLabeling, parseStudyProfile, parseStudyReading, parseStudyRubric, parseStudyScenario, projectStudyAgentRequest, readStudyFailure, studyStopToJSON, translateStudyAgentError, translateStudyAgentStop, validateStudyAgentUsage, validateStudyInputs };
+export { STUDY_CAUSES, STUDY_ERROR_BRAND, STUDY_GOALS, STUDY_LAYERS, STUDY_NAME, STUDY_ROLES, STUDY_TRIALS, StudyAgentJudge, StudyAgentObserver, StudyControl, StudyDeadline, StudyError, StudyMeter, StudyRequest, StudyScope, StudySeries, buildStudyAgentDispatch, buildStudyAgentParts, buildStudySchedule, computeStudyAdmittedStop, computeStudyOutputStop, computeStudyScores, failStudyTicket, failureToStudyError, isStudyAgentGauge, isStudyAgentRuntime, isStudyBounds, isStudyCause, isStudyCriterion, isStudyDefinition, isStudyDigest, isStudyError, isStudyErrorCode, isStudyGoal, isStudyGrading, isStudyJudgment, isStudyLabeling, isStudyLayer, isStudyLimit, isStudyName, isStudyProduct, isStudyProfile, isStudyProvider, isStudyRole, isStudyRoom, isStudyRubric, isStudyScenario, isStudyStop, isStudyTimestamp, isStudyUsage, matchesStudyKeys, normalizeStudyProfile, omitStudyAbsent, parseStudyDefinition, parseStudyGrading, parseStudyLabeling, parseStudyProfile, parseStudyReading, parseStudyRubric, parseStudyScenario, projectStudyAgentRequest, readStudyFailure, studyStopToJSON, translateStudyAgentError, translateStudyAgentStop, validateStudyAgentUsage, validateStudyInputs };
 
 //# sourceMappingURL=index.js.map