@orkestrel/program 0.0.7 → 0.0.9

package/dist/src/core/index.cjs

@@ -174,6 +174,202 @@ function isProgramDefinition(value) {
 		"metadata"
 	])(value);
 }
+/**
+* Determine whether a value is an open program sums record.
+*
+* @remarks
+* Every own string-named property is checked, including non-enumerable
+* properties. Inherited and symbol-named members are outside the record this
+* guard certifies. Values remain plain JavaScript numbers, including `NaN` and
+* infinities, because the published contract does not refine them.
+*
+* @param value - The candidate value
+* @returns `true` when every own string-named value is a number
+*
+* @example
+* ```ts
+* import { isProgramSums } from '@orkestrel/program'
+*
+* isProgramSums({ premium: 100 }) // true
+* ```
+*/
+function isProgramSums(value) {
+	return (0, _orkestrel_contract.whereOf)((0, _orkestrel_contract.objectOf)({}), (record) => Object.getOwnPropertyNames(record).every((key) => (0, _orkestrel_contract.isNumber)(Reflect.get(record, key))))(value);
+}
+/**
+* Determine whether a value is an open result-side {@link Determination}.
+*
+* @remarks
+* Unknown members and class instances are admitted. Arrays are refused.
+* Optional `scope` and `message` members may be absent or `undefined`.
+*
+* @param value - The candidate value
+* @returns `true` when every published determination member conforms
+*
+* @example
+* ```ts
+* import { isDetermination } from '@orkestrel/program'
+*
+* isDetermination({ id: 'audit', effect: 'notice', applied: true, premises: [] }) // true
+* ```
+*/
+var isDetermination = (0, _orkestrel_contract.objectOf)({
+	id: _orkestrel_contract.isString,
+	effect: isProgramEffect,
+	applied: _orkestrel_contract.isBoolean,
+	scope: _orkestrel_contract.isString,
+	message: _orkestrel_contract.isString,
+	premises: (0, _orkestrel_contract.arrayOf)(_orkestrel_qualifier.isPremise)
+}, ["scope", "message"]);
+/**
+* Determine whether a value is an open result-side {@link AggregateGroup}.
+*
+* @remarks
+* Unknown members and class instances are admitted. Arrays are refused.
+*
+* @param value - The candidate value
+* @returns `true` when every published aggregate-group member conforms
+*
+* @example
+* ```ts
+* import { isAggregateGroup } from '@orkestrel/program'
+*
+* isAggregateGroup({ key: 'east', count: 1, sums: { premium: 100 } }) // true
+* ```
+*/
+var isAggregateGroup = (0, _orkestrel_contract.objectOf)({
+	key: _orkestrel_contract.isString,
+	count: _orkestrel_contract.isNumber,
+	sums: isProgramSums
+});
+/**
+* Determine whether a value is an open result-side {@link Tally}.
+*
+* @remarks
+* Unknown members and class instances are admitted. Arrays are refused.
+*
+* @param value - The candidate value
+* @returns `true` when every published tally member conforms
+*
+* @example
+* ```ts
+* import { isTally } from '@orkestrel/program'
+*
+* isTally({ count: 1, sums: { premium: 100 } }) // true
+* ```
+*/
+var isTally = (0, _orkestrel_contract.objectOf)({
+	count: _orkestrel_contract.isNumber,
+	sums: isProgramSums
+});
+/**
+* Determine whether a value is a total open status-tally record.
+*
+* @remarks
+* Every {@link Status} in {@link STATUS_PRECEDENCE} is required and checked.
+* Unknown members and class instances are admitted. Arrays are refused.
+*
+* @param value - The candidate value
+* @returns `true` when every required status member is a {@link Tally}
+*
+* @example
+* ```ts
+* import { emptyTallies, isTallies } from '@orkestrel/program'
+*
+* isTallies(emptyTallies([])) // true
+* ```
+*/
+function isTallies(value) {
+	return (0, _orkestrel_contract.whereOf)((0, _orkestrel_contract.objectOf)({}), (record) => STATUS_PRECEDENCE.every((status) => isTally(Reflect.get(record, status))))(value);
+}
+/**
+* Determine whether a value is an open {@link ProgramResult}.
+*
+* @remarks
+* This guard is result-postured for values returned through a borrowed
+* {@link ProgramInterface}. It admits unknown members and class instances while
+* composing qualifier's `isQualificationResult` and rater's `isRatingResult`
+* over their complete nested result closures. Arrays are refused.
+*
+* @param value - The candidate value
+* @returns `true` when every published program-result member conforms
+*
+* @example
+* ```ts
+* import { isProgramResult } from '@orkestrel/program'
+*
+* isProgramResult(program.execute(subject)) // true
+* ```
+*/
+var isProgramResult = (0, _orkestrel_contract.objectOf)({
+	id: _orkestrel_contract.isString,
+	name: _orkestrel_contract.isString,
+	eligibility: _orkestrel_qualifier.isEligibility,
+	status: isStatus,
+	decision: isDecision,
+	qualification: _orkestrel_qualifier.isQualificationResult,
+	rating: _orkestrel_rater.isRatingResult,
+	determinations: (0, _orkestrel_contract.arrayOf)(isDetermination),
+	success: _orkestrel_contract.isBoolean,
+	trace: (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString),
+	errors: (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)
+}, ["decision", "rating"]);
+/**
+* Determine whether a value is an open {@link AggregateResult}.
+*
+* @remarks
+* This guard is result-postured for values returned through a borrowed
+* {@link ProgramInterface}. It admits unknown members and class instances while
+* checking every nested program result, determination, group, total tally
+* record, and sums record. Arrays are refused.
+*
+* @param value - The candidate value
+* @returns `true` when every published aggregate-result member conforms
+*
+* @example
+* ```ts
+* import { isAggregateResult } from '@orkestrel/program'
+*
+* isAggregateResult(program.execute(subjects)) // true
+* ```
+*/
+var isAggregateResult = (0, _orkestrel_contract.objectOf)({
+	id: _orkestrel_contract.isString,
+	name: _orkestrel_contract.isString,
+	subjects: (0, _orkestrel_contract.arrayOf)(isProgramResult),
+	determinations: (0, _orkestrel_contract.arrayOf)(isDetermination),
+	groups: (0, _orkestrel_contract.arrayOf)(isAggregateGroup),
+	tallies: isTallies,
+	count: _orkestrel_contract.isNumber,
+	sums: isProgramSums,
+	success: _orkestrel_contract.isBoolean,
+	trace: (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString),
+	errors: (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)
+});
+/**
+* Determine whether a value is an open {@link ProgramValidationResult}.
+*
+* @remarks
+* `ProgramValidationResult` is this package's own declared interface, not an
+* alias of reason's validation result. This guard therefore checks the three
+* program-owned members directly so the contracts may evolve independently.
+* Unknown members and class instances are admitted. Arrays are refused.
+*
+* @param value - The candidate value
+* @returns `true` when every published program-validation member conforms
+*
+* @example
+* ```ts
+* import { isProgramValidationResult } from '@orkestrel/program'
+*
+* isProgramValidationResult({ valid: true, errors: [], warnings: [] }) // true
+* ```
+*/
+var isProgramValidationResult = (0, _orkestrel_contract.objectOf)({
+	valid: _orkestrel_contract.isBoolean,
+	errors: (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString),
+	warnings: (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)
+});
 //#endregion
 //#region src/core/helpers.ts
 /**
@@ -978,6 +1174,83 @@ function buildAggregateResult(definition, subjects, determinations, groups, tall
 		errors: [...subjects.flatMap((entry) => entry.errors), ...gateErrors]
 	};
 }
+/**
+* Build a {@link ProgramDefinition}.
+*
+* @remarks
+* Copies every collection and omits absent optional keys, so the returned
+* definition is a fresh, JSON-serializable value that never aliases its inputs.
+*
+* @param id - The program id
+* @param name - The display name
+* @param qualification - The nested qualification definition
+* @param rating - The nested rating definition; omit for an eligibility-only program
+* @param input - Optional description, notices, authority, aggregate, and metadata
+* @returns A fresh program definition
+*
+* @example
+* ```ts
+* import { programDefinition } from '@orkestrel/program'
+*
+* programDefinition('standard', 'Standard', qualification, rating, { notices: [notice] })
+* ```
+*/
+function programDefinition(id, name, qualification, rating, input) {
+	return {
+		id,
+		name,
+		qualification,
+		...rating === void 0 ? {} : { rating },
+		...input?.description === void 0 ? {} : { description: input.description },
+		...input?.notices === void 0 ? {} : { notices: [...input.notices] },
+		...input?.authority === void 0 ? {} : { authority: input.authority },
+		...input?.aggregate === void 0 ? {} : { aggregate: input.aggregate },
+		...input?.metadata === void 0 ? {} : { metadata: copyJSONValue(input.metadata) }
+	};
+}
+/**
+* Build a {@link Notice}.
+*
+* @param id - The notice id
+* @param message - The message template, carrying optional `{{token}}`s
+* @param input - Optional presentation scope
+* @returns A fresh notice
+*
+* @example
+* ```ts
+* import { noticeDefinition } from '@orkestrel/program'
+*
+* noticeDefinition('minimum', 'Minimum earned premium applies')
+* ```
+*/
+function noticeDefinition(id, message, input) {
+	return {
+		id,
+		message,
+		...input?.scope === void 0 ? {} : { scope: input.scope }
+	};
+}
+/**
+* Build an {@link AggregateDefinition}.
+*
+* @param fields - The aggregate fields to sum across a batch
+* @param input - Optional partition field and aggregate gates
+* @returns A fresh aggregate definition
+*
+* @example
+* ```ts
+* import { aggregateDefinition } from '@orkestrel/program'
+*
+* aggregateDefinition(['amount'], { by: 'location' })
+* ```
+*/
+function aggregateDefinition(fields, input) {
+	return {
+		fields: [...fields],
+		...input?.by === void 0 ? {} : { by: input.by },
+		...input?.gates === void 0 ? {} : { gates: input.gates }
+	};
+}
 //#endregion
 //#region src/core/programs/Program.ts
 /**
@@ -1067,11 +1340,15 @@ var Program = class {
 		assertProgramSubject(subject);
 		const qualified = buildQualificationSubject(subject, aggregate);
 		const qualification = this.#qualifier.qualify(qualified, this.definition.qualification);
+		if (!(0, _orkestrel_qualifier.isQualificationResult)(qualification)) throw new ProgramError("MISMATCH", "Qualifier returned invalid qualification result", this.definition.qualification.id);
 		this.#emitter.emit("qualify", qualification);
 		if (!qualification.success || qualification.eligibility !== "eligible") return this.#finish(subject, qualification, void 0);
 		const lines = selectProgramLines(this.definition.rating?.lines ?? [], qualification.scopes);
 		const rating = lines.length === 0 ? void 0 : this.#rater.rate(lines, subject);
-		if (rating !== void 0) this.#emitter.emit("rate", rating);
+		if (rating !== void 0) {
+			if (!(0, _orkestrel_rater.isRatingResult)(rating)) throw new ProgramError("MISMATCH", "Rater returned invalid rating result", this.definition.rating?.id);
+			this.#emitter.emit("rate", rating);
+		}
 		return this.#finish(subject, qualification, rating);
 	}
 	#finish(subject, qualification, rating) {
@@ -1086,7 +1363,7 @@ var Program = class {
 		}
 		const outcome = { [OUTCOME_KEY]: buildOutcomeProjection(result) };
 		const resolved = this.#engine.reason(outcome, authority);
-		if (resolved.reasoning !== "logical") throw new ProgramError("MISMATCH", "Authority returned non-logical reasoning", authority.id);
+		if (!(0, _orkestrel_reason.isLogicalResult)(resolved)) throw new ProgramError("MISMATCH", "Authority returned invalid logical result", authority.id);
 		const limits = buildLimits(authority, resolved, outcome, this.#evaluator, this.#labels);
 		for (const limit of limits) this.#emitter.emit("determine", limit);
 		result = buildProgramResult(this.definition, qualification, rating, [...notices, ...limits], status, { authority: resolved });
@@ -1117,7 +1394,7 @@ var Program = class {
 		if (gates === void 0) return { determinations: [] };
 		const record = buildAggregateRecord(count, sums, groups);
 		const resolved = this.#engine.reason(record, gates);
-		if (resolved.reasoning !== "logical") throw new ProgramError("MISMATCH", "Aggregate gates returned non-logical reasoning", gates.id);
+		if (!(0, _orkestrel_reason.isLogicalResult)(resolved)) throw new ProgramError("MISMATCH", "Aggregate gates returned invalid logical result", gates.id);
 		const determinations = buildLimits(gates, resolved, record, this.#evaluator, this.#labels);
 		for (const determination of determinations) this.#emitter.emit("determine", determination);
 		return {
@@ -1308,83 +1585,6 @@ function createProgram(definition, options) {
 function createProgramManager(options) {
 	return new ProgramManager(options);
 }
-/**
-* Build a {@link ProgramDefinition}.
-*
-* @remarks
-* Copies every collection and omits absent optional keys, so the returned
-* definition is a fresh, JSON-serializable value that never aliases its inputs.
-*
-* @param id - The program id
-* @param name - The display name
-* @param qualification - The nested qualification definition
-* @param rating - The nested rating definition; omit for an eligibility-only program
-* @param input - Optional description, notices, authority, aggregate, and metadata
-* @returns A fresh program definition
-*
-* @example
-* ```ts
-* import { programDefinition } from '@orkestrel/program'
-*
-* programDefinition('standard', 'Standard', qualification, rating, { notices: [notice] })
-* ```
-*/
-function programDefinition(id, name, qualification, rating, input) {
-	return {
-		id,
-		name,
-		qualification,
-		...rating === void 0 ? {} : { rating },
-		...input?.description === void 0 ? {} : { description: input.description },
-		...input?.notices === void 0 ? {} : { notices: [...input.notices] },
-		...input?.authority === void 0 ? {} : { authority: input.authority },
-		...input?.aggregate === void 0 ? {} : { aggregate: input.aggregate },
-		...input?.metadata === void 0 ? {} : { metadata: copyJSONValue(input.metadata) }
-	};
-}
-/**
-* Build a {@link Notice}.
-*
-* @param id - The notice id
-* @param message - The message template, carrying optional `{{token}}`s
-* @param input - Optional presentation scope
-* @returns A fresh notice
-*
-* @example
-* ```ts
-* import { noticeDefinition } from '@orkestrel/program'
-*
-* noticeDefinition('minimum', 'Minimum earned premium applies')
-* ```
-*/
-function noticeDefinition(id, message, input) {
-	return {
-		id,
-		message,
-		...input?.scope === void 0 ? {} : { scope: input.scope }
-	};
-}
-/**
-* Build an {@link AggregateDefinition}.
-*
-* @param fields - The aggregate fields to sum across a batch
-* @param input - Optional partition field and aggregate gates
-* @returns A fresh aggregate definition
-*
-* @example
-* ```ts
-* import { aggregateDefinition } from '@orkestrel/program'
-*
-* aggregateDefinition(['amount'], { by: 'location' })
-* ```
-*/
-function aggregateDefinition(fields, input) {
-	return {
-		fields: [...fields],
-		...input?.by === void 0 ? {} : { by: input.by },
-		...input?.gates === void 0 ? {} : { gates: input.gates }
-	};
-}
 //#endregion
 exports.AGGREGATE_KEY = AGGREGATE_KEY;
 exports.DEFAULT_PROGRAM_VALIDATE = DEFAULT_PROGRAM_VALIDATE;
@@ -1419,12 +1619,20 @@ exports.findMissingScopes = findMissingScopes;
 exports.formatGroupKey = formatGroupKey;
 exports.hasReservedKey = hasReservedKey;
 exports.isAggregateDefinition = isAggregateDefinition;
+exports.isAggregateGroup = isAggregateGroup;
+exports.isAggregateResult = isAggregateResult;
 exports.isDecision = isDecision;
+exports.isDetermination = isDetermination;
 exports.isNotice = isNotice;
 exports.isProgramDefinition = isProgramDefinition;
 exports.isProgramEffect = isProgramEffect;
 exports.isProgramError = isProgramError;
+exports.isProgramResult = isProgramResult;
+exports.isProgramSums = isProgramSums;
+exports.isProgramValidationResult = isProgramValidationResult;
 exports.isStatus = isStatus;
+exports.isTallies = isTallies;
+exports.isTally = isTally;
 exports.noticeDefinition = noticeDefinition;
 exports.programDefinition = programDefinition;
 exports.selectProgramLines = selectProgramLines;

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

@@ -628,6 +628,45 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
        */
       export declare function isAggregateDefinition(value: unknown): value is AggregateDefinition;
 
+      /**
+       * Determine whether a value is an open result-side {@link AggregateGroup}.
+       *
+       * @remarks
+       * Unknown members and class instances are admitted. Arrays are refused.
+       *
+       * @param value - The candidate value
+       * @returns `true` when every published aggregate-group member conforms
+       *
+       * @example
+       * ```ts
+       * import { isAggregateGroup } from '@orkestrel/program'
+       *
+       * isAggregateGroup({ key: 'east', count: 1, sums: { premium: 100 } }) // true
+       * ```
+       */
+      export declare const isAggregateGroup: Guard<AggregateGroup>;
+
+      /**
+       * Determine whether a value is an open {@link AggregateResult}.
+       *
+       * @remarks
+       * This guard is result-postured for values returned through a borrowed
+       * {@link ProgramInterface}. It admits unknown members and class instances while
+       * checking every nested program result, determination, group, total tally
+       * record, and sums record. Arrays are refused.
+       *
+       * @param value - The candidate value
+       * @returns `true` when every published aggregate-result member conforms
+       *
+       * @example
+       * ```ts
+       * import { isAggregateResult } from '@orkestrel/program'
+       *
+       * isAggregateResult(program.execute(subjects)) // true
+       * ```
+       */
+      export declare const isAggregateResult: Guard<AggregateResult>;
+
       /**
        * Determine whether a value is a {@link Decision} literal.
        *
@@ -643,6 +682,25 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
        */
       export declare const isDecision: Guard<Decision>;
 
+      /**
+       * Determine whether a value is an open result-side {@link Determination}.
+       *
+       * @remarks
+       * Unknown members and class instances are admitted. Arrays are refused.
+       * Optional `scope` and `message` members may be absent or `undefined`.
+       *
+       * @param value - The candidate value
+       * @returns `true` when every published determination member conforms
+       *
+       * @example
+       * ```ts
+       * import { isDetermination } from '@orkestrel/program'
+       *
+       * isDetermination({ id: 'audit', effect: 'notice', applied: true, premises: [] }) // true
+       * ```
+       */
+      export declare const isDetermination: Guard<Determination>;
+
       /**
        * Determine whether a value is an exact {@link Notice} record.
        *
@@ -695,6 +753,69 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
       /** Narrow a caught value to a {@link ProgramError}. */
       export declare function isProgramError(value: unknown): value is ProgramError;
 
+      /**
+       * Determine whether a value is an open {@link ProgramResult}.
+       *
+       * @remarks
+       * This guard is result-postured for values returned through a borrowed
+       * {@link ProgramInterface}. It admits unknown members and class instances while
+       * composing qualifier's `isQualificationResult` and rater's `isRatingResult`
+       * over their complete nested result closures. Arrays are refused.
+       *
+       * @param value - The candidate value
+       * @returns `true` when every published program-result member conforms
+       *
+       * @example
+       * ```ts
+       * import { isProgramResult } from '@orkestrel/program'
+       *
+       * isProgramResult(program.execute(subject)) // true
+       * ```
+       */
+      export declare const isProgramResult: Guard<ProgramResult>;
+
+      /**
+       * Determine whether a value is an open program sums record.
+       *
+       * @remarks
+       * Every own string-named property is checked, including non-enumerable
+       * properties. Inherited and symbol-named members are outside the record this
+       * guard certifies. Values remain plain JavaScript numbers, including `NaN` and
+       * infinities, because the published contract does not refine them.
+       *
+       * @param value - The candidate value
+       * @returns `true` when every own string-named value is a number
+       *
+       * @example
+       * ```ts
+       * import { isProgramSums } from '@orkestrel/program'
+       *
+       * isProgramSums({ premium: 100 }) // true
+       * ```
+       */
+      export declare function isProgramSums(value: unknown): value is Readonly<Record<string, number>>;
+
+      /**
+       * Determine whether a value is an open {@link ProgramValidationResult}.
+       *
+       * @remarks
+       * `ProgramValidationResult` is this package's own declared interface, not an
+       * alias of reason's validation result. This guard therefore checks the three
+       * program-owned members directly so the contracts may evolve independently.
+       * Unknown members and class instances are admitted. Arrays are refused.
+       *
+       * @param value - The candidate value
+       * @returns `true` when every published program-validation member conforms
+       *
+       * @example
+       * ```ts
+       * import { isProgramValidationResult } from '@orkestrel/program'
+       *
+       * isProgramValidationResult({ valid: true, errors: [], warnings: [] }) // true
+       * ```
+       */
+      export declare const isProgramValidationResult: Guard<ProgramValidationResult>;
+
       /**
        * Determine whether a value is a {@link Status} literal.
        *
@@ -710,6 +831,43 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
        */
       export declare const isStatus: Guard<Status>;
 
+      /**
+       * Determine whether a value is a total open status-tally record.
+       *
+       * @remarks
+       * Every {@link Status} in {@link STATUS_PRECEDENCE} is required and checked.
+       * Unknown members and class instances are admitted. Arrays are refused.
+       *
+       * @param value - The candidate value
+       * @returns `true` when every required status member is a {@link Tally}
+       *
+       * @example
+       * ```ts
+       * import { emptyTallies, isTallies } from '@orkestrel/program'
+       *
+       * isTallies(emptyTallies([])) // true
+       * ```
+       */
+      export declare function isTallies(value: unknown): value is Readonly<Record<Status, Tally>>;
+
+      /**
+       * Determine whether a value is an open result-side {@link Tally}.
+       *
+       * @remarks
+       * Unknown members and class instances are admitted. Arrays are refused.
+       *
+       * @param value - The candidate value
+       * @returns `true` when every published tally member conforms
+       *
+       * @example
+       * ```ts
+       * import { isTally } from '@orkestrel/program'
+       *
+       * isTally({ count: 1, sums: { premium: 100 } }) // true
+       * ```
+       */
+      export declare const isTally: Guard<Tally>;
+
       /** An authored, unconditional program notice. */
       export declare interface Notice {
           readonly id: string;