@orkestrel/rater 0.0.12 → 0.0.14

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

@@ -1,24 +1,45 @@
-import { Aggregation } from '@orkestrel/reason';
-import { Check } from '@orkestrel/reason';
-import { CheckResult } from '@orkestrel/reason';
-import { Comparison } from '@orkestrel/reason';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { 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 { QuantitativeDefinition } from '@orkestrel/reason';
-import { QuantitativeResult } from '@orkestrel/reason';
-import { ReasonInterface } from '@orkestrel/reason';
-import { Subject } from '@orkestrel/reason';
-
-/**
- * Build evidence rows from a quantitative factor's authored checks and
- * evaluated check results.
+import type { Aggregation } from '@orkestrel/reason';
+import type { Check } from '@orkestrel/reason';
+import type { CheckResult } from '@orkestrel/reason';
+import type { Comparison } from '@orkestrel/reason';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { Factor } from '@orkestrel/reason';
+import type { FactorResult } from '@orkestrel/reason';
+import type { FieldPath } from '@orkestrel/contract';
+import type { GroupResult } from '@orkestrel/reason';
+import type { Guard } from '@orkestrel/contract';
+import type { JSONValue } from '@orkestrel/contract';
+import type { QuantitativeDefinition } from '@orkestrel/reason';
+import type { QuantitativeResult } from '@orkestrel/reason';
+import type { ReasonInterface } from '@orkestrel/reason';
+import type { Subject } from '@orkestrel/reason';
+
+/**
+ * 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,22 +48,188 @@ 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 fresh {@link LineDefinition} from a line id, a display name, and the
+ * line's quantitative rating definition, with `overrides` merged over those
+ * defaults.
+ *
+ * @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 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 buildLineResult(definition: LineDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>): LineResult;
+
+/**
+ * Builds a fresh {@link RatingDefinition} from a rating id, a display name, and
+ * the rating's ordered lines, with `overrides` merged over those defaults.
+ *
+ * @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'
  *
- * const checks = [check('age', 'above', 18)]
- * checkEvidence(checks, [{ field: 'age', met: true, actual: 25 }])
+ * buildRatingDefinition('r1', 'Rating', [
+ * 	buildLineDefinition('base', 'Base Amount', createQuantitativeDefinition('base', 'Base', [])),
+ * ])
  * ```
  */
-export declare function checkEvidence(checks: readonly Check[] | undefined, results: readonly CheckResult[] | undefined, labels?: Readonly<Record<string, string>>): readonly Evidence[];
+export declare function buildRatingDefinition(id: string, name: string, lines: readonly LineDefinition[], overrides?: Partial<Omit<RatingDefinition, 'id' | 'name' | 'lines'>>): RatingDefinition;
 
 /**
- * Create a rating orchestrator.
+ * 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 over the shared quantitative engine, seeded
+ * from {@link RaterOptions} and returning a {@link RaterInterface}.
  *
  * @param options - Optional total handler, labels, injected engine, and emitter hooks
  * @returns A {@link RaterInterface}
  *
- * @example
+ * @example Create a rater
  * ```ts
  * import { createRater } from '@orkestrel/rater'
  *
@@ -52,7 +239,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,36 +250,19 @@ 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
+ * Optional `field` is checked as a `FieldPath`, `label` as a string,
+ * `comparison` as a `Comparison`, and `met` as a boolean, each when defined.
  * Unknown members, prototypes, and class instances are admitted. Arrays are
  * refused. `expected` and `actual` are `unknown`, so this guard does not read or
- * check them; either member may also be absent because `objectOf` reads declared
- * members rather than requiring or enumerating own keys.
+ * check them and a borrowed result is never narrowed on them; either member may
+ * also be absent because `objectOf` reads declared 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 +274,58 @@ 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.
+ * Every `LineDefinition` member is checked, including its quantitative
+ * definition. Total guard: adversarial input (cycles, hostile prototypes)
+ * returns `false`, never throws. The record shape is exact — this package owns
+ * the authored input record, so an extra key fails and nothing is left
+ * unchecked.
  *
  * @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.
+ * Identity, an optional plain-number `amount`, and the nested `Worksheet` that
+ * carries the line's outcome are checked. Unknown members, prototypes, and
+ * class instances are admitted and left unchecked, because a borrowed result
+ * implementation may add them, and so is the relationship between `amount` and
+ * `worksheet.success`, which the published interface types independently.
+ * 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.
  *
  * @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 +341,17 @@ 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.
+ * Every `RatingDefinition` member is checked, including each nested line
+ * definition. Total guard: adversarial input (cycles, hostile prototypes)
+ * returns `false`, never throws. The record shape is exact — this package owns
+ * the authored input record, so an extra key fails and nothing is left
+ * unchecked.
  *
  * @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,16 +363,19 @@ 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
- * members, prototypes, and class instances are admitted. Arrays are refused.
- * `total` may be absent or read as `undefined`; when present it stays a plain
- * JavaScript `number` without a finite or range refinement.
+ * Use this guard for a result returned by a borrowed `RaterInterface`. Every
+ * nested `LineResult`, an optional plain-number `total`, and a boolean `success`
+ * are checked. Unknown members, prototypes, and class instances are admitted and
+ * left unchecked, and so are the relationships among totals, lines, and success,
+ * because the borrowed interface publishes only their member types. Arrays are
+ * refused. `total` may be absent or read as `undefined`; when present it stays a
+ * plain 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 +387,14 @@ 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.
+ *
+ * @remarks
+ * A scalar union has no open or exact axis, so this guard accepts one of the
+ * `Stage` literals and leaves nothing unchecked.
  *
  * @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 +407,17 @@ 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`.
+ * `stage` is checked through `isStage`, `id`, `name`, and `expression` when
+ * defined, and `value` as a plain number. Unknown members, prototypes, and
+ * class instances are admitted and left unchecked, because a borrowed result
+ * implementation may add them. 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 +429,18 @@ 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`.
+ * Identity, `aggregation` through reason's `isAggregation`, an optional
+ * plain-number `precision`, a plain-number `value`, the nested groups and steps,
+ * `trace`, `errors`, and `success` are checked. Unknown members, prototypes, and
+ * class instances are admitted and left unchecked, because a borrowed result
+ * implementation may add them. 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 +452,17 @@ 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`.
+ * `id`, the optional authored text, `applied`, an optional plain-number
+ * `value`, and each `Evidence` entry are checked. Unknown members, prototypes,
+ * and class instances are admitted and left unchecked, because a borrowed
+ * result implementation may add them. 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 +474,17 @@ 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`.
+ * `id`, the optional authored text, `applied`, a plain-number `value`, and each
+ * `WorksheetFactor` entry are checked. Unknown members, prototypes, and class
+ * instances are admitted and left unchecked, because a borrowed result
+ * implementation may add them. 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 +496,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 +511,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
+ * 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,12 +558,13 @@ 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
  * definition validation. `MISMATCH` — a rated subject is not a record.
- * `DESTROYED` — use of a destroyed entity.
+ * `DESTROYED` — use of a destroyed entity. `context` carries optional
+ * structured detail beside the message.
  *
  * @example
  * ```ts
@@ -417,40 +579,50 @@ 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. Each overload rates a single subject — there is no
+ * batch-of-subjects overload.
  */
 export declare interface RaterInterface {
+    /** Holds the typed emitter every `rate` call fires its event through. */
     readonly emitter: EmitterInterface<RaterEventMap>;
+    /**
+     * Rates an array of lines, or a {@link RatingDefinition}, against one subject over
+     * the shared quantitative engine.
+     */
     rate(lines: readonly LineDefinition[], subject: Subject): RatingResult;
     rate(definition: RatingDefinition, subject: Subject): RatingResult;
+    /**
+     * Destroys an owned engine and then the emitter, and does nothing on a later
+     * call.
+     */
     destroy(): void;
 }
 
 /**
- * Options for `createRater` / the `Rater` constructor.
+ * Configures `createRater` and 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
+ * 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}.
@@ -464,7 +636,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 +652,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 +665,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 +678,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 +713,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 +723,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 +733,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 { }