@orkestrel/rater 0.0.12 → 0.0.14

package/dist/src/core/index.cjs

@@ -4,12 +4,13 @@ let _orkestrel_reason = require("@orkestrel/reason");
 let _orkestrel_emitter = require("@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
@@ -29,10 +30,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
@@ -51,10 +52,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
@@ -66,21 +71,24 @@ function isRaterError(value) {
 */
 var isStage = (0, _orkestrel_contract.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) {
@@ -93,14 +101,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
@@ -119,16 +130,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
@@ -151,14 +165,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
@@ -182,14 +199,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
@@ -209,14 +229,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
@@ -239,14 +262,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
@@ -270,21 +297,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) {
@@ -292,21 +324,23 @@ function isLineResult(value) {
 		id: _orkestrel_contract.isString,
 		name: _orkestrel_contract.isString,
 		amount: _orkestrel_contract.isNumber,
-		worksheet: isWorksheet,
-		success: _orkestrel_contract.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
@@ -325,7 +359,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
@@ -335,13 +371,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,
@@ -350,7 +386,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
@@ -360,15 +397,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,
@@ -377,24 +414,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 = (0, _orkestrel_reason.formatField)(check.field);
 	return {
 		field: check.field,
@@ -406,8 +444,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
@@ -416,21 +454,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
@@ -439,14 +477,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,
@@ -454,11 +492,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
@@ -467,14 +505,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,
@@ -482,11 +520,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
@@ -497,13 +535,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 },
@@ -513,7 +551,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
@@ -522,27 +560,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
@@ -552,16 +590,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,
@@ -569,14 +607,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
@@ -586,38 +624,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) {
@@ -632,17 +669,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
@@ -684,10 +721,10 @@ var Rater = class {
 	rate(input, subject) {
 		this.#ensureAlive();
 		const lines = this.#normalize(input);
-		if (!(0, _orkestrel_reason.isSubject)(subject)) throw new RaterError("MISMATCH", "Subject must be a record");
+		if (!(0, _orkestrel_contract.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 },
@@ -708,7 +745,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);
@@ -736,12 +773,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'
 *
@@ -755,9 +793,17 @@ function createRater(options) {
 //#endregion
 exports.Rater = Rater;
 exports.RaterError = RaterError;
-exports.checkEvidence = checkEvidence;
+exports.buildEvidence = buildEvidence;
+exports.buildEvidenceRows = buildEvidenceRows;
+exports.buildLineDefinition = buildLineDefinition;
+exports.buildLineResult = buildLineResult;
+exports.buildRatingDefinition = buildRatingDefinition;
+exports.buildWorksheet = buildWorksheet;
+exports.buildWorksheetFactor = buildWorksheetFactor;
+exports.buildWorksheetGroup = buildWorksheetGroup;
+exports.buildWorksheetStep = buildWorksheetStep;
+exports.buildWorksheetSteps = buildWorksheetSteps;
 exports.createRater = createRater;
-exports.evidenceCheck = evidenceCheck;
 exports.isEvidence = isEvidence;
 exports.isLineDefinition = isLineDefinition;
 exports.isLineResult = isLineResult;
@@ -769,14 +815,6 @@ exports.isStep = isStep;
 exports.isWorksheet = isWorksheet;
 exports.isWorksheetFactor = isWorksheetFactor;
 exports.isWorksheetGroup = isWorksheetGroup;
-exports.lineDefinition = lineDefinition;
-exports.ratedLine = ratedLine;
-exports.ratingDefinition = ratingDefinition;
-exports.resultsWorksheet = resultsWorksheet;
 exports.sumAmounts = sumAmounts;
-exports.worksheetFactor = worksheetFactor;
-exports.worksheetGroup = worksheetGroup;
-exports.worksheetStep = worksheetStep;
-exports.worksheetSteps = worksheetSteps;
 
 //# sourceMappingURL=index.cjs.map