@orkestrel/program 0.0.6 → 0.0.8

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

@@ -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;

package/dist/src/core/index.js

@@ -1,7 +1,7 @@
-import { arrayOf, isArray, isFiniteNumber, isJSONValue, isRecord, isString, literalOf, recordOf, resolveField } from "@orkestrel/contract";
-import { createQualifier, findRule, interpolateMessage, isQualificationDefinition, logicalPremises } from "@orkestrel/qualifier";
-import { createRater, isRatingDefinition } from "@orkestrel/rater";
-import { createEvaluator, createLogicalReasoner, createQuantitativeReasoner, createReason, findDuplicates, formatField, isFieldPath, isLogicalDefinition } from "@orkestrel/reason";
+import { arrayOf, isArray, isBoolean, isFiniteNumber, isJSONValue, isNumber, isRecord, isString, literalOf, objectOf, recordOf, resolveField, whereOf } from "@orkestrel/contract";
+import { createQualifier, findRule, interpolateMessage, isEligibility, isPremise, isQualificationDefinition, isQualificationResult, logicalPremises } from "@orkestrel/qualifier";
+import { createRater, isRatingDefinition, isRatingResult } from "@orkestrel/rater";
+import { createEvaluator, createLogicalReasoner, createQuantitativeReasoner, createReason, findDuplicates, formatField, isFieldPath, isLogicalDefinition, isLogicalResult } from "@orkestrel/reason";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
 /** Default definition validation policy for `createProgram` / `ProgramManager.add`. */
@@ -173,6 +173,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 whereOf(objectOf({}), (record) => Object.getOwnPropertyNames(record).every((key) => 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 = objectOf({
+	id: isString,
+	effect: isProgramEffect,
+	applied: isBoolean,
+	scope: isString,
+	message: isString,
+	premises: arrayOf(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 = objectOf({
+	key: isString,
+	count: 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 = objectOf({
+	count: 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 whereOf(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 = objectOf({
+	id: isString,
+	name: isString,
+	eligibility: isEligibility,
+	status: isStatus,
+	decision: isDecision,
+	qualification: isQualificationResult,
+	rating: isRatingResult,
+	determinations: arrayOf(isDetermination),
+	success: isBoolean,
+	trace: arrayOf(isString),
+	errors: arrayOf(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 = objectOf({
+	id: isString,
+	name: isString,
+	subjects: arrayOf(isProgramResult),
+	determinations: arrayOf(isDetermination),
+	groups: arrayOf(isAggregateGroup),
+	tallies: isTallies,
+	count: isNumber,
+	sums: isProgramSums,
+	success: isBoolean,
+	trace: arrayOf(isString),
+	errors: arrayOf(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 = objectOf({
+	valid: isBoolean,
+	errors: arrayOf(isString),
+	warnings: arrayOf(isString)
+});
 //#endregion
 //#region src/core/helpers.ts
 /**
@@ -977,6 +1173,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
 /**
@@ -1066,11 +1339,15 @@ var Program = class {
 		assertProgramSubject(subject);
 		const qualified = buildQualificationSubject(subject, aggregate);
 		const qualification = this.#qualifier.qualify(qualified, this.definition.qualification);
+		if (!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 (!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) {
@@ -1085,7 +1362,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 (!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 });
@@ -1116,7 +1393,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 (!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 {
@@ -1307,84 +1584,7 @@ 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
-export { AGGREGATE_KEY, DEFAULT_PROGRAM_VALIDATE, ELIGIBILITY_DECISIONS, OUTCOME_KEY, Program, ProgramError, ProgramManager, STATUS_PRECEDENCE, aggregateDefinition, aggregateGroups, aggregateSums, assertProgramDefinition, assertProgramSubject, buildAggregateProjection, buildAggregateRecord, buildAggregateResult, buildLimits, buildNotices, buildOutcomeProjection, buildProgramResult, buildQualificationSubject, completeTallies, copyJSONValue, createProgram, createProgramManager, decideEligibility, deriveStatus, emptySums, emptyTallies, findMissingScopes, formatGroupKey, hasReservedKey, isAggregateDefinition, isDecision, isNotice, isProgramDefinition, isProgramEffect, isProgramError, isStatus, noticeDefinition, programDefinition, selectProgramLines, sumFields, tallyProgram, validateProgramDefinition };
+export { AGGREGATE_KEY, DEFAULT_PROGRAM_VALIDATE, ELIGIBILITY_DECISIONS, OUTCOME_KEY, Program, ProgramError, ProgramManager, STATUS_PRECEDENCE, aggregateDefinition, aggregateGroups, aggregateSums, assertProgramDefinition, assertProgramSubject, buildAggregateProjection, buildAggregateRecord, buildAggregateResult, buildLimits, buildNotices, buildOutcomeProjection, buildProgramResult, buildQualificationSubject, completeTallies, copyJSONValue, createProgram, createProgramManager, decideEligibility, deriveStatus, emptySums, emptyTallies, findMissingScopes, formatGroupKey, hasReservedKey, isAggregateDefinition, isAggregateGroup, isAggregateResult, isDecision, isDetermination, isNotice, isProgramDefinition, isProgramEffect, isProgramError, isProgramResult, isProgramSums, isProgramValidationResult, isStatus, isTallies, isTally, noticeDefinition, programDefinition, selectProgramLines, sumFields, tallyProgram, validateProgramDefinition };
 
 //# sourceMappingURL=index.js.map