@orkestrel/rater 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,1551 @@
+import { arrayOf, isFiniteNumber, isJSONValue, isRecord, isString, literalOf, recordOf, resolveField, unionOf, whereOf } from "@orkestrel/contract";
+import { assignField, buildErrorResult, createEvaluator, createLogicalReasoner, createQuantitativeReasoner, createReason, extractAtoms, extractConclusions, formatField, isBounds, isFieldPath, isLogicalDefinition, isQuantitativeDefinition, mergeSubjects } from "@orkestrel/reason";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/core/constants.ts
+/** Default definition validation policy for `ProgramManager.add`. */
+var DEFAULT_RATER_VALIDATE = true;
+/** Eligibility severity order, most severe first — the {@link combineEligibilities} scan order. */
+var ELIGIBILITY_PRECEDENCE = Object.freeze([
+	"ineligible",
+	"referral",
+	"eligible"
+]);
+/** Status tally precedence order — least to most resolved. */
+var STATUS_PRECEDENCE = Object.freeze([
+	"ineligible",
+	"referral",
+	"conditional",
+	"unrated",
+	"eligible"
+]);
+/** The deterministic authority decision for each eligibility. */
+var ELIGIBILITY_DECISIONS = Object.freeze({
+	eligible: "approved",
+	ineligible: "denied",
+	referral: "submitted"
+});
+/** The direct eligibility impact of an applied determination, by its effect. */
+var EFFECT_ELIGIBILITIES = Object.freeze({
+	restriction: "ineligible",
+	referral: "referral",
+	condition: void 0,
+	notice: void 0,
+	limit: void 0
+});
+/** The reserved working-subject key a batch's aggregate projection is written under. */
+var AGGREGATE_KEY = "aggregate";
+/** The reserved working-subject key an authority's outcome projection is written under. */
+var OUTCOME_KEY = "outcome";
+//#endregion
+//#region src/core/errors.ts
+/**
+* A coded programmer error thrown by the rating layer.
+*
+* @remarks
+* `DUPLICATE` — a program id collision on `ProgramManager.add`. `MISSING` — an
+* unknown authored line reference at compile time.
+* `DEFINITION` — a program definition failed `isProgramDefinition`. `MISMATCH` —
+* a rated subject is not a record, or uses a reserved working-subject key.
+* `DESTROYED` — use of a destroyed entity.
+*/
+var RaterError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "RaterError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/** Narrow a caught value to a {@link RaterError}. */
+function isRaterError(value) {
+	return value instanceof RaterError;
+}
+//#endregion
+//#region src/core/validators.ts
+/** Determine whether a value is an {@link Eligibility} literal. */
+var isEligibility = literalOf("eligible", "ineligible", "referral");
+/** Determine whether a value is a {@link Decision} literal. */
+var isDecision = literalOf("approved", "denied", "submitted");
+/** Determine whether a value is a {@link Status} literal. */
+var isStatus = literalOf("ineligible", "referral", "conditional", "unrated", "eligible");
+/** Determine whether a value is an {@link Effect} literal. */
+var isEffect = literalOf("restriction", "referral", "condition", "notice", "limit");
+/** Determine whether a value is a {@link Stage} literal. */
+var isStage = literalOf("factor", "group", "total");
+/** Determine whether a value is an exact {@link Ruling} record. */
+function isRuling(value) {
+	return recordOf({
+		effect: isEffect,
+		line: isString,
+		message: isString
+	}, ["line", "message"])(value);
+}
+/** Determine whether a value is an exact {@link Notice} record. */
+function isNotice(value) {
+	return recordOf({
+		id: isString,
+		message: isString,
+		line: isString
+	}, ["line"])(value);
+}
+/** Determine whether a value is an exact {@link PassDefinition} record. */
+function isPassDefinition(value) {
+	return recordOf({
+		line: isString,
+		definition: unionOf(isLogicalDefinition, isQuantitativeDefinition)
+	}, ["line"])(value);
+}
+/** Determine whether a value is an exact {@link LineDefinition} record. */
+function isLineDefinition(value) {
+	return recordOf({
+		id: isString,
+		name: isString,
+		description: isString,
+		rate: isQuantitativeDefinition,
+		metadata: isJSONValue
+	}, ["description", "metadata"])(value);
+}
+/** Determine whether a value is an exact {@link AggregateDefinition} record. */
+function isAggregateDefinition(value) {
+	return recordOf({
+		fields: arrayOf(isFieldPath),
+		by: isFieldPath,
+		gates: isLogicalDefinition
+	}, ["by", "gates"])(value);
+}
+/** Determine whether a value is a rule-id-keyed {@link Ruling} record. */
+var isRulings = whereOf(isRecord, (record) => Object.values(record).every(isRuling));
+/** Determine whether a value is an exact {@link ProgramDefinition} record. */
+function isProgramDefinition(value) {
+	return recordOf({
+		id: isString,
+		name: isString,
+		description: isString,
+		passes: arrayOf(isPassDefinition),
+		lines: arrayOf(isLineDefinition),
+		rulings: isRulings,
+		notices: arrayOf(isNotice),
+		authority: isLogicalDefinition,
+		aggregate: isAggregateDefinition,
+		metadata: isJSONValue
+	}, [
+		"description",
+		"passes",
+		"rulings",
+		"notices",
+		"authority",
+		"aggregate",
+		"metadata"
+	])(value);
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Interpolate `{{dotted.path}}` tokens in a message template against a record.
+*
+* @remarks
+* Each token is split on `.` into a {@link FieldPath} array and resolved with
+* the contracts {@link resolveField} (a plain string field is ONE key, never
+* dot-split — the split here is the token-to-path bridge). A finite number
+* renders with `en-US` thousand grouping (`5010` → `5,010`); any other resolved
+* value String-coerces. An UNRESOLVED path (the resolved value is `undefined`)
+* renders as the empty string — the deterministic "nothing to show" rule.
+*
+* @param template - The message template carrying `{{dotted.path}}` tokens
+* @param record - The record tokens resolve against
+* @returns The template with every token replaced
+*
+* @example
+* ```ts
+* import { interpolateMessage } from '@orkestrel/rater'
+*
+* interpolateMessage('Limit is {{limit}}', { limit: 5010 }) // 'Limit is 5,010'
+* interpolateMessage('Missing {{gone}}', {})                // 'Missing '
+* ```
+*/
+function interpolateMessage(template, record) {
+	return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, path) => {
+		const value = resolveField(record, path.split("."));
+		if (value === void 0) return "";
+		if (isFiniteNumber(value)) return value.toLocaleString("en-US");
+		return String(value);
+	});
+}
+/**
+* Describe a {@link Premise} comparison as a display-neutral verb phrase.
+*
+* @param comparison - The comparison to describe
+* @returns A display-neutral phrase
+*
+* @example
+* ```ts
+* import { describeComparison } from '@orkestrel/rater'
+*
+* describeComparison('above') // 'is more than'
+* ```
+*/
+function describeComparison(comparison) {
+	switch (comparison) {
+		case "equals": return "is";
+		case "not": return "is not";
+		case "above": return "is more than";
+		case "below": return "is less than";
+		case "from": return "is at least";
+		case "to": return "is at most";
+		case "any": return "is any of";
+		case "none": return "is none of";
+		case "between": return "is between";
+		case "outside": return "is outside";
+	}
+}
+/**
+* Render a structured or scalar value display-neutrally.
+*
+* @remarks
+* An array renders as its elements, each `String`-coerced, joined with
+* `', '`. A Bounds-shaped record (a reason `Bounds` — the `between`/`outside`
+* comparison's expected value shape) renders its present sides joined with
+* the word `and`; an absent side is omitted. A finite number and everything
+* else fall back to plain `String()` coercion — a finite number is NOT
+* grouped here (that grouping is {@link interpolateMessage}'s own,
+* message-token-only behavior).
+*
+* @param value - The value to render
+* @returns A display-neutral rendering
+*
+* @example
+* ```ts
+* import { describeValue } from '@orkestrel/rater'
+*
+* describeValue([18, 25, 40]) // '18, 25, 40'
+* describeValue({ minimum: 18, maximum: 65 }) // '18 and 65'
+* describeValue(42) // '42'
+* ```
+*/
+function describeValue(value) {
+	if (Array.isArray(value)) return value.map((entry) => String(entry)).join(", ");
+	if (isBounds(value)) {
+		const sides = [];
+		if (value.minimum !== void 0) sides.push(String(value.minimum));
+		if (value.maximum !== void 0) sides.push(String(value.maximum));
+		return sides.join(" and ");
+	}
+	return String(value);
+}
+/**
+* Render one {@link Premise} into a display-neutral sentence.
+*
+* @param entry - The premise to render
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A display-neutral sentence
+*
+* @example
+* ```ts
+* import { describePremise } from '@orkestrel/rater'
+*
+* describePremise({ field: 'age', comparison: 'above', expected: 18, actual: 25, met: true })
+* // 'age is more than 18 ? met'
+* ```
+*/
+function describePremise(entry, labels) {
+	const status = entry.met === void 0 ? "unknown" : entry.met ? "met" : "not met";
+	if (entry.field === void 0 || entry.comparison === void 0) return `${entry.description ?? "Premise"} ? ${status}`;
+	const field = formatField(entry.field);
+	const label = labels?.[field] ?? entry.label ?? field;
+	const expected = entry.expected === void 0 ? "" : ` ${describeValue(entry.expected)}`;
+	return `${label} ${describeComparison(entry.comparison)}${expected} ? ${status}`;
+}
+/**
+* Build a {@link Premise} from an evaluated {@link Check}.
+*
+* @param check - The authored check
+* @param actual - The resolved subject value
+* @param met - Whether the check was met (absent when not yet evaluated)
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh premise
+*/
+function premiseCheck(check, actual, met, labels) {
+	const field = formatField(check.field);
+	return {
+		field: check.field,
+		...labels?.[field] === void 0 ? {} : { label: labels[field] },
+		comparison: check.operator,
+		expected: check.value,
+		actual,
+		...met === void 0 ? {} : { met }
+	};
+}
+/**
+* Build premises from a quantitative factor's authored checks and evaluated
+* check results.
+*
+* @param checks - The factor's authored checks
+* @param results - The corresponding {@link CheckResult}s, in the same order
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh list of premises, one per authored check
+*/
+function checkPremises(checks, results, labels) {
+	return (checks ?? []).map((check, index) => {
+		const result = results?.[index];
+		return premiseCheck(check, result?.actual, result?.met, labels);
+	});
+}
+/**
+* Describe a logical {@link Expression} tree without atom-specific evidence.
+*
+* @param expression - The expression to describe
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A display-neutral description
+*/
+function describeExpression(expression, labels) {
+	if (expression.form === "atom") return describePremise(premiseCheck(expression.check, void 0, void 0, labels), labels);
+	const descriptions = expression.operands.map((operand) => describeExpression(operand, labels));
+	return `${expression.operator} (${descriptions.join(", ")})`;
+}
+/**
+* Build rich premises for one fired {@link Rule} by walking its premise atoms
+* and re-evaluating each against the working subject.
+*
+* @remarks
+* A reason {@link RuleResult} carries only booleans, so this is rater's own
+* premise-audit projection: each authored premise expression is flattened to
+* its atom leaves via {@link extractAtoms}, and each leaf's {@link Check} is
+* re-evaluated through the injected `evaluator`. A membership check (`any` /
+* `none`) over an EMPTY array value is content-free — a tautology or
+* contradiction that reads as "is none of —" in every surface — and is skipped.
+*
+* @param rule - The authored rule
+* @param working - The working subject to evaluate against
+* @param evaluator - The shared reason check evaluator
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh, ordered list of rich premises
+*/
+function logicalPremises(rule, working, evaluator, labels) {
+	const output = [];
+	for (const premise of rule.premises) for (const atom of extractAtoms(premise)) {
+		const { check } = atom;
+		if ((check.operator === "any" || check.operator === "none") && Array.isArray(check.value) && check.value.length === 0) continue;
+		const result = evaluator.evaluate(check, working);
+		output.push(premiseCheck(check, result.actual, result.met, labels));
+	}
+	return output;
+}
+/**
+* Locate an authored {@link Rule} by id.
+*
+* @param definition - The logical definition to search
+* @param id - The rule id
+* @returns The matching rule, or `undefined`
+*/
+function findRule(definition, id) {
+	return definition.rules.find((rule) => rule.id === id);
+}
+/**
+* Join one authored quantitative factor to its evaluated {@link FactorResult}.
+*
+* @param definition - The authored factor
+* @param results - The group's factor results
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh worksheet factor
+*/
+function worksheetFactor(definition, results, labels) {
+	const result = results.find((entry) => entry.id === definition.id);
+	return {
+		id: definition.id,
+		name: definition.name,
+		...definition.description === void 0 ? {} : { description: definition.description },
+		applied: result?.applied ?? false,
+		...result?.value === void 0 ? {} : { value: result.value },
+		premises: checkPremises(definition.checks, result?.checks, labels)
+	};
+}
+/**
+* Join one authored quantitative group to its evaluated {@link GroupResult}.
+*
+* @param definition - The authored group
+* @param results - The definition's group results
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh worksheet group
+*/
+function worksheetGroup(definition, results, labels) {
+	const result = results.find((entry) => entry.id === definition.id);
+	return {
+		id: definition.id,
+		name: definition.name,
+		...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))
+	};
+}
+/**
+* Build one display-neutral {@link Step} row.
+*
+* @param stage - The step's stage
+* @param id - The stage's authored id, when it has one
+* @param name - The stage's authored name, when it has one
+* @param value - The stage's resolved value
+* @param expression - A display-neutral expression string
+* @returns A fresh step
+*/
+function worksheetStep(stage, id, name, value, expression) {
+	return {
+		stage,
+		...id === void 0 ? {} : { id },
+		...name === void 0 ? {} : { name },
+		value,
+		expression
+	};
+}
+/**
+* Build the ordered {@link Step} rows for a resolved {@link Worksheet}.
+*
+* @param definition - The authored quantitative definition
+* @param result - The evaluated quantitative result
+* @param groups - The definition's already-joined worksheet groups
+* @returns A fresh, ordered list of steps: applied factors, then groups, then the total
+*/
+function worksheetSteps(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}`));
+	}
+	output.push(worksheetStep("total", definition.id, definition.name, result.value, `${definition.aggregation} = ${result.value}`));
+	return output;
+}
+/**
+* Join a {@link QuantitativeDefinition} and its {@link QuantitativeResult} into
+* a {@link Worksheet} — the rating audit trail.
+*
+* @param definition - The authored quantitative definition
+* @param result - The evaluated quantitative result
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh worksheet
+*/
+function resultsWorksheet(definition, result, labels) {
+	const groups = definition.groups.map((group) => worksheetGroup(group, result.groups, labels));
+	return {
+		id: definition.id,
+		name: definition.name,
+		aggregation: definition.aggregation,
+		...definition.precision === void 0 ? {} : { precision: definition.precision },
+		value: result.value,
+		groups,
+		steps: worksheetSteps(definition, result, groups),
+		trace: result.trace,
+		errors: result.errors,
+		success: result.success
+	};
+}
+/**
+* Convert fired logical {@link RuleResult}s into line- or program-scoped
+* {@link Determination}s.
+*
+* @param definition - The authored logical definition
+* @param result - The evaluated logical result
+* @param rulings - Authored consequences, keyed by rule id
+* @param working - The working subject the rules ran against
+* @param line - The line id this pass is scoped to, when it is line-scoped
+* @param evaluator - The shared reason check evaluator
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh list of determinations
+*/
+function rulesToDeterminations(definition, result, rulings, working, line, evaluator, labels) {
+	const output = [];
+	for (const entry of result.rules) {
+		const authored = findRule(definition, entry.id);
+		if (authored === void 0) continue;
+		const routed = rulings?.[entry.id];
+		if (!entry.applied && routed === void 0) continue;
+		const resolved = routed?.line ?? line;
+		output.push({
+			id: entry.id,
+			effect: routed?.effect ?? "restriction",
+			applied: entry.applied,
+			...resolved === void 0 ? {} : { line: resolved },
+			...routed?.message === void 0 ? {} : { message: interpolateMessage(routed.message, working) },
+			premises: logicalPremises(authored, working, evaluator, labels)
+		});
+	}
+	return output;
+}
+/**
+* Convert an authority's fired {@link RuleResult}s into `limit`
+* {@link Determination}s.
+*
+* @param definition - The authority's logical definition
+* @param result - The evaluated logical result
+* @param rulings - Authored consequences, keyed by rule id
+* @param working - The working subject the authority ran against
+* @param evaluator - The shared reason check evaluator
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh list of `limit` determinations
+*/
+function authorityToDeterminations(definition, result, rulings, working, evaluator, labels) {
+	const output = [];
+	for (const entry of result.rules) {
+		if (!entry.applied) continue;
+		const authored = findRule(definition, entry.id);
+		if (authored === void 0) continue;
+		const routed = rulings?.[entry.id];
+		output.push({
+			id: entry.id,
+			effect: "limit",
+			applied: true,
+			...routed?.line === void 0 ? {} : { line: routed.line },
+			...routed?.message === void 0 ? {} : { message: interpolateMessage(routed.message, working) },
+			premises: logicalPremises(authored, working, evaluator, labels)
+		});
+	}
+	return output;
+}
+/**
+* Convert authored {@link Notice}s into unconditionally-applied
+* `notice` {@link Determination}s.
+*
+* @param notices - The authored notices
+* @param working - The working subject to interpolate messages against
+* @returns A fresh list of notice determinations
+*/
+function noticesToDeterminations(notices, working) {
+	return (notices ?? []).map((entry) => ({
+		id: entry.id,
+		effect: "notice",
+		applied: true,
+		...entry.line === void 0 ? {} : { line: entry.line },
+		message: interpolateMessage(entry.message, working),
+		premises: []
+	}));
+}
+/**
+* Keep only the determinations scoped to one line.
+*
+* @param determinations - The determinations to filter
+* @param id - The line id to keep
+* @returns The determinations whose `line` matches `id`
+*/
+function filterLineDeterminations(determinations, id) {
+	return determinations.filter((entry) => entry.line === id);
+}
+/**
+* Keep only program-scoped (line-unscoped) determinations.
+*
+* @param determinations - The determinations to filter
+* @returns The determinations with no `line`
+*/
+function filterProgramDeterminations(determinations) {
+	return determinations.filter((entry) => entry.line === void 0);
+}
+/**
+* Derive the eligibility impact of a set of determinations.
+*
+* @param determinations - The determinations to fold
+* @returns The most severe eligibility any APPLIED determination's effect carries
+*
+* @example
+* ```ts
+* import { deriveDeterminationEligibility } from '@orkestrel/rater'
+*
+* deriveDeterminationEligibility([{ id: 'r1', effect: 'restriction', applied: true, premises: [] }])
+* // 'ineligible'
+* ```
+*/
+function deriveDeterminationEligibility(determinations) {
+	const impacts = ["eligible"];
+	for (const entry of determinations) {
+		const eligibility = entry.applied ? EFFECT_ELIGIBILITIES[entry.effect] : void 0;
+		if (eligibility !== void 0) impacts.push(eligibility);
+	}
+	return combineEligibilities(impacts);
+}
+/**
+* Return the most severe {@link Eligibility} in a list.
+*
+* @param eligibilities - The eligibilities to combine
+* @returns The most severe eligibility, or `'eligible'` for an empty list
+*
+* @example
+* ```ts
+* import { combineEligibilities } from '@orkestrel/rater'
+*
+* combineEligibilities(['eligible', 'referral']) // 'referral'
+* ```
+*/
+function combineEligibilities(eligibilities) {
+	for (const eligibility of ELIGIBILITY_PRECEDENCE) if (eligibilities.includes(eligibility)) return eligibility;
+	return "eligible";
+}
+/**
+* Convert an {@link Eligibility} to its deterministic authority {@link Decision}.
+*
+* @param eligibility - The eligibility to convert
+* @returns The matching decision
+*/
+function decideEligibility(eligibility) {
+	return ELIGIBILITY_DECISIONS[eligibility];
+}
+/**
+* Derive the final {@link Status} from eligibility, determinations, and rated
+* line evidence.
+*
+* @param eligibility - The program's combined eligibility
+* @param determinations - Every determination in scope (program and line)
+* @param lines - The program's rated lines
+* @returns The derived status
+*/
+function deriveStatus(eligibility, determinations, lines) {
+	if (eligibility === "ineligible") return "ineligible";
+	if (eligibility === "referral") return "referral";
+	if (determinations.some((entry) => entry.applied && entry.effect === "condition")) return "conditional";
+	if (lines.some((entry) => !(entry.worksheet?.success ?? false) || entry.amount === void 0)) return "unrated";
+	return "eligible";
+}
+/**
+* Build a rated {@link LineResult} from a line's evaluated
+* {@link QuantitativeResult}.
+*
+* @param definition - The authored line definition
+* @param result - The evaluated quantitative result
+* @param determinations - The line-scoped determinations
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh line result
+*/
+function ratedLine(definition, result, determinations, labels) {
+	return {
+		id: definition.id,
+		name: definition.name,
+		eligibility: deriveDeterminationEligibility(determinations),
+		...result.success ? { amount: result.value } : {},
+		worksheet: resultsWorksheet(definition.rate, result, labels),
+		determinations
+	};
+}
+/**
+* Sum defined line amounts.
+*
+* @param lines - The rated lines
+* @returns The sum of every line's `amount`, or `undefined` when no line has one
+*/
+function sumAmounts(lines) {
+	let total = 0;
+	let count = 0;
+	for (const rated of lines) if (rated.amount !== void 0) {
+		total += rated.amount;
+		count += 1;
+	}
+	return count === 0 ? void 0 : total;
+}
+/**
+* Build an authority outcome projection from an assembled {@link ProgramResult}.
+*
+* @param result - The program result computed before authority runs
+* @returns A record shaped for the authority's `outcome` projection
+*/
+function outcomeProjection(result) {
+	const lines = {};
+	for (const rated of result.lines) if (rated.amount !== void 0) lines[rated.id] = rated.amount;
+	return {
+		eligibility: result.eligibility,
+		status: result.status,
+		total: result.total,
+		lines
+	};
+}
+/**
+* Assemble a final {@link ProgramResult} from its rated parts.
+*
+* @param definition - The authored program definition
+* @param lines - The program's rated lines
+* @param determinations - The program-scoped determinations
+* @param derivations - The pass-level quantitative worksheets
+* @param total - The program's total amount, when the total handler produced one
+* @param decision - The authority-derived decision, when one was reached
+* @param trace - The accumulated reasoning trace
+* @param errors - The accumulated reasoning errors
+* @returns A fresh program result
+*/
+function programResult(definition, lines, determinations, derivations, total, decision, trace, errors) {
+	const eligibility = combineEligibilities([deriveDeterminationEligibility(determinations), ...lines.map((entry) => entry.eligibility)]);
+	const allDeterminations = [...determinations, ...lines.flatMap((entry) => entry.determinations)];
+	return {
+		id: definition.id,
+		name: definition.name,
+		eligibility,
+		status: deriveStatus(eligibility, allDeterminations, lines),
+		...decision === void 0 ? {} : { decision },
+		lines,
+		determinations,
+		derivations,
+		...total === void 0 ? {} : { total },
+		success: errors.length === 0 && lines.every((entry) => entry.worksheet?.success ?? true),
+		trace,
+		errors
+	};
+}
+/**
+* Return authored line references (in passes, rulings, or notices) that name
+* no line on the program.
+*
+* @param definition - The program definition to check
+* @returns A fresh, deduped list of missing line ids
+*/
+function findMissingLineReferences(definition) {
+	const ids = new Set(definition.lines.map((entry) => entry.id));
+	const missing = /* @__PURE__ */ new Set();
+	for (const entry of definition.passes ?? []) if (entry.line !== void 0 && !ids.has(entry.line)) missing.add(entry.line);
+	for (const entry of Object.values(definition.rulings ?? {})) if (entry.line !== void 0 && !ids.has(entry.line)) missing.add(entry.line);
+	for (const entry of definition.notices ?? []) if (entry.line !== void 0 && !ids.has(entry.line)) missing.add(entry.line);
+	return [...missing];
+}
+/** Determine whether a working record already carries a reserved rater key. */
+function hasReservedKey(subject) {
+	return Object.hasOwn(subject, "aggregate") || Object.hasOwn(subject, "outcome");
+}
+/**
+* Locate a {@link ProgramDefinition}'s reserved-key collisions — a quantitative
+* pass whose id shadows {@link AGGREGATE_KEY} / {@link OUTCOME_KEY}, or a
+* logical pass's or the authority's fired rule conclusion whose asserted
+* field's FIRST path segment shadows one.
+*
+* @remarks
+* A quantitative pass writes its value onto the working subject under its own
+* definition id (`assignField`), silently clobbering the reserved aggregate or
+* outcome projection when the id collides. A fired rule's conclusion atoms
+* merge onto the working subject (`mergeSubjects`/`extractConclusions`) keyed
+* by `formatField(check.field)` — an atom whose field's first segment is a
+* reserved key is flagged here even when its FULL formatted key is a nested
+* form (`outcome.total`), since authoring a conclusion under a reserved
+* top-level segment is never intentional.
+*
+* @param definition - The program definition to scan
+* @returns A fresh, deduped list of offending pass or rule ids
+*
+* @example
+* ```ts
+* import { quantitativeDefinition } from '@orkestrel/reason'
+* import { findReservedCollisions, passDefinition, programDefinition } from '@orkestrel/rater'
+*
+* findReservedCollisions(
+* 	programDefinition('p1', 'P1', [], {
+* 		passes: [passDefinition(quantitativeDefinition('aggregate', 'Aggregate', []))],
+* 	}),
+* ) // ['aggregate']
+* ```
+*/
+function findReservedCollisions(definition) {
+	const offending = /* @__PURE__ */ new Set();
+	const logicals = [];
+	for (const pass of definition.passes ?? []) if (pass.definition.reasoning === "quantitative") {
+		if (pass.definition.id === "aggregate" || pass.definition.id === "outcome") offending.add(pass.definition.id);
+	} else if (pass.definition.reasoning === "logical") logicals.push(pass.definition);
+	if (definition.authority !== void 0) logicals.push(definition.authority);
+	for (const logical of logicals) for (const rule of logical.rules) for (const atom of extractAtoms(rule.conclusion)) {
+		const head = Array.isArray(atom.check.field) ? atom.check.field[0] : atom.check.field;
+		if (head === "aggregate" || head === "outcome") offending.add(rule.id);
+	}
+	return [...offending];
+}
+/**
+* Assert a value is a valid rater {@link Subject}, narrowing it in place.
+*
+* @param subject - The candidate subject to validate
+* @throws {@link RaterError} `'MISMATCH'` when the value is not a record, or
+* when it already carries a reserved rater working-subject key
+*/
+function assertSubject(subject) {
+	if (!isRecord(subject)) throw new RaterError("MISMATCH", "Subject must be a record");
+	if (hasReservedKey(subject)) throw new RaterError("MISMATCH", "Subject uses a reserved rater key");
+}
+/**
+* Sum aggregate fields across a batch of subjects.
+*
+* @param subjects - The batch of subjects
+* @param fields - The fields to sum
+* @returns A fresh record of dot-joined field to summed finite value
+*/
+function aggregateSums(subjects, fields) {
+	const sums = {};
+	for (const field of fields) sums[formatField(field)] = 0;
+	for (const subject of subjects) for (const field of fields) {
+		const key = formatField(field);
+		const value = resolveField(subject, field);
+		if (isFiniteNumber(value)) sums[key] = (sums[key] ?? 0) + value;
+	}
+	return sums;
+}
+/**
+* Partition a batch of subjects by a field, summing aggregate fields per
+* partition.
+*
+* @remarks
+* The partition key is the resolved `by` field, coerced with `String` —
+* `undefined` collapses to the empty string, so a subject missing the field
+* and a subject whose field is literally `''` land in the SAME partition,
+* and a numeric `1` collides with the string `'1'`.
+*
+* @param subjects - The batch of subjects
+* @param fields - The fields to sum within each partition
+* @param by - The partition key field; no partition is built when absent
+* @returns A fresh list of aggregate groups, or an empty list when `by` is absent
+*/
+function aggregateGroups(subjects, fields, by) {
+	if (by === void 0) return [];
+	const groups = /* @__PURE__ */ new Map();
+	for (const subject of subjects) {
+		const key = String(resolveField(subject, by) ?? "");
+		const entries = groups.get(key) ?? [];
+		entries.push(subject);
+		groups.set(key, entries);
+	}
+	return [...groups.entries()].map(([key, entries]) => ({
+		key,
+		count: entries.length,
+		sums: aggregateSums(entries, fields)
+	}));
+}
+/**
+* Collect the deduped, ordered union of every program's aggregate fields.
+*
+* @param programs - The compiled programs to scan
+* @returns A fresh list of aggregate field paths, in first-seen order
+*
+* @example
+* ```ts
+* import { aggregateFields } from '@orkestrel/rater'
+*
+* aggregateFields(programs) // [['income'], ['assets']]
+* ```
+*/
+function aggregateFields(programs) {
+	const fields = [];
+	const keys = /* @__PURE__ */ new Set();
+	for (const program of programs) for (const field of program.definition.aggregate?.fields ?? []) {
+		const key = formatField(field);
+		if (!keys.has(key)) {
+			keys.add(key);
+			fields.push(field);
+		}
+	}
+	return fields;
+}
+/**
+* Locate the {@link AggregateGroup} a subject belongs to.
+*
+* @remarks
+* The lookup key is the resolved `by` field, coerced with `String` —
+* `undefined` collapses to the empty string, matching {@link aggregateGroups}'
+* partition-key coercion (a missing key and an empty-string key collide, and
+* a numeric `1` collides with the string `'1'`).
+*
+* @param subject - The subject to key
+* @param groups - The candidate groups to search
+* @param by - The partition key field; no group is found when absent
+* @returns The subject's matching group, or `undefined`
+*
+* @example
+* ```ts
+* import { groupFor } from '@orkestrel/rater'
+*
+* groupFor({ region: 'east' }, [{ key: 'east', count: 1, sums: {} }], ['region'])
+* // { key: 'east', count: 1, sums: {} }
+* ```
+*/
+function groupFor(subject, groups, by) {
+	if (by === void 0) return void 0;
+	const key = String(resolveField(subject, by) ?? "");
+	return groups.find((entry) => entry.key === key);
+}
+/**
+* Build the batch aggregate working projection written under
+* {@link AGGREGATE_KEY}'s value.
+*
+* @param count - The batch (or partition) subject count
+* @param sums - The summed aggregate fields
+* @param group - The subject's own partition, when the aggregate is partitioned
+* @returns A fresh aggregate projection record
+*/
+function aggregateProjection(count, sums, group) {
+	return {
+		count,
+		sums,
+		...group === void 0 ? {} : { group }
+	};
+}
+/**
+* Build the reserved-key record an aggregate gate definition runs against.
+*
+* @param count - The batch (or partition) subject count
+* @param sums - The summed aggregate fields
+* @param group - The subject's own partition, when the aggregate is partitioned
+* @returns A fresh record carrying the aggregate projection under {@link AGGREGATE_KEY}
+*/
+function aggregateRecord(count, sums, group) {
+	return { [AGGREGATE_KEY]: aggregateProjection(count, sums, group) };
+}
+/**
+* Build zero sums for a set of fields.
+*
+* @param fields - The fields to zero
+* @returns A fresh record of dot-joined field to `0`
+*/
+function emptySums(fields) {
+	const sums = {};
+	for (const field of fields) sums[formatField(field)] = 0;
+	return sums;
+}
+/**
+* Complete a partial status tally record with zero entries for every missing
+* {@link Status}.
+*
+* @param entries - The partial tally entries to complete
+* @returns A record with all five statuses present
+*/
+function completeTallies(entries) {
+	return {
+		ineligible: entries.ineligible ?? {
+			count: 0,
+			sums: {}
+		},
+		referral: entries.referral ?? {
+			count: 0,
+			sums: {}
+		},
+		conditional: entries.conditional ?? {
+			count: 0,
+			sums: {}
+		},
+		unrated: entries.unrated ?? {
+			count: 0,
+			sums: {}
+		},
+		eligible: entries.eligible ?? {
+			count: 0,
+			sums: {}
+		}
+	};
+}
+/**
+* Build empty status tallies in precedence order.
+*
+* @param fields - The fields each tally's sums are zeroed for
+* @returns A fresh, complete tally record
+*/
+function emptyTallies(fields) {
+	const entries = {};
+	for (const status of STATUS_PRECEDENCE) entries[status] = {
+		count: 0,
+		sums: emptySums(fields)
+	};
+	return completeTallies(entries);
+}
+/**
+* Add one subject's aggregate contribution to a status tally record.
+*
+* @param tallies - The tallies to update
+* @param status - The subject's derived status
+* @param subject - The subject to fold in
+* @param fields - The fields to sum
+* @returns A fresh, complete tally record with the subject folded in
+*/
+function tallySubject(tallies, status, subject, fields) {
+	const updated = { ...tallies };
+	const current = tallies[status];
+	const sums = { ...current.sums };
+	for (const field of fields) {
+		const key = formatField(field);
+		const value = resolveField(subject, field);
+		if (isFiniteNumber(value)) sums[key] = (sums[key] ?? 0) + value;
+	}
+	updated[status] = {
+		count: current.count + 1,
+		sums
+	};
+	return completeTallies(updated);
+}
+//#endregion
+//#region src/core/programs/Program.ts
+/**
+* A compiled program — rates one subject at a time over an injected, shared
+* reasoning engine.
+*
+* @remarks
+* The engine is INJECTED and never owned, destroyed, or otherwise mutated by
+* the program: every actual evaluation (passes, lines, authority) delegates to
+* it. `rate` builds its working subject through copy-on-write overlays only —
+* the caller's `subject` is never mutated.
+*/
+var Program = class {
+	#definition;
+	#engine;
+	#evaluator;
+	#total;
+	#labels;
+	constructor(definition, reason, options) {
+		const missing = findMissingLineReferences(definition);
+		if (missing.length > 0) throw new RaterError("MISSING", `Unknown line reference: ${missing.join(", ")}`, { program: definition.id });
+		const collisions = findReservedCollisions(definition);
+		if (collisions.length > 0) throw new RaterError("DEFINITION", `Reserved key collision: ${collisions.join(", ")}`, {
+			program: definition.id,
+			keys: collisions
+		});
+		this.#definition = definition;
+		this.#engine = reason;
+		this.#evaluator = createEvaluator();
+		this.#total = options?.total;
+		this.#labels = options?.labels;
+	}
+	get id() {
+		return this.#definition.id;
+	}
+	get name() {
+		return this.#definition.name;
+	}
+	get definition() {
+		return this.#definition;
+	}
+	rate(subject, aggregate) {
+		assertSubject(subject);
+		let working = aggregate === void 0 ? subject : assignField(subject, AGGREGATE_KEY, aggregate);
+		const determinations = [];
+		const derivations = [];
+		const trace = [];
+		const errors = [];
+		for (const pass of this.#definition.passes ?? []) if (pass.definition.reasoning === "quantitative") {
+			const result = this.#engine.reason(working, pass.definition);
+			trace.push(...result.trace);
+			errors.push(...result.errors);
+			if (result.reasoning === "quantitative") {
+				working = assignField(working, pass.definition.id, result.value);
+				derivations.push(resultsWorksheet(pass.definition, result, this.#labels));
+			}
+		} else {
+			const result = this.#engine.reason(working, pass.definition);
+			trace.push(...result.trace);
+			errors.push(...result.errors);
+			if (result.reasoning === "logical") {
+				determinations.push(...rulesToDeterminations(pass.definition, result, this.#definition.rulings, working, pass.line, this.#evaluator, this.#labels));
+				for (const entry of result.rules) {
+					if (!entry.applied) continue;
+					const rule = findRule(pass.definition, entry.id);
+					if (rule !== void 0) working = mergeSubjects(working, extractConclusions(rule.conclusion));
+				}
+			}
+		}
+		determinations.push(...noticesToDeterminations(this.#definition.notices, working));
+		const scoped = filterProgramDeterminations(determinations);
+		const lines = this.#rateLines(working, scoped, determinations);
+		const total = this.#total?.(lines);
+		const base = programResult(this.#definition, lines, scoped, derivations, total, void 0, trace, errors);
+		if (this.#definition.authority === void 0) return base;
+		const authorityWorking = assignField(working, OUTCOME_KEY, outcomeProjection(base));
+		const authorityResult = this.#engine.reason(authorityWorking, this.#definition.authority);
+		if (authorityResult.reasoning !== "logical") return base;
+		const limits = authorityToDeterminations(this.#definition.authority, authorityResult, this.#definition.rulings, authorityWorking, this.#evaluator, this.#labels);
+		const decision = limits.length === 0 && authorityResult.errors.length === 0 ? decideEligibility(base.eligibility) : void 0;
+		return programResult(this.#definition, lines, [...scoped, ...limits], derivations, total, decision, [...trace, ...authorityResult.trace], [...errors, ...authorityResult.errors]);
+	}
+	#rateLines(working, context, determinations) {
+		const lines = [];
+		for (const entry of this.#definition.lines) {
+			const own = filterLineDeterminations(determinations, entry.id);
+			const line = ratedLine(entry, this.#quantitative(working, entry.rate), own, this.#labels);
+			lines.push({
+				...line,
+				eligibility: deriveDeterminationEligibility([...context, ...line.determinations])
+			});
+		}
+		return lines;
+	}
+	#quantitative(subject, definition) {
+		const result = this.#engine.reason(subject, definition);
+		if (result.reasoning === "quantitative") return result;
+		const failure = buildErrorResult(definition, `Expected quantitative result, got ${result.reasoning}`);
+		const errors = [...result.errors, ...failure.errors];
+		if (failure.reasoning === "quantitative") return {
+			...failure,
+			errors
+		};
+		return {
+			reasoning: "quantitative",
+			value: 0,
+			groups: [],
+			count: 0,
+			success: false,
+			trace: [],
+			errors
+		};
+	}
+};
+//#endregion
+//#region src/core/programs/ProgramManager.ts
+/**
+* An ordered manager over compiled {@link ProgramInterface}s (AGENTS §9), built
+* over an injected, shared reasoning engine.
+*
+* @remarks
+* OWNS its `#programs` collection and its own {@link Emitter} over
+* {@link ProgramManagerEventMap}. `destroy()` is idempotent and tears the
+* emitter down LAST; every other call afterwards throws
+* {@link RaterError} `'DESTROYED'`.
+*/
+var ProgramManager = class {
+	#programs = /* @__PURE__ */ new Map();
+	#engine;
+	#emitter;
+	#total;
+	#labels;
+	#validate;
+	#destroyed = false;
+	constructor(engine, options) {
+		this.#engine = engine;
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#total = options?.total;
+		this.#labels = options?.labels;
+		this.#validate = options?.validate ?? true;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get size() {
+		this.#ensureAlive();
+		return this.#programs.size;
+	}
+	has(id) {
+		this.#ensureAlive();
+		return this.#programs.has(id);
+	}
+	program(id) {
+		this.#ensureAlive();
+		return this.#programs.get(id);
+	}
+	programs() {
+		this.#ensureAlive();
+		return [...this.#programs.values()];
+	}
+	add(definition, options) {
+		this.#ensureAlive();
+		if (this.#programs.has(definition.id)) throw new RaterError("DUPLICATE", `Program already exists: ${definition.id}`, { program: definition.id });
+		const id = definition.id;
+		if (this.#validate && !isProgramDefinition(definition)) throw new RaterError("DEFINITION", "Program definition failed validation", { program: id });
+		const program = new Program(definition, this.#engine, {
+			total: options?.total ?? this.#total,
+			labels: options?.labels ?? this.#labels
+		});
+		this.#programs.set(program.id, program);
+		this.#emitter.emit("add", program.id);
+		return program;
+	}
+	remove(target) {
+		this.#ensureAlive();
+		if (target === void 0) {
+			for (const id of this.#programs.keys()) this.#emitter.emit("remove", id);
+			this.#programs.clear();
+			return;
+		}
+		if (typeof target === "string") return this.#removeOne(target);
+		let removed = true;
+		for (const id of target) removed = this.#removeOne(id) && removed;
+		return removed;
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#programs.clear();
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#removeOne(id) {
+		const removed = this.#programs.delete(id);
+		if (removed) this.#emitter.emit("remove", id);
+		return removed;
+	}
+	#ensureAlive() {
+		if (this.#destroyed) throw new RaterError("DESTROYED", "ProgramManager has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/Rater.ts
+/**
+* The rating orchestrator — owns the shared reasoning engine and an ordered
+* {@link ProgramManager}, and projects results into the rating domain
+* vocabulary.
+*
+* @remarks
+* Constructs ONE shared reason engine (quantitative + logical reasoners,
+* `bail: false`) and injects it into every compiled program — Rater performs
+* NO evaluation arithmetic of its own; it only orchestrates and projects. The
+* batch `rate` overload is declared FIRST (AGENTS §9.2) so an array subject
+* resolves to the batch form. `destroy()` tears down the manager, then the
+* engine, then the emitter LAST (AGENTS §13); afterwards every other method
+* throws {@link RaterError} `'DESTROYED'`.
+*/
+var Rater = class {
+	#emitter;
+	#manager;
+	#engine;
+	#evaluator;
+	#destroyed = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#engine = createReason({
+			reasoners: [createQuantitativeReasoner(), createLogicalReasoner()],
+			bail: false
+		});
+		this.#evaluator = createEvaluator();
+		this.#manager = new ProgramManager(this.#engine, {
+			total: options?.total,
+			labels: options?.labels,
+			validate: options?.validate
+		});
+		for (const definition of options?.programs ?? []) this.#manager.add(definition);
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get programs() {
+		return this.#manager;
+	}
+	rate(subject) {
+		this.#ensureAlive();
+		if (isRecord(subject)) return this.#rateOne(subject);
+		return this.#rateBatch(subject);
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#manager.destroy();
+		this.#engine.destroy();
+		this.#destroyed = true;
+		this.#emitter.destroy();
+	}
+	#rateOne(subject) {
+		assertSubject(subject);
+		const result = this.#subject(subject);
+		this.#emitSubject(result);
+		return result;
+	}
+	#rateBatch(subjects) {
+		for (const subject of subjects) assertSubject(subject);
+		const programs = this.#manager.programs();
+		const sums = aggregateSums(subjects, aggregateFields(programs));
+		const programSums = /* @__PURE__ */ new Map();
+		const programGroups = /* @__PURE__ */ new Map();
+		for (const program of programs) {
+			const aggregate = program.definition.aggregate;
+			if (aggregate === void 0) continue;
+			programSums.set(program.id, aggregateSums(subjects, aggregate.fields));
+			programGroups.set(program.id, aggregateGroups(subjects, aggregate.fields, aggregate.by));
+		}
+		const groups = this.#groups(programs, programGroups);
+		const determinations = this.#aggregateDeterminations(programs, programSums, programGroups, subjects.length);
+		const subjectsResult = subjects.map((subject) => this.#subject(subject, this.#projections(subject, programs, programSums, programGroups, subjects.length)));
+		const result = {
+			subjects: subjectsResult,
+			determinations,
+			groups,
+			tallies: this.#tallies(subjects, subjectsResult, programs),
+			count: subjects.length,
+			sums
+		};
+		for (const rated of subjectsResult) this.#emitSubject(rated);
+		for (const determination of determinations) if (determination.applied) this.#emitter.emit("determine", determination);
+		this.#emitter.emit("aggregate", result);
+		return result;
+	}
+	#subject(subject, projections) {
+		return {
+			subject,
+			programs: this.#manager.programs().map((program) => {
+				const projection = projections?.[program.id];
+				return projection === void 0 ? program.rate(subject) : program.rate(subject, projection);
+			})
+		};
+	}
+	#emitSubject(result) {
+		for (const program of result.programs) {
+			const determinations = [...program.determinations, ...program.lines.flatMap((rated) => rated.determinations)];
+			for (const determination of determinations) if (determination.applied) this.#emitter.emit("determine", determination);
+			if (program.decision !== void 0) this.#emitter.emit("decide", program.decision, program);
+		}
+		this.#emitter.emit("rate", result);
+	}
+	#groups(programs, programGroups) {
+		const output = [];
+		for (const program of programs) if (program.definition.aggregate?.by !== void 0) output.push(...programGroups.get(program.id) ?? []);
+		return output;
+	}
+	#projections(subject, programs, programSums, programGroups, count) {
+		const output = {};
+		for (const program of programs) {
+			const aggregate = program.definition.aggregate;
+			if (aggregate === void 0) continue;
+			const sums = programSums.get(program.id);
+			if (sums === void 0) continue;
+			const group = groupFor(subject, programGroups.get(program.id) ?? [], aggregate.by);
+			output[program.id] = aggregateProjection(count, sums, group);
+		}
+		return output;
+	}
+	#aggregateDeterminations(programs, programSums, programGroups, count) {
+		const determinations = [];
+		for (const program of programs) {
+			const aggregate = program.definition.aggregate;
+			if (aggregate?.gates === void 0) continue;
+			const sums = programSums.get(program.id);
+			if (sums === void 0) continue;
+			determinations.push(...this.#gate(aggregate.gates, aggregateRecord(count, sums), program.definition.rulings));
+			for (const group of programGroups.get(program.id) ?? []) determinations.push(...this.#gate(aggregate.gates, aggregateRecord(group.count, group.sums, group), program.definition.rulings));
+		}
+		return determinations;
+	}
+	#gate(definition, record, rulings) {
+		return rulesToDeterminations(definition, this.#reasonLogical(record, definition), rulings, record, void 0, this.#evaluator);
+	}
+	#tallies(subjects, results, programs) {
+		const output = {};
+		for (const program of programs) {
+			let tallies = emptyTallies(program.definition.aggregate?.fields ?? []);
+			for (let index = 0; index < results.length; index += 1) {
+				const subject = subjects[index];
+				const rated = results[index]?.programs.find((entry) => entry.id === program.id);
+				if (subject !== void 0 && rated !== void 0) tallies = tallySubject(tallies, rated.status, subject, program.definition.aggregate?.fields ?? []);
+			}
+			output[program.id] = tallies;
+		}
+		return output;
+	}
+	#reasonLogical(subject, definition) {
+		const result = this.#engine.reason(subject, definition);
+		if (result.reasoning === "logical") return result;
+		const failure = buildErrorResult(definition, `Expected logical result, got ${result.reasoning}`);
+		const errors = [...result.errors, ...failure.errors];
+		if (failure.reasoning === "logical") return {
+			...failure,
+			errors
+		};
+		return {
+			reasoning: "logical",
+			conclusion: false,
+			rules: [],
+			count: 0,
+			success: false,
+			trace: [],
+			errors
+		};
+	}
+	#ensureAlive() {
+		if (this.#destroyed) throw new RaterError("DESTROYED", "Rater has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create a rating orchestrator.
+*
+* @param options - Optional total handler, seed programs, labels, validation policy, and emitter hooks
+* @returns A {@link RaterInterface}
+*
+* @example
+* ```ts
+* import { createRater } from '@orkestrel/rater'
+*
+* const rater = createRater()
+* rater.destroy()
+* ```
+*/
+function createRater(options) {
+	return new Rater(options);
+}
+/**
+* Create and validate one compiled program over a shared reasoning engine.
+*
+* @param definition - The authored program definition
+* @param reason - The shared reasoning engine, injected (never owned or destroyed by the program)
+* @param options - Optional total handler and labels
+* @returns A {@link ProgramInterface}
+* @throws {@link RaterError} `'DEFINITION'` when the definition fails {@link isProgramDefinition}
+*
+* @example
+* ```ts
+* import { createLogicalReasoner, createQuantitativeReasoner, createReason } from '@orkestrel/reason'
+* import { createProgram, programDefinition } from '@orkestrel/rater'
+*
+* const reason = createReason({ reasoners: [createQuantitativeReasoner(), createLogicalReasoner()], bail: false })
+* const program = createProgram(programDefinition('p1', 'Program', []), reason)
+* ```
+*/
+function createProgram(definition, reason, options) {
+	const id = isRecord(definition) ? definition.id : void 0;
+	if (!isProgramDefinition(definition)) throw new RaterError("DEFINITION", "Program definition failed validation", { program: id });
+	return new Program(definition, reason, options);
+}
+/**
+* Create an ordered manager over compiled programs (AGENTS §9), built over an
+* injected, shared reasoning engine.
+*
+* @param reason - The shared reasoning engine, injected into every compiled program
+* @param options - Optional total handler, labels, validation policy, and emitter hooks
+* @returns A {@link ProgramManagerInterface}
+*
+* @example
+* ```ts
+* import { createLogicalReasoner, createQuantitativeReasoner, createReason } from '@orkestrel/reason'
+* import { createProgramManager, programDefinition } from '@orkestrel/rater'
+*
+* const reason = createReason({ reasoners: [createQuantitativeReasoner(), createLogicalReasoner()], bail: false })
+* const manager = createProgramManager(reason)
+* manager.add(programDefinition('p1', 'Program', []))
+* manager.destroy()
+* ```
+*/
+function createProgramManager(reason, options) {
+	return new ProgramManager(reason, options);
+}
+/**
+* Build a {@link ProgramDefinition}.
+*
+* @param id - The program id
+* @param name - The display name
+* @param lines - The program's rateable lines
+* @param overrides - Optional {@link ProgramDefinition} fields merged over the defaults
+* @returns A fresh program definition
+*
+* @example
+* ```ts
+* import { programDefinition } from '@orkestrel/rater'
+*
+* programDefinition('p1', 'Program', [])
+* ```
+*/
+function programDefinition(id, name, lines, overrides) {
+	return {
+		id,
+		name,
+		lines,
+		...overrides
+	};
+}
+/**
+* Build a {@link LineDefinition}.
+*
+* @param id - The line id
+* @param name - The display name
+* @param rate - The line's quantitative rating definition
+* @param overrides - Optional {@link LineDefinition} fields merged over the defaults
+* @returns A fresh line definition
+*
+* @example
+* ```ts
+* import { quantitativeDefinition } from '@orkestrel/reason'
+* import { lineDefinition } from '@orkestrel/rater'
+*
+* lineDefinition('base', 'Base Amount', quantitativeDefinition('base', 'Base', []))
+* ```
+*/
+function lineDefinition(id, name, rate, overrides) {
+	return {
+		id,
+		name,
+		rate,
+		...overrides
+	};
+}
+/**
+* Build a {@link PassDefinition}.
+*
+* @param definition - The pass's logical or quantitative definition
+* @param line - The line id this pass is scoped to, when it is line-scoped
+* @returns A fresh pass definition
+*
+* @example
+* ```ts
+* import { quantitativeDefinition } from '@orkestrel/reason'
+* import { passDefinition } from '@orkestrel/rater'
+*
+* passDefinition(quantitativeDefinition('surcharge', 'Surcharge', []))
+* ```
+*/
+function passDefinition(definition, line) {
+	return {
+		definition,
+		...line === void 0 ? {} : { line }
+	};
+}
+/**
+* Build a {@link Ruling}.
+*
+* @param effect - The determination effect a fired rule routes to
+* @param line - The line id this ruling is scoped to, when it is line-scoped
+* @param message - An interpolated message template, when the ruling carries one
+* @returns A fresh ruling
+*
+* @example
+* ```ts
+* import { rulingDefinition } from '@orkestrel/rater'
+*
+* rulingDefinition('restriction', 'base', 'Amount exceeds {{limit}}')
+* ```
+*/
+function rulingDefinition(effect, line, message) {
+	return {
+		effect,
+		...line === void 0 ? {} : { line },
+		...message === void 0 ? {} : { message }
+	};
+}
+/**
+* Build a {@link Notice}.
+*
+* @param id - The notice id
+* @param message - An interpolated message template
+* @param line - The line id this notice is scoped to, when it is line-scoped
+* @returns A fresh notice
+*
+* @example
+* ```ts
+* import { noticeDefinition } from '@orkestrel/rater'
+*
+* noticeDefinition('n1', 'Rated on {{date}}')
+* ```
+*/
+function noticeDefinition(id, message, line) {
+	return {
+		id,
+		message,
+		...line === void 0 ? {} : { line }
+	};
+}
+/**
+* Build an {@link AggregateDefinition}.
+*
+* @param fields - The batch fields to sum
+* @param by - The partition key field, when the aggregate is partitioned
+* @param gates - The logical definition gating aggregate determinations, when present
+* @returns A fresh aggregate definition
+*
+* @example
+* ```ts
+* import { aggregateDefinition } from '@orkestrel/rater'
+*
+* aggregateDefinition(['amount'])
+* ```
+*/
+function aggregateDefinition(fields, by, gates) {
+	return {
+		fields,
+		...by === void 0 ? {} : { by },
+		...gates === void 0 ? {} : { gates }
+	};
+}
+//#endregion
+export { AGGREGATE_KEY, DEFAULT_RATER_VALIDATE, EFFECT_ELIGIBILITIES, ELIGIBILITY_DECISIONS, ELIGIBILITY_PRECEDENCE, OUTCOME_KEY, Program, ProgramManager, Rater, RaterError, STATUS_PRECEDENCE, aggregateDefinition, aggregateFields, aggregateGroups, aggregateProjection, aggregateRecord, aggregateSums, assertSubject, authorityToDeterminations, checkPremises, combineEligibilities, completeTallies, createProgram, createProgramManager, createRater, decideEligibility, deriveDeterminationEligibility, deriveStatus, describeComparison, describeExpression, describePremise, describeValue, emptySums, emptyTallies, filterLineDeterminations, filterProgramDeterminations, findMissingLineReferences, findReservedCollisions, findRule, groupFor, hasReservedKey, interpolateMessage, isAggregateDefinition, isDecision, isEffect, isEligibility, isLineDefinition, isNotice, isPassDefinition, isProgramDefinition, isRaterError, isRuling, isRulings, isStage, isStatus, lineDefinition, logicalPremises, noticeDefinition, noticesToDeterminations, outcomeProjection, passDefinition, premiseCheck, programDefinition, programResult, ratedLine, resultsWorksheet, rulesToDeterminations, rulingDefinition, sumAmounts, tallySubject, worksheetFactor, worksheetGroup, worksheetStep, worksheetSteps };
+
+//# sourceMappingURL=index.js.map