@orkestrel/rater 0.0.11 → 0.0.13

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

@@ -17,8 +17,29 @@ import { ReasonInterface } from '@orkestrel/reason';
 import { Subject } from '@orkestrel/reason';
 
 /**
- * Build evidence rows from a quantitative factor's authored checks and
- * evaluated check results.
+ * Builds an {@link Evidence} row from an evaluated {@link Check}.
+ *
+ * @param check - The authored check
+ * @param actual - The resolved subject value
+ * @param met - If `true`, the check was met; if `false`, it was not; absent when the check
+ * was not yet evaluated
+ * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+ * @returns A fresh evidence row
+ *
+ * @example
+ * ```ts
+ * import { createCheck } from '@orkestrel/reason'
+ * import { buildEvidence } from '@orkestrel/rater'
+ *
+ * const entry = createCheck('age', 'above', 18)
+ * buildEvidence(entry, 25, true) // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
+ * ```
+ */
+export declare function buildEvidence(check: Check, actual: unknown, met: boolean | undefined, labels?: Readonly<Record<string, string>>): Evidence;
+
+/**
+ * Builds one evidence row per authored check of a quantitative factor, joined
+ * to that check's evaluated result.
  *
  * @param checks - The factor's authored checks
  * @param results - The corresponding {@link CheckResult}s, in the same order
@@ -27,17 +48,179 @@ import { Subject } from '@orkestrel/reason';
  *
  * @example
  * ```ts
- * import { check } from '@orkestrel/reason'
- * import { checkEvidence } from '@orkestrel/rater'
+ * import { createCheck } from '@orkestrel/reason'
+ * import { buildEvidenceRows } from '@orkestrel/rater'
+ *
+ * const checks = [createCheck('age', 'above', 18)]
+ * buildEvidenceRows(checks, [{ field: 'age', met: true, actual: 25 }])
+ * ```
+ */
+export declare function buildEvidenceRows(checks: readonly Check[] | undefined, results: readonly CheckResult[] | undefined, labels?: Readonly<Record<string, string>>): readonly Evidence[];
+
+/**
+ * Builds 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 { createQuantitativeDefinition } from '@orkestrel/reason'
+ * import { buildLineDefinition } from '@orkestrel/rater'
+ *
+ * buildLineDefinition('base', 'Base Amount', createQuantitativeDefinition('base', 'Base', []))
+ * ```
+ */
+export declare function buildLineDefinition(id: string, name: string, rate: QuantitativeDefinition, overrides?: Partial<Omit<LineDefinition, 'id' | 'name' | 'rate'>>): LineDefinition;
+
+/**
+ * Builds 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 { createQuantitativeDefinition, createQuantitativeReasoner, createReason } from '@orkestrel/reason'
+ * import { buildLineDefinition, buildLineResult } from '@orkestrel/rater'
  *
- * const checks = [check('age', 'above', 18)]
- * checkEvidence(checks, [{ field: 'age', met: true, actual: 25 }])
+ * const line = buildLineDefinition('base', 'Base', createQuantitativeDefinition('base', 'Base', []))
+ * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, line.rate)
+ * if (result.reasoning === 'quantitative') buildLineResult(line, result) // amount present only on a successful worksheet
  * ```
  */
-export declare function checkEvidence(checks: readonly Check[] | undefined, results: readonly CheckResult[] | undefined, labels?: Readonly<Record<string, string>>): readonly Evidence[];
+export declare function buildLineResult(definition: LineDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>): LineResult;
 
 /**
- * Create a rating orchestrator.
+ * Builds 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 { buildLineDefinition, buildRatingDefinition } from '@orkestrel/rater'
+ * import { createQuantitativeDefinition } from '@orkestrel/reason'
+ *
+ * buildRatingDefinition('r1', 'Rating', [
+ * 	buildLineDefinition('base', 'Base Amount', createQuantitativeDefinition('base', 'Base', [])),
+ * ])
+ * ```
+ */
+export declare function buildRatingDefinition(id: string, name: string, lines: readonly LineDefinition[], overrides?: Partial<Omit<RatingDefinition, 'id' | 'name' | 'lines'>>): RatingDefinition;
+
+/**
+ * Joins 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 { createFactorGroup, createQuantitativeDefinition, createQuantitativeReasoner, createReason, createStaticFactor } from '@orkestrel/reason'
+ * import { buildWorksheet } from '@orkestrel/rater'
+ *
+ * const definition = createQuantitativeDefinition('base', 'Base', [createFactorGroup('g', 'sum', [createStaticFactor('flat', 100)])])
+ * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, definition)
+ * if (result.reasoning === 'quantitative') buildWorksheet(definition, result) // the full audit trail
+ * ```
+ */
+export declare function buildWorksheet(definition: QuantitativeDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>): Worksheet;
+
+/**
+ * Joins 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 { createFieldFactor } from '@orkestrel/reason'
+ * import { buildWorksheetFactor } from '@orkestrel/rater'
+ *
+ * const factor = createFieldFactor('seats', 'seats')
+ * buildWorksheetFactor(factor, [{ id: 'seats', applied: true, value: 10 }])
+ * ```
+ */
+export declare function buildWorksheetFactor(definition: Factor, results: readonly FactorResult[], labels?: Readonly<Record<string, string>>): WorksheetFactor;
+
+/**
+ * Joins 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 { createFactorGroup, createStaticFactor } from '@orkestrel/reason'
+ * import { buildWorksheetGroup } from '@orkestrel/rater'
+ *
+ * const group = createFactorGroup('charge', 'sum', [createStaticFactor('base', 100)])
+ * buildWorksheetGroup(group, [{ id: 'charge', applied: true, value: 100, factors: [] }])
+ * ```
+ */
+export declare function buildWorksheetGroup(definition: QuantitativeDefinition['groups'][number], results: readonly GroupResult[], labels?: Readonly<Record<string, string>>): WorksheetGroup;
+
+/**
+ * Builds 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 { buildWorksheetStep } from '@orkestrel/rater'
+ *
+ * buildWorksheetStep('total', 'quote', 'Quote', 110, 'sum = 110')
+ * // { stage: 'total', id: 'quote', name: 'Quote', value: 110, expression: 'sum = 110' }
+ * ```
+ */
+export declare function buildWorksheetStep(stage: Stage, id: string | undefined, name: string | undefined, value: number, expression: string): Step;
+
+/**
+ * Builds 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 { createFactorGroup, createQuantitativeDefinition, createQuantitativeReasoner, createReason, createStaticFactor } from '@orkestrel/reason'
+ * import { buildWorksheetGroup, buildWorksheetSteps } from '@orkestrel/rater'
+ *
+ * const definition = createQuantitativeDefinition('base', 'Base', [createFactorGroup('g', 'sum', [createStaticFactor('flat', 100)])])
+ * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, definition)
+ * if (result.reasoning === 'quantitative') {
+ * 	buildWorksheetSteps(definition, result, definition.groups.map((group) => buildWorksheetGroup(group, result.groups)))
+ * }
+ * ```
+ */
+export declare function buildWorksheetSteps(definition: QuantitativeDefinition, result: QuantitativeResult, groups: readonly WorksheetGroup[]): readonly Step[];
+
+/**
+ * Creates a rating orchestrator.
  *
  * @param options - Optional total handler, labels, injected engine, and emitter hooks
  * @returns A {@link RaterInterface}
@@ -52,7 +235,7 @@ export declare function checkEvidence(checks: readonly Check[] | undefined, resu
  */
 export declare function createRater(options?: RaterOptions): RaterInterface;
 
-/** A checked-evidence row rendered into a display-neutral sentence. */
+/** Represents a checked-evidence row rendered into a display-neutral sentence. */
 export declare interface Evidence {
     readonly field?: FieldPath;
     readonly label?: string;
@@ -63,27 +246,7 @@ export declare interface Evidence {
 }
 
 /**
- * Build an {@link Evidence} row 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 evidence row
- *
- * @example
- * ```ts
- * import { check } from '@orkestrel/reason'
- * import { evidenceCheck } from '@orkestrel/rater'
- *
- * const entry = check('age', 'above', 18)
- * evidenceCheck(entry, 25, true) // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
- * ```
- */
-export declare function evidenceCheck(check: Check, actual: unknown, met: boolean | undefined, labels?: Readonly<Record<string, string>>): Evidence;
-
-/**
- * Determine whether a value is an open result-side {@link Evidence} object.
+ * Determines whether a value is an open result-side {@link Evidence} object.
  *
  * @remarks
  * Unknown members, prototypes, and class instances are admitted. Arrays are
@@ -92,7 +255,7 @@ export declare function evidenceCheck(check: Check, actual: unknown, met: boolea
  * members rather than requiring or enumerating own keys.
  *
  * @param value - The value to test
- * @returns `true` when every checked `Evidence` member conforms
+ * @returns True if every checked `Evidence` member conforms; false otherwise
  *
  * @example
  * ```ts
@@ -104,50 +267,51 @@ export declare function evidenceCheck(check: Check, actual: unknown, met: boolea
 export declare function isEvidence(value: unknown): value is Evidence;
 
 /**
- * Determine whether a value is an exact {@link LineDefinition} record.
+ * Determines 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.
+ * Total guard: 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 `LineDefinition`
+ * @returns True if `value` is a `LineDefinition`; false otherwise
  *
  * @example
  * ```ts
- * import { quantitativeDefinition } from '@orkestrel/reason'
+ * import { createQuantitativeDefinition } from '@orkestrel/reason'
  * import { isLineDefinition } from '@orkestrel/rater'
  *
- * isLineDefinition({ id: 'base', name: 'Base', rate: quantitativeDefinition('base', 'Base', []) }) // true
+ * isLineDefinition({ id: 'base', name: 'Base', rate: createQuantitativeDefinition('base', 'Base', []) }) // true
  * ```
  */
 export declare function isLineDefinition(value: unknown): value is LineDefinition;
 
 /**
- * Determine whether a value is an open {@link LineResult} object.
+ * Determines whether a value is an open {@link LineResult} object.
  *
  * @remarks
  * Unknown members, prototypes, and class instances are admitted. Arrays are
  * refused. `amount` may be absent or read as `undefined`; when present it stays
- * a plain JavaScript `number` without a finite or range refinement.
+ * a plain JavaScript `number` without a finite or range refinement. The line's
+ * outcome lives on `worksheet`, so `worksheet.success` carries it.
  *
  * @param value - The value to test
- * @returns `true` when every published line-result member conforms
+ * @returns True if every published line-result member conforms; false otherwise
  *
  * @example
  * ```ts
  * import { isLineResult } from '@orkestrel/rater'
  *
- * isLineResult({ id: 'base', name: 'Base', worksheet: { id: 'base', name: 'Base', aggregation: 'sum', value: 0, groups: [], steps: [], trace: [], errors: [], success: false }, success: false }) // true
+ * isLineResult({ id: 'base', name: 'Base', worksheet: { id: 'base', name: 'Base', aggregation: 'sum', value: 0, groups: [], steps: [], trace: [], errors: [], success: false } }) // true
  * ```
  */
 export declare function isLineResult(value: unknown): value is LineResult;
 
 /**
- * Narrow a caught value to a {@link RaterError}.
+ * Narrows a caught value to a {@link RaterError}.
  *
  * @param value - The caught value to test
- * @returns `true` when `value` is a `RaterError`
+ * @returns True if `value` is a `RaterError`; false otherwise
  *
  * @example
  * ```ts
@@ -163,14 +327,14 @@ export declare function isLineResult(value: unknown): value is LineResult;
 export declare function isRaterError(value: unknown): value is RaterError;
 
 /**
- * Determine whether a value is an exact {@link RatingDefinition} record.
+ * Determines whether a value is an exact {@link RatingDefinition} record.
  *
  * @remarks
- * Total guard (AGENTS §14): adversarial input (cycles, hostile prototypes)
- * returns `false`, never throws. The record shape is EXACT — an extra key fails.
+ * Total guard: 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`
+ * @returns True if `value` is a `RatingDefinition`; false otherwise
  *
  * @example
  * ```ts
@@ -182,7 +346,7 @@ export declare function isRaterError(value: unknown): value is RaterError;
 export declare function isRatingDefinition(value: unknown): value is RatingDefinition;
 
 /**
- * Determine whether a value is an open {@link RatingResult} object.
+ * Determines whether a value is an open {@link RatingResult} object.
  *
  * @remarks
  * Use this guard for a result returned by a borrowed `RaterInterface`. Unknown
@@ -191,7 +355,7 @@ export declare function isRatingDefinition(value: unknown): value is RatingDefin
  * JavaScript `number` without a finite or range refinement.
  *
  * @param value - The value to test
- * @returns `true` when every published rating-result member conforms
+ * @returns True if every published rating-result member conforms; false otherwise
  *
  * @example
  * ```ts
@@ -203,10 +367,10 @@ export declare function isRatingDefinition(value: unknown): value is RatingDefin
 export declare function isRatingResult(value: unknown): value is RatingResult;
 
 /**
- * Determine whether a value is a {@link Stage} literal.
+ * Determines whether a value is a {@link Stage} literal.
  *
  * @param value - The value to test
- * @returns `true` when `value` is `'factor'`, `'group'`, or `'total'`
+ * @returns True if `value` is `'factor'`, `'group'`, or `'total'`; false otherwise
  *
  * @example
  * ```ts
@@ -219,14 +383,14 @@ export declare function isRatingResult(value: unknown): value is RatingResult;
 export declare const isStage: Guard<Stage>;
 
 /**
- * Determine whether a value is an open {@link Step} result object.
+ * Determines whether a value is an open {@link Step} result object.
  *
  * @remarks
  * Unknown members, prototypes, and class instances are admitted. Arrays are
  * refused. Optional members may be absent or read as `undefined`.
  *
  * @param value - The value to test
- * @returns `true` when every published worksheet-step member conforms
+ * @returns True if every published worksheet-step member conforms; false otherwise
  *
  * @example
  * ```ts
@@ -238,14 +402,14 @@ export declare const isStage: Guard<Stage>;
 export declare function isStep(value: unknown): value is Step;
 
 /**
- * Determine whether a value is an open {@link Worksheet} result object.
+ * Determines whether a value is an open {@link Worksheet} result object.
  *
  * @remarks
  * Unknown members, prototypes, and class instances are admitted. Arrays are
  * refused. Optional members may be absent or read as `undefined`.
  *
  * @param value - The value to test
- * @returns `true` when every published worksheet member conforms
+ * @returns True if every published worksheet member conforms; false otherwise
  *
  * @example
  * ```ts
@@ -257,14 +421,14 @@ export declare function isStep(value: unknown): value is Step;
 export declare function isWorksheet(value: unknown): value is Worksheet;
 
 /**
- * Determine whether a value is an open {@link WorksheetFactor} result object.
+ * Determines whether a value is an open {@link WorksheetFactor} result object.
  *
  * @remarks
  * Unknown members, prototypes, and class instances are admitted. Arrays are
  * refused. Optional members may be absent or read as `undefined`.
  *
  * @param value - The value to test
- * @returns `true` when every published worksheet-factor member conforms
+ * @returns True if every published worksheet-factor member conforms; false otherwise
  *
  * @example
  * ```ts
@@ -276,14 +440,14 @@ export declare function isWorksheet(value: unknown): value is Worksheet;
 export declare function isWorksheetFactor(value: unknown): value is WorksheetFactor;
 
 /**
- * Determine whether a value is an open {@link WorksheetGroup} result object.
+ * Determines whether a value is an open {@link WorksheetGroup} result object.
  *
  * @remarks
  * Unknown members, prototypes, and class instances are admitted. Arrays are
  * refused. Optional members may be absent or read as `undefined`.
  *
  * @param value - The value to test
- * @returns `true` when every published worksheet-group member conforms
+ * @returns True if every published worksheet-group member conforms; false otherwise
  *
  * @example
  * ```ts
@@ -295,7 +459,7 @@ export declare function isWorksheetFactor(value: unknown): value is WorksheetFac
 export declare function isWorksheetGroup(value: unknown): value is WorksheetGroup;
 
 /**
- * One rateable line — a quantitative definition joined to display metadata.
+ * Represents one rateable line — a quantitative definition joined to display metadata.
  *
  * @remarks
  * `rate` is a plain reason {@link QuantitativeDefinition}; Rater delegates every
@@ -310,73 +474,33 @@ export declare interface LineDefinition {
 }
 
 /**
- * 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.
+ * Represents one line's rating outcome.
  *
  * @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`.
+ * The worksheet also carries the line's outcome: `amount` is present ONLY
+ * when `worksheet.success` is `true`.
  */
 export declare interface LineResult {
     readonly id: string;
     readonly name: string;
     readonly amount?: number;
     readonly worksheet: Worksheet;
-    readonly success: boolean;
 }
 
 /**
- * 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;
-
-/**
- * The rating orchestrator — owns (or receives) the shared quantitative
+ * Orchestrates rating — 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'`.
+ * array-of-lines `rate` overload is declared FIRST so a plain line list
+ * resolves to that form. `destroy()` destroys an OWNED engine, then the
+ * emitter LAST; an INJECTED engine is never destroyed. Afterwards every
+ * other method throws {@link RaterError} `'DESTROYED'`.
  *
  * @example
  * ```ts
@@ -397,7 +521,7 @@ export declare class Rater implements RaterInterface {
 }
 
 /**
- * A coded programmer error thrown by the rating layer.
+ * Represents a coded programmer error thrown by the rating layer.
  *
  * @remarks
  * `DEFINITION` — the `rate` input failed both the array-of-lines and rating
@@ -417,26 +541,27 @@ export declare class RaterError extends Error {
     constructor(code: RaterErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
 }
 
-/** A coded {@link RaterError} programmer-error code. */
+/** Names a coded {@link RaterError} programmer-error code. */
 export declare type RaterErrorCode = 'DEFINITION' | 'MISMATCH' | 'DESTROYED';
 
 /**
- * The push observation surface of a {@link RaterInterface} (AGENTS §13).
+ * Represents the push observation surface of a {@link RaterInterface}.
  *
  * @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. */
+    /** Fires when a subject is rated — carries the subject and its result. */
     readonly rate: readonly [subject: Subject, result: RatingResult];
 };
 
 /**
- * The rating orchestrator over the shared quantitative reasoning engine.
+ * Represents 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.
+ * The array-of-lines `rate` overload is declared FIRST so a plain line list
+ * resolves to that form. Both overloads rate a SINGLE subject — there is no
+ * batch-of-subjects overload.
  */
 export declare interface RaterInterface {
     readonly emitter: EmitterInterface<RaterEventMap>;
@@ -446,7 +571,7 @@ export declare interface RaterInterface {
 }
 
 /**
- * Options for `createRater` / the `Rater` constructor.
+ * Configures `createRater` and the `Rater` constructor.
  *
  * @remarks
  * `engine` — an injected {@link ReasonInterface}; when omitted, `Rater` builds
@@ -464,7 +589,7 @@ export declare interface RaterOptions {
 }
 
 /**
- * A pure authored rating — a named, ordered set of lines.
+ * Represents a pure authored rating — a named, ordered set of lines.
  *
  * @remarks
  * `rate` accepts either a plain `readonly LineDefinition[]` or a full
@@ -480,33 +605,12 @@ export declare interface RatingDefinition {
 }
 
 /**
- * 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 rated outcome across every line of one `rate` call.
+ * Represents 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.
+ * is `true` only when every line's `worksheet.success` is `true`.
  */
 export declare interface RatingResult {
     readonly lines: readonly LineResult[];
@@ -514,31 +618,10 @@ export declare interface RatingResult {
     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. */
+/** Names a worksheet derivation step stage. */
 export declare type Stage = 'factor' | 'group' | 'total';
 
-/** A display-neutral worksheet derivation step. */
+/** Represents a display-neutral worksheet derivation step. */
 export declare interface Step {
     readonly stage: Stage;
     readonly id?: string;
@@ -548,28 +631,28 @@ export declare interface Step {
 }
 
 /**
- * Sum defined line amounts.
+ * Sums 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'
+ * import { createFactorGroup, createQuantitativeDefinition, createQuantitativeReasoner, createReason, createStaticFactor } from '@orkestrel/reason'
+ * import { buildLineDefinition, buildLineResult, sumAmounts } from '@orkestrel/rater'
  *
- * const rate = quantitativeDefinition('base', 'Base', [factorGroup('g', 'sum', [staticFactor('flat', 100)])])
- * const line = lineDefinition('base', 'Base', rate)
+ * const rate = createQuantitativeDefinition('base', 'Base', [createFactorGroup('g', 'sum', [createStaticFactor('flat', 100)])])
+ * const line = buildLineDefinition('base', 'Base', rate)
  * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, rate)
- * if (result.reasoning === 'quantitative') sumAmounts([ratedLine(line, result)]) // 100
+ * if (result.reasoning === 'quantitative') sumAmounts([buildLineResult(line, result)]) // 100
  * ```
  */
 export declare function sumAmounts(lines: readonly LineResult[]): number | undefined;
 
-/** A pure total port over resolved lines. */
+/** Represents 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. */
+/** Represents a quantitative definition joined to its result — the rating audit trail. */
 export declare interface Worksheet {
     readonly id: string;
     readonly name: string;
@@ -583,7 +666,7 @@ export declare interface Worksheet {
     readonly success: boolean;
 }
 
-/** A resolved quantitative factor, joined to its authored metadata. */
+/** Represents a resolved quantitative factor, joined to its authored metadata. */
 export declare interface WorksheetFactor {
     readonly id: string;
     readonly name?: string;
@@ -593,26 +676,7 @@ export declare interface WorksheetFactor {
     readonly evidence: readonly Evidence[];
 }
 
-/**
- * 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. */
+/** Represents a resolved quantitative group, joined to its authored metadata. */
 export declare interface WorksheetGroup {
     readonly id: string;
     readonly name?: string;
@@ -622,65 +686,4 @@ export declare interface WorksheetGroup {
     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
- *
- * @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
- *
- * @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
- *
- * @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 { }