@orkestrel/qualifier 0.0.13 → 0.0.15

package/dist/src/core/index.js

@@ -1,18 +1,27 @@
-import { arrayOf, isBoolean, isFiniteNumber, isNumber, isRecord, isString, literalOf, objectOf, recordOf, resolveField, whereOf } from "@orkestrel/contract";
+import { arrayOf, isArray, isBoolean, isError, isFiniteNumber, isInstance, isNumber, isRecord, isString, literalOf, objectOf, recordOf, resolveField, whereOf } from "@orkestrel/contract";
 import { createEvaluator, createLogicalReasoner, createQuantitativeReasoner, createReason, extractAtoms, extractConclusions, findDuplicates, formatField, isBounds, isComparison, isFieldPath, isLogicalDefinition, isQuantitativeDefinition, isReasonError } from "@orkestrel/reason";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
-/** Holds the default definition validation policy for `createQualifier` / `Qualifier.qualify`. */
+/**
+* Holds the default definition validation policy for `createQualifier` and
+* `Qualifier.qualify`, `true`.
+*/
 var DEFAULT_QUALIFIER_VALIDATE = true;
-/** Names the reserved internal projection namespace a pass's working projection is written under. */
+/**
+* Names `'qualification'`, the reserved internal projection namespace a pass's working
+* projection is written under.
+*/
 var QUALIFICATION_KEY = "qualification";
-/** Lists the eligibility severities in order — most to least severe. */
+/** Lists the eligibility severities most to least severe: `ineligible`, `referral`, `eligible`. */
 var ELIGIBILITY_PRECEDENCE = Object.freeze([
 	"ineligible",
 	"referral",
 	"eligible"
 ]);
-/** Maps each {@link QualificationEffect} to its eligibility impact; `condition` remains eligible. */
+/**
+* Maps each {@link QualificationEffect} to its eligibility impact — `restriction` to
+* `ineligible`, `referral` to `referral`, and `condition` to `eligible`.
+*/
 var EFFECT_ELIGIBILITIES = Object.freeze({
 	restriction: "ineligible",
 	referral: "referral",
@@ -21,7 +30,8 @@ var EFFECT_ELIGIBILITIES = Object.freeze({
 //#endregion
 //#region src/core/errors.ts
 /**
-* Represents a coded programmer error thrown by the qualifier layer.
+* Represents a coded programmer error thrown by the qualifier layer, carrying a
+* `QualifierErrorCode` and an optional context record.
 *
 * @remarks
 * `DEFINITION` — a qualification definition failed semantic validation; when
@@ -52,13 +62,17 @@ var QualifierError = class extends Error {
 * @returns True if `value` is a {@link QualifierError} instance; false otherwise
 */
 function isQualifierError(value) {
-	return value instanceof QualifierError;
+	return isInstance(value, QualifierError);
 }
 //#endregion
 //#region src/core/validators.ts
 /**
 * Determines whether a value is an {@link Eligibility} literal.
 *
+* @remarks
+* The guard is total and leaves nothing unchecked: a scalar union has no open or exact
+* axis.
+*
 * @param value - The value to test
 * @returns True if `value` is one of the eligibility literals; false otherwise
 */
@@ -66,6 +80,10 @@ var isEligibility = literalOf("eligible", "ineligible", "referral");
 /**
 * Determines whether a value is a {@link QualificationEffect} literal.
 *
+* @remarks
+* The guard is total and leaves nothing unchecked: a scalar union has no open or exact
+* axis.
+*
 * @param value - The value to test
 * @returns True if `value` is one of the effect literals; false otherwise
 */
@@ -74,8 +92,9 @@ var isQualificationEffect = literalOf("restriction", "referral", "condition");
 * Determines whether a value is an open string-keyed record of {@link Eligibility} values.
 *
 * @remarks
-* Every own string-named property is checked, including non-enumerable properties. Inherited and
-* symbol-named members are left unchecked because they are outside the record this guard certifies.
+* Every own string-named value is checked through {@link isEligibility}, including
+* non-enumerable values. Inherited and symbol-named members are left unchecked because they
+* are outside the own string-keyed record this guard certifies.
 *
 * @param value - The value to test
 * @returns True if `value` is a non-array object whose own string-named values are
@@ -88,9 +107,11 @@ function isEligibilityRecord(value) {
 * Determines whether a value is an open result-side {@link Premise}.
 *
 * @remarks
-* `expected` is unchecked and may be absent or contain any value because its published type is
-* `unknown`. `actual` is unchecked and may be absent or contain any value for the same reason.
-* Unknown members are admitted.
+* The optional `field`, `label`, `description`, `comparison`, and `met` members are checked
+* when they are defined. `expected` is unchecked and may be absent or contain any value
+* because its published type is `unknown`. `actual` is unchecked and may be absent or contain
+* any value for the same reason. Unknown members are admitted, because an open result admits
+* what the published contract does not name.
 *
 * @param value - The value to test
 * @returns True if every checked premise member follows its published type; false otherwise
@@ -114,8 +135,10 @@ function isPremise(value) {
 * Determines whether a value is an open result-side {@link Finding}.
 *
 * @remarks
-* Unknown members are admitted. Optional `scope` and `message` members may be absent or
-* `undefined`; a present defined value must be a string.
+* Every published member is checked, including each nested {@link Premise}. Optional `scope`
+* and `message` members may be absent or `undefined`; a present defined value must be a
+* string. Unknown members are admitted, because a foreign result implementation may add them
+* without changing the published contract.
 *
 * @param value - The value to test
 * @returns True if every published finding member is valid; false otherwise
@@ -136,8 +159,10 @@ function isFinding(value) {
 * Determines whether a value is an open result-side {@link Derivation}.
 *
 * @remarks
-* Unknown members are admitted. `value` follows the published `number` type, including `NaN` and
-* infinities.
+* Every published member is checked: `value` follows the published `number` type, including
+* `NaN` and the infinities, and `trace` and `errors` hold strings. Unknown members are
+* admitted, because a foreign result implementation may add them without changing the
+* published contract.
 *
 * @param value - The value to test
 * @returns True if every published derivation member is valid; false otherwise
@@ -156,7 +181,10 @@ function isDerivation(value) {
 *
 * @remarks
 * This guard is result-postured for values returned through a borrowed qualifier interface. It
-* admits unknown members and class instances while checking the complete published result closure.
+* checks the complete published result closure — eligibility, scope values, findings,
+* derivations, success, and the audit trail — and admits unknown members and class instances,
+* because a borrowed `QualifierInterface` implementation may add them beyond the
+* published contract.
 *
 * @param value - The value to test
 * @returns True if every published qualification-result member is valid; false otherwise
@@ -177,6 +205,11 @@ function isQualificationResult(value) {
 /**
 * Determines whether a value is a {@link QualificationPass} (a quantitative or logical definition).
 *
+* @remarks
+* The guard is exact and requires either complete reason shape, the quantitative definition or
+* the logical one. Nothing is left unchecked, because the reason package owns both authored
+* input shapes.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete reason quantitative or logical definition; false otherwise
 */
@@ -186,6 +219,10 @@ function isQualificationPass(value) {
 /**
 * Determines whether a value is an exact {@link Ruling} record.
 *
+* @remarks
+* Every authored ruling member and the complete key set are checked. Nothing is left
+* unchecked, because this package owns the authored input record.
+*
 * @param value - The value to test
 * @returns True if `value` carries every ruling member and no unknown key; false otherwise
 */
@@ -202,6 +239,11 @@ function isRuling(value) {
 /**
 * Determines whether a value is an exact {@link QualificationDefinition} record.
 *
+* @remarks
+* Every authored definition member, the nested pass and ruling shapes, and the complete key
+* set are checked. Nothing is left unchecked, because this package owns the authored input
+* record.
+*
 * @param value - The value to test
 * @returns True if `value` carries every definition member and no unknown key; false otherwise
 */
@@ -226,10 +268,10 @@ function isQualificationDefinition(value) {
 *
 * @remarks
 * Each token is split on `.` into a `FieldPath` array and resolved with
-* `resolveField` (a plain string field is ONE key, never dot-split — the split
+* `resolveField` (a plain string field is one key, never dot-split — the split
 * here is the token-to-path bridge). A finite number renders with `en-US`
 * thousand grouping (`5010` → `5,010`); any other resolved value String-coerces.
-* An UNRESOLVED path renders as the empty string.
+* An unresolved path renders as the empty string.
 *
 * @param template - The message template carrying `{{dotted.path}}` tokens
 * @param subject - The record tokens resolve against
@@ -286,7 +328,7 @@ function renderComparison(comparison) {
 * A reason `Bounds`-shaped record (the `between` / `outside` expected value)
 * renders its present sides joined with the word `and`; an absent side is
 * omitted. A finite number and everything else fall back to plain `String()` —
-* a finite number is NOT grouped here (grouping is {@link interpolateMessage}'s
+* a finite number is not grouped here (grouping is {@link interpolateMessage}'s
 * message-token-only behavior).
 *
 * @param value - The value to render
@@ -302,7 +344,7 @@ function renderComparison(comparison) {
 * ```
 */
 function renderValue(value) {
-	if (Array.isArray(value)) return value.map((entry) => String(entry)).join(", ");
+	if (isArray(value)) return value.map((entry) => String(entry)).join(", ");
 	if (isBounds(value)) {
 		const sides = [];
 		if (value.minimum !== void 0) sides.push(String(value.minimum));
@@ -315,7 +357,7 @@ function renderValue(value) {
 * Renders one {@link Premise} into a display-neutral sentence.
 *
 * @remarks
-* The checked form renders only when `field` and `comparison` are BOTH
+* The checked form renders only when `field` and `comparison` are both
 * present, and `description` then goes unused; a premise missing either half
 * of the checked pair renders as described instead.
 *
@@ -380,7 +422,7 @@ function checkToPremise(check, result, labels) {
 * A reason rule result carries only booleans, so this is the qualifier's own
 * premise-audit projection: each authored premise expression is flattened to its
 * atom leaves through `extractAtoms`, and each leaf's `Check` is re-evaluated through
-* the injected `evaluator`. A membership check (`any` / `none`) over an EMPTY
+* the injected `evaluator`. A membership check (`any` / `none`) over an empty
 * array value is content-free and is skipped.
 *
 * @param rule - The authored rule
@@ -407,7 +449,7 @@ function ruleToPremises(rule, working, evaluator, labels) {
 	const output = [];
 	for (const premise of rule.premises) for (const atom of extractAtoms(premise)) {
 		const { check } = atom;
-		if ((check.operator === "any" || check.operator === "none") && Array.isArray(check.value) && check.value.length === 0) continue;
+		if ((check.operator === "any" || check.operator === "none") && isArray(check.value) && check.value.length === 0) continue;
 		output.push(checkToPremise(check, evaluator.evaluate(check, working), labels));
 	}
 	return output;
@@ -549,7 +591,7 @@ function mergeQualificationContext(context, id, projection) {
 *
 * @remarks
 * `applied` reflects whether the ruling's rule fired. Premises are re-evaluated
-* against the SAME subject snapshot the pass evaluated, so a conclusion the pass
+* against the same subject snapshot the pass evaluated, so a conclusion the pass
 * derived can never satisfy its own reported premise. The message interpolates
 * against that snapshot.
 *
@@ -776,7 +818,7 @@ function mapEngineError(error, pass) {
 			cause: error
 		});
 	}
-	return new QualifierError("ENGINE", `Pass '${pass}' engine failure: ${error instanceof Error ? error.message : String(error)}`, {
+	return new QualifierError("ENGINE", `Pass '${pass}' engine failure: ${isError(error) ? error.message : String(error)}`, {
 		pass,
 		cause: error
 	});
@@ -862,8 +904,9 @@ function describeUnreadDerivations(definition) {
 * Runs ordered passes over one reason engine and returns eligibility.
 *
 * @remarks
-* The engine is OWNED when self-created (destroyed on `destroy()`) and borrowed
-* when injected (never destroyed). `qualify` builds its working subject through
+* The engine is owned when self-created (destroyed on `destroy()`) and borrowed
+* when injected (never destroyed). Semantic validation runs before the first pass
+* whenever the `validate` option is on. `qualify` builds its working subject through
 * copy-on-write overlays only — the caller's `subject` is never mutated, and the
 * qualifier's internal projection is discarded after each call.
 */
@@ -1091,10 +1134,10 @@ var Qualifier = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Creates one qualifier over a reason engine.
+* Creates one {@link QualifierInterface} over a reason engine.
 *
 * @remarks
-* A standalone qualifier creates and OWNS one shared quantitative-plus-logical
+* A standalone qualifier creates and owns one shared quantitative-plus-logical
 * reason engine, destroying it on `destroy()`. An injected `options.engine`
 * remains caller-owned and is never destroyed. `validate` runs semantic
 * validation before every qualification. Default: `true`. `labels` overrides the
@@ -1104,12 +1147,37 @@ var Qualifier = class {
 * @param options - Optional injected engine, validation, labels, and emitter hooks
 * @returns A {@link QualifierInterface}
 *
-* @example
+* @example Create a qualifier
 * ```ts
-* import { createQualifier } from '@orkestrel/qualifier'
+* import { createQualificationDefinition, createQualifier, createRuling } from '@orkestrel/qualifier'
+* import { createAtom, createLogicalDefinition, createRule } from '@orkestrel/reason'
+*
+* const gates = createLogicalDefinition('gates', 'Eligibility gates', [
+* 	createRule(
+* 		'licensed',
+* 		[createAtom('licensed', 'equals', false)],
+* 		createAtom('blocked', 'equals', true),
+* 	),
+* ])
+*
+* const bare = createRuling('license', 'gates', 'licensed', 'restriction')
+* const messaged = createRuling('license', 'gates', 'licensed', 'restriction', {
+* 	message: 'A license is required',
+* })
+*
+* 'message' in bare // false — an absent optional key is omitted, never written as undefined
+* messaged.message // 'A license is required'
+*
+* const passes = [gates]
+* const definition = createQualificationDefinition('standard', 'Standard eligibility', passes, {
+* 	rulings: [messaged],
+* })
+*
+* 'description' in definition // false
+* definition.passes === passes // false — the factory copies what it is handed
 *
 * const qualifier = createQualifier()
-* qualifier.qualify({ id: 'risk-1' }, definition)
+* qualifier.qualify({ id: 'risk-1', licensed: false }, definition)
 * qualifier.destroy()
 * ```
 */
@@ -1117,10 +1185,9 @@ function createQualifier(options) {
 	return new Qualifier(options);
 }
 /**
-* Creates a {@link QualificationDefinition}.
+* Creates a fresh {@link QualificationDefinition}, omitting every absent optional key.
 *
 * @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.
 *
@@ -1148,7 +1215,7 @@ function createQualificationDefinition(id, name, passes, input) {
 	};
 }
 /**
-* Creates a {@link Ruling} — one authored consequence for one rule in one pass.
+* Creates a fresh {@link Ruling} from the rule it reacts to and the effect it applies.
 *
 * @param id - The ruling id
 * @param pass - The logical pass id the rule lives in