@orkestrel/qualifier 0.0.12 → 0.0.14

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

@@ -1,25 +1,25 @@
-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';
 
 /**
- * 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
@@ -35,7 +35,28 @@ import { Subject } from '@orkestrel/reason';
  export declare function assertSubject(value: unknown): asserts value is Subject;
 
  /**
-  * Return the most severe {@link Eligibility} in a list.
+  * Builds a {@link Premise} from an authored {@link Check} and its evaluated
+  * `CheckResult`.
+  *
+  * @param check - The authored check
+  * @param result - The evaluated check result carrying the resolved `actual` and `met`
+  * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+  * @returns A fresh premise
+  *
+  * @example
+  * ```ts
+  * import { checkToPremise } from '@orkestrel/qualifier'
+  * import { createCheck } from '@orkestrel/reason'
+  *
+  * const authored = createCheck('age', 'above', 18)
+  * checkToPremise(authored, { field: 'age', actual: 25, met: true })
+  * // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
+  * ```
+  */
+ export declare function checkToPremise(check: Check, result: CheckResult, labels?: Readonly<Record<string, string>>): Premise;
+
+ /**
+  * 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
@@ -47,34 +68,106 @@ import { Subject } from '@orkestrel/reason';
   * combineEligibilities(['eligible', 'referral']) // 'referral'
   * ```
   */
- export declare function combineEligibilities(eligibilities: Eligibility[]): Eligibility;
+ export declare function combineEligibilities(eligibilities: readonly Eligibility[]): Eligibility;
 
  /**
-  * Create one qualifier over a reason engine.
+  * Creates a fresh {@link QualificationDefinition}, omitting every absent optional key.
   *
   * @remarks
-  * A standalone qualifier creates and OWNS one shared quantitative-plus-logical
+  * `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] })
+  * ```
+  */
+ export declare function createQualificationDefinition(id: string, name: string, passes: readonly QualificationPass[], input?: QualificationInput): QualificationDefinition;
+
+ /**
+  * Creates one {@link QualifierInterface} 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}
   *
-  * @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;
 
- /** Default definition validation policy for `createQualifier` / `Qualifier.qualify`. */
+ /**
+  * 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
+  * @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' })
+  * ```
+  */
+ export declare function createRuling(id: string, pass: string, rule: string, effect: QualificationEffect, input?: RulingInput): Ruling;
+
+ /**
+  * Holds the default definition validation policy for `createQualifier` and
+  * `Qualifier.qualify`, `true`.
+  */
  export declare const DEFAULT_QUALIFIER_VALIDATE = true;
 
- /** One quantitative pass's audit result. */
+ /** Represents one quantitative pass's audit result. */
  export declare interface Derivation {
      readonly id: string;
      readonly value: number;
@@ -84,7 +177,7 @@ import { Subject } from '@orkestrel/reason';
  }
 
  /**
-  * 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.
@@ -92,7 +185,8 @@ import { Subject } from '@orkestrel/reason';
   * `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
@@ -103,10 +197,10 @@ import { Subject } from '@orkestrel/reason';
   * deriveFindingEligibility([finding]) // 'ineligible'
   * ```
   */
- export declare function deriveFindingEligibility(findings: Finding[], failed?: boolean): Eligibility;
+ export declare function deriveFindingEligibility(findings: readonly Finding[], failed?: boolean): Eligibility;
 
  /**
-  * Derive one eligibility per finding scope.
+  * Derives one eligibility per finding scope.
   *
   * @remarks
   * Only applied, scoped findings contribute. Each named scope combines its own
@@ -124,109 +218,100 @@ import { Subject } from '@orkestrel/reason';
   * deriveScopeEligibilities([finding]) // { wind: 'ineligible' }
   * ```
   */
- export declare function deriveScopeEligibilities(findings: Finding[]): Readonly<Record<string, Eligibility>>;
+ export declare function deriveScopeEligibilities(findings: readonly Finding[]): Readonly<Record<string, Eligibility>>;
 
  /**
-  * Describe 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'
-  *
-  * describeComparison('above') // 'is more than'
-  * ```
-  */
- export declare function describeComparison(comparison: NonNullable<Premise['comparison']>): string;
-
- /**
-  * Render one {@link Premise} into a display-neutral sentence.
+  * Describes each logical pass carrying no rulings.
   *
   * @remarks
-  * 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.
+  * A logical pass with no matching ruling can never contribute a finding, so its
+  * rules only ever influence later passes' reads — this is very likely an authoring
+  * oversight.
   *
-  * @param entry - The premise to render
-  * @param labels - Optional field-to-label overrides, keyed by dot-joined field
-  * @returns A display-neutral sentence
+  * @param definition - The qualification definition to check
+  * @returns A fresh list of warning messages
   *
   * @example
   * ```ts
-  * import { describePremise } from '@orkestrel/qualifier'
+  * import { createQualificationDefinition, describeEmptyLogicalPasses } from '@orkestrel/qualifier'
+  * import { createAtom, createLogicalDefinition, createRule } from '@orkestrel/reason'
   *
-  * describePremise({ field: 'age', comparison: 'above', expected: 18, actual: 25, met: true })
-  * // 'age is more than 18 → met'
+  * const gates = createLogicalDefinition('gates', 'Gates', [
+  *   createRule('licensed', [createAtom('licensed', 'equals', false)], createAtom('blocked', 'equals', true)),
+  * ])
+  * const definition = createQualificationDefinition('standard', 'Standard', [gates])
   *
-  * describePremise({ description: 'Applicant is enrolled', met: true })
-  * // 'Applicant is enrolled → met'
+  * describeEmptyLogicalPasses(definition) // ["Logical pass 'gates' has no rulings"]
   * ```
   */
- export declare function describePremise(entry: Premise, labels?: Readonly<Record<string, string>>): string;
+ export declare function describeEmptyLogicalPasses(definition: QualificationDefinition): readonly string[];
 
  /**
-  * Render a structured or scalar expected value display-neutrally.
+  * 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}.
   *
-  * @remarks
-  * An array renders as its elements, each `String`-coerced, joined with `', '`.
-  * 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
-  * message-token-only behavior).
-  *
-  * @param value - The value to render
-  * @returns A display-neutral rendering
+  * @param definition - The qualification definition to check
+  * @returns A fresh list of reference-error messages
   *
   * @example
   * ```ts
-  * import { describeValue } from '@orkestrel/qualifier'
+  * import { createQualificationDefinition, createRuling, describeMissingReferences } from '@orkestrel/qualifier'
+  * import { createAtom, createLogicalDefinition, createRule } from '@orkestrel/reason'
+  *
+  * const gates = createLogicalDefinition('gates', 'Gates', [
+  *   createRule('licensed', [createAtom('licensed', 'equals', false)], createAtom('blocked', 'equals', true)),
+  * ])
+  * const definition = createQualificationDefinition('standard', 'Standard', [gates], {
+  *   rulings: [createRuling('license', 'gates', 'absent', 'restriction')],
+  * })
   *
-  * describeValue([18, 25, 40]) // '18, 25, 40'
-  * describeValue({ minimum: 18, maximum: 65 }) // '18 and 65'
-  * describeValue(42) // '42'
+  * describeMissingReferences(definition)
+  * // ["Ruling 'license' references missing rule 'absent' in pass 'gates'"]
   * ```
   */
- export declare function describeValue(value: unknown): string;
-
- /** The eligibility impact of each {@link QualificationEffect}; `condition` remains eligible. */
- export declare const EFFECT_ELIGIBILITIES: Readonly<Record<QualificationEffect, Eligibility>>;
-
- /** The eligibility outcome axis. */
- export declare type Eligibility = 'eligible' | 'ineligible' | 'referral';
-
- /** Eligibility severity order — most to least severe. */
- export declare const ELIGIBILITY_PRECEDENCE: readonly Eligibility[];
+ export declare function describeMissingReferences(definition: QualificationDefinition): readonly string[];
 
  /**
-  * Find logical passes carrying no rulings.
+  * Describes each quantitative pass never read by a later pass.
   *
   * @remarks
-  * A logical pass with no matching ruling can never contribute a finding, so its
-  * rules only ever influence later passes' reads — this is very likely an authoring
-  * oversight.
+  * A quantitative pass's projected value lives under `qualification.<id>` — if no
+  * later logical premise or quantitative factor field reads that key, the
+  * derivation is dead weight. Reads are collected per later pass: a logical pass's
+  * premise atoms (conclusion atoms are writes, not reads), and a quantitative
+  * pass's field/lookup/range factor sources plus factor checks.
   *
   * @param definition - The qualification definition to check
   * @returns A fresh list of warning messages
   *
   * @example
   * ```ts
-  * import { findEmptyLogicalPasses, qualificationDefinition } from '@orkestrel/qualifier'
-  * import { atom, logicalDefinition, rule } from '@orkestrel/reason'
+  * import { createQualificationDefinition, describeUnreadDerivations } from '@orkestrel/qualifier'
+  * import { createFactorGroup, createQuantitativeDefinition, createStaticFactor } from '@orkestrel/reason'
   *
-  * const gates = logicalDefinition('gates', 'Gates', [
-  *   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+  * const cap = createQuantitativeDefinition('cap', 'TIV cap', [
+  *   createFactorGroup('limit', 'sum', [createStaticFactor('base', 500_000)]),
   * ])
-  * const definition = qualificationDefinition('standard', 'Standard', [gates])
+  * const definition = createQualificationDefinition('standard', 'Standard', [cap])
   *
-  * findEmptyLogicalPasses(definition) // ["Logical pass 'gates' has no rulings"]
+  * describeUnreadDerivations(definition) // ["Quantitative pass 'cap' is never read by a later pass"]
   * ```
   */
- export declare function findEmptyLogicalPasses(definition: QualificationDefinition): readonly string[];
+ export declare function describeUnreadDerivations(definition: QualificationDefinition): readonly string[];
 
- /** One resolved ruling. */
+ /**
+  * 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 most to least severe: `ineligible`, `referral`, `eligible`. */
+ export declare const ELIGIBILITY_PRECEDENCE: readonly Eligibility[];
+
+ /** Represents one resolved ruling. */
  export declare interface Finding {
      readonly id: string;
      readonly pass: string;
@@ -239,32 +324,7 @@ import { Subject } from '@orkestrel/reason';
  }
 
  /**
-  * Find rulings whose pass or rule does not exist, whose pass is not logical, or
-  * a 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'
-  *
-  * const gates = logicalDefinition('gates', 'Gates', [
-  *   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
-  * ])
-  * const definition = qualificationDefinition('standard', 'Standard', [gates], {
-  *   rulings: [rulingDefinition('license', 'gates', 'absent', 'restriction')],
-  * })
-  *
-  * findMissingReferences(definition)
-  * // ["Ruling 'license' references missing rule 'absent' in pass 'gates'"]
-  * ```
-  */
- export declare function findMissingReferences(definition: QualificationDefinition): readonly string[];
-
- /**
-  * 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
@@ -273,10 +333,10 @@ import { Subject } from '@orkestrel/reason';
   * @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'
@@ -285,38 +345,10 @@ import { Subject } from '@orkestrel/reason';
  export declare function findRule(definition: LogicalDefinition, id: string): Rule | undefined;
 
  /**
-  * Find quantitative passes never read by a later pass.
-  *
-  * @remarks
-  * A quantitative pass's projected value lives under `qualification.<id>` — if no
-  * later logical premise or quantitative factor field reads that key, the
-  * derivation is dead weight. Reads are collected per later pass: a logical pass's
-  * premise atoms (conclusion atoms are writes, not reads), and a quantitative
-  * pass's field/lookup/range factor sources plus factor checks.
-  *
-  * @param definition - The qualification definition to check
-  * @returns A fresh list of warning messages
-  *
-  * @example
-  * ```ts
-  * import { findUnreadDerivations, qualificationDefinition } from '@orkestrel/qualifier'
-  * import { factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
-  *
-  * const cap = quantitativeDefinition('cap', 'TIV cap', [
-  *   factorGroup('limit', 'sum', [staticFactor('base', 500_000)]),
-  * ])
-  * const definition = qualificationDefinition('standard', 'Standard', [cap])
-  *
-  * findUnreadDerivations(definition) // ["Quantitative pass 'cap' is never read by a later pass"]
-  * ```
-  */
- export declare function findUnreadDerivations(definition: QualificationDefinition): readonly string[];
-
- /**
-  * 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
@@ -328,14 +360,14 @@ import { Subject } from '@orkestrel/reason';
  export declare function hasReservedKey(subject: Subject): boolean;
 
  /**
-  * 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
-  * `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
@@ -352,138 +384,154 @@ import { Subject } from '@orkestrel/reason';
  export declare function interpolateMessage(template: string, subject: Readonly<Record<string, unknown>>): string;
 
  /**
-  * 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.
+  * 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` when every published derivation member is valid
+  * @returns True if every published derivation member is valid; false otherwise
   */
  export declare function isDerivation(value: unknown): value is Derivation;
 
- /** Determine whether a value is an {@link Eligibility} literal. */
+ /**
+  * 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
+  */
  export declare const isEligibility: Guard<"eligible" | "ineligible" | "referral">;
 
  /**
-  * 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.
+  * 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` 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
   */
  export declare function isEligibilityRecord(value: unknown): value is Readonly<Record<string, Eligibility>>;
 
  /**
-  * 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.
+  * 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` when every published finding member is valid
+  * @returns True if every published finding member is valid; false otherwise
   */
  export declare function isFinding(value: unknown): value is Finding;
 
  /**
-  * 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
-  * `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` when every checked premise member follows its published type
+  * @returns True if every checked premise member follows its published type; false otherwise
   */
  export declare function isPremise(value: unknown): value is Premise;
 
- /** Determine whether a value is an exact {@link QualificationDefinition} record. */
+ /**
+  * 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
+  */
  export declare function isQualificationDefinition(value: unknown): value is QualificationDefinition;
 
- /** Determine whether a value is a {@link QualificationEffect} literal. */
+ /**
+  * 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
+  */
  export declare const isQualificationEffect: Guard<"referral" | "restriction" | "condition">;
 
- /** Determine whether a value is a {@link QualificationPass} (a quantitative or logical definition). */
- export declare function isQualificationPass(value: unknown): value is QualificationPass;
-
  /**
-  * Determine whether a value is an open {@link QualificationResult} returned by a qualifier.
+  * Determines whether a value is a {@link QualificationPass} (a quantitative or logical definition).
   *
   * @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.
+  * 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` when every published qualification-result member is valid
+  * @returns True if `value` is a complete reason quantitative or logical definition; false otherwise
   */
- export declare function isQualificationResult(value: unknown): value is QualificationResult;
+ export declare function isQualificationPass(value: unknown): value is QualificationPass;
 
  /**
-  * Determine whether a value is an open {@link QualificationValidationResult} returned by a qualifier.
+  * Determines whether a value is an open {@link QualificationResult} 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.
+  * This guard is result-postured for values returned through a borrowed qualifier interface. It
+  * 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` when every published qualification-validation-result member is valid
+  * @returns True if every published qualification-result member is valid; false otherwise
   */
- export declare const isQualificationValidationResult: Guard<QualificationValidationResult>;
+ export declare function isQualificationResult(value: unknown): value is QualificationResult;
 
- /** 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
+  */
  export declare function isQualifierError(value: unknown): value is QualifierError;
 
- /** Determine whether a value is an exact {@link Ruling} record. */
- export declare function isRuling(value: unknown): value is Ruling;
-
  /**
-  * Build rich premises for one fired {@link Rule} by walking its premise atoms
-  * and re-evaluating each against the working subject.
+  * Determines whether a value is an exact {@link Ruling} record.
   *
   * @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
-  * the injected `evaluator`. A membership check (`any` / `none`) over an EMPTY
-  * array value is content-free and is skipped.
-  *
-  * @param rule - The authored rule
-  * @param working - The working subject to evaluate against
-  * @param evaluator - The shared reason check evaluator
-  * @param labels - Optional field-to-label overrides, keyed by dot-joined field
-  * @returns A fresh, ordered list of rich premises
-  *
-  * @example
-  * ```ts
-  * import { logicalPremises } from '@orkestrel/qualifier'
-  * import { atom, createEvaluator, logicalDefinition, rule } from '@orkestrel/reason'
-  *
-  * const gates = logicalDefinition('gates', 'Gates', [
-  *   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
-  * ])
-  * const evaluator = createEvaluator()
-  * const premises = logicalPremises(gates.rules[0], { licensed: false }, evaluator)
+  * Every authored ruling member and the complete key set are checked. Nothing is left
+  * unchecked, because this package owns the authored input record.
   *
-  * premises[0]?.met // true
-  * ```
+  * @param value - The value to test
+  * @returns True if `value` carries every ruling member and no unknown key; false otherwise
   */
- export declare function logicalPremises(rule: Rule, working: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): readonly Premise[];
+ export declare function isRuling(value: unknown): value is Ruling;
 
  /**
-  * 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`.
   *
@@ -502,7 +550,7 @@ import { Subject } from '@orkestrel/reason';
  export declare function mapEngineError(error: unknown, pass: string): QualifierError;
 
  /**
-  * 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
@@ -520,10 +568,13 @@ import { Subject } from '@orkestrel/reason';
  export declare function mergeQualificationContext(context: QualificationContext, id: string, projection: QualificationProjection): QualificationContext;
 
  /**
-  * 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).
@@ -539,33 +590,15 @@ import { Subject } from '@orkestrel/reason';
  }
 
  /**
-  * Build a {@link Premise} from an authored {@link Check} and its evaluated
-  * `CheckResult`.
-  *
-  * @param check - The authored check
-  * @param result - The evaluated check result carrying the resolved `actual` and `met`
-  * @param labels - Optional field-to-label overrides, keyed by dot-joined field
-  * @returns A fresh premise
-  *
-  * @example
-  * ```ts
-  * import { premiseCheck } from '@orkestrel/qualifier'
-  * import { check } from '@orkestrel/reason'
-  *
-  * const authored = check('age', 'above', 18)
-  * premiseCheck(authored, { field: 'age', actual: 25, met: true })
-  * // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
-  * ```
+  * Names `'qualification'`, the reserved internal projection namespace a pass's working
+  * projection is written under.
   */
- export declare function premiseCheck(check: Check, result: CheckResult, labels?: Readonly<Record<string, string>>): Premise;
-
- /** The reserved internal projection namespace a pass's working projection is written under. */
  export declare const QUALIFICATION_KEY = "qualification";
 
- /** The internal projection record stored under `QUALIFICATION_KEY`. */
+ /** Represents the internal projection record stored under `QUALIFICATION_KEY`. */
  export declare type QualificationContext = Readonly<Record<string, QualificationProjection>>;
 
- /** A pure authored qualification definition. */
+ /** Represents a pure authored qualification definition. */
  export declare interface QualificationDefinition {
      readonly id: string;
      readonly name: string;
@@ -575,46 +608,23 @@ import { Subject } from '@orkestrel/reason';
      readonly metadata?: Readonly<Record<string, JSONValue>>;
  }
 
- /**
-  * 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] })
-  * ```
-  */
- export declare function qualificationDefinition(id: string, name: string, passes: QualificationPass[], input?: QualificationInput): QualificationDefinition;
-
- /** An authored ruling's eligibility impact. */
+ /** Represents an authored ruling's eligibility impact. */
  export declare type QualificationEffect = 'restriction' | 'referral' | 'condition';
 
- /** Optional fields accepted by `qualificationDefinition`. */
+ /** Carries the optional fields `createQualificationDefinition` accepts. */
  export declare interface QualificationInput {
      readonly description?: string;
      readonly rulings?: readonly Ruling[];
      readonly metadata?: Readonly<Record<string, JSONValue>>;
  }
 
- /** One ordered derivation or rule pass. */
+ /** Represents one ordered derivation or rule pass. */
  export declare type QualificationPass = QuantitativeDefinition | LogicalDefinition;
 
- /** One pass's internal working projection. */
+ /** Represents one pass's internal working projection. */
  export declare type QualificationProjection = number | boolean | Readonly<Record<string, unknown>>;
 
- /** One subject's complete qualification outcome. */
+ /** Represents one subject's complete qualification outcome. */
  export declare interface QualificationResult {
      readonly id: string;
      readonly name: string;
@@ -628,7 +638,7 @@ import { Subject } from '@orkestrel/reason';
  }
 
  /**
-  * 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
@@ -642,193 +652,469 @@ import { Subject } from '@orkestrel/reason';
   */
  export declare function qualificationToRecord(context: QualificationContext): Readonly<Record<string, QualificationContext>>;
 
- /** Semantic definition validation. */
- export declare type QualificationValidationResult = ReasonValidationResult;
-
  /**
-  * 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
-  * 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.
   */
  export declare class Qualifier implements QualifierInterface {
      #private;
      constructor(options?: QualifierOptions);
+     /**
+      * 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(): EmitterInterface<QualifierEventMap>;
-     qualify(subject: Subject, definition: QualificationDefinition): QualificationResult;
-     validate(definition: QualificationDefinition): QualificationValidationResult;
-     destroy(): void;
- }
+     /**
+      * 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: Subject, definition: QualificationDefinition): QualificationResult;
+      /**
+       * 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: QualificationDefinition): ReasonValidationResult;
+       /**
+        * 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(): void;
+      }
 
- /**
-  * 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`).
-  */
- export declare class QualifierError extends Error {
-     readonly code: QualifierErrorCode;
-     readonly context: unknown;
-     constructor(code: QualifierErrorCode, message: string, context?: unknown);
- }
+      /**
+       * 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
+       * `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.
+       */
+      export declare class QualifierError extends Error {
+          readonly code: QualifierErrorCode;
+          readonly context: QualifierErrorContext | undefined;
+          constructor(code: QualifierErrorCode, message: string, context?: QualifierErrorContext);
+      }
 
- /** A coded {@link QualifierError} programmer-error code. */
- export declare type QualifierErrorCode = 'DEFINITION' | 'MISMATCH' | 'DESTROYED' | 'ENGINE';
-
- /** The push observation surface of a {@link QualifierInterface} (AGENTS §13). */
- export declare type QualifierEventMap = {
-     readonly derive: readonly [derivation: Derivation];
-     readonly finding: readonly [finding: Finding];
-     readonly qualify: readonly [result: QualificationResult];
-     readonly destroy: readonly [];
- };
-
- /** One qualifier — owns or borrows one reason engine and returns eligibility. */
- export declare interface QualifierInterface {
-     readonly emitter: EmitterInterface<QualifierEventMap>;
-     qualify(subject: Subject, definition: QualificationDefinition): QualificationResult;
-     validate(definition: QualificationDefinition): QualificationValidationResult;
-     destroy(): void;
- }
+      /** Represents a coded {@link QualifierError} programmer-error code. */
+      export declare type QualifierErrorCode = 'DEFINITION' | 'MISMATCH' | 'DESTROYED' | 'ENGINE';
 
- /** Options for `createQualifier` / the `Qualifier` constructor. */
- export declare interface QualifierOptions {
-     readonly engine?: ReasonInterface;
-     readonly validate?: boolean;
-     readonly labels?: Readonly<Record<string, string>>;
-     readonly on?: EmitterHooks<QualifierEventMap>;
-     readonly error?: EmitterErrorHandler;
- }
+      /**
+       * Represents the structured payload a {@link QualifierError} carries.
+       *
+       * @remarks
+       * `pass` names the pass that was running when the engine threw. `definition` names the
+       * qualification definition that failed semantic validation. `cause` is the original throw
+       * an engine failure wrapped, and stays `unknown` because a thrown value can be anything.
+       * Every member is absent rather than `undefined` when the throw does not carry it.
+       */
+      export declare interface QualifierErrorContext {
+          readonly pass?: string;
+          readonly definition?: string;
+          readonly cause?: unknown;
+      }
 
- /**
-  * Project a quantitative result into a {@link Derivation} audit record.
-  *
-  * @param id - The pass id
-  * @param result - The evaluated quantitative result
-  * @returns A fresh derivation
-  *
-  * @example
-  * ```ts
-  * import { quantitativeResultToDerivation } from '@orkestrel/qualifier'
-  *
-  * const result = { reasoning: 'quantitative' as const, value: 500_000, groups: [], count: 1, success: true, trace: ['cap: 500000'], errors: [] }
-  * quantitativeResultToDerivation('cap', result)
-  * // { id: 'cap', value: 500000, success: true, trace: ['cap: 500000'], errors: [] }
-  * ```
-  */
- export declare function quantitativeResultToDerivation(id: string, result: QuantitativeResult): Derivation;
+      /** Represents the push observation surface of a {@link QualifierInterface}. */
+      export declare type QualifierEventMap = {
+          readonly derive: readonly [derivation: Derivation];
+          readonly finding: readonly [finding: Finding];
+          readonly qualify: readonly [result: QualificationResult];
+          readonly destroy: readonly [];
+      };
 
- /**
-  * Project one reason result into the internal qualification namespace.
-  *
-  * @remarks
-  * A quantitative result contributes its numeric `value`. A logical result
-  * contributes a record of its `conclusion` plus every applied rule's asserted
-  * conclusion fields (`extractConclusions`). A mismatched pairing contributes
-  * `false`. The projection is pure — it never mutates the subject or the result.
-  *
-  * @param definition - The pass definition that produced the result
-  * @param result - The evaluated reason result
-  * @returns The pass's working projection
-  *
-  * @example
-  * ```ts
-  * import { reasonResultToProjection } from '@orkestrel/qualifier'
-  * import { factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
-  *
-  * const cap = quantitativeDefinition('cap', 'TIV cap', [
-  *   factorGroup('limit', 'sum', [staticFactor('base', 500_000)]),
-  * ])
-  * const result = {
-  *   reasoning: 'quantitative' as const,
-  *   value: 500_000,
-  *   groups: [],
-  *   count: 1,
-  *   success: true,
-  *   trace: [],
-  *   errors: [],
-  * }
-  * reasonResultToProjection(cap, result) // 500000
-  * ```
-  */
- export declare function reasonResultToProjection(definition: QualificationPass, result: ReasonResult): QualificationProjection;
+      /** Owns or borrows one reason engine and returns eligibility. */
+      export declare interface QualifierInterface {
+          /** Holds the typed observation surface carrying `derive`, `finding`, `qualify`, and `destroy`. */
+          readonly emitter: EmitterInterface<QualifierEventMap>;
+          /**
+           * 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 and the
+           * caller's `subject` is never mutated: the working projection under
+           * `QUALIFICATION_KEY` is built copy-on-write and discarded after the call.
+           *
+           * @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, 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 definition = createQualificationDefinition('standard', 'Standard eligibility', [gates], {
+               *   rulings: [createRuling('license', 'gates', 'licensed', 'restriction')],
+               * })
+               *
+               * const qualifier = createQualifier()
+               * qualifier.qualify({ id: 'risk-1', licensed: false }, definition).eligibility // 'ineligible'
+               * qualifier.destroy()
+               * ```
+               */
+           qualify(subject: Subject, definition: QualificationDefinition): QualificationResult;
+           /**
+            * 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, createQualifier } from '@orkestrel/qualifier'
+                *
+                * const qualifier = createQualifier()
+                * qualifier.validate(createQualificationDefinition('empty', 'Empty', []))
+                * // { valid: true, errors: [], warnings: ['Definition has no passes'] }
+                * qualifier.destroy()
+                * ```
+                */
+            validate(definition: QualificationDefinition): ReasonValidationResult;
+            /**
+             * Destroys this qualifier, idempotently.
+             *
+             * @remarks
+             * An owned engine 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 { createQualifier } from '@orkestrel/qualifier'
+             *
+             * const qualifier = createQualifier()
+             * qualifier.destroy()
+             * qualifier.destroy() // idempotent
+             * ```
+             */
+            destroy(): void;
+           }
 
- /** An authored consequence for one rule in one logical pass. */
- export declare interface Ruling {
-     readonly id: string;
-     readonly pass: string;
-     readonly rule: string;
-     readonly effect: QualificationEffect;
-     readonly scope?: string;
-     readonly message?: string;
- }
+           /**
+            * Carries the options for `createQualifier` and the `Qualifier` constructor.
+            *
+            * @remarks
+            * `engine` injects a reason engine that stays caller-owned and is never destroyed; an
+            * absent `engine` makes the qualifier create and own one. `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`. `on` carries the initial emitter hooks,
+            * and `error` handles a listener throw.
+            */
+           export declare interface QualifierOptions {
+               readonly engine?: ReasonInterface;
+               readonly validate?: boolean;
+               readonly labels?: Readonly<Record<string, string>>;
+               readonly on?: EmitterHooks<QualifierEventMap>;
+               readonly error?: EmitterErrorHandler;
+           }
 
- /**
-  * 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' })
-  * ```
-  */
- export declare function rulingDefinition(id: string, pass: string, rule: string, effect: QualificationEffect, input?: RulingInput): Ruling;
+           /**
+            * Projects a quantitative result into a {@link Derivation} audit record.
+            *
+            * @param id - The pass id
+            * @param result - The evaluated quantitative result
+            * @returns A fresh derivation
+            *
+            * @example
+            * ```ts
+            * import { quantitativeResultToDerivation } from '@orkestrel/qualifier'
+            *
+            * const result = { reasoning: 'quantitative' as const, value: 500_000, groups: [], count: 1, success: true, trace: ['cap: 500000'], errors: [] }
+            * quantitativeResultToDerivation('cap', result)
+            * // { id: 'cap', value: 500000, success: true, trace: ['cap: 500000'], errors: [] }
+            * ```
+            */
+           export declare function quantitativeResultToDerivation(id: string, result: QuantitativeResult): Derivation;
 
- /** Optional fields accepted by `rulingDefinition`. */
- export declare interface RulingInput {
-     readonly scope?: string;
-     readonly message?: string;
- }
+           /**
+            * Projects one reason result into the internal qualification namespace.
+            *
+            * @remarks
+            * A quantitative result contributes its numeric `value`. A logical result
+            * contributes a record of its `conclusion` plus every applied rule's asserted
+            * conclusion fields (`extractConclusions`). A mismatched pairing contributes
+            * `false`. The projection is pure — it never mutates the subject or the result.
+            *
+            * @param definition - The pass definition that produced the result
+            * @param result - The evaluated reason result
+            * @returns The pass's working projection
+            *
+            * @example
+            * ```ts
+            * import { reasonResultToProjection } from '@orkestrel/qualifier'
+            * import { createFactorGroup, createQuantitativeDefinition, createStaticFactor } from '@orkestrel/reason'
+            *
+            * const cap = createQuantitativeDefinition('cap', 'TIV cap', [
+            *   createFactorGroup('limit', 'sum', [createStaticFactor('base', 500_000)]),
+            * ])
+            * const result = {
+            *   reasoning: 'quantitative' as const,
+            *   value: 500_000,
+            *   groups: [],
+            *   count: 1,
+            *   success: true,
+            *   trace: [],
+            *   errors: [],
+            * }
+            * reasonResultToProjection(cap, result) // 500000
+            * ```
+            */
+           export declare function reasonResultToProjection(definition: QualificationPass, result: ReasonResult): QualificationProjection;
 
- /**
-  * Join a ruling, its logical rule result, the pass, the pre-projection subject,
-  * and an evaluator into a {@link Finding}.
-  *
-  * @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
-  * derived can never satisfy its own reported premise. The message interpolates
-  * against that snapshot.
-  *
-  * @param ruling - The authored ruling
-  * @param pass - The pass the ruling's rule lives in
-  * @param result - The pass's evaluated logical result
-  * @param subject - The pre-projection subject snapshot the pass evaluated
-  * @param evaluator - The shared reason check evaluator
-  * @param labels - Optional field-to-label overrides, keyed by dot-joined field
-  * @returns A fresh finding
-  *
-  * @example
-  * ```ts
-  * import { rulingToFinding } from '@orkestrel/qualifier'
-  * import { atom, createEvaluator, logicalDefinition, rule } from '@orkestrel/reason'
-  *
-  * const gates = logicalDefinition('gates', 'Gates', [
-  *   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
-  * ])
-  * const ruling = { id: 'license', pass: 'gates', rule: 'licensed', effect: 'restriction' as const }
-  * const result = { reasoning: 'logical' as const, conclusion: true, rules: [{ id: 'licensed', applied: true, premises: [true], conclusion: true }], count: 1, success: true, trace: [], errors: [] }
-  * const finding = rulingToFinding(ruling, gates, result, { licensed: false }, createEvaluator())
-  *
-  * finding.applied // true
-  * ```
-  */
- export declare function rulingToFinding(ruling: Ruling, pass: QualificationPass, result: LogicalResult, subject: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): Finding;
+           /**
+            * 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 { renderComparison } from '@orkestrel/qualifier'
+            *
+            * renderComparison('above') // 'is more than'
+            * ```
+            */
+           export declare function renderComparison(comparison: NonNullable<Premise['comparison']>): string;
+
+           /**
+            * Renders one {@link Premise} into a display-neutral sentence.
+            *
+            * @remarks
+            * 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.
+            *
+            * @param entry - The premise to render
+            * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+            * @returns A display-neutral sentence
+            *
+            * @example
+            * ```ts
+            * import { renderPremise } from '@orkestrel/qualifier'
+            *
+            * renderPremise({ field: 'age', comparison: 'above', expected: 18, actual: 25, met: true })
+            * // 'age is more than 18 → met'
+            *
+            * renderPremise({ description: 'Applicant is enrolled', met: true })
+            * // 'Applicant is enrolled → met'
+            * ```
+            */
+           export declare function renderPremise(entry: Premise, labels?: Readonly<Record<string, string>>): string;
+
+           /**
+            * Renders a structured or scalar expected value display-neutrally.
+            *
+            * @remarks
+            * An array renders as its elements, each `String`-coerced, joined with `', '`.
+            * 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
+            * message-token-only behavior).
+            *
+            * @param value - The value to render
+            * @returns A display-neutral rendering
+            *
+            * @example
+            * ```ts
+            * import { renderValue } from '@orkestrel/qualifier'
+            *
+            * renderValue([18, 25, 40]) // '18, 25, 40'
+            * renderValue({ minimum: 18, maximum: 65 }) // '18 and 65'
+            * renderValue(42) // '42'
+            * ```
+            */
+           export declare function renderValue(value: unknown): string;
+
+           /**
+            * 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 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.
+            *
+            * @param rule - The authored rule
+            * @param working - The working subject to evaluate against
+            * @param evaluator - The shared reason check evaluator
+            * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+            * @returns A fresh, ordered list of rich premises
+            *
+            * @example
+            * ```ts
+            * import { ruleToPremises } from '@orkestrel/qualifier'
+            * import { createAtom, createEvaluator, createLogicalDefinition, createRule } from '@orkestrel/reason'
+            *
+            * const gates = createLogicalDefinition('gates', 'Gates', [
+            *   createRule('licensed', [createAtom('licensed', 'equals', false)], createAtom('blocked', 'equals', true)),
+            * ])
+            * const evaluator = createEvaluator()
+            * const premises = ruleToPremises(gates.rules[0], { licensed: false }, evaluator)
+            *
+            * premises[0]?.met // true
+            * ```
+            */
+           export declare function ruleToPremises(rule: Rule, working: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): readonly Premise[];
+
+           /** Represents an authored consequence for one rule in one logical pass. */
+           export declare interface Ruling {
+               readonly id: string;
+               readonly pass: string;
+               readonly rule: string;
+               readonly effect: QualificationEffect;
+               readonly scope?: string;
+               readonly message?: string;
+           }
+
+           /** Carries the optional fields `createRuling` accepts. */
+           export declare interface RulingInput {
+               readonly scope?: string;
+               readonly message?: string;
+           }
+
+           /**
+            * Joins a ruling, its logical rule result, the pass, the pre-projection subject,
+            * and an evaluator into a {@link Finding}.
+            *
+            * @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
+            * derived can never satisfy its own reported premise. The message interpolates
+            * against that snapshot.
+            *
+            * @param ruling - The authored ruling
+            * @param pass - The pass the ruling's rule lives in
+            * @param result - The pass's evaluated logical result
+            * @param subject - The pre-projection subject snapshot the pass evaluated
+            * @param evaluator - The shared reason check evaluator
+            * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+            * @returns A fresh finding
+            *
+            * @example
+            * ```ts
+            * import { rulingToFinding } from '@orkestrel/qualifier'
+            * import { createAtom, createEvaluator, createLogicalDefinition, createRule } from '@orkestrel/reason'
+            *
+            * 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] }], count: 1, success: true, trace: [], errors: [] }
+            * const finding = rulingToFinding(ruling, gates, result, { licensed: false }, createEvaluator())
+            *
+            * finding.applied // true
+            * ```
+            */
+           export declare function rulingToFinding(ruling: Ruling, pass: QualificationPass, result: LogicalResult, subject: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): Finding;
 
- export { }
+           export { }