@orkestrel/rater 0.0.1

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

@@ -0,0 +1,1171 @@
+import { Aggregation } from '@orkestrel/reason';
+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 { Expression } from '@orkestrel/reason';
+import { Factor } from '@orkestrel/reason';
+import { FactorResult } from '@orkestrel/reason';
+import { FieldPath } from '@orkestrel/contract';
+import { GroupResult } from '@orkestrel/reason';
+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 { Rule } from '@orkestrel/reason';
+import { Subject } from '@orkestrel/reason';
+
+/** The reserved working-subject key a batch's aggregate projection is written under. */
+export declare const AGGREGATE_KEY = "aggregate";
+
+/** Batch aggregate fields, an optional partition key, and optional gates. */
+export declare interface AggregateDefinition {
+    readonly fields: readonly FieldPath[];
+    readonly by?: FieldPath;
+    readonly gates?: LogicalDefinition;
+}
+
+/**
+ * Build an {@link AggregateDefinition}.
+ *
+ * @param fields - The batch fields to sum
+ * @param by - The partition key field, when the aggregate is partitioned
+ * @param gates - The logical definition gating aggregate determinations, when present
+ * @returns A fresh aggregate definition
+ *
+ * @example
+ * ```ts
+ * import { aggregateDefinition } from '@orkestrel/rater'
+ *
+ * aggregateDefinition(['amount'])
+ * ```
+ */
+export declare function aggregateDefinition(fields: readonly FieldPath[], by?: FieldPath, gates?: LogicalDefinition): AggregateDefinition;
+
+/**
+ * Collect the deduped, ordered union of every program's aggregate fields.
+ *
+ * @param programs - The compiled programs to scan
+ * @returns A fresh list of aggregate field paths, in first-seen order
+ *
+ * @example
+ * ```ts
+ * import { aggregateFields } from '@orkestrel/rater'
+ *
+ * aggregateFields(programs) // [['income'], ['assets']]
+ * ```
+ */
+export declare function aggregateFields(programs: readonly ProgramInterface[]): readonly FieldPath[];
+
+/** One batch aggregate partition. */
+export declare interface AggregateGroup {
+    readonly key: string;
+    readonly count: number;
+    readonly sums: Readonly<Record<string, number>>;
+}
+
+/**
+ * Partition a batch of subjects by a field, summing aggregate fields per
+ * partition.
+ *
+ * @remarks
+ * The partition key is the resolved `by` field, coerced with `String` —
+ * `undefined` collapses to the empty string, so a subject missing the field
+ * and a subject whose field is literally `''` land in the SAME partition,
+ * and a numeric `1` collides with the string `'1'`.
+ *
+ * @param subjects - The batch of subjects
+ * @param fields - The fields to sum within each partition
+ * @param by - The partition key field; no partition is built when absent
+ * @returns A fresh list of aggregate groups, or an empty list when `by` is absent
+ */
+export declare function aggregateGroups(subjects: readonly Subject[], fields: readonly FieldPath[], by?: FieldPath): readonly AggregateGroup[];
+
+/**
+ * Build the batch aggregate working projection written under
+ * {@link AGGREGATE_KEY}'s value.
+ *
+ * @param count - The batch (or partition) subject count
+ * @param sums - The summed aggregate fields
+ * @param group - The subject's own partition, when the aggregate is partitioned
+ * @returns A fresh aggregate projection record
+ */
+export declare function aggregateProjection(count: number, sums: Readonly<Record<string, number>>, group?: AggregateGroup): Readonly<Record<string, unknown>>;
+
+/**
+ * Build the reserved-key record an aggregate gate definition runs against.
+ *
+ * @param count - The batch (or partition) subject count
+ * @param sums - The summed aggregate fields
+ * @param group - The subject's own partition, when the aggregate is partitioned
+ * @returns A fresh record carrying the aggregate projection under {@link AGGREGATE_KEY}
+ */
+export declare function aggregateRecord(count: number, sums: Readonly<Record<string, number>>, group?: AggregateGroup): Readonly<Record<string, unknown>>;
+
+/** A batch rating outcome across every subject. */
+export declare interface AggregateResult {
+    readonly subjects: readonly SubjectResult[];
+    readonly determinations: readonly Determination[];
+    readonly groups: readonly AggregateGroup[];
+    readonly tallies: Readonly<Record<string, Readonly<Record<Status, Tally>>>>;
+    readonly count: number;
+    readonly sums: Readonly<Record<string, number>>;
+}
+
+/**
+ * Sum aggregate fields across a batch of subjects.
+ *
+ * @param subjects - The batch of subjects
+ * @param fields - The fields to sum
+ * @returns A fresh record of dot-joined field to summed finite value
+ */
+export declare function aggregateSums(subjects: readonly Subject[], fields: readonly FieldPath[]): Readonly<Record<string, number>>;
+
+/**
+ * Assert a value is a valid rater {@link Subject}, narrowing it in place.
+ *
+ * @param subject - The candidate subject to validate
+ * @throws {@link RaterError} `'MISMATCH'` when the value is not a record, or
+     * when it already carries a reserved rater working-subject key
+     */
+ export declare function assertSubject(subject: unknown): asserts subject is Subject;
+
+ /**
+  * Convert an authority's fired {@link RuleResult}s into `limit`
+  * {@link Determination}s.
+  *
+  * @param definition - The authority's logical definition
+  * @param result - The evaluated logical result
+  * @param rulings - Authored consequences, keyed by rule id
+  * @param working - The working subject the authority ran against
+  * @param evaluator - The shared reason check evaluator
+  * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+  * @returns A fresh list of `limit` determinations
+  */
+ export declare function authorityToDeterminations(definition: LogicalDefinition, result: LogicalResult, rulings: Readonly<Record<string, Ruling>> | undefined, working: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): readonly Determination[];
+
+ /**
+  * Build premises from a quantitative factor's authored checks and evaluated
+  * check results.
+  *
+  * @param checks - The factor's authored checks
+  * @param results - The corresponding {@link CheckResult}s, in the same order
+  * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+  * @returns A fresh list of premises, one per authored check
+  */
+ export declare function checkPremises(checks: readonly Check[] | undefined, results: readonly CheckResult[] | undefined, labels?: Readonly<Record<string, string>>): readonly Premise[];
+
+ /**
+  * 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/rater'
+  *
+  * combineEligibilities(['eligible', 'referral']) // 'referral'
+  * ```
+  */
+ export declare function combineEligibilities(eligibilities: readonly Eligibility[]): Eligibility;
+
+ /**
+  * Complete a partial status tally record with zero entries for every missing
+  * {@link Status}.
+  *
+  * @param entries - The partial tally entries to complete
+  * @returns A record with all five statuses present
+  */
+ export declare function completeTallies(entries: Partial<Record<Status, Tally>>): Readonly<Record<Status, Tally>>;
+
+ /**
+  * Create and validate one compiled program over a shared reasoning engine.
+  *
+  * @param definition - The authored program definition
+  * @param reason - The shared reasoning engine, injected (never owned or destroyed by the program)
+  * @param options - Optional total handler and labels
+  * @returns A {@link ProgramInterface}
+  * @throws {@link RaterError} `'DEFINITION'` when the definition fails {@link isProgramDefinition}
+      *
+      * @example
+      * ```ts
+      * import { createLogicalReasoner, createQuantitativeReasoner, createReason } from '@orkestrel/reason'
+      * import { createProgram, programDefinition } from '@orkestrel/rater'
+      *
+      * const reason = createReason({ reasoners: [createQuantitativeReasoner(), createLogicalReasoner()], bail: false })
+      * const program = createProgram(programDefinition('p1', 'Program', []), reason)
+      * ```
+      */
+  export declare function createProgram(definition: ProgramDefinition, reason: ReasonInterface, options?: ProgramOptions): ProgramInterface;
+
+  /**
+   * Create an ordered manager over compiled programs (AGENTS §9), built over an
+   * injected, shared reasoning engine.
+   *
+   * @param reason - The shared reasoning engine, injected into every compiled program
+   * @param options - Optional total handler, labels, validation policy, and emitter hooks
+   * @returns A {@link ProgramManagerInterface}
+   *
+   * @example
+   * ```ts
+   * import { createLogicalReasoner, createQuantitativeReasoner, createReason } from '@orkestrel/reason'
+   * import { createProgramManager, programDefinition } from '@orkestrel/rater'
+   *
+   * const reason = createReason({ reasoners: [createQuantitativeReasoner(), createLogicalReasoner()], bail: false })
+   * const manager = createProgramManager(reason)
+   * manager.add(programDefinition('p1', 'Program', []))
+   * manager.destroy()
+   * ```
+   */
+  export declare function createProgramManager(reason: ReasonInterface, options?: ProgramManagerOptions): ProgramManagerInterface;
+
+  /**
+   * Create a rating orchestrator.
+   *
+   * @param options - Optional total handler, seed programs, labels, validation policy, and emitter hooks
+   * @returns A {@link RaterInterface}
+   *
+   * @example
+   * ```ts
+   * import { createRater } from '@orkestrel/rater'
+   *
+   * const rater = createRater()
+   * rater.destroy()
+   * ```
+   */
+  export declare function createRater(options?: RaterOptions): RaterInterface;
+
+  /**
+   * Convert an {@link Eligibility} to its deterministic authority {@link Decision}.
+   *
+   * @param eligibility - The eligibility to convert
+   * @returns The matching decision
+   */
+  export declare function decideEligibility(eligibility: Eligibility): Decision;
+
+  /** Deterministic authority decision derived from eligibility. */
+  export declare type Decision = 'approved' | 'denied' | 'submitted';
+
+  /** Default definition validation policy for `ProgramManager.add`. */
+  export declare const DEFAULT_RATER_VALIDATE = true;
+
+  /**
+   * Derive the eligibility impact of a set of determinations.
+   *
+   * @param determinations - The determinations to fold
+   * @returns The most severe eligibility any APPLIED determination's effect carries
+   *
+   * @example
+   * ```ts
+   * import { deriveDeterminationEligibility } from '@orkestrel/rater'
+   *
+   * deriveDeterminationEligibility([{ id: 'r1', effect: 'restriction', applied: true, premises: [] }])
+   * // 'ineligible'
+   * ```
+   */
+  export declare function deriveDeterminationEligibility(determinations: readonly Determination[]): Eligibility;
+
+  /**
+   * Derive the final {@link Status} from eligibility, determinations, and rated
+   * line evidence.
+   *
+   * @param eligibility - The program's combined eligibility
+   * @param determinations - Every determination in scope (program and line)
+   * @param lines - The program's rated lines
+   * @returns The derived status
+   */
+  export declare function deriveStatus(eligibility: Eligibility, determinations: readonly Determination[], lines: readonly LineResult[]): Status;
+
+  /**
+   * 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/rater'
+   *
+   * describeComparison('above') // 'is more than'
+   * ```
+   */
+  export declare function describeComparison(comparison: NonNullable<Premise['comparison']>): string;
+
+  /**
+   * Describe a logical {@link Expression} tree without atom-specific evidence.
+   *
+   * @param expression - The expression to describe
+   * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+   * @returns A display-neutral description
+   */
+  export declare function describeExpression(expression: Expression, labels?: Readonly<Record<string, string>>): 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/rater'
+   *
+   * 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 value display-neutrally.
+   *
+   * @remarks
+   * An array renders as its elements, each `String`-coerced, joined with
+   * `', '`. A Bounds-shaped record (a reason `Bounds` — the `between`/`outside`
+   * comparison's expected value shape) 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()` coercion — a finite number is NOT
+   * grouped here (that grouping is {@link interpolateMessage}'s own,
+   * message-token-only behavior).
+   *
+   * @param value - The value to render
+   * @returns A display-neutral rendering
+   *
+   * @example
+   * ```ts
+   * import { describeValue } from '@orkestrel/rater'
+   *
+   * 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;
+
+  /**
+   * A resolved rule, authority, or notice outcome.
+   *
+   * @remarks
+   * `premises` lists only content-bearing premises — content-free atoms (an
+   * empty `any`/`none` membership check) are omitted, so its length may be
+   * smaller than the engine's boolean premise count.
+   */
+  export declare interface Determination {
+      readonly id: string;
+      readonly effect: Effect;
+      readonly applied: boolean;
+      readonly line?: string;
+      readonly message?: string;
+      readonly premises: readonly Premise[];
+  }
+
+  /** A resolved determination effect. */
+  export declare type Effect = 'restriction' | 'referral' | 'condition' | 'notice' | 'limit';
+
+  /** The direct eligibility impact of an applied determination, by its effect. */
+  export declare const EFFECT_ELIGIBILITIES: Readonly<Record<Effect, Eligibility | undefined>>;
+
+  /** Advisory eligibility axis a program or line outcome carries. */
+  export declare type Eligibility = 'eligible' | 'ineligible' | 'referral';
+
+  /** The deterministic authority decision for each eligibility. */
+  export declare const ELIGIBILITY_DECISIONS: Readonly<Record<Eligibility, Decision>>;
+
+  /** Eligibility severity order, most severe first — the {@link combineEligibilities} scan order. */
+  export declare const ELIGIBILITY_PRECEDENCE: readonly Eligibility[];
+
+  /**
+   * Build zero sums for a set of fields.
+   *
+   * @param fields - The fields to zero
+   * @returns A fresh record of dot-joined field to `0`
+   */
+  export declare function emptySums(fields: readonly FieldPath[]): Readonly<Record<string, number>>;
+
+  /**
+   * Build empty status tallies in precedence order.
+   *
+   * @param fields - The fields each tally's sums are zeroed for
+   * @returns A fresh, complete tally record
+   */
+  export declare function emptyTallies(fields: readonly FieldPath[]): Readonly<Record<Status, Tally>>;
+
+  /**
+   * Keep only the determinations scoped to one line.
+   *
+   * @param determinations - The determinations to filter
+   * @param id - The line id to keep
+   * @returns The determinations whose `line` matches `id`
+   */
+  export declare function filterLineDeterminations(determinations: readonly Determination[], id: string): readonly Determination[];
+
+  /**
+   * Keep only program-scoped (line-unscoped) determinations.
+   *
+   * @param determinations - The determinations to filter
+   * @returns The determinations with no `line`
+   */
+  export declare function filterProgramDeterminations(determinations: readonly Determination[]): readonly Determination[];
+
+  /**
+   * Return authored line references (in passes, rulings, or notices) that name
+   * no line on the program.
+   *
+   * @param definition - The program definition to check
+   * @returns A fresh, deduped list of missing line ids
+   */
+  export declare function findMissingLineReferences(definition: ProgramDefinition): readonly string[];
+
+  /**
+   * Locate a {@link ProgramDefinition}'s reserved-key collisions — a quantitative
+   * pass whose id shadows {@link AGGREGATE_KEY} / {@link OUTCOME_KEY}, or a
+   * logical pass's or the authority's fired rule conclusion whose asserted
+   * field's FIRST path segment shadows one.
+   *
+   * @remarks
+   * A quantitative pass writes its value onto the working subject under its own
+   * definition id (`assignField`), silently clobbering the reserved aggregate or
+   * outcome projection when the id collides. A fired rule's conclusion atoms
+   * merge onto the working subject (`mergeSubjects`/`extractConclusions`) keyed
+   * by `formatField(check.field)` — an atom whose field's first segment is a
+   * reserved key is flagged here even when its FULL formatted key is a nested
+   * form (`outcome.total`), since authoring a conclusion under a reserved
+   * top-level segment is never intentional.
+   *
+   * @param definition - The program definition to scan
+   * @returns A fresh, deduped list of offending pass or rule ids
+   *
+   * @example
+   * ```ts
+   * import { quantitativeDefinition } from '@orkestrel/reason'
+   * import { findReservedCollisions, passDefinition, programDefinition } from '@orkestrel/rater'
+   *
+   * findReservedCollisions(
+   * 	programDefinition('p1', 'P1', [], {
+   * 		passes: [passDefinition(quantitativeDefinition('aggregate', 'Aggregate', []))],
+   * 	}),
+   * ) // ['aggregate']
+   * ```
+   */
+  export declare function findReservedCollisions(definition: ProgramDefinition): 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`
+   */
+  export declare function findRule(definition: LogicalDefinition, id: string): Rule | undefined;
+
+  /**
+   * Locate the {@link AggregateGroup} a subject belongs to.
+   *
+   * @remarks
+   * The lookup key is the resolved `by` field, coerced with `String` —
+   * `undefined` collapses to the empty string, matching {@link aggregateGroups}'
+   * partition-key coercion (a missing key and an empty-string key collide, and
+   * a numeric `1` collides with the string `'1'`).
+   *
+   * @param subject - The subject to key
+   * @param groups - The candidate groups to search
+   * @param by - The partition key field; no group is found when absent
+   * @returns The subject's matching group, or `undefined`
+   *
+   * @example
+   * ```ts
+   * import { groupFor } from '@orkestrel/rater'
+   *
+   * groupFor({ region: 'east' }, [{ key: 'east', count: 1, sums: {} }], ['region'])
+   * // { key: 'east', count: 1, sums: {} }
+   * ```
+   */
+  export declare function groupFor(subject: Subject, groups: readonly AggregateGroup[], by?: FieldPath): AggregateGroup | undefined;
+
+  /** Determine whether a working record already carries a reserved rater key. */
+  export declare function hasReservedKey(subject: Readonly<Record<string, unknown>>): boolean;
+
+  /**
+   * Interpolate `{{dotted.path}}` tokens in a message template against a record.
+   *
+   * @remarks
+   * Each token is split on `.` into a {@link FieldPath} array and resolved with
+   * the contracts {@link 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 (the resolved value is `undefined`)
+   * renders as the empty string — the deterministic "nothing to show" rule.
+   *
+   * @param template - The message template carrying `{{dotted.path}}` tokens
+   * @param record - The record tokens resolve against
+   * @returns The template with every token replaced
+   *
+   * @example
+   * ```ts
+   * import { interpolateMessage } from '@orkestrel/rater'
+   *
+   * interpolateMessage('Limit is {{limit}}', { limit: 5010 }) // 'Limit is 5,010'
+   * interpolateMessage('Missing {{gone}}', {})                // 'Missing '
+   * ```
+   */
+  export declare function interpolateMessage(template: string, record: Readonly<Record<string, unknown>>): string;
+
+  /** Determine whether a value is an exact {@link AggregateDefinition} record. */
+  export declare function isAggregateDefinition(value: unknown): value is AggregateDefinition;
+
+  /** Determine whether a value is a {@link Decision} literal. */
+  export declare const isDecision: Guard<Decision>;
+
+  /** Determine whether a value is an {@link Effect} literal. */
+  export declare const isEffect: Guard<Effect>;
+
+  /** Determine whether a value is an {@link Eligibility} literal. */
+  export declare const isEligibility: Guard<Eligibility>;
+
+  /** Determine whether a value is an exact {@link LineDefinition} record. */
+  export declare function isLineDefinition(value: unknown): value is LineDefinition;
+
+  /** Determine whether a value is an exact {@link Notice} record. */
+  export declare function isNotice(value: unknown): value is Notice;
+
+  /** Determine whether a value is an exact {@link PassDefinition} record. */
+  export declare function isPassDefinition(value: unknown): value is PassDefinition;
+
+  /** Determine whether a value is an exact {@link ProgramDefinition} record. */
+  export declare function isProgramDefinition(value: unknown): value is ProgramDefinition;
+
+  /** Narrow a caught value to a {@link RaterError}. */
+  export declare function isRaterError(value: unknown): value is RaterError;
+
+  /** Determine whether a value is an exact {@link Ruling} record. */
+  export declare function isRuling(value: unknown): value is Ruling;
+
+  /** Determine whether a value is a rule-id-keyed {@link Ruling} record. */
+  export declare const isRulings: Guard<Readonly<Record<string, Ruling>>>;
+
+  /** Determine whether a value is a {@link Stage} literal. */
+  export declare const isStage: Guard<Stage>;
+
+  /** Determine whether a value is a {@link Status} literal. */
+  export declare const isStatus: Guard<Status>;
+
+  /**
+   * One rateable line — a quantitative definition joined to display metadata.
+   *
+   * @remarks
+   * `rate` is a plain reason {@link QuantitativeDefinition}; Rater delegates every
+   * actual evaluation of it to the shared engine.
+   */
+  export declare interface LineDefinition {
+      readonly id: string;
+      readonly name: string;
+      readonly description?: string;
+      readonly rate: QuantitativeDefinition;
+      readonly metadata?: JSONValue;
+  }
+
+  /**
+   * Build a {@link LineDefinition}.
+   *
+   * @param id - The line id
+   * @param name - The display name
+   * @param rate - The line's quantitative rating definition
+   * @param overrides - Optional {@link LineDefinition} fields merged over the defaults
+   * @returns A fresh line definition
+   *
+   * @example
+   * ```ts
+   * import { quantitativeDefinition } from '@orkestrel/reason'
+   * import { lineDefinition } from '@orkestrel/rater'
+   *
+   * lineDefinition('base', 'Base Amount', quantitativeDefinition('base', 'Base', []))
+   * ```
+   */
+  export declare function lineDefinition(id: string, name: string, rate: QuantitativeDefinition, overrides?: Partial<Omit<LineDefinition, 'id' | 'name' | 'rate'>>): LineDefinition;
+
+  /** One line's rating outcome. */
+  export declare interface LineResult {
+      readonly id: string;
+      readonly name: string;
+      readonly eligibility: Eligibility;
+      readonly amount?: number;
+      readonly worksheet?: Worksheet;
+      readonly determinations: readonly Determination[];
+  }
+
+  /**
+   * Build rich premises for one fired {@link Rule} by walking its premise atoms
+   * and re-evaluating each against the working subject.
+   *
+   * @remarks
+   * A reason {@link RuleResult} carries only booleans, so this is rater's own
+   * premise-audit projection: each authored premise expression is flattened to
+   * its atom leaves via {@link extractAtoms}, and each leaf's {@link Check} is
+   * re-evaluated through the injected `evaluator`. A membership check (`any` /
+   * `none`) over an EMPTY array value is content-free — a tautology or
+   * contradiction that reads as "is none of —" in every surface — 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
+   */
+  export declare function logicalPremises(rule: Rule, working: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): readonly Premise[];
+
+  /** An authored informational determination emitted unconditionally. */
+  export declare interface Notice {
+      readonly id: string;
+      readonly message: string;
+      readonly line?: string;
+  }
+
+  /**
+   * Build a {@link Notice}.
+   *
+   * @param id - The notice id
+   * @param message - An interpolated message template
+   * @param line - The line id this notice is scoped to, when it is line-scoped
+   * @returns A fresh notice
+   *
+   * @example
+   * ```ts
+   * import { noticeDefinition } from '@orkestrel/rater'
+   *
+   * noticeDefinition('n1', 'Rated on {{date}}')
+   * ```
+   */
+  export declare function noticeDefinition(id: string, message: string, line?: string): Notice;
+
+  /**
+   * Convert authored {@link Notice}s into unconditionally-applied
+   * `notice` {@link Determination}s.
+   *
+   * @param notices - The authored notices
+   * @param working - The working subject to interpolate messages against
+   * @returns A fresh list of notice determinations
+   */
+  export declare function noticesToDeterminations(notices: readonly Notice[] | undefined, working: Readonly<Record<string, unknown>>): readonly Determination[];
+
+  /** The reserved working-subject key an authority's outcome projection is written under. */
+  export declare const OUTCOME_KEY = "outcome";
+
+  /**
+   * Build an authority outcome projection from an assembled {@link ProgramResult}.
+   *
+   * @param result - The program result computed before authority runs
+   * @returns A record shaped for the authority's `outcome` projection
+   */
+  export declare function outcomeProjection(result: ProgramResult): Readonly<Record<string, unknown>>;
+
+  /**
+   * An ordered pre-rating pass over the working subject.
+   *
+   * @remarks
+   * `line` scopes a logical pass's determinations to one line; a quantitative pass
+   * has no line scope (its value is assigned onto the working subject under its own
+   * definition id).
+   */
+  export declare interface PassDefinition {
+      readonly line?: string;
+      readonly definition: LogicalDefinition | QuantitativeDefinition;
+  }
+
+  /**
+   * Build a {@link PassDefinition}.
+   *
+   * @param definition - The pass's logical or quantitative definition
+   * @param line - The line id this pass is scoped to, when it is line-scoped
+   * @returns A fresh pass definition
+   *
+   * @example
+   * ```ts
+   * import { quantitativeDefinition } from '@orkestrel/reason'
+   * import { passDefinition } from '@orkestrel/rater'
+   *
+   * passDefinition(quantitativeDefinition('surcharge', 'Surcharge', []))
+   * ```
+   */
+  export declare function passDefinition(definition: LogicalDefinition | QuantitativeDefinition, line?: string): PassDefinition;
+
+  /** A shared checked-evidence row rendered into a display-neutral sentence. */
+  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 evaluated {@link Check}.
+   *
+   * @param check - The authored check
+   * @param actual - The resolved subject value
+   * @param met - Whether the check was met (absent when not yet evaluated)
+   * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+   * @returns A fresh premise
+   */
+  export declare function premiseCheck(check: Check, actual: unknown, met: boolean | undefined, labels?: Readonly<Record<string, string>>): Premise;
+
+  /**
+   * A compiled program — rates one subject at a time over an injected, shared
+   * reasoning engine.
+   *
+   * @remarks
+   * The engine is INJECTED and never owned, destroyed, or otherwise mutated by
+   * the program: every actual evaluation (passes, lines, authority) delegates to
+   * it. `rate` builds its working subject through copy-on-write overlays only —
+   * the caller's `subject` is never mutated.
+   */
+  export declare class Program implements ProgramInterface {
+      #private;
+      constructor(definition: ProgramDefinition, reason: ReasonInterface, options?: ProgramOptions);
+      get id(): string;
+      get name(): string;
+      get definition(): ProgramDefinition;
+      rate(subject: Subject, aggregate?: Readonly<Record<string, unknown>>): ProgramResult;
+  }
+
+  /**
+   * A pure authored program definition.
+   *
+   * @remarks
+   * `passes` runs in order before `lines`; `authority` (a logical definition) runs
+   * over the assembled result, extended with an outcome projection, to derive limit
+   * determinations and the final decision.
+   */
+  export declare interface ProgramDefinition {
+      readonly id: string;
+      readonly name: string;
+      readonly description?: string;
+      readonly passes?: readonly PassDefinition[];
+      readonly lines: readonly LineDefinition[];
+      readonly rulings?: Readonly<Record<string, Ruling>>;
+      readonly notices?: readonly Notice[];
+      readonly authority?: LogicalDefinition;
+      readonly aggregate?: AggregateDefinition;
+      readonly metadata?: JSONValue;
+  }
+
+  /**
+   * Build a {@link ProgramDefinition}.
+   *
+   * @param id - The program id
+   * @param name - The display name
+   * @param lines - The program's rateable lines
+   * @param overrides - Optional {@link ProgramDefinition} fields merged over the defaults
+   * @returns A fresh program definition
+   *
+   * @example
+   * ```ts
+   * import { programDefinition } from '@orkestrel/rater'
+   *
+   * programDefinition('p1', 'Program', [])
+   * ```
+   */
+  export declare function programDefinition(id: string, name: string, lines: readonly LineDefinition[], overrides?: Partial<Omit<ProgramDefinition, 'id' | 'name' | 'lines'>>): ProgramDefinition;
+
+  /**
+   * A compiled program — engine-injected, rates one subject at a time against its
+   * frozen definition.
+   */
+  export declare interface ProgramInterface {
+      readonly id: string;
+      readonly name: string;
+      readonly definition: ProgramDefinition;
+      rate(subject: Subject, aggregate?: Readonly<Record<string, unknown>>): ProgramResult;
+  }
+
+  /**
+   * An ordered manager over compiled {@link ProgramInterface}s (AGENTS §9), built
+   * over an injected, shared reasoning engine.
+   *
+   * @remarks
+   * OWNS its `#programs` collection and its own {@link Emitter} over
+   * {@link ProgramManagerEventMap}. `destroy()` is idempotent and tears the
+   * emitter down LAST; every other call afterwards throws
+   * {@link RaterError} `'DESTROYED'`.
+   */
+  export declare class ProgramManager implements ProgramManagerInterface {
+      #private;
+      constructor(engine: ReasonInterface, options?: ProgramManagerOptions);
+      get emitter(): EmitterInterface<ProgramManagerEventMap>;
+      get size(): number;
+      has(id: string): boolean;
+      program(id: string): ProgramInterface | undefined;
+      programs(): readonly ProgramInterface[];
+      add(definition: ProgramDefinition, options?: ProgramOptions): ProgramInterface;
+      remove(ids: readonly string[]): boolean;
+      remove(id: string): boolean;
+      remove(): void;
+      destroy(): void;
+  }
+
+  /**
+   * The push observation surface of a {@link ProgramManagerInterface} (AGENTS §13).
+   */
+  export declare type ProgramManagerEventMap = {
+      /** A program was added — carries its id. */
+      readonly add: readonly [id: string];
+      /** A program was removed — carries its id. */
+      readonly remove: readonly [id: string];
+      /** The manager was destroyed. */
+      readonly destroy: readonly [];
+  };
+
+  /** An ordered manager over compiled programs (AGENTS §9). */
+  export declare interface ProgramManagerInterface {
+      readonly emitter: EmitterInterface<ProgramManagerEventMap>;
+      readonly size: number;
+      has(id: string): boolean;
+      program(id: string): ProgramInterface | undefined;
+      programs(): readonly ProgramInterface[];
+      add(definition: ProgramDefinition, options?: ProgramOptions): ProgramInterface;
+      remove(ids: readonly string[]): boolean;
+      remove(id: string): boolean;
+      remove(): void;
+      destroy(): void;
+  }
+
+  /** Options for `createProgramManager` / the `ProgramManager` constructor. */
+  export declare interface ProgramManagerOptions {
+      readonly on?: EmitterHooks<ProgramManagerEventMap>;
+      readonly error?: EmitterErrorHandler;
+      readonly total?: TotalHandler;
+      readonly labels?: Readonly<Record<string, string>>;
+      readonly validate?: boolean;
+  }
+
+  /** Runtime options for one compiled program. */
+  export declare interface ProgramOptions {
+      readonly total?: TotalHandler;
+      readonly labels?: Readonly<Record<string, string>>;
+  }
+
+  /** One program's rating outcome. */
+  export declare interface ProgramResult {
+      readonly id: string;
+      readonly name: string;
+      readonly eligibility: Eligibility;
+      readonly status: Status;
+      /**
+       * @remarks
+       * Present ONLY when the program HAS an `authority`, the authority result is
+       * `logical`, NO `limit` determinations fired, and the authority result
+       * carries no errors — absent otherwise.
+       */
+      readonly decision?: Decision;
+      readonly lines: readonly LineResult[];
+      readonly determinations: readonly Determination[];
+      readonly derivations: readonly Worksheet[];
+      readonly total?: number;
+      readonly success: boolean;
+      readonly trace: readonly string[];
+      readonly errors: readonly string[];
+  }
+
+  /**
+   * Assemble a final {@link ProgramResult} from its rated parts.
+   *
+   * @param definition - The authored program definition
+   * @param lines - The program's rated lines
+   * @param determinations - The program-scoped determinations
+   * @param derivations - The pass-level quantitative worksheets
+   * @param total - The program's total amount, when the total handler produced one
+   * @param decision - The authority-derived decision, when one was reached
+   * @param trace - The accumulated reasoning trace
+   * @param errors - The accumulated reasoning errors
+   * @returns A fresh program result
+   */
+  export declare function programResult(definition: ProgramDefinition, lines: readonly LineResult[], determinations: readonly Determination[], derivations: readonly Worksheet[], total: number | undefined, decision: Decision | undefined, trace: readonly string[], errors: readonly string[]): ProgramResult;
+
+  /**
+   * Build a rated {@link LineResult} from a line's evaluated
+   * {@link QuantitativeResult}.
+   *
+   * @param definition - The authored line definition
+   * @param result - The evaluated quantitative result
+   * @param determinations - The line-scoped determinations
+   * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+   * @returns A fresh line result
+   */
+  export declare function ratedLine(definition: LineDefinition, result: QuantitativeResult, determinations: readonly Determination[], labels?: Readonly<Record<string, string>>): LineResult;
+
+  /**
+   * The rating orchestrator — owns the shared reasoning engine and an ordered
+   * {@link ProgramManager}, and projects results into the rating domain
+   * vocabulary.
+   *
+   * @remarks
+   * Constructs ONE shared reason engine (quantitative + logical reasoners,
+   * `bail: false`) and injects it into every compiled program — Rater performs
+   * NO evaluation arithmetic of its own; it only orchestrates and projects. The
+   * batch `rate` overload is declared FIRST (AGENTS §9.2) so an array subject
+   * resolves to the batch form. `destroy()` tears down the manager, then the
+   * engine, then the emitter LAST (AGENTS §13); afterwards every other method
+   * throws {@link RaterError} `'DESTROYED'`.
+   */
+  export declare class Rater implements RaterInterface {
+      #private;
+      constructor(options?: RaterOptions);
+      get emitter(): EmitterInterface<RaterEventMap>;
+      get programs(): ProgramManagerInterface;
+      rate(subjects: readonly Subject[]): AggregateResult;
+      rate(subject: Subject): SubjectResult;
+      destroy(): void;
+  }
+
+  /**
+   * A coded programmer error thrown by the rating layer.
+   *
+   * @remarks
+   * `DUPLICATE` — a program id collision on `ProgramManager.add`. `MISSING` — an
+   * unknown authored line reference at compile time.
+   * `DEFINITION` — a program definition failed `isProgramDefinition`. `MISMATCH` —
+   * a rated subject is not a record, or uses a reserved working-subject key.
+   * `DESTROYED` — use of a destroyed entity.
+   */
+  export declare class RaterError extends Error {
+      readonly code: RaterErrorCode;
+      readonly context?: Readonly<Record<string, unknown>>;
+      constructor(code: RaterErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+  }
+
+  /** A coded {@link RaterError} programmer-error code. */
+  export declare type RaterErrorCode = 'DUPLICATE' | 'MISSING' | 'DEFINITION' | 'MISMATCH' | 'DESTROYED';
+
+  /**
+   * The push observation surface of a {@link RaterInterface} (AGENTS §13).
+   *
+   * @remarks
+   * `rate` fires once per rated subject (batch or single); `aggregate` fires once
+   * per batch call; `determine` fires per APPLIED determination; `decide` fires
+   * once a program derives a decision.
+   */
+  export declare type RaterEventMap = {
+      /** A subject was rated — carries its result. */
+      readonly rate: readonly [result: SubjectResult];
+      /** A batch was rated — carries the aggregate result. */
+      readonly aggregate: readonly [result: AggregateResult];
+      /** An applied determination was produced — carries it. */
+      readonly determine: readonly [determination: Determination];
+      /** A program derived a decision — carries the decision and its result. */
+      readonly decide: readonly [decision: Decision, result: ProgramResult];
+  };
+
+  /**
+   * The rating orchestrator over the program manager and the shared reasoning
+   * engine.
+   *
+   * @remarks
+   * The batch `rate` overload is declared FIRST (AGENTS §9.2) so an array subject
+   * resolves to the batch form.
+   */
+  export declare interface RaterInterface {
+      readonly emitter: EmitterInterface<RaterEventMap>;
+      readonly programs: ProgramManagerInterface;
+      rate(subjects: readonly Subject[]): AggregateResult;
+      rate(subject: Subject): SubjectResult;
+      destroy(): void;
+  }
+
+  /** Options for `createRater` / the `Rater` constructor. */
+  export declare interface RaterOptions {
+      readonly on?: EmitterHooks<RaterEventMap>;
+      readonly error?: EmitterErrorHandler;
+      readonly total?: TotalHandler;
+      readonly programs?: readonly ProgramDefinition[];
+      readonly labels?: Readonly<Record<string, string>>;
+      readonly validate?: boolean;
+  }
+
+  /**
+   * Join a {@link QuantitativeDefinition} and its {@link QuantitativeResult} into
+   * a {@link Worksheet} — the rating audit trail.
+   *
+   * @param definition - The authored quantitative definition
+   * @param result - The evaluated quantitative result
+   * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+   * @returns A fresh worksheet
+   */
+  export declare function resultsWorksheet(definition: QuantitativeDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>): Worksheet;
+
+  /**
+   * Convert fired logical {@link RuleResult}s into line- or program-scoped
+   * {@link Determination}s.
+   *
+   * @param definition - The authored logical definition
+   * @param result - The evaluated logical result
+   * @param rulings - Authored consequences, keyed by rule id
+   * @param working - The working subject the rules ran against
+   * @param line - The line id this pass is scoped to, when it is line-scoped
+   * @param evaluator - The shared reason check evaluator
+   * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+   * @returns A fresh list of determinations
+   */
+  export declare function rulesToDeterminations(definition: LogicalDefinition, result: LogicalResult, rulings: Readonly<Record<string, Ruling>> | undefined, working: Subject, line: string | undefined, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): readonly Determination[];
+
+  /** An authored consequence routed to a fired rule by its id. */
+  export declare interface Ruling {
+      readonly effect: Effect;
+      readonly line?: string;
+      readonly message?: string;
+  }
+
+  /**
+   * Build a {@link Ruling}.
+   *
+   * @param effect - The determination effect a fired rule routes to
+   * @param line - The line id this ruling is scoped to, when it is line-scoped
+   * @param message - An interpolated message template, when the ruling carries one
+   * @returns A fresh ruling
+   *
+   * @example
+   * ```ts
+   * import { rulingDefinition } from '@orkestrel/rater'
+   *
+   * rulingDefinition('restriction', 'base', 'Amount exceeds {{limit}}')
+   * ```
+   */
+  export declare function rulingDefinition(effect: Effect, line?: string, message?: string): Ruling;
+
+  /** A worksheet derivation step stage. */
+  export declare type Stage = 'factor' | 'group' | 'total';
+
+  /** Presentation and tally status derived from eligibility, conditions, and rating success. */
+  export declare type Status = 'ineligible' | 'referral' | 'conditional' | 'unrated' | 'eligible';
+
+  /** Status tally precedence order — least to most resolved. */
+  export declare const STATUS_PRECEDENCE: readonly Status[];
+
+  /** A display-neutral worksheet derivation step. */
+  export declare interface Step {
+      readonly stage: Stage;
+      readonly id?: string;
+      readonly name?: string;
+      readonly value: number;
+      readonly expression?: string;
+  }
+
+  /** One rated subject's outcome across every compiled program. */
+  export declare interface SubjectResult {
+      readonly subject: Subject;
+      readonly programs: readonly ProgramResult[];
+  }
+
+  /**
+   * Sum defined line amounts.
+   *
+   * @param lines - The rated lines
+   * @returns The sum of every line's `amount`, or `undefined` when no line has one
+   */
+  export declare function sumAmounts(lines: readonly LineResult[]): number | undefined;
+
+  /** A status tally for one program — a count plus summed aggregate fields. */
+  export declare interface Tally {
+      readonly count: number;
+      readonly sums: Readonly<Record<string, number>>;
+  }
+
+  /**
+   * Add one subject's aggregate contribution to a status tally record.
+   *
+   * @param tallies - The tallies to update
+   * @param status - The subject's derived status
+   * @param subject - The subject to fold in
+   * @param fields - The fields to sum
+   * @returns A fresh, complete tally record with the subject folded in
+   */
+  export declare function tallySubject(tallies: Readonly<Record<Status, Tally>>, status: Status, subject: Subject, fields: readonly FieldPath[]): Readonly<Record<Status, Tally>>;
+
+  /** A pure total port over resolved lines. */
+  export declare type TotalHandler = (lines: readonly LineResult[]) => number | undefined;
+
+  /** A quantitative definition joined to its result — the rating audit trail. */
+  export declare interface Worksheet {
+      readonly id: string;
+      readonly name: string;
+      readonly aggregation: Aggregation;
+      readonly precision?: number;
+      readonly value: number;
+      readonly groups: readonly WorksheetGroup[];
+      readonly steps: readonly Step[];
+      readonly trace: readonly string[];
+      readonly errors: readonly string[];
+      readonly success: boolean;
+  }
+
+  /** A resolved quantitative factor, joined to its authored metadata. */
+  export declare interface WorksheetFactor {
+      readonly id: string;
+      readonly name?: string;
+      readonly description?: string;
+      readonly applied: boolean;
+      readonly value?: number;
+      readonly premises: readonly Premise[];
+  }
+
+  /**
+   * Join one authored quantitative factor to its evaluated {@link FactorResult}.
+   *
+   * @param definition - The authored factor
+   * @param results - The group's factor results
+   * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+   * @returns A fresh worksheet factor
+   */
+  export declare function worksheetFactor(definition: Factor, results: readonly FactorResult[], labels?: Readonly<Record<string, string>>): WorksheetFactor;
+
+  /** A resolved quantitative group, joined to its authored metadata. */
+  export declare interface WorksheetGroup {
+      readonly id: string;
+      readonly name?: string;
+      readonly description?: string;
+      readonly applied: boolean;
+      readonly value: number;
+      readonly factors: readonly WorksheetFactor[];
+  }
+
+  /**
+   * Join one authored quantitative group to its evaluated {@link GroupResult}.
+   *
+   * @param definition - The authored group
+   * @param results - The definition's group results
+   * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+   * @returns A fresh worksheet group
+   */
+  export declare function worksheetGroup(definition: QuantitativeDefinition['groups'][number], results: readonly GroupResult[], labels?: Readonly<Record<string, string>>): WorksheetGroup;
+
+  /**
+   * Build one display-neutral {@link Step} row.
+   *
+   * @param stage - The step's stage
+   * @param id - The stage's authored id, when it has one
+   * @param name - The stage's authored name, when it has one
+   * @param value - The stage's resolved value
+   * @param expression - A display-neutral expression string
+   * @returns A fresh step
+   */
+  export declare function worksheetStep(stage: Stage, id: string | undefined, name: string | undefined, value: number, expression: string): Step;
+
+  /**
+   * Build the ordered {@link Step} rows for a resolved {@link Worksheet}.
+   *
+   * @param definition - The authored quantitative definition
+   * @param result - The evaluated quantitative result
+   * @param groups - The definition's already-joined worksheet groups
+   * @returns A fresh, ordered list of steps: applied factors, then groups, then the total
+   */
+  export declare function worksheetSteps(definition: QuantitativeDefinition, result: QuantitativeResult, groups: readonly WorksheetGroup[]): readonly Step[];
+
+  export { }