@orkestrel/rater 0.0.12 → 0.0.14

package/dist/src/core/index.js

@@ -1,14 +1,15 @@
-import { arrayOf, isArray, isBoolean, isJSONValue, isNumber, isString, literalOf, objectOf, recordOf } from "@orkestrel/contract";
-import { buildErrorResult, createQuantitativeReasoner, createReason, formatField, isAggregation, isComparison, isFieldPath, isQuantitativeDefinition, isSubject } from "@orkestrel/reason";
+import { arrayOf, isArray, isBoolean, isJSONValue, isNumber, isRecord, isString, literalOf, objectOf, recordOf } from "@orkestrel/contract";
+import { buildErrorResult, createQuantitativeReasoner, createReason, formatField, isAggregation, isComparison, isFieldPath, isQuantitativeDefinition } from "@orkestrel/reason";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/errors.ts
 /**
-* 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
@@ -28,10 +29,10 @@ var RaterError = class extends Error {
 	}
 };
 /**
-* 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
@@ -50,10 +51,14 @@ function isRaterError(value) {
 //#endregion
 //#region src/core/validators.ts
 /**
-* 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
@@ -65,21 +70,24 @@ function isRaterError(value) {
 */
 var isStage = literalOf("factor", "group", "total");
 /**
-* 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
 * ```
 */
 function isLineDefinition(value) {
@@ -92,14 +100,17 @@ function isLineDefinition(value) {
 	}, ["description", "metadata"])(value);
 }
 /**
-* 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
@@ -118,16 +129,19 @@ function isRatingDefinition(value) {
 	}, ["description", "metadata"])(value);
 }
 /**
-* 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
@@ -150,14 +164,17 @@ function isEvidence(value) {
 	])(value);
 }
 /**
-* 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
@@ -181,14 +198,17 @@ function isWorksheetFactor(value) {
 	])(value);
 }
 /**
-* 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
@@ -208,14 +228,17 @@ function isWorksheetGroup(value) {
 	}, ["name", "description"])(value);
 }
 /**
-* 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 +261,18 @@ function isStep(value) {
 	])(value);
 }
 /**
-* 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
@@ -269,21 +296,26 @@ function isWorksheet(value) {
 	}, ["precision"])(value);
 }
 /**
-* 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
 * ```
 */
 function isLineResult(value) {
@@ -291,21 +323,23 @@ function isLineResult(value) {
 		id: isString,
 		name: isString,
 		amount: isNumber,
-		worksheet: isWorksheet,
-		success: isBoolean
+		worksheet: isWorksheet
 	}, ["amount"])(value);
 }
 /**
-* 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
@@ -324,7 +358,9 @@ function isRatingResult(value) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Build 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
@@ -334,13 +370,13 @@ function isRatingResult(value) {
 *
 * @example
 * ```ts
-* import { quantitativeDefinition } from '@orkestrel/reason'
-* import { lineDefinition } from '@orkestrel/rater'
+* import { createQuantitativeDefinition } from '@orkestrel/reason'
+* import { buildLineDefinition } from '@orkestrel/rater'
 *
-* lineDefinition('base', 'Base Amount', quantitativeDefinition('base', 'Base', []))
+* buildLineDefinition('base', 'Base Amount', createQuantitativeDefinition('base', 'Base', []))
 * ```
 */
-function lineDefinition(id, name, rate, overrides) {
+function buildLineDefinition(id, name, rate, overrides) {
 	return {
 		id,
 		name,
@@ -349,7 +385,8 @@ function lineDefinition(id, name, rate, overrides) {
 	};
 }
 /**
-* Build 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
@@ -359,15 +396,15 @@ function lineDefinition(id, name, rate, overrides) {
 *
 * @example
 * ```ts
-* import { lineDefinition, ratingDefinition } from '@orkestrel/rater'
-* import { quantitativeDefinition } from '@orkestrel/reason'
+* import { buildLineDefinition, buildRatingDefinition } from '@orkestrel/rater'
+* import { createQuantitativeDefinition } from '@orkestrel/reason'
 *
-* ratingDefinition('r1', 'Rating', [
-* 	lineDefinition('base', 'Base Amount', quantitativeDefinition('base', 'Base', [])),
+* buildRatingDefinition('r1', 'Rating', [
+* 	buildLineDefinition('base', 'Base Amount', createQuantitativeDefinition('base', 'Base', [])),
 * ])
 * ```
 */
-function ratingDefinition(id, name, lines, overrides) {
+function buildRatingDefinition(id, name, lines, overrides) {
 	return {
 		id,
 		name,
@@ -376,24 +413,25 @@ function ratingDefinition(id, name, lines, overrides) {
 	};
 }
 /**
-* Build an {@link Evidence} row from an evaluated {@link Check}.
+* Builds 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 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 { check } from '@orkestrel/reason'
-* import { evidenceCheck } from '@orkestrel/rater'
+* import { createCheck } from '@orkestrel/reason'
+* import { buildEvidence } from '@orkestrel/rater'
 *
-* const entry = check('age', 'above', 18)
-* evidenceCheck(entry, 25, true) // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
+* const entry = createCheck('age', 'above', 18)
+* buildEvidence(entry, 25, true) // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
 * ```
 */
-function evidenceCheck(check, actual, met, labels) {
+function buildEvidence(check, actual, met, labels) {
 	const field = formatField(check.field);
 	return {
 		field: check.field,
@@ -405,8 +443,8 @@ function evidenceCheck(check, actual, met, labels) {
 	};
 }
 /**
-* Build evidence rows from a quantitative factor's authored checks and
-* evaluated check results.
+* 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
@@ -415,21 +453,21 @@ function evidenceCheck(check, actual, met, labels) {
 *
 * @example
 * ```ts
-* import { check } from '@orkestrel/reason'
-* import { checkEvidence } from '@orkestrel/rater'
+* import { createCheck } from '@orkestrel/reason'
+* import { buildEvidenceRows } from '@orkestrel/rater'
 *
-* const checks = [check('age', 'above', 18)]
-* checkEvidence(checks, [{ field: 'age', met: true, actual: 25 }])
+* const checks = [createCheck('age', 'above', 18)]
+* buildEvidenceRows(checks, [{ field: 'age', met: true, actual: 25 }])
 * ```
 */
-function checkEvidence(checks, results, labels) {
+function buildEvidenceRows(checks, results, labels) {
 	return (checks ?? []).map((check, index) => {
 		const result = results?.[index];
-		return evidenceCheck(check, result?.actual, result?.met, labels);
+		return buildEvidence(check, result?.actual, result?.met, labels);
 	});
 }
 /**
-* Join one authored quantitative factor to its evaluated {@link FactorResult}.
+* Joins one authored quantitative factor to its evaluated {@link FactorResult}.
 *
 * @param definition - The authored factor
 * @param results - The group's factor results
@@ -438,14 +476,14 @@ function checkEvidence(checks, results, labels) {
 *
 * @example
 * ```ts
-* import { fieldFactor } from '@orkestrel/reason'
-* import { worksheetFactor } from '@orkestrel/rater'
+* import { createFieldFactor } from '@orkestrel/reason'
+* import { buildWorksheetFactor } from '@orkestrel/rater'
 *
-* const factor = fieldFactor('seats', 'seats')
-* worksheetFactor(factor, [{ id: 'seats', applied: true, value: 10 }])
+* const factor = createFieldFactor('seats', 'seats')
+* buildWorksheetFactor(factor, [{ id: 'seats', applied: true, value: 10 }])
 * ```
 */
-function worksheetFactor(definition, results, labels) {
+function buildWorksheetFactor(definition, results, labels) {
 	const result = results.find((entry) => entry.id === definition.id);
 	return {
 		id: definition.id,
@@ -453,11 +491,11 @@ function worksheetFactor(definition, results, labels) {
 		...definition.description === void 0 ? {} : { description: definition.description },
 		applied: result?.applied ?? false,
 		...result?.value === void 0 ? {} : { value: result.value },
-		evidence: checkEvidence(definition.checks, result?.checks, labels)
+		evidence: buildEvidenceRows(definition.checks, result?.checks, labels)
 	};
 }
 /**
-* Join one authored quantitative group to its evaluated {@link GroupResult}.
+* Joins one authored quantitative group to its evaluated {@link GroupResult}.
 *
 * @param definition - The authored group
 * @param results - The definition's group results
@@ -466,14 +504,14 @@ function worksheetFactor(definition, results, labels) {
 *
 * @example
 * ```ts
-* import { factorGroup, staticFactor } from '@orkestrel/reason'
-* import { worksheetGroup } from '@orkestrel/rater'
+* import { createFactorGroup, createStaticFactor } from '@orkestrel/reason'
+* import { buildWorksheetGroup } from '@orkestrel/rater'
 *
-* const group = factorGroup('charge', 'sum', [staticFactor('base', 100)])
-* worksheetGroup(group, [{ id: 'charge', applied: true, value: 100, factors: [] }])
+* const group = createFactorGroup('charge', 'sum', [createStaticFactor('base', 100)])
+* buildWorksheetGroup(group, [{ id: 'charge', applied: true, value: 100, factors: [] }])
 * ```
 */
-function worksheetGroup(definition, results, labels) {
+function buildWorksheetGroup(definition, results, labels) {
 	const result = results.find((entry) => entry.id === definition.id);
 	return {
 		id: definition.id,
@@ -481,11 +519,11 @@ function worksheetGroup(definition, results, labels) {
 		...definition.description === void 0 ? {} : { description: definition.description },
 		applied: result?.applied ?? false,
 		value: result?.value ?? 0,
-		factors: definition.factors.map((factor) => worksheetFactor(factor, result?.factors ?? [], labels))
+		factors: definition.factors.map((factor) => buildWorksheetFactor(factor, result?.factors ?? [], labels))
 	};
 }
 /**
-* Build one display-neutral {@link Step} row.
+* Builds one display-neutral {@link Step} row.
 *
 * @param stage - The step's stage
 * @param id - The stage's authored id, when it has one
@@ -496,13 +534,13 @@ function worksheetGroup(definition, results, labels) {
 *
 * @example
 * ```ts
-* import { worksheetStep } from '@orkestrel/rater'
+* import { buildWorksheetStep } from '@orkestrel/rater'
 *
-* worksheetStep('total', 'quote', 'Quote', 110, 'sum = 110')
+* buildWorksheetStep('total', 'quote', 'Quote', 110, 'sum = 110')
 * // { stage: 'total', id: 'quote', name: 'Quote', value: 110, expression: 'sum = 110' }
 * ```
 */
-function worksheetStep(stage, id, name, value, expression) {
+function buildWorksheetStep(stage, id, name, value, expression) {
 	return {
 		stage,
 		...id === void 0 ? {} : { id },
@@ -512,7 +550,7 @@ function worksheetStep(stage, id, name, value, expression) {
 	};
 }
 /**
-* Build the ordered {@link Step} rows for a resolved {@link Worksheet}.
+* Builds the ordered {@link Step} rows for a resolved {@link Worksheet}.
 *
 * @param definition - The authored quantitative definition
 * @param result - The evaluated quantitative result
@@ -521,27 +559,27 @@ function worksheetStep(stage, id, name, value, expression) {
 *
 * @example
 * ```ts
-* import { createQuantitativeReasoner, createReason, factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
-* import { worksheetGroup, worksheetSteps } from '@orkestrel/rater'
+* import { createFactorGroup, createQuantitativeDefinition, createQuantitativeReasoner, createReason, createStaticFactor } from '@orkestrel/reason'
+* import { buildWorksheetGroup, buildWorksheetSteps } from '@orkestrel/rater'
 *
-* const definition = quantitativeDefinition('base', 'Base', [factorGroup('g', 'sum', [staticFactor('flat', 100)])])
+* const definition = createQuantitativeDefinition('base', 'Base', [createFactorGroup('g', 'sum', [createStaticFactor('flat', 100)])])
 * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, definition)
 * if (result.reasoning === 'quantitative') {
-* 	worksheetSteps(definition, result, definition.groups.map((group) => worksheetGroup(group, result.groups)))
+* 	buildWorksheetSteps(definition, result, definition.groups.map((group) => buildWorksheetGroup(group, result.groups)))
 * }
 * ```
 */
-function worksheetSteps(definition, result, groups) {
+function buildWorksheetSteps(definition, result, groups) {
 	const output = [];
 	for (const group of groups) {
-		for (const factor of group.factors) if (factor.applied && factor.value !== void 0) output.push(worksheetStep("factor", factor.id, factor.name, factor.value, `${factor.id} = ${factor.value}`));
-		output.push(worksheetStep("group", group.id, group.name, group.value, `${group.id} = ${group.value}`));
+		for (const factor of group.factors) if (factor.applied && factor.value !== void 0) output.push(buildWorksheetStep("factor", factor.id, factor.name, factor.value, `${factor.id} = ${factor.value}`));
+		output.push(buildWorksheetStep("group", group.id, group.name, group.value, `${group.id} = ${group.value}`));
 	}
-	output.push(worksheetStep("total", definition.id, definition.name, result.value, `${definition.aggregation} = ${result.value}`));
+	output.push(buildWorksheetStep("total", definition.id, definition.name, result.value, `${definition.aggregation} = ${result.value}`));
 	return output;
 }
 /**
-* Join a {@link QuantitativeDefinition} and its {@link QuantitativeResult} into
+* Joins a {@link QuantitativeDefinition} and its {@link QuantitativeResult} into
 * a {@link Worksheet} — the rating audit trail.
 *
 * @param definition - The authored quantitative definition
@@ -551,16 +589,16 @@ function worksheetSteps(definition, result, groups) {
 *
 * @example
 * ```ts
-* import { createQuantitativeReasoner, createReason, factorGroup, quantitativeDefinition, staticFactor } from '@orkestrel/reason'
-* import { resultsWorksheet } from '@orkestrel/rater'
+* import { createFactorGroup, createQuantitativeDefinition, createQuantitativeReasoner, createReason, createStaticFactor } from '@orkestrel/reason'
+* import { buildWorksheet } from '@orkestrel/rater'
 *
-* const definition = quantitativeDefinition('base', 'Base', [factorGroup('g', 'sum', [staticFactor('flat', 100)])])
+* const definition = createQuantitativeDefinition('base', 'Base', [createFactorGroup('g', 'sum', [createStaticFactor('flat', 100)])])
 * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, definition)
-* if (result.reasoning === 'quantitative') resultsWorksheet(definition, result) // the full audit trail
+* if (result.reasoning === 'quantitative') buildWorksheet(definition, result) // the full audit trail
 * ```
 */
-function resultsWorksheet(definition, result, labels) {
-	const groups = definition.groups.map((group) => worksheetGroup(group, result.groups, labels));
+function buildWorksheet(definition, result, labels) {
+	const groups = definition.groups.map((group) => buildWorksheetGroup(group, result.groups, labels));
 	return {
 		id: definition.id,
 		name: definition.name,
@@ -568,14 +606,14 @@ function resultsWorksheet(definition, result, labels) {
 		...definition.precision === void 0 ? {} : { precision: definition.precision },
 		value: result.value,
 		groups,
-		steps: worksheetSteps(definition, result, groups),
+		steps: buildWorksheetSteps(definition, result, groups),
 		trace: result.trace,
 		errors: result.errors,
 		success: result.success
 	};
 }
 /**
-* Build a rated {@link LineResult} from a line's evaluated
+* Builds a rated {@link LineResult} from a line's evaluated
 * {@link QuantitativeResult}.
 *
 * @param definition - The authored line definition
@@ -585,38 +623,37 @@ function resultsWorksheet(definition, result, labels) {
 *
 * @example
 * ```ts
-* import { createQuantitativeReasoner, createReason, quantitativeDefinition } from '@orkestrel/reason'
-* import { lineDefinition, ratedLine } from '@orkestrel/rater'
+* import { createQuantitativeDefinition, createQuantitativeReasoner, createReason } from '@orkestrel/reason'
+* import { buildLineDefinition, buildLineResult } from '@orkestrel/rater'
 *
-* const line = lineDefinition('base', 'Base', quantitativeDefinition('base', 'Base', []))
+* const line = buildLineDefinition('base', 'Base', createQuantitativeDefinition('base', 'Base', []))
 * const result = createReason({ reasoners: [createQuantitativeReasoner()] }).reason({}, line.rate)
-* if (result.reasoning === 'quantitative') ratedLine(line, result) // amount present only when success
+* if (result.reasoning === 'quantitative') buildLineResult(line, result) // amount present only on a successful worksheet
 * ```
 */
-function ratedLine(definition, result, labels) {
+function buildLineResult(definition, result, labels) {
 	return {
 		id: definition.id,
 		name: definition.name,
 		...result.success ? { amount: result.value } : {},
-		worksheet: resultsWorksheet(definition.rate, result, labels),
-		success: result.success
+		worksheet: buildWorksheet(definition.rate, result, labels)
 	};
 }
 /**
-* 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
 * ```
 */
 function sumAmounts(lines) {
@@ -631,17 +668,17 @@ function sumAmounts(lines) {
 //#endregion
 //#region src/core/Rater.ts
 /**
-* 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
@@ -683,10 +720,10 @@ var Rater = class {
 	rate(input, subject) {
 		this.#ensureAlive();
 		const lines = this.#normalize(input);
-		if (!isSubject(subject)) throw new RaterError("MISMATCH", "Subject must be a record");
+		if (!isRecord(subject)) throw new RaterError("MISMATCH", "Subject must be a record");
 		const results = lines.map((line) => this.#rateLine(line, subject));
 		const total = (this.#total ?? sumAmounts)(results);
-		const success = results.every((entry) => entry.success);
+		const success = results.every((entry) => entry.worksheet.success);
 		const result = {
 			lines: results,
 			...total === void 0 ? {} : { total },
@@ -707,7 +744,7 @@ var Rater = class {
 		throw new RaterError("DEFINITION", "Rating input must be an array of line definitions or a rating definition");
 	}
 	#rateLine(line, subject) {
-		return ratedLine(line, this.#reasonQuantitative(subject, line.rate), this.#labels);
+		return buildLineResult(line, this.#reasonQuantitative(subject, line.rate), this.#labels);
 	}
 	#reasonQuantitative(subject, definition) {
 		const result = this.#engine.reason(subject, definition);
@@ -735,12 +772,13 @@ var Rater = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create 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'
 *
@@ -752,6 +790,6 @@ function createRater(options) {
 	return new Rater(options);
 }
 //#endregion
-export { Rater, RaterError, checkEvidence, createRater, evidenceCheck, isEvidence, isLineDefinition, isLineResult, isRaterError, isRatingDefinition, isRatingResult, isStage, isStep, isWorksheet, isWorksheetFactor, isWorksheetGroup, lineDefinition, ratedLine, ratingDefinition, resultsWorksheet, sumAmounts, worksheetFactor, worksheetGroup, worksheetStep, worksheetSteps };
+export { Rater, RaterError, buildEvidence, buildEvidenceRows, buildLineDefinition, buildLineResult, buildRatingDefinition, buildWorksheet, buildWorksheetFactor, buildWorksheetGroup, buildWorksheetStep, buildWorksheetSteps, createRater, isEvidence, isLineDefinition, isLineResult, isRaterError, isRatingDefinition, isRatingResult, isStage, isStep, isWorksheet, isWorksheetFactor, isWorksheetGroup, sumAmounts };
 
 //# sourceMappingURL=index.js.map