@orkestrel/qualifier 0.0.11 → 0.0.13

package/dist/src/core/index.js

@@ -1,18 +1,18 @@
 import { arrayOf, isBoolean, isFiniteNumber, 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, isReasonValidationResult } from "@orkestrel/reason";
+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
-/** Default definition validation policy for `createQualifier` / `Qualifier.qualify`. */
+/** Holds the default definition validation policy for `createQualifier` / `Qualifier.qualify`. */
 var DEFAULT_QUALIFIER_VALIDATE = true;
-/** The reserved internal projection namespace a pass's working projection is written under. */
+/** Names the reserved internal projection namespace a pass's working projection is written under. */
 var QUALIFICATION_KEY = "qualification";
-/** Eligibility severity order — most to least severe. */
+/** Lists the eligibility severities in order — most to least severe. */
 var ELIGIBILITY_PRECEDENCE = Object.freeze([
 	"ineligible",
 	"referral",
 	"eligible"
 ]);
-/** The eligibility impact of each {@link QualificationEffect}; `condition` remains eligible. */
+/** Maps each {@link QualificationEffect} to its eligibility impact; `condition` remains eligible. */
 var EFFECT_ELIGIBILITIES = Object.freeze({
 	restriction: "ineligible",
 	referral: "referral",
@@ -21,14 +21,19 @@ var EFFECT_ELIGIBILITIES = Object.freeze({
 //#endregion
 //#region src/core/errors.ts
 /**
-* A coded programmer error thrown by the qualifier layer.
+* Represents a coded programmer error thrown by the qualifier layer.
 *
 * @remarks
-* `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`).
+* `DEFINITION` — a qualification definition failed semantic validation; when
+* `qualify`'s own validation raises it, `context.definition` names the
+* definition, and when an engine throw maps to it, `context.pass` names the pass
+* and `context.cause` preserves the original throw. `MISMATCH` — a subject is
+* not a record or already carries the reserved `qualification` key.
+* `DESTROYED` — use of a destroyed qualifier; an engine-mapped one carries
+* `context.pass` and `context.cause`. `ENGINE` — the underlying reason engine
+* threw while running a pass; `context.pass` names the pass and `context.cause`
+* preserves the original throw. `context` is absent for a throw that carries no
+* payload.
 */
 var QualifierError = class extends Error {
 	code;
@@ -40,31 +45,47 @@ var QualifierError = class extends Error {
 		this.context = context;
 	}
 };
-/** Narrow a caught value to a {@link QualifierError}. */
+/**
+* Narrows a caught value to a {@link QualifierError}.
+*
+* @param value - The caught value to test
+* @returns True if `value` is a {@link QualifierError} instance; false otherwise
+*/
 function isQualifierError(value) {
 	return value instanceof QualifierError;
 }
 //#endregion
 //#region src/core/validators.ts
-/** Determine whether a value is an {@link Eligibility} literal. */
+/**
+* Determines whether a value is an {@link Eligibility} literal.
+*
+* @param value - The value to test
+* @returns True if `value` is one of the eligibility literals; false otherwise
+*/
 var isEligibility = literalOf("eligible", "ineligible", "referral");
-/** Determine whether a value is a {@link QualificationEffect} literal. */
+/**
+* Determines whether a value is a {@link QualificationEffect} literal.
+*
+* @param value - The value to test
+* @returns True if `value` is one of the effect literals; false otherwise
+*/
 var isQualificationEffect = literalOf("restriction", "referral", "condition");
 /**
-* Determine whether a value is an open string-keyed record of {@link Eligibility} values.
+* 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.
 *
 * @param value - The value to test
-* @returns `true` when `value` is a non-array object whose own string-named values are eligibilities
+* @returns True if `value` is a non-array object whose own string-named values are
+* eligibilities; false otherwise
 */
 function isEligibilityRecord(value) {
 	return whereOf(objectOf({}), (record) => Object.getOwnPropertyNames(record).every((key) => isEligibility(Reflect.get(record, key))))(value);
 }
 /**
-* Determine whether a value is an open result-side {@link Premise}.
+* 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
@@ -72,7 +93,7 @@ function isEligibilityRecord(value) {
 * Unknown members are admitted.
 *
 * @param value - The value to test
-* @returns `true` when every checked premise member follows its published type
+* @returns True if every checked premise member follows its published type; false otherwise
 */
 function isPremise(value) {
 	return objectOf({
@@ -90,14 +111,14 @@ function isPremise(value) {
 	])(value);
 }
 /**
-* Determine whether a value is an open result-side {@link Finding}.
+* 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.
 *
 * @param value - The value to test
-* @returns `true` when every published finding member is valid
+* @returns True if every published finding member is valid; false otherwise
 */
 function isFinding(value) {
 	return objectOf({
@@ -112,14 +133,14 @@ function isFinding(value) {
 	}, ["scope", "message"])(value);
 }
 /**
-* Determine whether a value is an open result-side {@link Derivation}.
+* 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.
 *
 * @param value - The value to test
-* @returns `true` when every published derivation member is valid
+* @returns True if every published derivation member is valid; false otherwise
 */
 function isDerivation(value) {
 	return objectOf({
@@ -131,14 +152,14 @@ function isDerivation(value) {
 	})(value);
 }
 /**
-* Determine whether a value is an open {@link QualificationResult} returned by a qualifier.
+* Determines whether a value is an open {@link QualificationResult} returned by a qualifier.
 *
 * @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.
 *
 * @param value - The value to test
-* @returns `true` when every published qualification-result member is valid
+* @returns True if every published qualification-result member is valid; false otherwise
 */
 function isQualificationResult(value) {
 	return objectOf({
@@ -154,23 +175,20 @@ function isQualificationResult(value) {
 	})(value);
 }
 /**
-* Determine whether a value is an open {@link QualificationValidationResult} returned by a qualifier.
-*
-* @remarks
-* `QualificationValidationResult` is an alias of reasons' validation-result type, so this IS
-* reasons' published open result guard by delegation — the alias tracks reasons' shape
-* automatically, and a hand-written member list here would silently stop checking a member a
-* later reason release adds.
+* Determines whether a value is a {@link QualificationPass} (a quantitative or logical definition).
 *
 * @param value - The value to test
-* @returns `true` when every published qualification-validation-result member is valid
+* @returns True if `value` is a complete reason quantitative or logical definition; false otherwise
 */
-var isQualificationValidationResult = isReasonValidationResult;
-/** Determine whether a value is a {@link QualificationPass} (a quantitative or logical definition). */
 function isQualificationPass(value) {
 	return isQuantitativeDefinition(value) || isLogicalDefinition(value);
 }
-/** Determine whether a value is an exact {@link Ruling} record. */
+/**
+* Determines whether a value is an exact {@link Ruling} record.
+*
+* @param value - The value to test
+* @returns True if `value` carries every ruling member and no unknown key; false otherwise
+*/
 function isRuling(value) {
 	return recordOf({
 		id: isString,
@@ -181,7 +199,12 @@ function isRuling(value) {
 		message: isString
 	}, ["scope", "message"])(value);
 }
-/** Determine whether a value is an exact {@link QualificationDefinition} record. */
+/**
+* Determines whether a value is an exact {@link QualificationDefinition} record.
+*
+* @param value - The value to test
+* @returns True if `value` carries every definition member and no unknown key; false otherwise
+*/
 function isQualificationDefinition(value) {
 	return recordOf({
 		id: isString,
@@ -199,7 +222,7 @@ function isQualificationDefinition(value) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Interpolate `{{dotted.path}}` tokens in a message template against a subject.
+* Interpolates `{{dotted.path}}` tokens in a message template against a subject.
 *
 * @remarks
 * Each token is split on `.` into a `FieldPath` array and resolved with
@@ -229,19 +252,19 @@ function interpolateMessage(template, subject) {
 	});
 }
 /**
-* Describe a {@link Premise} comparison as a display-neutral verb phrase.
+* Renders a {@link Premise} comparison as a display-neutral verb phrase.
 *
 * @param comparison - The comparison to describe
 * @returns A display-neutral phrase
 *
 * @example
 * ```ts
-* import { describeComparison } from '@orkestrel/qualifier'
+* import { renderComparison } from '@orkestrel/qualifier'
 *
-* describeComparison('above') // 'is more than'
+* renderComparison('above') // 'is more than'
 * ```
 */
-function describeComparison(comparison) {
+function renderComparison(comparison) {
 	switch (comparison) {
 		case "equals": return "is";
 		case "not": return "is not";
@@ -256,7 +279,7 @@ function describeComparison(comparison) {
 	}
 }
 /**
-* Render a structured or scalar expected value display-neutrally.
+* Renders a structured or scalar expected value display-neutrally.
 *
 * @remarks
 * An array renders as its elements, each `String`-coerced, joined with `', '`.
@@ -271,14 +294,14 @@ function describeComparison(comparison) {
 *
 * @example
 * ```ts
-* import { describeValue } from '@orkestrel/qualifier'
+* import { renderValue } from '@orkestrel/qualifier'
 *
-* describeValue([18, 25, 40]) // '18, 25, 40'
-* describeValue({ minimum: 18, maximum: 65 }) // '18 and 65'
-* describeValue(42) // '42'
+* renderValue([18, 25, 40]) // '18, 25, 40'
+* renderValue({ minimum: 18, maximum: 65 }) // '18 and 65'
+* renderValue(42) // '42'
 * ```
 */
-function describeValue(value) {
+function renderValue(value) {
 	if (Array.isArray(value)) return value.map((entry) => String(entry)).join(", ");
 	if (isBounds(value)) {
 		const sides = [];
@@ -289,7 +312,7 @@ function describeValue(value) {
 	return String(value);
 }
 /**
-* Render one {@link Premise} into a display-neutral sentence.
+* Renders one {@link Premise} into a display-neutral sentence.
 *
 * @remarks
 * The checked form renders only when `field` and `comparison` are BOTH
@@ -302,25 +325,25 @@ function describeValue(value) {
 *
 * @example
 * ```ts
-* import { describePremise } from '@orkestrel/qualifier'
+* import { renderPremise } from '@orkestrel/qualifier'
 *
-* describePremise({ field: 'age', comparison: 'above', expected: 18, actual: 25, met: true })
+* renderPremise({ field: 'age', comparison: 'above', expected: 18, actual: 25, met: true })
 * // 'age is more than 18 → met'
 *
-* describePremise({ description: 'Applicant is enrolled', met: true })
+* renderPremise({ description: 'Applicant is enrolled', met: true })
 * // 'Applicant is enrolled → met'
 * ```
 */
-function describePremise(entry, labels) {
+function renderPremise(entry, labels) {
 	const status = entry.met === void 0 ? "unknown" : entry.met ? "met" : "not met";
 	if (entry.field === void 0 || entry.comparison === void 0) return `${entry.description ?? "Premise"} → ${status}`;
 	const field = formatField(entry.field);
 	const label = labels?.[field] ?? entry.label ?? field;
-	const expected = entry.expected === void 0 ? "" : ` ${describeValue(entry.expected)}`;
-	return `${label} ${describeComparison(entry.comparison)}${expected} → ${status}`;
+	const expected = entry.expected === void 0 ? "" : ` ${renderValue(entry.expected)}`;
+	return `${label} ${renderComparison(entry.comparison)}${expected} → ${status}`;
 }
 /**
-* Build a {@link Premise} from an authored {@link Check} and its evaluated
+* Builds a {@link Premise} from an authored {@link Check} and its evaluated
 * `CheckResult`.
 *
 * @param check - The authored check
@@ -330,15 +353,15 @@ function describePremise(entry, labels) {
 *
 * @example
 * ```ts
-* import { premiseCheck } from '@orkestrel/qualifier'
-* import { check } from '@orkestrel/reason'
+* import { checkToPremise } from '@orkestrel/qualifier'
+* import { createCheck } from '@orkestrel/reason'
 *
-* const authored = check('age', 'above', 18)
-* premiseCheck(authored, { field: 'age', actual: 25, met: true })
+* const authored = createCheck('age', 'above', 18)
+* checkToPremise(authored, { field: 'age', actual: 25, met: true })
 * // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
 * ```
 */
-function premiseCheck(check, result, labels) {
+function checkToPremise(check, result, labels) {
 	const field = formatField(check.field);
 	return {
 		field: check.field,
@@ -350,13 +373,13 @@ function premiseCheck(check, result, labels) {
 	};
 }
 /**
-* Build rich premises for one fired {@link Rule} by walking its premise atoms
+* Builds rich premises for one fired {@link Rule} by walking its premise atoms
 * and re-evaluating each against the working subject.
 *
 * @remarks
 * 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 via `extractAtoms`, and each leaf's `Check` is re-evaluated through
+* atom leaves through `extractAtoms`, and each leaf's `Check` is re-evaluated through
 * the injected `evaluator`. A membership check (`any` / `none`) over an EMPTY
 * array value is content-free and is skipped.
 *
@@ -368,29 +391,29 @@ function premiseCheck(check, result, labels) {
 *
 * @example
 * ```ts
-* import { logicalPremises } from '@orkestrel/qualifier'
-* import { atom, createEvaluator, logicalDefinition, rule } from '@orkestrel/reason'
+* import { ruleToPremises } from '@orkestrel/qualifier'
+* import { createAtom, createEvaluator, createLogicalDefinition, createRule } from '@orkestrel/reason'
 *
-* const gates = logicalDefinition('gates', 'Gates', [
-*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* const gates = createLogicalDefinition('gates', 'Gates', [
+*   createRule('licensed', [createAtom('licensed', 'equals', false)], createAtom('blocked', 'equals', true)),
 * ])
 * const evaluator = createEvaluator()
-* const premises = logicalPremises(gates.rules[0], { licensed: false }, evaluator)
+* const premises = ruleToPremises(gates.rules[0], { licensed: false }, evaluator)
 *
 * premises[0]?.met // true
 * ```
 */
-function logicalPremises(rule, working, evaluator, labels) {
+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;
-		output.push(premiseCheck(check, evaluator.evaluate(check, working), labels));
+		output.push(checkToPremise(check, evaluator.evaluate(check, working), labels));
 	}
 	return output;
 }
 /**
-* Locate an authored {@link Rule} by id.
+* Locates an authored {@link Rule} by id.
 *
 * @param definition - The logical definition to search
 * @param id - The rule id
@@ -399,10 +422,10 @@ function logicalPremises(rule, working, evaluator, labels) {
 * @example
 * ```ts
 * import { findRule } from '@orkestrel/qualifier'
-* import { atom, logicalDefinition, rule } from '@orkestrel/reason'
+* import { createAtom, createLogicalDefinition, createRule } from '@orkestrel/reason'
 *
-* const gates = logicalDefinition('gates', 'Gates', [
-*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* const gates = createLogicalDefinition('gates', 'Gates', [
+*   createRule('licensed', [createAtom('licensed', 'equals', false)], createAtom('blocked', 'equals', true)),
 * ])
 *
 * findRule(gates, 'licensed')?.id // 'licensed'
@@ -412,7 +435,7 @@ function findRule(definition, id) {
 	return definition.rules.find((rule) => rule.id === id);
 }
 /**
-* Project one reason result into the internal qualification namespace.
+* Projects one reason result into the internal qualification namespace.
 *
 * @remarks
 * A quantitative result contributes its numeric `value`. A logical result
@@ -427,10 +450,10 @@ function findRule(definition, id) {
 * @example
 * ```ts
 * import { reasonResultToProjection } from '@orkestrel/qualifier'
-* import { factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
+* import { createFactorGroup, createQuantitativeDefinition, createStaticFactor } from '@orkestrel/reason'
 *
-* const cap = quantitativeDefinition('cap', 'TIV cap', [
-*   factorGroup('limit', 'sum', [staticFactor('base', 500_000)]),
+* const cap = createQuantitativeDefinition('cap', 'TIV cap', [
+*   createFactorGroup('limit', 'sum', [createStaticFactor('base', 500_000)]),
 * ])
 * const result = {
 *   reasoning: 'quantitative' as const,
@@ -458,7 +481,7 @@ function reasonResultToProjection(definition, result) {
 	return projection;
 }
 /**
-* Project a quantitative result into a {@link Derivation} audit record.
+* Projects a quantitative result into a {@link Derivation} audit record.
 *
 * @param id - The pass id
 * @param result - The evaluated quantitative result
@@ -483,7 +506,7 @@ function quantitativeResultToDerivation(id, result) {
 	};
 }
 /**
-* Wrap a {@link QualificationContext} under {@link QUALIFICATION_KEY}.
+* Wraps a {@link QualificationContext} under {@link QUALIFICATION_KEY}.
 *
 * @param context - The accumulated projection context
 * @returns A record carrying the context under the reserved key
@@ -499,7 +522,7 @@ function qualificationToRecord(context) {
 	return { [QUALIFICATION_KEY]: context };
 }
 /**
-* Copy-on-write merge one pass projection into the context.
+* Merges one pass projection into the context, copy-on-write.
 *
 * @param context - The current projection context
 * @param id - The pass id to project under
@@ -521,7 +544,7 @@ function mergeQualificationContext(context, id, projection) {
 	};
 }
 /**
-* Join a ruling, its logical rule result, the pass, the pre-projection subject,
+* Joins a ruling, its logical rule result, the pass, the pre-projection subject,
 * and an evaluator into a {@link Finding}.
 *
 * @remarks
@@ -541,22 +564,22 @@ function mergeQualificationContext(context, id, projection) {
 * @example
 * ```ts
 * import { rulingToFinding } from '@orkestrel/qualifier'
-* import { atom, createEvaluator, logicalDefinition, rule } from '@orkestrel/reason'
+* import { createAtom, createEvaluator, createLogicalDefinition, createRule } from '@orkestrel/reason'
 *
-* const gates = logicalDefinition('gates', 'Gates', [
-*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* const gates = createLogicalDefinition('gates', 'Gates', [
+*   createRule('licensed', [createAtom('licensed', 'equals', false)], createAtom('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 result = { reasoning: 'logical' as const, conclusion: true, rules: [{ id: 'licensed', applied: true, premises: [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;
+	const applied = result.rules.find((resolved) => resolved.id === ruling.rule)?.applied ?? false;
 	const rule = pass.reasoning === "logical" ? findRule(pass, ruling.rule) : void 0;
-	const premises = rule === void 0 ? [] : logicalPremises(rule, subject, evaluator, labels);
+	const premises = rule === void 0 ? [] : ruleToPremises(rule, subject, evaluator, labels);
 	return {
 		id: ruling.id,
 		pass: ruling.pass,
@@ -569,7 +592,7 @@ function rulingToFinding(ruling, pass, result, subject, evaluator, labels) {
 	};
 }
 /**
-* Derive global eligibility from applied, unscoped findings.
+* Derives global eligibility from applied, unscoped findings.
 *
 * @remarks
 * Only findings that both applied and carry no `scope` shape global eligibility.
@@ -577,7 +600,8 @@ function rulingToFinding(ruling, pass, result, subject, evaluator, labels) {
 * `failed`.
 *
 * @param findings - The resolved findings
-* @param failed - Whether an operational pass failure occurred
+* @param failed - If `true`, adds a synthetic `referral` impact so an operational failure
+* fails closed; if `false`, derives eligibility from the findings alone. Default: `false`
 * @returns The most severe global eligibility
 *
 * @example
@@ -594,7 +618,7 @@ function deriveFindingEligibility(findings, failed = false) {
 	return combineEligibilities(eligibilities);
 }
 /**
-* Return the most severe {@link Eligibility} in a list.
+* Returns the most severe {@link Eligibility} in a list.
 *
 * @param eligibilities - The eligibilities to combine
 * @returns The most severe eligibility, or `'eligible'` for an empty list
@@ -611,7 +635,7 @@ function combineEligibilities(eligibilities) {
 	return "eligible";
 }
 /**
-* Derive one eligibility per finding scope.
+* Derives one eligibility per finding scope.
 *
 * @remarks
 * Only applied, scoped findings contribute. Each named scope combines its own
@@ -641,29 +665,29 @@ function deriveScopeEligibilities(findings) {
 	return scopes;
 }
 /**
-* Find rulings whose pass or rule does not exist, whose pass is not logical, or
-* a pass id shadowing the reserved {@link QUALIFICATION_KEY}.
+* Describes each ruling whose pass or rule does not exist or whose pass is not
+* logical, and each pass id shadowing the reserved {@link QUALIFICATION_KEY}.
 *
 * @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'
+* import { createQualificationDefinition, createRuling, describeMissingReferences } from '@orkestrel/qualifier'
+* import { createAtom, createLogicalDefinition, createRule } from '@orkestrel/reason'
 *
-* const gates = logicalDefinition('gates', 'Gates', [
-*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* const gates = createLogicalDefinition('gates', 'Gates', [
+*   createRule('licensed', [createAtom('licensed', 'equals', false)], createAtom('blocked', 'equals', true)),
 * ])
-* const definition = qualificationDefinition('standard', 'Standard', [gates], {
-*   rulings: [rulingDefinition('license', 'gates', 'absent', 'restriction')],
+* const definition = createQualificationDefinition('standard', 'Standard', [gates], {
+*   rulings: [createRuling('license', 'gates', 'absent', 'restriction')],
 * })
 *
-* findMissingReferences(definition)
+* describeMissingReferences(definition)
 * // ["Ruling 'license' references missing rule 'absent' in pass 'gates'"]
 * ```
 */
-function findMissingReferences(definition) {
+function describeMissingReferences(definition) {
 	const errors = [];
 	const passes = new Map(definition.passes.map((pass) => [pass.id, pass]));
 	for (const pass of definition.passes) if (pass.id === "qualification") errors.push(`Pass id must not equal reserved key '${QUALIFICATION_KEY}'`);
@@ -682,10 +706,10 @@ function findMissingReferences(definition) {
 	return errors;
 }
 /**
-* Determine whether a subject already owns the reserved {@link QUALIFICATION_KEY}.
+* Determines 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
+* @returns True if the subject owns the reserved key; false otherwise
 *
 * @example
 * ```ts
@@ -698,7 +722,7 @@ function hasReservedKey(subject) {
 	return Object.hasOwn(subject, QUALIFICATION_KEY);
 }
 /**
-* Assert a value is a valid qualification {@link Subject}, narrowing it in place.
+* Asserts a value is a valid qualification {@link Subject}, narrowing it in place.
 *
 * @param value - The candidate subject to validate
 * @throws {@link QualifierError} `'MISMATCH'` when the value is not a record, or
@@ -716,12 +740,12 @@ function assertSubject(value) {
 	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}.
+* Maps 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
+* every other `ReasonError` code (for example `MISSING`) and every non-`ReasonError` throw
 * (including a `bail: true` reasoner rethrow) maps to `ENGINE`. The original throw
 * is preserved as `context.cause`.
 *
@@ -758,7 +782,7 @@ function mapEngineError(error, pass) {
 	});
 }
 /**
-* Find logical passes carrying no rulings.
+* Describes each logical pass carrying no rulings.
 *
 * @remarks
 * A logical pass with no matching ruling can never contribute a finding, so its
@@ -770,18 +794,18 @@ function mapEngineError(error, pass) {
 *
 * @example
 * ```ts
-* import { findEmptyLogicalPasses, qualificationDefinition } from '@orkestrel/qualifier'
-* import { atom, logicalDefinition, rule } from '@orkestrel/reason'
+* import { createQualificationDefinition, describeEmptyLogicalPasses } from '@orkestrel/qualifier'
+* import { createAtom, createLogicalDefinition, createRule } from '@orkestrel/reason'
 *
-* const gates = logicalDefinition('gates', 'Gates', [
-*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* const gates = createLogicalDefinition('gates', 'Gates', [
+*   createRule('licensed', [createAtom('licensed', 'equals', false)], createAtom('blocked', 'equals', true)),
 * ])
-* const definition = qualificationDefinition('standard', 'Standard', [gates])
+* const definition = createQualificationDefinition('standard', 'Standard', [gates])
 *
-* findEmptyLogicalPasses(definition) // ["Logical pass 'gates' has no rulings"]
+* describeEmptyLogicalPasses(definition) // ["Logical pass 'gates' has no rulings"]
 * ```
 */
-function findEmptyLogicalPasses(definition) {
+function describeEmptyLogicalPasses(definition) {
 	const warnings = [];
 	for (const pass of definition.passes) {
 		if (pass.reasoning !== "logical") continue;
@@ -790,7 +814,7 @@ function findEmptyLogicalPasses(definition) {
 	return warnings;
 }
 /**
-* Find quantitative passes never read by a later pass.
+* Describes each quantitative pass never read by a later pass.
 *
 * @remarks
 * A quantitative pass's projected value lives under `qualification.<id>` — if no
@@ -804,18 +828,18 @@ function findEmptyLogicalPasses(definition) {
 *
 * @example
 * ```ts
-* import { findUnreadDerivations, qualificationDefinition } from '@orkestrel/qualifier'
-* import { factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
+* import { createQualificationDefinition, describeUnreadDerivations } from '@orkestrel/qualifier'
+* import { createFactorGroup, createQuantitativeDefinition, createStaticFactor } from '@orkestrel/reason'
 *
-* const cap = quantitativeDefinition('cap', 'TIV cap', [
-*   factorGroup('limit', 'sum', [staticFactor('base', 500_000)]),
+* const cap = createQuantitativeDefinition('cap', 'TIV cap', [
+*   createFactorGroup('limit', 'sum', [createStaticFactor('base', 500_000)]),
 * ])
-* const definition = qualificationDefinition('standard', 'Standard', [cap])
+* const definition = createQualificationDefinition('standard', 'Standard', [cap])
 *
-* findUnreadDerivations(definition) // ["Quantitative pass 'cap' is never read by a later pass"]
+* describeUnreadDerivations(definition) // ["Quantitative pass 'cap' is never read by a later pass"]
 * ```
 */
-function findUnreadDerivations(definition) {
+function describeUnreadDerivations(definition) {
 	const warnings = [];
 	definition.passes.forEach((pass, index) => {
 		if (pass.reasoning !== "quantitative") return;
@@ -832,69 +856,10 @@ function findUnreadDerivations(definition) {
 	});
 	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
-* eligibility.
+* Runs ordered passes over one reason engine and returns eligibility.
 *
 * @remarks
 * The engine is OWNED when self-created (destroyed on `destroy()`) and borrowed
@@ -924,17 +889,92 @@ var Qualifier = class {
 		this.#validate = options?.validate ?? true;
 		this.#labels = options?.labels;
 	}
+	/**
+	* Holds the typed observation surface carrying `derive`, `finding`, `qualify`, and
+	* `destroy`.
+	*
+	* @returns The emitter this qualifier owns
+	*
+	* @example
+	* ```ts
+	* import { Qualifier } from '@orkestrel/qualifier'
+	*
+	* const qualifier = new Qualifier()
+	* qualifier.emitter.on('qualify', (result) => console.log(result.eligibility))
+	* qualifier.destroy()
+	* ```
+	*/
 	get emitter() {
 		return this.#emitter;
 	}
+	/**
+	* Qualifies one subject against one authored definition.
+	*
+	* @remarks
+	* Semantic validation runs first when the `validate` option is on, so an invalid
+	* definition throws before any pass runs. Passes run in authored order over a
+	* copy-on-write working subject, and the caller's `subject` is never mutated. An
+	* unscoped restriction stops the remaining passes because no later finding can be
+	* more severe.
+	*
+	* @param subject - The record to qualify
+	* @param definition - The authored qualification definition
+	* @returns A fresh, frozen qualification result
+	* @throws {@link QualifierError} `'DEFINITION'` when validation is enabled and the
+	* definition fails semantic validation, or when the engine rejects a pass as an invalid
+	* definition; `'MISMATCH'` when the subject is not a record or already carries the
+	* reserved `qualification` key; `'DESTROYED'` after `destroy`, or when the engine
+	* reports itself destroyed mid-pass; `'ENGINE'` for every other engine throw
+	*
+	* @example
+	* ```ts
+	* import { createQualificationDefinition, createRuling, Qualifier } 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 definition = createQualificationDefinition('standard', 'Standard eligibility', [gates], {
+	*   rulings: [createRuling('license', 'gates', 'licensed', 'restriction')],
+	* })
+	*
+	* const qualifier = new Qualifier()
+	* qualifier.qualify({ id: 'risk-1', licensed: false }, definition).eligibility // 'ineligible'
+	* qualifier.destroy()
+	* ```
+	*/
 	qualify(subject, definition) {
 		this.#alive();
 		if (this.#validate) {
 			const validation = this.validate(definition);
-			if (!validation.valid) throw new QualifierError("DEFINITION", `Qualification definition is invalid: ${validation.errors.join(", ")}`, definition.id);
+			if (!validation.valid) throw new QualifierError("DEFINITION", `Qualification definition is invalid: ${validation.errors.join(", ")}`, { definition: definition.id });
 		}
 		return this.#qualify(subject, definition);
 	}
+	/**
+	* Validates one authored definition semantically, without running it.
+	*
+	* @remarks
+	* Structural shape is `isQualificationDefinition`'s job. This checks the meaning:
+	* non-empty id and name, valid and uniquely identified passes and rulings, every
+	* ruling reference resolving to a logical pass and one of its rules, and no pass id
+	* shadowing `QUALIFICATION_KEY`. An empty definition, a logical pass carrying no
+	* ruling, and a derivation no later pass reads are warnings rather than errors.
+	*
+	* @param definition - The authored qualification definition
+	* @returns A fresh validation result carrying `valid`, `errors`, and `warnings`
+	* @throws {@link QualifierError} `'DESTROYED'` after `destroy`
+	*
+	* @example
+	* ```ts
+	* import { createQualificationDefinition, Qualifier } from '@orkestrel/qualifier'
+	*
+	* const qualifier = new Qualifier()
+	* qualifier.validate(createQualificationDefinition('empty', 'Empty', []))
+	* // { valid: true, errors: [], warnings: ['Definition has no passes'] }
+	* qualifier.destroy()
+	* ```
+	*/
 	validate(definition) {
 		this.#alive();
 		const errors = [];
@@ -949,16 +989,33 @@ var Qualifier = class {
 		});
 		for (const id of findDuplicates(definition.passes)) errors.push(`Duplicate pass id '${id}'`);
 		for (const id of findDuplicates(definition.rulings ?? [])) errors.push(`Duplicate ruling id '${id}'`);
-		for (const reference of findMissingReferences(definition)) errors.push(reference);
+		for (const reference of describeMissingReferences(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);
+		for (const warning of describeEmptyLogicalPasses(definition)) warnings.push(warning);
+		for (const warning of describeUnreadDerivations(definition)) warnings.push(warning);
 		return {
 			valid: errors.length === 0,
 			errors,
 			warnings
 		};
 	}
+	/**
+	* Destroys this qualifier, idempotently.
+	*
+	* @remarks
+	* An engine this qualifier created is destroyed; an injected engine stays
+	* caller-owned and is left alone. The `destroy` event fires before the emitter
+	* itself is destroyed, and a later call returns without re-emitting.
+	*
+	* @example
+	* ```ts
+	* import { Qualifier } from '@orkestrel/qualifier'
+	*
+	* const qualifier = new Qualifier()
+	* qualifier.destroy()
+	* qualifier.destroy() // idempotent
+	* ```
+	*/
 	destroy() {
 		if (this.#destroyed) return;
 		if (this.#owned) this.#engine.destroy();
@@ -1034,12 +1091,15 @@ var Qualifier = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create one qualifier over a reason engine.
+* Creates one qualifier over a reason engine.
 *
 * @remarks
 * 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. Validation is on by default.
+* remains caller-owned and is never destroyed. `validate` runs semantic
+* validation before every qualification. Default: `true`. `labels` overrides the
+* display name of a premise field, keyed by the dot-joined field path
+* `formatField` produces, and takes precedence over a premise's own `label`.
 *
 * @param options - Optional injected engine, validation, labels, and emitter hooks
 * @returns A {@link QualifierInterface}
@@ -1056,7 +1116,65 @@ var Qualifier = class {
 function createQualifier(options) {
 	return new Qualifier(options);
 }
+/**
+* Creates 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 { createQualificationDefinition } from '@orkestrel/qualifier'
+*
+* createQualificationDefinition('standard', 'Standard', [gates], { rulings: [ruling] })
+* ```
+*/
+function createQualificationDefinition(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 } }
+	};
+}
+/**
+* Creates 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 { createRuling } from '@orkestrel/qualifier'
+*
+* createRuling('license', 'gates', 'licensed', 'restriction', { message: 'A license is required' })
+* ```
+*/
+function createRuling(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
-export { DEFAULT_QUALIFIER_VALIDATE, EFFECT_ELIGIBILITIES, ELIGIBILITY_PRECEDENCE, QUALIFICATION_KEY, Qualifier, QualifierError, assertSubject, combineEligibilities, createQualifier, deriveFindingEligibility, deriveScopeEligibilities, describeComparison, describePremise, describeValue, findEmptyLogicalPasses, findMissingReferences, findRule, findUnreadDerivations, hasReservedKey, interpolateMessage, isDerivation, isEligibility, isEligibilityRecord, isFinding, isPremise, isQualificationDefinition, isQualificationEffect, isQualificationPass, isQualificationResult, isQualificationValidationResult, isQualifierError, isRuling, logicalPremises, mapEngineError, mergeQualificationContext, premiseCheck, qualificationDefinition, qualificationToRecord, quantitativeResultToDerivation, reasonResultToProjection, rulingDefinition, rulingToFinding };
+export { DEFAULT_QUALIFIER_VALIDATE, EFFECT_ELIGIBILITIES, ELIGIBILITY_PRECEDENCE, QUALIFICATION_KEY, Qualifier, QualifierError, assertSubject, checkToPremise, combineEligibilities, createQualificationDefinition, createQualifier, createRuling, deriveFindingEligibility, deriveScopeEligibilities, describeEmptyLogicalPasses, describeMissingReferences, describeUnreadDerivations, findRule, hasReservedKey, interpolateMessage, isDerivation, isEligibility, isEligibilityRecord, isFinding, isPremise, isQualificationDefinition, isQualificationEffect, isQualificationPass, isQualificationResult, isQualifierError, isRuling, mapEngineError, mergeQualificationContext, qualificationToRecord, quantitativeResultToDerivation, reasonResultToProjection, renderComparison, renderPremise, renderValue, ruleToPremises, rulingToFinding };
 
 //# sourceMappingURL=index.js.map