@orkestrel/rater 0.0.13 → 0.0.14

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

@@ -1,20 +1,20 @@
-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';
+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}.
@@ -58,7 +58,9 @@ export declare function buildEvidence(check: Check, actual: unknown, met: boolea
 export declare function buildEvidenceRows(checks: readonly Check[] | undefined, results: readonly CheckResult[] | undefined, labels?: Readonly<Record<string, string>>): readonly Evidence[];
 
 /**
- * Builds a {@link LineDefinition}.
+ * 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
@@ -98,7 +100,8 @@ export declare function buildLineDefinition(id: string, name: string, rate: Quan
 export declare function buildLineResult(definition: LineDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>): LineResult;
 
 /**
- * Builds a {@link RatingDefinition}.
+ * 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
@@ -220,12 +223,13 @@ export declare function buildWorksheetStep(stage: Stage, id: string | undefined,
 export declare function buildWorksheetSteps(definition: QuantitativeDefinition, result: QuantitativeResult, groups: readonly WorksheetGroup[]): readonly Step[];
 
 /**
- * Creates a rating orchestrator.
+ * 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'
  *
@@ -249,10 +253,13 @@ export declare interface Evidence {
  * 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 if every checked `Evidence` member conforms; false otherwise
@@ -270,8 +277,11 @@ export declare function isEvidence(value: unknown): value is Evidence;
  * Determines whether a value is an exact {@link LineDefinition} record.
  *
  * @remarks
- * Total guard: 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 if `value` is a `LineDefinition`; false otherwise
@@ -290,10 +300,14 @@ export declare function isLineDefinition(value: unknown): value is LineDefinitio
  * 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. The line's
- * outcome lives on `worksheet`, so `worksheet.success` carries it.
+ * 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 if every published line-result member conforms; false otherwise
@@ -330,8 +344,11 @@ export declare function isRaterError(value: unknown): value is RaterError;
  * Determines whether a value is an exact {@link RatingDefinition} record.
  *
  * @remarks
- * Total guard: 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 if `value` is a `RatingDefinition`; false otherwise
@@ -349,10 +366,13 @@ export declare function isRatingDefinition(value: unknown): value is RatingDefin
  * 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 if every published rating-result member conforms; false otherwise
@@ -369,6 +389,10 @@ export declare function isRatingResult(value: unknown): value is RatingResult;
 /**
  * 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 if `value` is `'factor'`, `'group'`, or `'total'`; false otherwise
  *
@@ -386,8 +410,11 @@ export declare const isStage: Guard<Stage>;
  * 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 if every published worksheet-step member conforms; false otherwise
@@ -405,8 +432,12 @@ export declare function isStep(value: unknown): value is Step;
  * 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 if every published worksheet member conforms; false otherwise
@@ -424,8 +455,11 @@ export declare function isWorksheet(value: unknown): value is Worksheet;
  * 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 if every published worksheet-factor member conforms; false otherwise
@@ -443,8 +477,11 @@ export declare function isWorksheetFactor(value: unknown): value is WorksheetFac
  * 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 if every published worksheet-group member conforms; false otherwise
@@ -479,7 +516,7 @@ export declare interface LineDefinition {
  * @remarks
  * `worksheet` is always present — even a failed evaluation resolves to a
  * type-shaped failure worksheet, so a `LineResult` is always constructible.
- * The worksheet also carries the line's outcome: `amount` is present ONLY
+ * The worksheet also carries the line's outcome: `amount` is present only
  * when `worksheet.success` is `true`.
  */
 export declare interface LineResult {
@@ -494,12 +531,12 @@ export declare interface LineResult {
  * 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 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
+ * 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
@@ -526,7 +563,8 @@ export declare class Rater implements RaterInterface {
  * @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
@@ -559,14 +597,23 @@ export declare type RaterEventMap = {
  * Represents the rating orchestrator over the shared quantitative reasoning engine.
  *
  * @remarks
- * 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
+ * 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;
 }
 
@@ -575,7 +622,7 @@ export declare interface RaterInterface {
  *
  * @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}.

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

@@ -1,20 +1,20 @@
-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';
+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}.
@@ -58,7 +58,9 @@ export declare function buildEvidence(check: Check, actual: unknown, met: boolea
 export declare function buildEvidenceRows(checks: readonly Check[] | undefined, results: readonly CheckResult[] | undefined, labels?: Readonly<Record<string, string>>): readonly Evidence[];
 
 /**
- * Builds a {@link LineDefinition}.
+ * 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
@@ -98,7 +100,8 @@ export declare function buildLineDefinition(id: string, name: string, rate: Quan
 export declare function buildLineResult(definition: LineDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>): LineResult;
 
 /**
- * Builds a {@link RatingDefinition}.
+ * 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
@@ -220,12 +223,13 @@ export declare function buildWorksheetStep(stage: Stage, id: string | undefined,
 export declare function buildWorksheetSteps(definition: QuantitativeDefinition, result: QuantitativeResult, groups: readonly WorksheetGroup[]): readonly Step[];
 
 /**
- * Creates a rating orchestrator.
+ * 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'
  *
@@ -249,10 +253,13 @@ export declare interface Evidence {
  * 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 if every checked `Evidence` member conforms; false otherwise
@@ -270,8 +277,11 @@ export declare function isEvidence(value: unknown): value is Evidence;
  * Determines whether a value is an exact {@link LineDefinition} record.
  *
  * @remarks
- * Total guard: 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 if `value` is a `LineDefinition`; false otherwise
@@ -290,10 +300,14 @@ export declare function isLineDefinition(value: unknown): value is LineDefinitio
  * 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. The line's
- * outcome lives on `worksheet`, so `worksheet.success` carries it.
+ * 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 if every published line-result member conforms; false otherwise
@@ -330,8 +344,11 @@ export declare function isRaterError(value: unknown): value is RaterError;
  * Determines whether a value is an exact {@link RatingDefinition} record.
  *
  * @remarks
- * Total guard: 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 if `value` is a `RatingDefinition`; false otherwise
@@ -349,10 +366,13 @@ export declare function isRatingDefinition(value: unknown): value is RatingDefin
  * 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 if every published rating-result member conforms; false otherwise
@@ -369,6 +389,10 @@ export declare function isRatingResult(value: unknown): value is RatingResult;
 /**
  * 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 if `value` is `'factor'`, `'group'`, or `'total'`; false otherwise
  *
@@ -386,8 +410,11 @@ export declare const isStage: Guard<Stage>;
  * 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 if every published worksheet-step member conforms; false otherwise
@@ -405,8 +432,12 @@ export declare function isStep(value: unknown): value is Step;
  * 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 if every published worksheet member conforms; false otherwise
@@ -424,8 +455,11 @@ export declare function isWorksheet(value: unknown): value is Worksheet;
  * 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 if every published worksheet-factor member conforms; false otherwise
@@ -443,8 +477,11 @@ export declare function isWorksheetFactor(value: unknown): value is WorksheetFac
  * 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 if every published worksheet-group member conforms; false otherwise
@@ -479,7 +516,7 @@ export declare interface LineDefinition {
  * @remarks
  * `worksheet` is always present — even a failed evaluation resolves to a
  * type-shaped failure worksheet, so a `LineResult` is always constructible.
- * The worksheet also carries the line's outcome: `amount` is present ONLY
+ * The worksheet also carries the line's outcome: `amount` is present only
  * when `worksheet.success` is `true`.
  */
 export declare interface LineResult {
@@ -494,12 +531,12 @@ export declare interface LineResult {
  * 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 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
+ * 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
@@ -526,7 +563,8 @@ export declare class Rater implements RaterInterface {
  * @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
@@ -559,14 +597,23 @@ export declare type RaterEventMap = {
  * Represents the rating orchestrator over the shared quantitative reasoning engine.
  *
  * @remarks
- * 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
+ * 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;
 }
 
@@ -575,7 +622,7 @@ export declare interface RaterInterface {
  *
  * @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}.