@orkestrel/qualifier 0.0.1 → 0.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @orkestrel/qualifier
 
-A typed **pre-rating eligibility engine** over [`@orkestrel/reason`](https://github.com/orkestrel/reason):
+A typed **eligibility engine** over [`@orkestrel/reason`](https://github.com/orkestrel/reason):
 authored **passes** — quantitative derivations and logical rule gates — run in order
 against a **subject** (a plain data record) to produce **findings** (evidence-rich
 ruling outcomes), **derivations** (quantitative audit trails), and **eligibility**

package/dist/src/core/index.cjs

@@ -28,6 +28,8 @@ var EFFECT_ELIGIBILITIES = Object.freeze({
 * `DEFINITION` — a qualification definition failed semantic validation.
 * `MISMATCH` — a subject is not a record or already carries the reserved
 * `qualification` key. `DESTROYED` — use of a destroyed qualifier.
+* `ENGINE` — the underlying reason engine threw while running a pass (the
+* original throw is preserved as `context.cause`).
 */
 var QualifierError = class extends Error {
 	code;
@@ -66,7 +68,6 @@ function isRuling(value) {
 }
 /** Determine whether a value is an exact {@link QualificationDefinition} record. */
 function isQualificationDefinition(value) {
-	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
 	return (0, _orkestrel_contract.recordOf)({
 		id: _orkestrel_contract.isString,
 		name: _orkestrel_contract.isString,
@@ -299,6 +300,26 @@ function findRule(definition, id) {
 * @param definition - The pass definition that produced the result
 * @param result - The evaluated reason result
 * @returns The pass's working projection
+*
+* @example
+* ```ts
+* import { reasonResultToProjection } from '@orkestrel/qualifier'
+* import { factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
+*
+* const cap = quantitativeDefinition('cap', 'TIV cap', [
+*   factorGroup('limit', 'sum', [staticFactor('base', 500_000)]),
+* ])
+* const result = {
+*   reasoning: 'quantitative' as const,
+*   value: 500_000,
+*   groups: [],
+*   count: 1,
+*   success: true,
+*   trace: [],
+*   errors: [],
+* }
+* reasonResultToProjection(cap, result) // 500000
+* ```
 */
 function reasonResultToProjection(definition, result) {
 	if (definition.reasoning === "quantitative" && result.reasoning === "quantitative") return result.value;
@@ -319,6 +340,15 @@ function reasonResultToProjection(definition, result) {
 * @param id - The pass id
 * @param result - The evaluated quantitative result
 * @returns A fresh derivation
+*
+* @example
+* ```ts
+* import { quantitativeResultToDerivation } from '@orkestrel/qualifier'
+*
+* const result = { reasoning: 'quantitative' as const, value: 500_000, groups: [], count: 1, success: true, trace: ['cap: 500000'], errors: [] }
+* quantitativeResultToDerivation('cap', result)
+* // { id: 'cap', value: 500000, success: true, trace: ['cap: 500000'], errors: [] }
+* ```
 */
 function quantitativeResultToDerivation(id, result) {
 	return {
@@ -334,6 +364,13 @@ function quantitativeResultToDerivation(id, result) {
 *
 * @param context - The accumulated projection context
 * @returns A record carrying the context under the reserved key
+*
+* @example
+* ```ts
+* import { qualificationToRecord } from '@orkestrel/qualifier'
+*
+* qualificationToRecord({ cap: 500_000 }) // { qualification: { cap: 500000 } }
+* ```
 */
 function qualificationToRecord(context) {
 	return { [QUALIFICATION_KEY]: context };
@@ -345,6 +382,14 @@ function qualificationToRecord(context) {
 * @param id - The pass id to project under
 * @param projection - The pass's working projection
 * @returns A fresh context with the projection added
+*
+* @example
+* ```ts
+* import { mergeQualificationContext } from '@orkestrel/qualifier'
+*
+* mergeQualificationContext({ cap: 500_000 }, 'excess', 250_000)
+* // { cap: 500000, excess: 250000 }
+* ```
 */
 function mergeQualificationContext(context, id, projection) {
 	return {
@@ -369,6 +414,21 @@ function mergeQualificationContext(context, id, projection) {
 * @param evaluator - The shared reason check evaluator
 * @param labels - Optional field-to-label overrides, keyed by dot-joined field
 * @returns A fresh finding
+*
+* @example
+* ```ts
+* import { rulingToFinding } from '@orkestrel/qualifier'
+* import { atom, createEvaluator, logicalDefinition, rule } from '@orkestrel/reason'
+*
+* const gates = logicalDefinition('gates', 'Gates', [
+*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* ])
+* const ruling = { id: 'license', pass: 'gates', rule: 'licensed', effect: 'restriction' as const }
+* const result = { reasoning: 'logical' as const, conclusion: true, rules: [{ id: 'licensed', applied: true, premises: [true], conclusion: true }], count: 1, success: true, trace: [], errors: [] }
+* const finding = rulingToFinding(ruling, gates, result, { licensed: false }, createEvaluator())
+*
+* finding.applied // true
+* ```
 */
 function rulingToFinding(ruling, pass, result, subject, evaluator, labels) {
 	const applied = result.rules.find((item) => item.id === ruling.rule)?.applied ?? false;
@@ -396,6 +456,14 @@ function rulingToFinding(ruling, pass, result, subject, evaluator, labels) {
 * @param findings - The resolved findings
 * @param failed - Whether an operational pass failure occurred
 * @returns The most severe global eligibility
+*
+* @example
+* ```ts
+* import { deriveFindingEligibility } from '@orkestrel/qualifier'
+*
+* const finding = { id: 'license', pass: 'gates', rule: 'licensed', effect: 'restriction' as const, applied: true, premises: [] }
+* deriveFindingEligibility([finding]) // 'ineligible'
+* ```
 */
 function deriveFindingEligibility(findings, failed = false) {
 	const eligibilities = findings.filter((finding) => finding.applied && finding.scope === void 0).map((finding) => EFFECT_ELIGIBILITIES[finding.effect]);
@@ -429,6 +497,14 @@ function combineEligibilities(eligibilities) {
 *
 * @param findings - The resolved findings
 * @returns A fresh record of scope to its combined eligibility
+*
+* @example
+* ```ts
+* import { deriveScopeEligibilities } from '@orkestrel/qualifier'
+*
+* const finding = { id: 'coastal', pass: 'wind', rule: 'coastal', effect: 'restriction' as const, scope: 'wind', applied: true, premises: [] }
+* deriveScopeEligibilities([finding]) // { wind: 'ineligible' }
+* ```
 */
 function deriveScopeEligibilities(findings) {
 	const grouped = {};
@@ -447,6 +523,22 @@ function deriveScopeEligibilities(findings) {
 *
 * @param definition - The qualification definition to check
 * @returns A fresh list of reference-error messages
+*
+* @example
+* ```ts
+* import { findMissingReferences, qualificationDefinition, rulingDefinition } from '@orkestrel/qualifier'
+* import { atom, logicalDefinition, rule } from '@orkestrel/reason'
+*
+* const gates = logicalDefinition('gates', 'Gates', [
+*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* ])
+* const definition = qualificationDefinition('standard', 'Standard', [gates], {
+*   rulings: [rulingDefinition('license', 'gates', 'absent', 'restriction')],
+* })
+*
+* findMissingReferences(definition)
+* // ["Ruling 'license' references missing rule 'absent' in pass 'gates'"]
+* ```
 */
 function findMissingReferences(definition) {
 	const errors = [];
@@ -467,23 +559,17 @@ function findMissingReferences(definition) {
 	return errors;
 }
 /**
-* Find duplicate ids in a list, once each.
-*
-* @param ids - The ids to scan
-* @returns A fresh list of ids that appear more than once
-*/
-function findDuplicateIds(ids) {
-	const seen = /* @__PURE__ */ new Set();
-	const duplicates = /* @__PURE__ */ new Set();
-	for (const id of ids) if (seen.has(id)) duplicates.add(id);
-	else seen.add(id);
-	return [...duplicates];
-}
-/**
 * Determine whether a subject already owns the reserved {@link QUALIFICATION_KEY}.
 *
 * @param subject - The subject to check
 * @returns `true` when the subject owns the reserved key
+*
+* @example
+* ```ts
+* import { hasReservedKey } from '@orkestrel/qualifier'
+*
+* hasReservedKey({ id: 's1', qualification: {} }) // true
+* ```
 */
 function hasReservedKey(subject) {
 	return Object.hasOwn(subject, QUALIFICATION_KEY);
@@ -494,16 +580,198 @@ function hasReservedKey(subject) {
 * @param value - The candidate subject to validate
 * @throws {@link QualifierError} `'MISMATCH'` when the value is not a record, or
 * when it already carries the reserved `qualification` key
+*
+* @example
+* ```ts
+* import { assertSubject } from '@orkestrel/qualifier'
+*
+* assertSubject({ id: 's1' }) // narrows to Subject
+* ```
 */
 function assertSubject(value) {
 	if (!(0, _orkestrel_contract.isRecord)(value)) throw new QualifierError("MISMATCH", "Qualification subject must be a record");
 	if (hasReservedKey(value)) throw new QualifierError("MISMATCH", `Qualification subject must not contain reserved key '${QUALIFICATION_KEY}'`);
 }
+/**
+* Map an engine throw caught while running one pass to a typed {@link QualifierError}.
+*
+* @remarks
+* A reason `ReasonError('INVALID')` maps to `DEFINITION` (the engine rejected the
+* pass as an invalid definition); `ReasonError('DESTROYED')` maps to `DESTROYED`;
+* every other `ReasonError` code (e.g. `MISSING`) and every non-`ReasonError` throw
+* (including a `bail: true` reasoner rethrow) maps to `ENGINE`. The original throw
+* is preserved as `context.cause`.
+*
+* @param error - The value caught from the engine's `reason` call
+* @param pass - The id of the pass that was running
+* @returns A fresh, typed {@link QualifierError}
+*
+* @example
+* ```ts
+* import { mapEngineError } from '@orkestrel/qualifier'
+* import { ReasonError } from '@orkestrel/reason'
+*
+* mapEngineError(new ReasonError('MISSING', 'No reasoner registered'), 'cap').code // 'ENGINE'
+* ```
+*/
+function mapEngineError(error, pass) {
+	if ((0, _orkestrel_reason.isReasonError)(error)) {
+		if (error.code === "INVALID") return new QualifierError("DEFINITION", `Pass '${pass}' failed engine validation: ${error.message}`, {
+			pass,
+			cause: error
+		});
+		if (error.code === "DESTROYED") return new QualifierError("DESTROYED", `Qualifier engine was destroyed during pass '${pass}'`, {
+			pass,
+			cause: error
+		});
+		return new QualifierError("ENGINE", `Pass '${pass}' engine failure: ${error.message}`, {
+			pass,
+			cause: error
+		});
+	}
+	return new QualifierError("ENGINE", `Pass '${pass}' engine failure: ${error instanceof Error ? error.message : String(error)}`, {
+		pass,
+		cause: error
+	});
+}
+/**
+* Find logical passes carrying no rulings.
+*
+* @remarks
+* A logical pass with no matching ruling can never contribute a finding, so its
+* rules only ever influence later passes' reads — this is very likely an authoring
+* oversight.
+*
+* @param definition - The qualification definition to check
+* @returns A fresh list of warning messages
+*
+* @example
+* ```ts
+* import { findEmptyLogicalPasses, qualificationDefinition } from '@orkestrel/qualifier'
+* import { atom, logicalDefinition, rule } from '@orkestrel/reason'
+*
+* const gates = logicalDefinition('gates', 'Gates', [
+*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* ])
+* const definition = qualificationDefinition('standard', 'Standard', [gates])
+*
+* findEmptyLogicalPasses(definition) // ["Logical pass 'gates' has no rulings"]
+* ```
+*/
+function findEmptyLogicalPasses(definition) {
+	const warnings = [];
+	for (const pass of definition.passes) {
+		if (pass.reasoning !== "logical") continue;
+		if (!(definition.rulings ?? []).some((ruling) => ruling.pass === pass.id)) warnings.push(`Logical pass '${pass.id}' has no rulings`);
+	}
+	return warnings;
+}
+/**
+* Find quantitative passes never read by a later pass.
+*
+* @remarks
+* A quantitative pass's projected value lives under `qualification.<id>` — if no
+* later logical premise or quantitative factor field reads that key, the
+* derivation is dead weight. Reads are collected per later pass: a logical pass's
+* premise atoms (conclusion atoms are writes, not reads), and a quantitative
+* pass's field/lookup/range factor sources plus factor checks.
+*
+* @param definition - The qualification definition to check
+* @returns A fresh list of warning messages
+*
+* @example
+* ```ts
+* import { findUnreadDerivations, qualificationDefinition } from '@orkestrel/qualifier'
+* import { factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
+*
+* const cap = quantitativeDefinition('cap', 'TIV cap', [
+*   factorGroup('limit', 'sum', [staticFactor('base', 500_000)]),
+* ])
+* const definition = qualificationDefinition('standard', 'Standard', [cap])
+*
+* findUnreadDerivations(definition) // ["Quantitative pass 'cap' is never read by a later pass"]
+* ```
+*/
+function findUnreadDerivations(definition) {
+	const warnings = [];
+	definition.passes.forEach((pass, index) => {
+		if (pass.reasoning !== "quantitative") return;
+		const key = (0, _orkestrel_reason.formatField)(["qualification", pass.id]);
+		const reads = /* @__PURE__ */ new Set();
+		for (const later of definition.passes.slice(index + 1)) {
+			if (later.reasoning === "logical") for (const rule of later.rules) for (const premise of rule.premises) for (const atom of (0, _orkestrel_reason.extractAtoms)(premise)) reads.add((0, _orkestrel_reason.formatField)(atom.check.field));
+			if (later.reasoning === "quantitative") for (const group of later.groups) for (const factor of group.factors) {
+				if (factor.source.origin === "field" || factor.source.origin === "lookup" || factor.source.origin === "range") reads.add((0, _orkestrel_reason.formatField)(factor.source.field));
+				for (const check of factor.checks ?? []) reads.add((0, _orkestrel_reason.formatField)(check.field));
+			}
+		}
+		if (!reads.has(key)) warnings.push(`Quantitative pass '${pass.id}' is never read by a later pass`);
+	});
+	return warnings;
+}
+/**
+* Build a {@link QualificationDefinition}.
+*
+* @remarks
+* Returns a fresh top-level definition, omitting absent optional keys;
+* `passes` and `rulings` arrays are copied, and record `metadata` is
+* shallow-copied so nested values are not deep-cloned.
+*
+* @param id - The definition id
+* @param name - The display name
+* @param passes - The ordered qualification passes
+* @param input - Optional description, rulings, and metadata
+* @returns A fresh qualification definition
+*
+* @example
+* ```ts
+* import { qualificationDefinition } from '@orkestrel/qualifier'
+*
+* qualificationDefinition('standard', 'Standard', [gates], { rulings: [ruling] })
+* ```
+*/
+function qualificationDefinition(id, name, passes, input) {
+	return {
+		id,
+		name,
+		passes: [...passes],
+		...input?.description === void 0 ? {} : { description: input.description },
+		...input?.rulings === void 0 ? {} : { rulings: [...input.rulings] },
+		...input?.metadata === void 0 ? {} : { metadata: { ...input.metadata } }
+	};
+}
+/**
+* Build a {@link Ruling} — one authored consequence for one rule in one pass.
+*
+* @param id - The ruling id
+* @param pass - The logical pass id the rule lives in
+* @param rule - The rule id whose firing this ruling reacts to
+* @param effect - The eligibility impact when the rule fires
+* @param input - Optional selection scope and message template
+* @returns A fresh ruling
+*
+* @example
+* ```ts
+* import { rulingDefinition } from '@orkestrel/qualifier'
+*
+* rulingDefinition('license', 'gates', 'licensed', 'restriction', { message: 'A license is required' })
+* ```
+*/
+function rulingDefinition(id, pass, rule, effect, input) {
+	return {
+		id,
+		pass,
+		rule,
+		effect,
+		...input?.scope === void 0 ? {} : { scope: input.scope },
+		...input?.message === void 0 ? {} : { message: input.message }
+	};
+}
 //#endregion
 //#region src/core/Qualifier.ts
 /**
 * A qualifier — runs ordered passes over one reason engine and returns
-* pre-rating eligibility.
+* eligibility.
 *
 * @remarks
 * The engine is OWNED when self-created (destroyed on `destroy()`) and borrowed
@@ -550,10 +818,18 @@ var Qualifier = class {
 		const warnings = [];
 		if (definition.id.length === 0) errors.push("Definition id must not be empty");
 		if (definition.name.length === 0) errors.push("Definition name must not be empty");
-		if (definition.passes.length === 0) warnings.push("Definition has no passes");
-		for (const id of findDuplicateIds(definition.passes.map((pass) => pass.id))) errors.push(`Duplicate pass id '${id}'`);
-		for (const id of findDuplicateIds((definition.rulings ?? []).map((ruling) => ruling.id))) errors.push(`Duplicate ruling id '${id}'`);
+		definition.passes.forEach((pass, index) => {
+			if (!isQualificationPass(pass)) errors.push(`Pass at index ${index} is not a valid qualification pass`);
+		});
+		(definition.rulings ?? []).forEach((ruling, index) => {
+			if (!isRuling(ruling)) errors.push(`Ruling at index ${index} is not a valid ruling`);
+		});
+		for (const id of (0, _orkestrel_reason.findDuplicates)(definition.passes)) errors.push(`Duplicate pass id '${id}'`);
+		for (const id of (0, _orkestrel_reason.findDuplicates)(definition.rulings ?? [])) errors.push(`Duplicate ruling id '${id}'`);
 		for (const reference of findMissingReferences(definition)) errors.push(reference);
+		if (definition.passes.length === 0) warnings.push("Definition has no passes");
+		for (const warning of findEmptyLogicalPasses(definition)) warnings.push(warning);
+		for (const warning of findUnreadDerivations(definition)) warnings.push(warning);
 		return {
 			valid: errors.length === 0,
 			errors,
@@ -577,8 +853,14 @@ var Qualifier = class {
 		const errors = [];
 		let failed = false;
 		for (const pass of definition.passes) {
+			this.#alive();
 			const evaluated = working;
-			const result = this.#engine.reason(evaluated, pass);
+			let result;
+			try {
+				result = this.#engine.reason(evaluated, pass);
+			} catch (error) {
+				throw mapEngineError(error, pass.id);
+			}
 			trace.push(...result.trace.map((entry) => `${pass.id}: ${entry}`));
 			errors.push(...result.errors.map((entry) => `${pass.id}: ${entry}`));
 			if (result.reasoning === "quantitative") {
@@ -607,17 +889,18 @@ var Qualifier = class {
 			if (deriveFindingEligibility(findings) === "ineligible") break;
 		}
 		const success = !failed && errors.length === 0;
-		const qualification = {
+		const scopes = deriveScopeEligibilities(findings);
+		const qualification = Object.freeze({
 			id: definition.id,
 			name: definition.name,
 			eligibility: deriveFindingEligibility(findings, !success),
-			scopes: deriveScopeEligibilities(findings),
-			findings,
-			derivations,
+			scopes: Object.freeze(scopes),
+			findings: Object.freeze(findings),
+			derivations: Object.freeze(derivations),
 			success,
-			trace,
-			errors
-		};
+			trace: Object.freeze(trace),
+			errors: Object.freeze(errors)
+		});
 		this.#emitter.emit("qualify", qualification);
 		return qualification;
 	}
@@ -650,64 +933,6 @@ var Qualifier = class {
 function createQualifier(options) {
 	return new Qualifier(options);
 }
-/**
-* Build a {@link QualificationDefinition}.
-*
-* @remarks
-* Returns a fresh top-level definition, omitting absent optional keys;
-* `passes` and `rulings` arrays are copied, and record `metadata` is
-* shallow-copied so nested values are not deep-cloned.
-*
-* @param id - The definition id
-* @param name - The display name
-* @param passes - The ordered qualification passes
-* @param input - Optional description, rulings, and metadata
-* @returns A fresh qualification definition
-*
-* @example
-* ```ts
-* import { qualificationDefinition } from '@orkestrel/qualifier'
-*
-* qualificationDefinition('standard', 'Standard', [gates], { rulings: [ruling] })
-* ```
-*/
-function qualificationDefinition(id, name, passes, input) {
-	return {
-		id,
-		name,
-		passes: [...passes],
-		...input?.description === void 0 ? {} : { description: input.description },
-		...input?.rulings === void 0 ? {} : { rulings: [...input.rulings] },
-		...input?.metadata === void 0 ? {} : { metadata: { ...input.metadata } }
-	};
-}
-/**
-* Build a {@link Ruling} — one authored consequence for one rule in one pass.
-*
-* @param id - The ruling id
-* @param pass - The logical pass id the rule lives in
-* @param rule - The rule id whose firing this ruling reacts to
-* @param effect - The eligibility impact when the rule fires
-* @param input - Optional rating scope and message template
-* @returns A fresh ruling
-*
-* @example
-* ```ts
-* import { rulingDefinition } from '@orkestrel/qualifier'
-*
-* rulingDefinition('license', 'gates', 'licensed', 'restriction', { message: 'A license is required' })
-* ```
-*/
-function rulingDefinition(id, pass, rule, effect, input) {
-	return {
-		id,
-		pass,
-		rule,
-		effect,
-		...input?.scope === void 0 ? {} : { scope: input.scope },
-		...input?.message === void 0 ? {} : { message: input.message }
-	};
-}
 //#endregion
 exports.DEFAULT_QUALIFIER_VALIDATE = DEFAULT_QUALIFIER_VALIDATE;
 exports.EFFECT_ELIGIBILITIES = EFFECT_ELIGIBILITIES;
@@ -723,9 +948,10 @@ exports.deriveScopeEligibilities = deriveScopeEligibilities;
 exports.describeComparison = describeComparison;
 exports.describePremise = describePremise;
 exports.describeValue = describeValue;
-exports.findDuplicateIds = findDuplicateIds;
+exports.findEmptyLogicalPasses = findEmptyLogicalPasses;
 exports.findMissingReferences = findMissingReferences;
 exports.findRule = findRule;
+exports.findUnreadDerivations = findUnreadDerivations;
 exports.hasReservedKey = hasReservedKey;
 exports.interpolateMessage = interpolateMessage;
 exports.isEligibility = isEligibility;
@@ -735,6 +961,7 @@ exports.isQualificationPass = isQualificationPass;
 exports.isQualifierError = isQualifierError;
 exports.isRuling = isRuling;
 exports.logicalPremises = logicalPremises;
+exports.mapEngineError = mapEngineError;
 exports.mergeQualificationContext = mergeQualificationContext;
 exports.premiseCheck = premiseCheck;
 exports.qualificationDefinition = qualificationDefinition;