@orkestrel/qualifier 0.0.1

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

@@ -0,0 +1,569 @@
+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 { 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 { Rule } from '@orkestrel/reason';
+import { Subject } from '@orkestrel/reason';
+
+/**
+ * Assert 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
+     * when it already carries the reserved `qualification` key
+     */
+ export declare function assertSubject(value: unknown): asserts value is Subject;
+
+ /**
+  * Return 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
+  *
+  * @example
+  * ```ts
+  * import { combineEligibilities } from '@orkestrel/qualifier'
+  *
+  * combineEligibilities(['eligible', 'referral']) // 'referral'
+  * ```
+  */
+ export declare function combineEligibilities(eligibilities: Eligibility[]): Eligibility;
+
+ /**
+  * Create one qualifier over a reason engine.
+  *
+  * @remarks
+  * A standalone qualifier creates and OWNS one shared quantitative-plus-logical
+  * reason engine, destroying it on `destroy()`. An injected `options.engine`
+  * remains caller-owned and is never destroyed. Validation is on by default.
+  *
+  * @param options - Optional injected engine, validation, labels, and emitter hooks
+  * @returns A {@link QualifierInterface}
+  *
+  * @example
+  * ```ts
+  * import { createQualifier } from '@orkestrel/qualifier'
+  *
+  * const qualifier = createQualifier()
+  * qualifier.qualify({ id: 'risk-1' }, definition)
+  * qualifier.destroy()
+  * ```
+  */
+ export declare function createQualifier(options?: QualifierOptions): QualifierInterface;
+
+ /** Default definition validation policy for `createQualifier` / `Qualifier.qualify`. */
+ export declare const DEFAULT_QUALIFIER_VALIDATE = true;
+
+ /** One quantitative pass's audit result. */
+ export declare interface Derivation {
+     readonly id: string;
+     readonly value: number;
+     readonly success: boolean;
+     readonly trace: readonly string[];
+     readonly errors: readonly string[];
+ }
+
+ /**
+  * Derive global eligibility from applied, unscoped findings.
+  *
+  * @remarks
+  * Only findings that both applied and carry no `scope` shape global eligibility.
+  * A failed pass contributes a synthetic `referral` (fail-closed), passed through
+  * `failed`.
+  *
+  * @param findings - The resolved findings
+  * @param failed - Whether an operational pass failure occurred
+  * @returns The most severe global eligibility
+  */
+ export declare function deriveFindingEligibility(findings: Finding[], failed?: boolean): Eligibility;
+
+ /**
+  * Derive one eligibility per finding scope.
+  *
+  * @remarks
+  * Only applied, scoped findings contribute. Each named scope combines its own
+  * findings' impacts by severity. An unmentioned scope is absent (eligible by
+  * default at the program layer).
+  *
+  * @param findings - The resolved findings
+  * @returns A fresh record of scope to its combined eligibility
+  */
+ export declare function deriveScopeEligibilities(findings: 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.
+  *
+  * @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 { describePremise } from '@orkestrel/qualifier'
+  *
+  * describePremise({ field: 'age', comparison: 'above', expected: 18, actual: 25, met: true })
+  * // 'age is more than 18 → met'
+  * ```
+  */
+ export declare function describePremise(entry: Premise, labels?: Readonly<Record<string, string>>): string;
+
+ /**
+  * Render 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 { describeValue } from '@orkestrel/qualifier'
+  *
+  * describeValue([18, 25, 40]) // '18, 25, 40'
+  * describeValue({ minimum: 18, maximum: 65 }) // '18 and 65'
+  * describeValue(42) // '42'
+  * ```
+  */
+ 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 pre-rating 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.
+  *
+  * @param ids - The ids to scan
+  * @returns A fresh list of ids that appear more than once
+  */
+ export declare function findDuplicateIds(ids: readonly string[]): readonly string[];
+
+ /** One resolved ruling. */
+ export declare interface Finding {
+     readonly id: string;
+     readonly pass: string;
+     readonly rule: string;
+     readonly effect: QualificationEffect;
+     readonly scope?: string;
+     readonly applied: boolean;
+     readonly message?: string;
+     readonly premises: readonly Premise[];
+ }
+
+ /**
+  * 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
+  */
+ export declare function findMissingReferences(definition: QualificationDefinition): readonly string[];
+
+ /**
+  * Locate an authored {@link Rule} by id.
+  *
+  * @param definition - The logical definition to search
+  * @param id - The rule id
+  * @returns The matching rule, or `undefined`
+  *
+  * @example
+  * ```ts
+  * import { findRule } 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)),
+  * ])
+  *
+  * findRule(gates, 'licensed')?.id // 'licensed'
+  * ```
+  */
+ export declare function findRule(definition: LogicalDefinition, id: string): Rule | undefined;
+
+ /**
+  * 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
+  */
+ export declare function hasReservedKey(subject: Subject): boolean;
+
+ /**
+  * Interpolate `{{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
+  * 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.
+  *
+  * @param template - The message template carrying `{{dotted.path}}` tokens
+  * @param subject - The record tokens resolve against
+  * @returns The template with every token replaced
+  *
+  * @example
+  * ```ts
+  * import { interpolateMessage } from '@orkestrel/qualifier'
+  *
+  * interpolateMessage('Limit is {{limit}}', { limit: 5010 }) // 'Limit is 5,010'
+  * interpolateMessage('Missing {{gone}}', {})                // 'Missing '
+  * ```
+  */
+ export declare function interpolateMessage(template: string, subject: Readonly<Record<string, unknown>>): string;
+
+ /** Determine whether a value is an {@link Eligibility} literal. */
+ export declare const isEligibility: Guard<"eligible" | "ineligible" | "referral">;
+
+ /** Determine whether a value is an exact {@link QualificationDefinition} record. */
+ export declare function isQualificationDefinition(value: unknown): value is QualificationDefinition;
+
+ /** Determine whether a value is a {@link QualificationEffect} literal. */
+ 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;
+
+ /** Narrow a caught value to a {@link QualifierError}. */
+ 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.
+  *
+  * @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)
+  *
+  * premises[0]?.met // true
+  * ```
+  */
+ export declare function logicalPremises(rule: Rule, working: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): readonly Premise[];
+
+ /**
+  * Copy-on-write merge one pass projection into the context.
+  *
+  * @param context - The current projection context
+  * @param id - The pass id to project under
+  * @param projection - The pass's working projection
+  * @returns A fresh context with the projection added
+  */
+ export declare function mergeQualificationContext(context: QualificationContext, id: string, projection: QualificationProjection): QualificationContext;
+
+ /** Display-neutral checked evidence. */
+ export declare interface Premise {
+     readonly field?: FieldPath;
+     readonly label?: string;
+     readonly description?: string;
+     readonly comparison?: Comparison;
+     readonly expected?: unknown;
+     readonly actual?: unknown;
+     readonly met?: boolean;
+ }
+
+ /**
+  * 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 }
+  * ```
+  */
+ 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`. */
+ export declare type QualificationContext = Readonly<Record<string, QualificationProjection>>;
+
+ /** A pure authored qualification definition. */
+ export declare interface QualificationDefinition {
+     readonly id: string;
+     readonly name: string;
+     readonly description?: string;
+     readonly passes: readonly QualificationPass[];
+     readonly rulings?: readonly Ruling[];
+     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. */
+ export declare type QualificationEffect = 'restriction' | 'referral' | 'condition';
+
+ /** Optional fields accepted by `qualificationDefinition`. */
+ export declare interface QualificationInput {
+     readonly description?: string;
+     readonly rulings?: readonly Ruling[];
+     readonly metadata?: Readonly<Record<string, JSONValue>>;
+ }
+
+ /** One ordered derivation or rule pass. */
+ export declare type QualificationPass = QuantitativeDefinition | LogicalDefinition;
+
+ /** One pass's internal working projection. */
+ export declare type QualificationProjection = number | boolean | Readonly<Record<string, unknown>>;
+
+ /** One subject's complete qualification outcome. */
+ export declare interface QualificationResult {
+     readonly id: string;
+     readonly name: string;
+     readonly eligibility: Eligibility;
+     readonly scopes: Readonly<Record<string, Eligibility>>;
+     readonly findings: readonly Finding[];
+     readonly derivations: readonly Derivation[];
+     readonly success: boolean;
+     readonly trace: readonly string[];
+     readonly errors: readonly string[];
+ }
+
+ /**
+  * Wrap a {@link QualificationContext} under {@link QUALIFICATION_KEY}.
+  *
+  * @param context - The accumulated projection context
+  * @returns A record carrying the context under the reserved key
+  */
+ 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[];
+ }
+
+ /**
+  * A qualifier — runs ordered passes over one reason engine and returns
+  * pre-rating eligibility.
+  *
+  * @remarks
+  * The engine is OWNED when self-created (destroyed on `destroy()`) and borrowed
+  * when injected (never destroyed). `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);
+     get emitter(): EmitterInterface<QualifierEventMap>;
+     qualify(subject: Subject, definition: QualificationDefinition): QualificationResult;
+     validate(definition: QualificationDefinition): QualificationValidationResult;
+     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.
+  */
+ export declare class QualifierError extends Error {
+     readonly code: QualifierErrorCode;
+     readonly context: unknown;
+     constructor(code: QualifierErrorCode, message: string, context?: unknown);
+ }
+
+ /** A coded {@link QualifierError} programmer-error code. */
+ export declare type QualifierErrorCode = 'DEFINITION' | 'MISMATCH' | 'DESTROYED';
+
+ /** 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 pre-rating eligibility. */
+ export declare interface QualifierInterface {
+     readonly emitter: EmitterInterface<QualifierEventMap>;
+     qualify(subject: Subject, definition: QualificationDefinition): QualificationResult;
+     validate(definition: QualificationDefinition): QualificationValidationResult;
+     destroy(): void;
+ }
+
+ /** 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;
+ }
+
+ /**
+  * 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
+  */
+ export declare function quantitativeResultToDerivation(id: string, result: QuantitativeResult): Derivation;
+
+ /**
+  * 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
+  */
+ export declare function reasonResultToProjection(definition: QualificationPass, result: ReasonResult): QualificationProjection;
+
+ /** 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;
+ }
+
+ /**
+  * 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 rating 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;
+
+ /** Optional fields accepted by `rulingDefinition`. */
+ export declare interface RulingInput {
+     readonly scope?: string;
+     readonly message?: string;
+ }
+
+ /**
+  * 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
+  */
+ export declare function rulingToFinding(ruling: Ruling, pass: QualificationPass, result: LogicalResult, subject: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): Finding;
+
+ export { }