@orkestrel/rater 0.0.1 → 0.0.3

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

@@ -5,1167 +5,544 @@ 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";
+/**
+ * Build evidence rows 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 evidence rows, one per authored check
+ *
+ * @example
+ * ```ts
+ * import { check } from '@orkestrel/reason'
+ * import { checkEvidence } from '@orkestrel/rater'
+ *
+ * const checks = [check('age', 'above', 18)]
+ * checkEvidence(checks, [{ field: 'age', met: true, actual: 25 }])
+ * ```
+ */
+export declare function checkEvidence(checks: readonly Check[] | undefined, results: readonly CheckResult[] | undefined, labels?: Readonly<Record<string, string>>): readonly Evidence[];
 
-/** Batch aggregate fields, an optional partition key, and optional gates. */
-export declare interface AggregateDefinition {
-    readonly fields: readonly FieldPath[];
-    readonly by?: FieldPath;
-    readonly gates?: LogicalDefinition;
+/**
+ * Create a rating orchestrator.
+ *
+ * @param options - Optional total handler, labels, injected engine, 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;
+
+/** A checked-evidence row rendered into a display-neutral sentence. */
+export declare interface Evidence {
+    readonly field?: FieldPath;
+    readonly label?: string;
+    readonly comparison?: Comparison;
+    readonly expected?: unknown;
+    readonly actual?: unknown;
+    readonly met?: boolean;
 }
 
 /**
- * Build an {@link AggregateDefinition}.
+ * Build an {@link Evidence} row from an evaluated {@link Check}.
  *
- * @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
+ * @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 evidence row
  *
  * @example
  * ```ts
- * import { aggregateDefinition } from '@orkestrel/rater'
+ * import { check } from '@orkestrel/reason'
+ * import { evidenceCheck } from '@orkestrel/rater'
  *
- * aggregateDefinition(['amount'])
+ * const entry = check('age', 'above', 18)
+ * evidenceCheck(entry, 25, true) // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
  * ```
  */
-export declare function aggregateDefinition(fields: readonly FieldPath[], by?: FieldPath, gates?: LogicalDefinition): AggregateDefinition;
+export declare function evidenceCheck(check: Check, actual: unknown, met: boolean | undefined, labels?: Readonly<Record<string, string>>): Evidence;
 
 /**
- * Collect the deduped, ordered union of every program's aggregate fields.
+ * Determine whether a value is an exact {@link LineDefinition} record.
+ *
+ * @remarks
+ * Total guard (AGENTS §14): adversarial input (cycles, hostile prototypes)
+ * returns `false`, never throws. The record shape is EXACT — an extra key fails.
  *
- * @param programs - The compiled programs to scan
- * @returns A fresh list of aggregate field paths, in first-seen order
+ * @param value - The value to test
+ * @returns `true` when `value` is a `LineDefinition`
  *
  * @example
  * ```ts
- * import { aggregateFields } from '@orkestrel/rater'
+ * import { quantitativeDefinition } from '@orkestrel/reason'
+ * import { isLineDefinition } from '@orkestrel/rater'
  *
- * aggregateFields(programs) // [['income'], ['assets']]
+ * isLineDefinition({ id: 'base', name: 'Base', rate: quantitativeDefinition('base', 'Base', []) }) // true
  * ```
  */
-export declare function aggregateFields(programs: readonly ProgramInterface[]): readonly FieldPath[];
+export declare function isLineDefinition(value: unknown): value is LineDefinition;
 
-/** One batch aggregate partition. */
-export declare interface AggregateGroup {
-    readonly key: string;
-    readonly count: number;
-    readonly sums: Readonly<Record<string, number>>;
-}
+/**
+ * Narrow a caught value to a {@link RaterError}.
+ *
+ * @param value - The caught value to test
+ * @returns `true` when `value` is a `RaterError`
+ *
+ * @example
+ * ```ts
+ * import { isRaterError, RaterError } from '@orkestrel/rater'
+ *
+ * try {
+ * 	throw new RaterError('DESTROYED', 'Rater has been destroyed')
+ * } catch (error) {
+ * 	if (isRaterError(error)) error.code // 'DESTROYED'
+ * }
+ * ```
+ */
+export declare function isRaterError(value: unknown): value is RaterError;
 
 /**
- * Partition a batch of subjects by a field, summing aggregate fields per
- * partition.
+ * Determine whether a value is an exact {@link RatingDefinition} record.
  *
  * @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'`.
+ * Total guard (AGENTS §14): adversarial input (cycles, hostile prototypes)
+ * returns `false`, never throws. The record shape is EXACT — an extra key fails.
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is a `RatingDefinition`
+ *
+ * @example
+ * ```ts
+ * import { isRatingDefinition } from '@orkestrel/rater'
  *
- * @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
+ * isRatingDefinition({ id: 'r1', name: 'Rating', lines: [] }) // true
+ * ```
  */
-export declare function aggregateGroups(subjects: readonly Subject[], fields: readonly FieldPath[], by?: FieldPath): readonly AggregateGroup[];
+export declare function isRatingDefinition(value: unknown): value is RatingDefinition;
 
 /**
- * Build the batch aggregate working projection written under
- * {@link AGGREGATE_KEY}'s value.
+ * Determine whether a value is a {@link Stage} literal.
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is `'factor'`, `'group'`, or `'total'`
+ *
+ * @example
+ * ```ts
+ * import { isStage } from '@orkestrel/rater'
  *
- * @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
+ * isStage('group') // true
+ * isStage('step') // false
+ * ```
  */
-export declare function aggregateProjection(count: number, sums: Readonly<Record<string, number>>, group?: AggregateGroup): Readonly<Record<string, unknown>>;
+export declare const isStage: Guard<Stage>;
 
 /**
- * Build the reserved-key record an aggregate gate definition runs against.
+ * One rateable line — a quantitative definition joined to display metadata.
  *
- * @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}
+ * @remarks
+ * `rate` is a plain reason {@link QuantitativeDefinition}; Rater delegates every
+ * actual evaluation of it to the shared engine.
  */
-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>>;
+export declare interface LineDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly rate: QuantitativeDefinition;
+    readonly metadata?: JSONValue;
 }
 
 /**
- * Sum aggregate fields across a batch of subjects.
+ * 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
  *
- * @param subjects - The batch of subjects
- * @param fields - The fields to sum
- * @returns A fresh record of dot-joined field to summed finite value
+ * @example
+ * ```ts
+ * import { quantitativeDefinition } from '@orkestrel/reason'
+ * import { lineDefinition } from '@orkestrel/rater'
+ *
+ * lineDefinition('base', 'Base Amount', quantitativeDefinition('base', 'Base', []))
+ * ```
  */
-export declare function aggregateSums(subjects: readonly Subject[], fields: readonly FieldPath[]): Readonly<Record<string, number>>;
+export declare function lineDefinition(id: string, name: string, rate: QuantitativeDefinition, overrides?: Partial<Omit<LineDefinition, 'id' | 'name' | 'rate'>>): LineDefinition;
 
 /**
- * Assert a value is a valid rater {@link Subject}, narrowing it in place.
+ * One line's rating outcome.
  *
- * @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;
-  }
+ * @remarks
+ * `worksheet` is always present — even a failed evaluation resolves to a
+ * type-shaped failure worksheet, so a `LineResult` is always constructible.
+ * `amount` is present ONLY when `success` is `true`.
+ */
+export declare interface LineResult {
+    readonly id: string;
+    readonly name: string;
+    readonly amount?: number;
+    readonly worksheet: Worksheet;
+    readonly success: boolean;
+}
 
-  /**
-   * 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;
+/**
+ * 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 labels - Optional field-to-label overrides, keyed by dot-joined field
+ * @returns A fresh line result
+ *
+ * @example
+ * ```ts
+ * import { createQuantitativeReasoner, createReason, quantitativeDefinition } from '@orkestrel/reason'
+ * import { lineDefinition, ratedLine } from '@orkestrel/rater'
+ *
+ * const line = lineDefinition('base', 'Base', quantitativeDefinition('base', 'Base', []))
+ * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, line.rate)
+ * if (result.reasoning === 'quantitative') ratedLine(line, result) // amount present only when success
+ * ```
+ */
+export declare function ratedLine(definition: LineDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>): LineResult;
 
-  /** A worksheet derivation step stage. */
-  export declare type Stage = 'factor' | 'group' | 'total';
+/**
+ * The rating orchestrator — owns (or receives) the shared quantitative
+ * reasoning engine and projects results into the rating domain vocabulary.
+ *
+ * @remarks
+ * When no `engine` is injected, `Rater` builds and OWNS its own
+ * quantitative-only engine (`bail: false`) — Rater performs NO evaluation
+ * arithmetic of its own; it only orchestrates and projects. The
+ * array-of-lines `rate` overload is declared FIRST (AGENTS §9.2). `destroy()`
+ * destroys an OWNED engine, then the emitter LAST (AGENTS §13); an INJECTED
+ * engine is never destroyed. Afterwards every other method throws
+ * {@link RaterError} `'DESTROYED'`.
+ *
+ * @example
+ * ```ts
+ * import { Rater } from '@orkestrel/rater'
+ *
+ * const rater = new Rater()
+ * rater.rate([], { id: 'subject-1' }) // { lines: [], success: true }
+ * rater.destroy()
+ * ```
+ */
+export declare class Rater implements RaterInterface {
+    #private;
+    constructor(options?: RaterOptions);
+    get emitter(): EmitterInterface<RaterEventMap>;
+    rate(lines: readonly LineDefinition[], subject: Subject): RatingResult;
+    rate(definition: RatingDefinition, subject: Subject): RatingResult;
+    destroy(): void;
+}
 
-  /** Presentation and tally status derived from eligibility, conditions, and rating success. */
-  export declare type Status = 'ineligible' | 'referral' | 'conditional' | 'unrated' | 'eligible';
+/**
+ * A coded programmer error thrown by the rating layer.
+ *
+ * @remarks
+ * `DEFINITION` — the `rate` input failed both the array-of-lines and rating
+ * definition validation. `MISMATCH` — a rated subject is not a record.
+ * `DESTROYED` — use of a destroyed entity.
+ *
+ * @example
+ * ```ts
+ * import { RaterError } from '@orkestrel/rater'
+ *
+ * throw new RaterError('MISMATCH', 'Subject must be a record')
+ * ```
+ */
+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>>);
+}
 
-  /** Status tally precedence order — least to most resolved. */
-  export declare const STATUS_PRECEDENCE: readonly Status[];
+/** A coded {@link RaterError} programmer-error code. */
+export declare type RaterErrorCode = 'DEFINITION' | 'MISMATCH' | 'DESTROYED';
 
-  /** 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;
-  }
+/**
+ * The push observation surface of a {@link RaterInterface} (AGENTS §13).
+ *
+ * @remarks
+ * `rate` fires once per `rate` call, carrying the rated subject and the result.
+ */
+export declare type RaterEventMap = {
+    /** A subject was rated — carries the subject and its result. */
+    readonly rate: readonly [subject: Subject, result: RatingResult];
+};
 
-  /** One rated subject's outcome across every compiled program. */
-  export declare interface SubjectResult {
-      readonly subject: Subject;
-      readonly programs: readonly ProgramResult[];
-  }
+/**
+ * The rating orchestrator over the shared quantitative reasoning engine.
+ *
+ * @remarks
+ * The array-of-lines `rate` overload is declared FIRST (AGENTS §9.2). Both
+ * overloads rate a SINGLE subject — there is no batch-of-subjects overload.
+ */
+export declare interface RaterInterface {
+    readonly emitter: EmitterInterface<RaterEventMap>;
+    rate(lines: readonly LineDefinition[], subject: Subject): RatingResult;
+    rate(definition: RatingDefinition, subject: Subject): RatingResult;
+    destroy(): void;
+}
 
-  /**
-   * 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;
+/**
+ * Options for `createRater` / the `Rater` constructor.
+ *
+ * @remarks
+ * `engine` — an injected {@link ReasonInterface}; when omitted, `Rater` builds
+ * and OWNS its own quantitative-only engine (`bail: false`), destroying it on
+ * `destroy()`. `total` — a {@link TotalHandler} overriding the default
+ * {@link sumAmounts} projection. `labels` — field-to-label display overrides
+ * threaded into every resolved {@link Evidence}.
+ */
+export declare interface RaterOptions {
+    readonly on?: EmitterHooks<RaterEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly engine?: ReasonInterface;
+    readonly total?: TotalHandler;
+    readonly labels?: Readonly<Record<string, string>>;
+}
 
-  /** 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>>;
-  }
+/**
+ * A pure authored rating — a named, ordered set of lines.
+ *
+ * @remarks
+ * `rate` accepts either a plain `readonly LineDefinition[]` or a full
+ * `RatingDefinition`; the array overload is the terse path, this shape adds
+ * an id, a name, and optional metadata for authoring and storage.
+ */
+export declare interface RatingDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly lines: readonly LineDefinition[];
+    readonly metadata?: JSONValue;
+}
 
-  /**
-   * 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>>;
+/**
+ * Build a {@link RatingDefinition}.
+ *
+ * @param id - The rating id
+ * @param name - The display name
+ * @param lines - The rating's ordered lines
+ * @param overrides - Optional {@link RatingDefinition} fields merged over the defaults
+ * @returns A fresh rating definition
+ *
+ * @example
+ * ```ts
+ * import { lineDefinition, ratingDefinition } from '@orkestrel/rater'
+ * import { quantitativeDefinition } from '@orkestrel/reason'
+ *
+ * ratingDefinition('r1', 'Rating', [
+ * 	lineDefinition('base', 'Base Amount', quantitativeDefinition('base', 'Base', [])),
+ * ])
+ * ```
+ */
+export declare function ratingDefinition(id: string, name: string, lines: readonly LineDefinition[], overrides?: Partial<Omit<RatingDefinition, 'id' | 'name' | 'lines'>>): RatingDefinition;
 
-  /** A pure total port over resolved lines. */
-  export declare type TotalHandler = (lines: readonly LineResult[]) => number | undefined;
+/**
+ * A rated outcome across every line of one `rate` call.
+ *
+ * @remarks
+ * `total` is derived by the {@link TotalHandler} (default {@link sumAmounts})
+ * over `lines` — only successfully rated lines carry an `amount`. `success`
+ * is `true` only when every line succeeded.
+ */
+export declare interface RatingResult {
+    readonly lines: readonly LineResult[];
+    readonly total?: number;
+    readonly success: boolean;
+}
 
-  /** 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;
-  }
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * import { createQuantitativeReasoner, createReason, factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
+ * import { resultsWorksheet } from '@orkestrel/rater'
+ *
+ * const definition = quantitativeDefinition('base', 'Base', [factorGroup('g', 'sum', [staticFactor('flat', 100)])])
+ * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, definition)
+ * if (result.reasoning === 'quantitative') resultsWorksheet(definition, result) // the full audit trail
+ * ```
+ */
+export declare function resultsWorksheet(definition: QuantitativeDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>): Worksheet;
+
+/** A worksheet derivation step stage. */
+export declare type Stage = 'factor' | 'group' | 'total';
+
+/** 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;
+}
 
-  /** 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[];
-  }
+/**
+ * Sum defined line amounts.
+ *
+ * @param lines - The rated lines
+ * @returns The sum of every line's `amount`, or `undefined` when no line has one
+ *
+ * @example
+ * ```ts
+ * import { createQuantitativeReasoner, createReason, factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
+ * import { lineDefinition, ratedLine, sumAmounts } from '@orkestrel/rater'
+ *
+ * const rate = quantitativeDefinition('base', 'Base', [factorGroup('g', 'sum', [staticFactor('flat', 100)])])
+ * const line = lineDefinition('base', 'Base', rate)
+ * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, rate)
+ * if (result.reasoning === 'quantitative') sumAmounts([ratedLine(line, result)]) // 100
+ * ```
+ */
+export declare function sumAmounts(lines: readonly LineResult[]): number | undefined;
+
+/** 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;
+}
 
-  /**
-   * 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 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 evidence: readonly Evidence[];
+}
 
-  /** 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 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
+ *
+ * @example
+ * ```ts
+ * import { fieldFactor } from '@orkestrel/reason'
+ * import { worksheetFactor } from '@orkestrel/rater'
+ *
+ * const factor = fieldFactor('seats', 'seats')
+ * worksheetFactor(factor, [{ id: 'seats', applied: true, value: 10 }])
+ * ```
+ */
+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;
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * import { factorGroup, staticFactor } from '@orkestrel/reason'
+ * import { worksheetGroup } from '@orkestrel/rater'
+ *
+ * const group = factorGroup('charge', 'sum', [staticFactor('base', 100)])
+ * worksheetGroup(group, [{ id: 'charge', applied: true, value: 100, factors: [] }])
+ * ```
+ */
+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 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
+ *
+ * @example
+ * ```ts
+ * import { worksheetStep } from '@orkestrel/rater'
+ *
+ * worksheetStep('total', 'quote', 'Quote', 110, 'sum = 110')
+ * // { stage: 'total', id: 'quote', name: 'Quote', value: 110, expression: 'sum = 110' }
+ * ```
+ */
+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[];
+/**
+ * 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
+ *
+ * @example
+ * ```ts
+ * import { createQuantitativeReasoner, createReason, factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
+ * import { worksheetGroup, worksheetSteps } from '@orkestrel/rater'
+ *
+ * const definition = quantitativeDefinition('base', 'Base', [factorGroup('g', 'sum', [staticFactor('flat', 100)])])
+ * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, definition)
+ * if (result.reasoning === 'quantitative') {
+ * 	worksheetSteps(definition, result, definition.groups.map((group) => worksheetGroup(group, result.groups)))
+ * }
+ * ```
+ */
+export declare function worksheetSteps(definition: QuantitativeDefinition, result: QuantitativeResult, groups: readonly WorksheetGroup[]): readonly Step[];
 
-  export { }
+export { }