@orkestrel/qualifier 0.0.1 → 0.0.3

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

@@ -14,6 +14,7 @@ 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';
 
@@ -23,6 +24,13 @@ import { Subject } from '@orkestrel/reason';
  * @param value - The candidate subject to validate
  * @throws {@link QualifierError} `'MISMATCH'` when the value is not a record, or
      * when it already carries the reserved `qualification` key
+     *
+     * @example
+     * ```ts
+     * import { assertSubject } from '@orkestrel/qualifier'
+     *
+     * assertSubject({ id: 's1' }) // narrows to Subject
+     * ```
      */
  export declare function assertSubject(value: unknown): asserts value is Subject;
 
@@ -86,6 +94,14 @@ import { Subject } from '@orkestrel/reason';
   * @param findings - The resolved findings
   * @param failed - Whether an operational pass failure occurred
   * @returns The most severe global eligibility
+  *
+  * @example
+  * ```ts
+  * import { deriveFindingEligibility } from '@orkestrel/qualifier'
+  *
+  * const finding = { id: 'license', pass: 'gates', rule: 'licensed', effect: 'restriction' as const, applied: true, premises: [] }
+  * deriveFindingEligibility([finding]) // 'ineligible'
+  * ```
   */
  export declare function deriveFindingEligibility(findings: Finding[], failed?: boolean): Eligibility;
 
@@ -99,6 +115,14 @@ import { Subject } from '@orkestrel/reason';
   *
   * @param findings - The resolved findings
   * @returns A fresh record of scope to its combined eligibility
+  *
+  * @example
+  * ```ts
+  * import { deriveScopeEligibilities } from '@orkestrel/qualifier'
+  *
+  * const finding = { id: 'coastal', pass: 'wind', rule: 'coastal', effect: 'restriction' as const, scope: 'wind', applied: true, premises: [] }
+  * deriveScopeEligibilities([finding]) // { wind: 'ineligible' }
+  * ```
   */
  export declare function deriveScopeEligibilities(findings: Finding[]): Readonly<Record<string, Eligibility>>;
 
@@ -162,19 +186,37 @@ import { Subject } from '@orkestrel/reason';
  /** The eligibility impact of each {@link QualificationEffect}; `condition` remains eligible. */
  export declare const EFFECT_ELIGIBILITIES: Readonly<Record<QualificationEffect, Eligibility>>;
 
- /** The pre-rating outcome axis. */
+ /** 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[];
 
  /**
-  * Find duplicate ids in a list, once each.
+  * Find logical passes carrying no rulings.
+  *
+  * @remarks
+  * A logical pass with no matching ruling can never contribute a finding, so its
+  * rules only ever influence later passes' reads — this is very likely an authoring
+  * oversight.
   *
-  * @param ids - The ids to scan
-  * @returns A fresh list of ids that appear more than once
+  * @param definition - The qualification definition to check
+  * @returns A fresh list of warning messages
+  *
+  * @example
+  * ```ts
+  * import { findEmptyLogicalPasses, qualificationDefinition } from '@orkestrel/qualifier'
+  * import { atom, logicalDefinition, rule } from '@orkestrel/reason'
+  *
+  * const gates = logicalDefinition('gates', 'Gates', [
+  *   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+  * ])
+  * const definition = qualificationDefinition('standard', 'Standard', [gates])
+  *
+  * findEmptyLogicalPasses(definition) // ["Logical pass 'gates' has no rulings"]
+  * ```
   */
- export declare function findDuplicateIds(ids: readonly string[]): readonly string[];
+ export declare function findEmptyLogicalPasses(definition: QualificationDefinition): readonly string[];
 
  /** One resolved ruling. */
  export declare interface Finding {
@@ -194,6 +236,22 @@ import { Subject } from '@orkestrel/reason';
   *
   * @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[];
 
@@ -218,11 +276,46 @@ 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}.
   *
   * @param subject - The subject to check
   * @returns `true` when the subject owns the reserved key
+  *
+  * @example
+  * ```ts
+  * import { hasReservedKey } from '@orkestrel/qualifier'
+  *
+  * hasReservedKey({ id: 's1', qualification: {} }) // true
+  * ```
   */
  export declare function hasReservedKey(subject: Subject): boolean;
 
@@ -301,6 +394,30 @@ import { Subject } from '@orkestrel/reason';
   */
  export declare function logicalPremises(rule: Rule, working: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): readonly Premise[];
 
+ /**
+  * Map an engine throw caught while running one pass to a typed {@link QualifierError}.
+  *
+  * @remarks
+  * A reason `ReasonError('INVALID')` maps to `DEFINITION` (the engine rejected the
+  * pass as an invalid definition); `ReasonError('DESTROYED')` maps to `DESTROYED`;
+  * every other `ReasonError` code (e.g. `MISSING`) and every non-`ReasonError` throw
+  * (including a `bail: true` reasoner rethrow) maps to `ENGINE`. The original throw
+  * is preserved as `context.cause`.
+  *
+  * @param error - The value caught from the engine's `reason` call
+  * @param pass - The id of the pass that was running
+  * @returns A fresh, typed {@link QualifierError}
+  *
+  * @example
+  * ```ts
+  * import { mapEngineError } from '@orkestrel/qualifier'
+  * import { ReasonError } from '@orkestrel/reason'
+  *
+  * mapEngineError(new ReasonError('MISSING', 'No reasoner registered'), 'cap').code // 'ENGINE'
+  * ```
+  */
+ export declare function mapEngineError(error: unknown, pass: string): QualifierError;
+
  /**
   * Copy-on-write merge one pass projection into the context.
   *
@@ -308,6 +425,14 @@ import { Subject } from '@orkestrel/reason';
   * @param id - The pass id to project under
   * @param projection - The pass's working projection
   * @returns A fresh context with the projection added
+  *
+  * @example
+  * ```ts
+  * import { mergeQualificationContext } from '@orkestrel/qualifier'
+  *
+  * mergeQualificationContext({ cap: 500_000 }, 'excess', 250_000)
+  * // { cap: 500000, excess: 250000 }
+  * ```
   */
  export declare function mergeQualificationContext(context: QualificationContext, id: string, projection: QualificationProjection): QualificationContext;
 
@@ -416,19 +541,22 @@ import { Subject } from '@orkestrel/reason';
   *
   * @param context - The accumulated projection context
   * @returns A record carrying the context under the reserved key
+  *
+  * @example
+  * ```ts
+  * import { qualificationToRecord } from '@orkestrel/qualifier'
+  *
+  * qualificationToRecord({ cap: 500_000 }) // { qualification: { cap: 500000 } }
+  * ```
   */
  export declare function qualificationToRecord(context: QualificationContext): Readonly<Record<string, QualificationContext>>;
 
  /** Semantic definition validation. */
- export declare interface QualificationValidationResult {
-     readonly valid: boolean;
-     readonly errors: readonly string[];
-     readonly warnings: readonly string[];
- }
+ export declare type QualificationValidationResult = ReasonValidationResult;
 
  /**
   * A qualifier — runs ordered passes over one reason engine and returns
-  * pre-rating eligibility.
+  * eligibility.
   *
   * @remarks
   * The engine is OWNED when self-created (destroyed on `destroy()`) and borrowed
@@ -452,6 +580,8 @@ import { Subject } from '@orkestrel/reason';
   * `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;
@@ -460,7 +590,7 @@ import { Subject } from '@orkestrel/reason';
  }
 
  /** A coded {@link QualifierError} programmer-error code. */
- export declare type QualifierErrorCode = 'DEFINITION' | 'MISMATCH' | 'DESTROYED';
+ export declare type QualifierErrorCode = 'DEFINITION' | 'MISMATCH' | 'DESTROYED' | 'ENGINE';
 
  /** The push observation surface of a {@link QualifierInterface} (AGENTS §13). */
  export declare type QualifierEventMap = {
@@ -470,7 +600,7 @@ import { Subject } from '@orkestrel/reason';
      readonly destroy: readonly [];
  };
 
- /** One qualifier — owns or borrows one reason engine and returns pre-rating eligibility. */
+ /** 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;
@@ -493,6 +623,15 @@ import { Subject } from '@orkestrel/reason';
   * @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;
 
@@ -508,6 +647,26 @@ import { Subject } from '@orkestrel/reason';
   * @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;
 
@@ -528,7 +687,7 @@ import { Subject } from '@orkestrel/reason';
   * @param pass - The logical pass id the rule lives in
   * @param rule - The rule id whose firing this ruling reacts to
   * @param effect - The eligibility impact when the rule fires
-  * @param input - Optional rating scope and message template
+  * @param input - Optional selection scope and message template
   * @returns A fresh ruling
   *
   * @example
@@ -563,6 +722,21 @@ import { Subject } from '@orkestrel/reason';
   * @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;