@orkestrel/qualifier 0.0.13 → 0.0.14

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

@@ -1,22 +1,22 @@
-import { Check } from '@orkestrel/reason';
-import { CheckResult } from '@orkestrel/reason';
-import { Comparison } from '@orkestrel/reason';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { EvaluatorInterface } from '@orkestrel/reason';
-import { FieldPath } from '@orkestrel/contract';
+import type { Check } from '@orkestrel/reason';
+import type { CheckResult } from '@orkestrel/reason';
+import type { Comparison } from '@orkestrel/reason';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { EvaluatorInterface } from '@orkestrel/reason';
+import type { FieldPath } from '@orkestrel/contract';
 import { Guard } from '@orkestrel/contract';
-import { JSONValue } from '@orkestrel/contract';
-import { LogicalDefinition } from '@orkestrel/reason';
-import { LogicalResult } from '@orkestrel/reason';
-import { QuantitativeDefinition } from '@orkestrel/reason';
-import { QuantitativeResult } from '@orkestrel/reason';
-import { ReasonInterface } from '@orkestrel/reason';
-import { ReasonResult } from '@orkestrel/reason';
-import { ReasonValidationResult } from '@orkestrel/reason';
-import { Rule } from '@orkestrel/reason';
-import { Subject } from '@orkestrel/reason';
+import type { JSONValue } from '@orkestrel/contract';
+import type { LogicalDefinition } from '@orkestrel/reason';
+import type { LogicalResult } from '@orkestrel/reason';
+import type { QuantitativeDefinition } from '@orkestrel/reason';
+import type { QuantitativeResult } from '@orkestrel/reason';
+import type { ReasonInterface } from '@orkestrel/reason';
+import type { ReasonResult } from '@orkestrel/reason';
+import type { ReasonValidationResult } from '@orkestrel/reason';
+import type { Rule } from '@orkestrel/reason';
+import type { Subject } from '@orkestrel/reason';
 
 /**
  * Asserts a value is a valid qualification {@link Subject}, narrowing it in place.
@@ -71,10 +71,9 @@ import { Subject } from '@orkestrel/reason';
  export declare function combineEligibilities(eligibilities: readonly Eligibility[]): Eligibility;
 
  /**
-  * 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.
   *
@@ -94,10 +93,10 @@ import { Subject } from '@orkestrel/reason';
  export declare function createQualificationDefinition(id: string, name: string, passes: readonly QualificationPass[], input?: QualificationInput): QualificationDefinition;
 
  /**
-  * 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
@@ -107,19 +106,44 @@ import { Subject } from '@orkestrel/reason';
   * @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()
   * ```
   */
  export declare function createQualifier(options?: QualifierOptions): QualifierInterface;
 
  /**
-  * 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
@@ -137,7 +161,10 @@ import { Subject } from '@orkestrel/reason';
   */
  export declare function createRuling(id: string, pass: string, rule: string, effect: QualificationEffect, input?: RulingInput): Ruling;
 
- /** Holds the default definition validation policy for `createQualifier` / `Qualifier.qualify`. */
+ /**
+  * Holds the default definition validation policy for `createQualifier` and
+  * `Qualifier.qualify`, `true`.
+  */
  export declare const DEFAULT_QUALIFIER_VALIDATE = true;
 
  /** Represents one quantitative pass's audit result. */
@@ -272,13 +299,16 @@ import { Subject } from '@orkestrel/reason';
   */
  export declare function describeUnreadDerivations(definition: QualificationDefinition): readonly string[];
 
- /** 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`.
+  */
  export declare const EFFECT_ELIGIBILITIES: Readonly<Record<QualificationEffect, Eligibility>>;
 
  /** Represents the eligibility outcome axis. */
  export declare type Eligibility = 'eligible' | 'ineligible' | 'referral';
 
- /** Lists the eligibility severities in order — most to least severe. */
+ /** Lists the eligibility severities most to least severe: `ineligible`, `referral`, `eligible`. */
  export declare const ELIGIBILITY_PRECEDENCE: readonly Eligibility[];
 
  /** Represents one resolved ruling. */
@@ -334,10 +364,10 @@ import { Subject } from '@orkestrel/reason';
   *
   * @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
@@ -357,8 +387,10 @@ import { Subject } from '@orkestrel/reason';
   * 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
@@ -368,6 +400,10 @@ import { Subject } from '@orkestrel/reason';
  /**
   * 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
   */
@@ -377,8 +413,9 @@ import { Subject } from '@orkestrel/reason';
   * 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
@@ -390,8 +427,10 @@ import { Subject } from '@orkestrel/reason';
   * 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
@@ -402,9 +441,11 @@ import { Subject } from '@orkestrel/reason';
   * 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
@@ -414,6 +455,11 @@ import { Subject } from '@orkestrel/reason';
  /**
   * 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
   */
@@ -422,6 +468,10 @@ import { Subject } from '@orkestrel/reason';
  /**
   * 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
   */
@@ -430,6 +480,11 @@ import { Subject } from '@orkestrel/reason';
  /**
   * 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
   */
@@ -440,7 +495,10 @@ import { Subject } from '@orkestrel/reason';
   *
   * @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
@@ -458,6 +516,10 @@ import { Subject } from '@orkestrel/reason';
  /**
   * 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
   */
@@ -506,10 +568,13 @@ import { Subject } from '@orkestrel/reason';
  export declare function mergeQualificationContext(context: QualificationContext, id: string, projection: QualificationProjection): QualificationContext;
 
  /**
-  * Represents display-neutral evidence for one condition, in one of two authoring modes.
-  * A CHECKED premise carries `field` and `comparison`; a DESCRIBED premise
+  * Represents display-neutral evidence for one condition, authored as a checked or a
+  * described premise.
+  *
+  * @remarks
+  * A checked premise carries `field` and `comparison`; a described premise
   * carries neither and renders from `description` instead. The checked form
-  * renders only when `field` and `comparison` are BOTH present, and
+  * 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. `met` is three-state: `true`
   * (met), `false` (not met), or absent (not evaluated, rendered as unknown).
@@ -524,7 +589,10 @@ import { Subject } from '@orkestrel/reason';
      readonly met?: boolean;
  }
 
- /** 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.
+  */
  export declare const QUALIFICATION_KEY = "qualification";
 
  /** Represents the internal projection record stored under `QUALIFICATION_KEY`. */
@@ -588,8 +656,9 @@ import { Subject } from '@orkestrel/reason';
   * 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.
   */
@@ -695,7 +764,8 @@ import { Subject } from '@orkestrel/reason';
       }
 
       /**
-       * 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
@@ -827,7 +897,7 @@ import { Subject } from '@orkestrel/reason';
            }
 
            /**
-            * Carries the options for `createQualifier` / the `Qualifier` constructor.
+            * Carries the options for `createQualifier` and the `Qualifier` constructor.
             *
             * @remarks
             * `engine` injects a reason engine that stays caller-owned and is never destroyed; an
@@ -917,7 +987,7 @@ import { Subject } from '@orkestrel/reason';
             * 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.
             *
@@ -946,7 +1016,7 @@ import { Subject } from '@orkestrel/reason';
             * 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
@@ -971,7 +1041,7 @@ import { Subject } from '@orkestrel/reason';
             * 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
@@ -1018,7 +1088,7 @@ import { Subject } from '@orkestrel/reason';
             *
             * @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.
             *

package/dist/src/core/index.js

@@ -2,17 +2,26 @@ import { arrayOf, isBoolean, isFiniteNumber, isNumber, isRecord, isString, liter
 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
@@ -59,6 +69,10 @@ function isQualifierError(value) {
 /**
 * 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
@@ -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
@@ -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.
 *
@@ -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