@orkestrel/program 0.0.11 → 0.0.13

package/dist/src/core/index.js

@@ -1,64 +1,106 @@
 import { arrayOf, isArray, isBoolean, isFiniteNumber, isJSONValue, isNumber, isRecord, isString, literalOf, objectOf, recordOf, resolveField, whereOf } from "@orkestrel/contract";
-import { createQualifier, findRule, interpolateMessage, isEligibility, isPremise, isQualificationDefinition, isQualificationResult, isQualificationValidationResult, logicalPremises } from "@orkestrel/qualifier";
+import { createQualifier, findRule, interpolateMessage, isEligibility, isPremise, isQualificationDefinition, isQualificationResult, ruleToPremises } from "@orkestrel/qualifier";
 import { createRater, isRatingDefinition, isRatingResult } from "@orkestrel/rater";
 import { createEvaluator, createLogicalReasoner, createQuantitativeReasoner, createReason, findDuplicates, formatField, isFieldPath, isLogicalDefinition, isLogicalResult, isReasonValidationResult } from "@orkestrel/reason";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
-/** Default definition validation policy for `createProgram` / `ProgramManager.add`. */
+/**
+* Names the default definition validation policy, `true`, for `createProgram` /
+* `ProgramManager.add`.
+*/
 var DEFAULT_PROGRAM_VALIDATE = true;
-/** Status tally precedence order — least to most resolved. */
-var STATUS_PRECEDENCE = Object.freeze([
+/**
+* Lists every {@link Status} literal in tally order — the source the union and its
+* guard derive from.
+*/
+var STATUSES = Object.freeze([
 	"ineligible",
 	"referral",
 	"conditional",
 	"unrated",
 	"eligible"
 ]);
-/** The deterministic authority decision for each global eligibility. */
+/** Maps each global eligibility to its deterministic authority decision. */
 var ELIGIBILITY_DECISIONS = Object.freeze({
 	eligible: "approved",
 	ineligible: "denied",
 	referral: "submitted"
 });
-/** The reserved working-subject key a batch's aggregate projection is written under. */
+/**
+* Names the reserved working-subject key a batch's aggregate projection is written
+* under, `'aggregate'`.
+*/
 var AGGREGATE_KEY = "aggregate";
-/** The reserved working-subject key the authority's outcome projection is written under. */
+/**
+* Names the reserved working-subject key the authority's outcome projection is
+* written under, `'outcome'`.
+*/
 var OUTCOME_KEY = "outcome";
 //#endregion
 //#region src/core/errors.ts
 /**
-* A coded programmer error thrown by the program layer.
+* Reports a coded programmer error thrown by the program layer, carrying a
+* machine-readable code and an optional context and cause.
 *
 * @remarks
 * `DUPLICATE` — a program id collision on `ProgramManager.add`, or a duplicate
-* authored rating-line or notice id. `MISSING` — an
-* authored notice or qualification ruling scope names no rating line.
+* authored rating-line or notice id. `MISSING` — an authored notice or
+* qualification ruling scope names no rating line.
 * `DEFINITION` — a program, qualification, rating, authority, or aggregate
 * policy failed validation. `MISMATCH` — an injected entity or a returned
 * reason result has the wrong contract. `RESERVED` — a subject already
 * carries `aggregate` or `outcome`. `DESTROYED` — use of a destroyed entity.
+*
+* @example
+* ```ts
+* import { ProgramError } from '@orkestrel/program'
+*
+* const error = new ProgramError('RESERVED', 'Subject carries a reserved key', 'aggregate')
+* error.code // 'RESERVED'
+* ```
 */
 var ProgramError = class extends Error {
 	code;
 	context;
-	constructor(code, message, context) {
-		super(message);
+	/**
+	* Creates a coded program error.
+	*
+	* @param code - The machine-readable failure category
+	* @param message - The human-readable failure description
+	* @param context - Optional structured context for the failure
+	* @param cause - Optional underlying value the failure wraps
+	*/
+	constructor(code, message, context, cause) {
+		super(message, cause === void 0 ? void 0 : { cause });
 		this.name = "ProgramError";
 		this.code = code;
 		this.context = context;
 	}
 };
-/** Narrow a caught value to a {@link ProgramError}. */
+/**
+* Determines whether a caught value is a {@link ProgramError}.
+*
+* @param value - The candidate value
+* @returns True if the value is a {@link ProgramError}; false otherwise
+*
+* @example
+* ```ts
+* import { isProgramError, ProgramError } from '@orkestrel/program'
+*
+* isProgramError(new ProgramError('RESERVED', 'Subject carries a reserved key')) // true
+* isProgramError(new Error('Subject carries a reserved key')) // false
+* ```
+*/
 function isProgramError(value) {
 	return value instanceof ProgramError;
 }
 //#endregion
 //#region src/core/validators.ts
 /**
-* Determine whether a value is a {@link Decision} literal.
+* Determines whether a value is a {@link Decision} literal.
 *
 * @param value - The candidate value
-* @returns `true` when `value` is a {@link Decision}
+* @returns True if `value` is a {@link Decision}; false otherwise
 *
 * @example
 * ```ts
@@ -69,10 +111,10 @@ function isProgramError(value) {
 */
 var isDecision = literalOf("approved", "denied", "submitted");
 /**
-* Determine whether a value is a {@link Status} literal.
+* Determines whether a value is a {@link Status} literal.
 *
 * @param value - The candidate value
-* @returns `true` when `value` is a {@link Status}
+* @returns True if `value` is a {@link Status}; false otherwise
 *
 * @example
 * ```ts
@@ -81,12 +123,12 @@ var isDecision = literalOf("approved", "denied", "submitted");
 * isStatus('eligible') // true
 * ```
 */
-var isStatus = literalOf("ineligible", "referral", "conditional", "unrated", "eligible");
+var isStatus = literalOf(STATUSES);
 /**
-* Determine whether a value is a {@link ProgramEffect} literal.
+* Determines whether a value is a {@link ProgramEffect} literal.
 *
 * @param value - The candidate value
-* @returns `true` when `value` is a {@link ProgramEffect}
+* @returns True if `value` is a {@link ProgramEffect}; false otherwise
 *
 * @example
 * ```ts
@@ -97,10 +139,10 @@ var isStatus = literalOf("ineligible", "referral", "conditional", "unrated", "el
 */
 var isProgramEffect = literalOf("notice", "limit");
 /**
-* Determine whether a value is an exact {@link Notice} record.
+* Determines whether a value is an exact {@link Notice} record.
 *
 * @param value - The candidate value
-* @returns `true` when `value` is a {@link Notice}
+* @returns True if `value` is a {@link Notice}; false otherwise
 *
 * @example
 * ```ts
@@ -117,10 +159,10 @@ function isNotice(value) {
 	}, ["scope"])(value);
 }
 /**
-* Determine whether a value is an exact {@link AggregateDefinition} record.
+* Determines whether a value is an exact {@link AggregateDefinition} record.
 *
 * @param value - The candidate value
-* @returns `true` when `value` is an {@link AggregateDefinition}
+* @returns True if `value` is an {@link AggregateDefinition}; false otherwise
 *
 * @example
 * ```ts
@@ -132,19 +174,19 @@ function isNotice(value) {
 function isAggregateDefinition(value) {
 	return recordOf({
 		fields: arrayOf(isFieldPath),
-		by: isFieldPath,
+		partition: isFieldPath,
 		gates: isLogicalDefinition
-	}, ["by", "gates"])(value);
+	}, ["partition", "gates"])(value);
 }
 /**
-* Determine whether a value is an exact {@link ProgramDefinition} record.
+* Determines whether a value is an exact {@link ProgramDefinition} record.
 *
 * @remarks
 * `rating` is optional — an omitted `rating` authors an eligibility-only
 * program (see {@link ProgramDefinition}).
 *
 * @param value - The candidate value
-* @returns `true` when `value` is a {@link ProgramDefinition}
+* @returns True if `value` is a {@link ProgramDefinition}; false otherwise
 *
 * @example
 * ```ts
@@ -174,7 +216,7 @@ function isProgramDefinition(value) {
 	])(value);
 }
 /**
-* Determine whether a value is an open program sums record.
+* Determines whether a value is an open program sums record.
 *
 * @remarks
 * Every own string-named property is checked, including non-enumerable
@@ -183,7 +225,7 @@ function isProgramDefinition(value) {
 * infinities, because the published contract does not refine them.
 *
 * @param value - The candidate value
-* @returns `true` when every own string-named value is a number
+* @returns True if every own string-named value is a number; false otherwise
 *
 * @example
 * ```ts
@@ -196,14 +238,14 @@ function isProgramSums(value) {
 	return whereOf(objectOf({}), (record) => Object.getOwnPropertyNames(record).every((key) => isNumber(Reflect.get(record, key))))(value);
 }
 /**
-* Determine whether a value is an open result-side {@link Determination}.
+* Determines whether a value is an open result-side {@link Determination}.
 *
 * @remarks
 * Unknown members and class instances are admitted. Arrays are refused.
 * Optional `scope` and `message` members may be absent or `undefined`.
 *
 * @param value - The candidate value
-* @returns `true` when every published determination member conforms
+* @returns True if every published determination member conforms; false otherwise
 *
 * @example
 * ```ts
@@ -221,13 +263,13 @@ var isDetermination = objectOf({
 	premises: arrayOf(isPremise)
 }, ["scope", "message"]);
 /**
-* Determine whether a value is an open result-side {@link AggregateGroup}.
+* Determines whether a value is an open result-side {@link AggregateGroup}.
 *
 * @remarks
 * Unknown members and class instances are admitted. Arrays are refused.
 *
 * @param value - The candidate value
-* @returns `true` when every published aggregate-group member conforms
+* @returns True if every published aggregate-group member conforms; false otherwise
 *
 * @example
 * ```ts
@@ -242,13 +284,13 @@ var isAggregateGroup = objectOf({
 	sums: isProgramSums
 });
 /**
-* Determine whether a value is an open result-side {@link Tally}.
+* Determines whether a value is an open result-side {@link Tally}.
 *
 * @remarks
 * Unknown members and class instances are admitted. Arrays are refused.
 *
 * @param value - The candidate value
-* @returns `true` when every published tally member conforms
+* @returns True if every published tally member conforms; false otherwise
 *
 * @example
 * ```ts
@@ -262,27 +304,27 @@ var isTally = objectOf({
 	sums: isProgramSums
 });
 /**
-* Determine whether a value is a total open status-tally record.
+* Determines whether a value is a total open status-tally record.
 *
 * @remarks
-* Every {@link Status} in {@link STATUS_PRECEDENCE} is required and checked.
+* Every {@link Status} in {@link STATUSES} is required and checked.
 * Unknown members and class instances are admitted. Arrays are refused.
 *
 * @param value - The candidate value
-* @returns `true` when every required status member is a {@link Tally}
+* @returns True if every required status member is a {@link Tally}; false otherwise
 *
 * @example
 * ```ts
-* import { emptyTallies, isTallies } from '@orkestrel/program'
+* import { buildEmptyTallies, isTallies } from '@orkestrel/program'
 *
-* isTallies(emptyTallies([])) // true
+* isTallies(buildEmptyTallies([])) // true
 * ```
 */
 function isTallies(value) {
-	return whereOf(objectOf({}), (record) => STATUS_PRECEDENCE.every((status) => isTally(Reflect.get(record, status))))(value);
+	return whereOf(objectOf({}), (record) => STATUSES.every((status) => isTally(Reflect.get(record, status))))(value);
 }
 /**
-* Determine whether a value is an open {@link ProgramResult}.
+* Determines whether a value is an open {@link ProgramResult}.
 *
 * @remarks
 * This guard is result-postured for values returned through a borrowed
@@ -291,7 +333,7 @@ function isTallies(value) {
 * over their complete nested result closures. Arrays are refused.
 *
 * @param value - The candidate value
-* @returns `true` when every published program-result member conforms
+* @returns True if every published program-result member conforms; false otherwise
 *
 * @example
 * ```ts
@@ -314,7 +356,7 @@ var isProgramResult = objectOf({
 	errors: arrayOf(isString)
 }, ["decision", "rating"]);
 /**
-* Determine whether a value is an open {@link AggregateResult}.
+* Determines whether a value is an open {@link AggregateResult}.
 *
 * @remarks
 * This guard is result-postured for values returned through a borrowed
@@ -323,7 +365,7 @@ var isProgramResult = objectOf({
 * record, and sums record. Arrays are refused.
 *
 * @param value - The candidate value
-* @returns `true` when every published aggregate-result member conforms
+* @returns True if every published aggregate-result member conforms; false otherwise
 *
 * @example
 * ```ts
@@ -346,16 +388,16 @@ var isAggregateResult = objectOf({
 	errors: arrayOf(isString)
 });
 /**
-* Determine whether a value is an open {@link ProgramValidationResult}.
+* Determines whether a value is an open {@link ProgramValidationResult}.
 *
 * @remarks
 * `ProgramValidationResult` is this package's own declared interface, not an
-* alias of reason's validation result. This guard therefore checks the three
+* alias of reason's validation result. This guard therefore checks the
 * program-owned members directly so the contracts may evolve independently.
 * Unknown members and class instances are admitted. Arrays are refused.
 *
 * @param value - The candidate value
-* @returns `true` when every published program-validation member conforms
+* @returns True if every published program-validation member conforms; false otherwise
 *
 * @example
 * ```ts
@@ -372,38 +414,7 @@ var isProgramValidationResult = objectOf({
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Return a fresh JSON value tree that does not alias the input.
-*
-* @remarks
-* The input must be an acyclic JSON tree of bounded depth — a pathologically
-* deep tree throws the engine's `RangeError` (stack exhaustion) rather than
-* hanging. Each copied record uses `Object.defineProperty` for own-property
-* definition, which defends against prototype-pollution keys (`__proto__`).
-*
-* @param value - The JSON value to copy
-* @returns A fresh JSON value
-*
-* @example
-* ```ts
-* import { copyJSONValue } from '@orkestrel/program'
-*
-* copyJSONValue({ a: [1, 2] }) // { a: [1, 2] }, a fresh copy
-* ```
-*/
-function copyJSONValue(value) {
-	if (value === null || typeof value !== "object") return value;
-	if (Array.isArray(value)) return value.map(copyJSONValue);
-	const copy = {};
-	for (const [key, entry] of Object.entries(value)) Object.defineProperty(copy, key, {
-		value: copyJSONValue(entry),
-		enumerable: true,
-		writable: true,
-		configurable: true
-	});
-	return copy;
-}
-/**
-* Determine whether a caller subject already carries a reserved program key.
+* Determines whether a caller subject already carries a reserved program key.
 *
 * @remarks
 * `aggregate` and `outcome` are program-private working-subject namespaces — the
@@ -412,7 +423,7 @@ function copyJSONValue(value) {
 * collide with a projection, so it is rejected before qualification.
 *
 * @param subject - The caller subject to check
-* @returns `true` when the subject owns `aggregate` or `outcome`
+* @returns True if the subject owns `aggregate` or `outcome`; false otherwise
 *
 * @example
 * ```ts
@@ -426,11 +437,12 @@ function hasReservedKey(subject) {
 	return Object.hasOwn(subject, "aggregate") || Object.hasOwn(subject, "outcome");
 }
 /**
-* Assert a value is a valid program {@link Subject}, narrowing it in place.
+* Asserts a value is a valid program {@link Subject}, narrowing it in place.
 *
 * @param subject - The candidate subject to validate
-* @throws {@link ProgramError} `'MISMATCH'` when the value is not a record, or
-* `'RESERVED'` when it already carries the `aggregate` or `outcome` key
+* @throws {@link ProgramError} Thrown when the value is not a record (`'MISMATCH'`).
+* @throws {@link ProgramError} Thrown when the value already carries the `aggregate`
+* or `outcome` key (`'RESERVED'`).
 *
 * @example
 * ```ts
@@ -447,13 +459,13 @@ function assertProgramSubject(subject) {
 	}
 }
 /**
-* Select the rating lines a subject may be rated on from scoped eligibility.
+* Selects the rating lines a subject may be rated on from scoped eligibility.
 *
 * @remarks
 * A scope names a rating-line id. A line survives when its scope is absent
 * (eligible by default), `eligible`, or a `condition` (which is not an
 * eligibility value and never appears here). A scoped `ineligible` or `referral`
-* removes the line BEFORE the rater is invoked — the excluded line is never
+* removes the line before the rater is invoked — the excluded line is never
 * evaluated merely to discard its amount.
 *
 * @param lines - The program's authored rating lines
@@ -474,16 +486,16 @@ function selectProgramLines(lines, scopes) {
 	});
 }
 /**
-* Derive the final program {@link Status} from a definition's rating policy and
+* Derives the final program {@link Status} from a definition's rating policy and
 * qualification/rating evidence.
 *
 * @remarks
-* Explicit policy, not an opaque precedence reduce (AGENTS §10): global
+* Explicit policy, not an opaque precedence reduce: global
 * ineligibility or referral is terminal; a scoped referral yields `referral`;
 * an applied `condition` or an applied scoped `restriction` (a line was
-* removed but others rated) is `conditional`. When the definition OMITS
+* removed but others rated) is `conditional`. When the definition omits
 * `rating` the program is eligibility-only — status resolves to `conditional`
-* or `eligible` and is NEVER `unrated`. Otherwise a subject with no successful
+* or `eligible` and is never `unrated`. Otherwise a subject with no successful
 * rating is `unrated`.
 *
 * @param definition - The authored program definition
@@ -508,7 +520,7 @@ function deriveStatus(definition, qualification, rating) {
 	return conditional ? "conditional" : "eligible";
 }
 /**
-* Map a global {@link Eligibility} to its deterministic authority {@link Decision}.
+* Maps a global {@link Eligibility} to its deterministic authority {@link Decision}.
 *
 * @param eligibility - The global eligibility
 * @returns The matching decision
@@ -525,8 +537,8 @@ function decideEligibility(eligibility) {
 	return ELIGIBILITY_DECISIONS[eligibility];
 }
 /**
-* Resolve authored {@link Notice}s into unconditionally-applied `notice`
-* {@link Determination}s.
+* Resolves authored {@link Notice} values into unconditionally-applied `notice`
+* {@link Determination} values.
 *
 * @remarks
 * Notices are program output only — they never affect eligibility, status, line
@@ -539,12 +551,12 @@ function decideEligibility(eligibility) {
 *
 * @example
 * ```ts
-* import { buildNotices } from '@orkestrel/program'
+* import { buildNoticeDeterminations } from '@orkestrel/program'
 *
-* buildNotices([{ id: 'min', message: 'Minimum applies' }], { id: 'r1' })
+* buildNoticeDeterminations([{ id: 'min', message: 'Minimum applies' }], { id: 'r1' })
 * ```
 */
-function buildNotices(notices, subject) {
+function buildNoticeDeterminations(notices, subject) {
 	return notices.map((notice) => ({
 		id: notice.id,
 		effect: "notice",
@@ -555,14 +567,14 @@ function buildNotices(notices, subject) {
 	}));
 }
 /**
-* Convert a logical result's applied rules into `limit` {@link Determination}s.
+* Converts a logical result's applied rules into `limit` {@link Determination} values.
 *
 * @remarks
 * Fires for both the per-subject authority and the batch aggregate gates — both
-* are plain {@link LogicalDefinition}s with no program-authored ruling map, so a
+* are plain {@link LogicalDefinition} definitions with no program-authored ruling map, so a
 * fired rule's own `description` (from `@orkestrel/reason`) is the message
 * template, interpolated against the working record the definition ran against.
-* Rich premises reuse the qualifier's {@link logicalPremises}. A rule that never
+* Rich premises reuse the qualifier's {@link ruleToPremises}. A rule that never
 * fires produces no determination — program has no authored ruling map to keep
 * evidence for.
 *
@@ -575,12 +587,12 @@ function buildNotices(notices, subject) {
 *
 * @example
 * ```ts
-* import { buildLimits } from '@orkestrel/program'
+* import { buildLimitDeterminations } from '@orkestrel/program'
 *
-* buildLimits(authority, resolved, outcome, evaluator)
+* buildLimitDeterminations(authority, resolved, outcome, evaluator)
 * ```
 */
-function buildLimits(definition, result, working, evaluator, labels) {
+function buildLimitDeterminations(definition, result, working, evaluator, labels) {
 	const output = [];
 	for (const entry of result.rules) {
 		if (!entry.applied) continue;
@@ -591,13 +603,13 @@ function buildLimits(definition, result, working, evaluator, labels) {
 			effect: "limit",
 			applied: true,
 			...rule.description === void 0 ? {} : { message: interpolateMessage(rule.description, working) },
-			premises: logicalPremises(rule, working, evaluator, labels)
+			premises: ruleToPremises(rule, working, evaluator, labels)
 		});
 	}
 	return output;
 }
 /**
-* Build the private authority outcome projection from an assembled program result.
+* Builds the private authority outcome projection from an assembled program result.
 *
 * @remarks
 * The authority reads this record under {@link OUTCOME_KEY}; it never receives
@@ -626,7 +638,7 @@ function buildOutcomeProjection(result) {
 	};
 }
 /**
-* Assemble a {@link ProgramResult} from its qualification, rating, and
+* Assembles a {@link ProgramResult} from its qualification, rating, and
 * determination parts — before or after authority.
 *
 * @remarks
@@ -634,8 +646,8 @@ function buildOutcomeProjection(result) {
 * qualification succeeded, rating (when it ran) succeeded, and authority (when it
 * ran) produced no errors — a valid ineligible or referral outcome still
 * succeeds. `trace` and `errors` accumulate the qualification's, every rated
-* line's worksheet trail, and the authority's. A `decision` is present ONLY when
-* an authority ran (`options.authority`), the execution SUCCEEDED (`success`),
+* line's worksheet trail, and the authority's. A `decision` is present only when
+* an authority ran (`options.authority`), the execution succeeded (`success`),
 * no `limit` determination applied, and status is not `unrated`.
 *
 * @param definition - The authored program definition
@@ -687,7 +699,7 @@ function buildProgramResult(definition, qualification, rating, determinations, s
 	};
 }
 /**
-* Add optional aggregate context to a private subject copy for qualification.
+* Adds optional aggregate context to a private subject copy for qualification.
 *
 * @remarks
 * The original subject is returned unchanged when no aggregate context exists.
@@ -722,7 +734,7 @@ function buildQualificationSubject(subject, aggregate) {
 	};
 }
 /**
-* Return authored scopes (qualification ruling scopes or notice scopes) that
+* Returns authored scopes (qualification ruling scopes or notice scopes) that
 * name no rating line on the program.
 *
 * @remarks
@@ -749,7 +761,7 @@ function findMissingScopes(definition) {
 	return [...missing];
 }
 /**
-* Assert a program definition's always-on construction invariants — missing
+* Asserts a program definition's always-on construction invariants — missing
 * scope references and duplicate rating-line or notice ids.
 *
 * @remarks
@@ -758,10 +770,10 @@ function findMissingScopes(definition) {
 * an authoring mistake this severe cannot silently compile.
 *
 * @param definition - The program definition to assert
-* @throws {@link ProgramError} `'MISSING'` when a ruling or notice scope names
-* no rating line
-* @throws {@link ProgramError} `'DUPLICATE'` when two rating lines or two
-* notices share an id
+* @throws {@link ProgramError} Thrown when a ruling or notice scope names no
+* rating line (`'MISSING'`).
+* @throws {@link ProgramError} Thrown when two rating lines or two notices share
+* an id (`'DUPLICATE'`).
 *
 * @example
 * ```ts
@@ -779,7 +791,7 @@ function assertProgramDefinition(definition) {
 	if (duplicateNotices.length > 0) throw new ProgramError("DUPLICATE", `Duplicate notice id: ${duplicateNotices.join(", ")}`, definition.id);
 }
 /**
-* Validate a program definition's shape, references, and nested definitions.
+* Validates a program definition's shape, references, and nested definitions.
 *
 * @remarks
 * The single semantic-validation implementation used by `Program.validate`. It
@@ -812,7 +824,7 @@ function validateProgramDefinition(definition, qualifier, engine) {
 	if (definition.id.length === 0) errors.push("Program id must not be empty");
 	if (definition.name.length === 0) errors.push("Program name must not be empty");
 	const qualification = qualifier.validate(definition.qualification);
-	if (isQualificationValidationResult(qualification)) {
+	if (isReasonValidationResult(qualification)) {
 		errors.push(...qualification.errors.map((error) => `qualification: ${error}`));
 		warnings.push(...qualification.warnings.map((warning) => `qualification: ${warning}`));
 	} else errors.push("qualification: Qualifier returned invalid validation result");
@@ -842,7 +854,7 @@ function validateProgramDefinition(definition, qualifier, engine) {
 			if (fields.has(key)) errors.push(`Duplicate aggregate field "${key}"`);
 			fields.add(key);
 		}
-		if (aggregate.by !== void 0 && formatField(aggregate.by).length === 0) errors.push("Aggregate partition field must be non-empty");
+		if (aggregate.partition !== void 0 && formatField(aggregate.partition).length === 0) errors.push("Aggregate partition field must be non-empty");
 		if (aggregate.gates !== void 0) {
 			const validation = engine.validate(aggregate.gates);
 			if (isReasonValidationResult(validation)) {
@@ -860,16 +872,16 @@ function validateProgramDefinition(definition, qualifier, engine) {
 	};
 }
 /**
-* Coerce a subject's partition-key field to its group-key string.
+* Coerces a subject's partition-key field to its group-key string.
 *
 * @remarks
 * The key is the resolved 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`
+* field is literally `''` land in the same partition, and a numeric `1`
 * collides with the string `'1'`.
 *
 * @param subject - The subject to key
-* @param by - The partition key field
+* @param partition - The field the batch partitions on
 * @returns The subject's group key
 *
 * @example
@@ -879,14 +891,14 @@ function validateProgramDefinition(definition, qualifier, engine) {
 * formatGroupKey({ location: 'east' }, 'location') // 'east'
 * ```
 */
-function formatGroupKey(subject, by) {
-	return String(resolveField(subject, by) ?? "");
+function formatGroupKey(subject, partition) {
+	return String(resolveField(subject, partition) ?? "");
 }
 /**
-* Fold one subject's finite aggregate field values into a sums record.
+* Folds one subject's finite aggregate field values into a sums record.
 *
 * @remarks
-* Returns a FRESH record — `sums` is never mutated. Only finite numbers
+* Returns a fresh record — `sums` is never mutated. Only finite numbers
 * contribute; a non-numeric or absent value contributes zero (never a
 * coercion). A {@link FieldPath} may be nested — `formatField` renders the
 * dot-joined key the returned record is keyed by.
@@ -913,7 +925,7 @@ function sumFields(sums, subject, fields) {
 	return next;
 }
 /**
-* Sum aggregate fields across a batch of subjects.
+* Sums aggregate fields across a batch of subjects.
 *
 * @remarks
 * A {@link FieldPath} may be nested — a nested path sums a nested subject field
@@ -933,12 +945,12 @@ function sumFields(sums, subject, fields) {
 * ```
 */
 function aggregateSums(subjects, fields) {
-	let sums = emptySums(fields);
+	let sums = buildEmptySums(fields);
 	for (const subject of subjects) sums = sumFields(sums, subject, fields);
 	return sums;
 }
 /**
-* Partition a batch of subjects by a field, summing aggregate fields per key.
+* Partitions a batch of subjects by a field, summing aggregate fields per key.
 *
 * @remarks
 * The partition key is derived by {@link formatGroupKey}. Group order follows
@@ -946,8 +958,8 @@ function aggregateSums(subjects, fields) {
 *
 * @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
+* @param partition - The field the batch partitions on; no partition is built when absent
+* @returns A fresh list of aggregate groups, or an empty list when `partition` is absent
 *
 * @example
 * ```ts
@@ -956,11 +968,11 @@ function aggregateSums(subjects, fields) {
 * aggregateGroups([{ location: 'east', amount: 5 }], ['amount'], 'location')
 * ```
 */
-function aggregateGroups(subjects, fields, by) {
-	if (by === void 0) return [];
+function aggregateGroups(subjects, fields, partition) {
+	if (partition === void 0) return [];
 	const records = /* @__PURE__ */ new Map();
 	for (const subject of subjects) {
-		const key = formatGroupKey(subject, by);
+		const key = formatGroupKey(subject, partition);
 		const group = records.get(key);
 		if (group === void 0) records.set(key, [subject]);
 		else group.push(subject);
@@ -972,18 +984,18 @@ function aggregateGroups(subjects, fields, by) {
 	}));
 }
 /**
-* Build one subject's overall and optional group aggregate projection.
+* Builds one subject's overall and optional group aggregate projection.
 *
 * @remarks
 * The projection carries the whole-batch `count` and `sums` plus the subject's
-* OWN partition, located by the same {@link formatGroupKey} key
+* own partition, located by the same {@link formatGroupKey} key
 * {@link aggregateGroups} partitions under.
 *
 * @param subject - The subject to project for
 * @param count - The whole-batch subject count
 * @param sums - The whole-batch summed aggregate fields
 * @param groups - The batch partitions
-* @param by - The partition key field; no group is attached when absent
+* @param partition - The field the batch partitions on; no group is attached when absent
 * @returns A fresh aggregate projection
 *
 * @example
@@ -993,8 +1005,8 @@ function aggregateGroups(subjects, fields, by) {
 * buildAggregateProjection(subject, 2, { amount: 8 }, groups, 'location')
 * ```
 */
-function buildAggregateProjection(subject, count, sums, groups, by) {
-	const group = by === void 0 ? void 0 : groups.find((entry) => entry.key === formatGroupKey(subject, by));
+function buildAggregateProjection(subject, count, sums, groups, partition) {
+	const group = partition === void 0 ? void 0 : groups.find((entry) => entry.key === formatGroupKey(subject, partition));
 	return {
 		count,
 		sums: { ...sums },
@@ -1002,7 +1014,7 @@ function buildAggregateProjection(subject, count, sums, groups, by) {
 	};
 }
 /**
-* Build the reserved-key record a batch aggregate-gate definition runs against.
+* Builds the reserved-key record a batch aggregate-gate definition runs against.
 *
 * @remarks
 * Unlike a per-subject {@link buildAggregateProjection}, the batch record carries
@@ -1029,29 +1041,29 @@ function buildAggregateRecord(count, sums, groups) {
 	} };
 }
 /**
-* Build a zero-sum record for a set of aggregate fields.
+* Builds a zero-sum record for a set of aggregate fields.
 *
 * @param fields - The fields to zero
 * @returns A fresh record of dot-joined field to `0`
 *
 * @example
 * ```ts
-* import { emptySums } from '@orkestrel/program'
+* import { buildEmptySums } from '@orkestrel/program'
 *
-* emptySums(['amount']) // { amount: 0 }
+* buildEmptySums(['amount']) // { amount: 0 }
 * ```
 */
-function emptySums(fields) {
+function buildEmptySums(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
+* Completes 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
+* @returns A record carrying every {@link Status}
 *
 * @example
 * ```ts
@@ -1085,28 +1097,28 @@ function completeTallies(entries) {
 	};
 }
 /**
-* Build complete zero status tallies in {@link STATUS_PRECEDENCE} order.
+* Builds complete zero status tallies in {@link STATUSES} order.
 *
 * @param fields - The fields each tally's sums are zeroed for
 * @returns A fresh, complete tally record
 *
 * @example
 * ```ts
-* import { emptyTallies } from '@orkestrel/program'
+* import { buildEmptyTallies } from '@orkestrel/program'
 *
-* emptyTallies(['amount'])
+* buildEmptyTallies(['amount'])
 * ```
 */
-function emptyTallies(fields) {
+function buildEmptyTallies(fields) {
 	const entries = {};
-	for (const status of STATUS_PRECEDENCE) entries[status] = {
+	for (const status of STATUSES) entries[status] = {
 		count: 0,
-		sums: emptySums(fields)
+		sums: buildEmptySums(fields)
 	};
 	return completeTallies(entries);
 }
 /**
-* Add one subject's aggregate contribution to a status tally record.
+* Adds one subject's aggregate contribution to a status tally record.
 *
 * @param tallies - The tallies to update
 * @param result - The subject's program result (its `status` selects the tally)
@@ -1116,12 +1128,12 @@ function emptyTallies(fields) {
 *
 * @example
 * ```ts
-* import { tallyProgram } from '@orkestrel/program'
+* import { tallySubject } from '@orkestrel/program'
 *
-* tallyProgram(tallies, result, { id: 'r1', amount: 5 }, ['amount'])
+* tallySubject(tallies, result, { id: 'r1', amount: 5 }, ['amount'])
 * ```
 */
-function tallyProgram(tallies, result, subject, fields) {
+function tallySubject(tallies, result, subject, fields) {
 	const status = result.status;
 	const current = tallies[status];
 	const sums = sumFields(current.sums, subject, fields);
@@ -1134,13 +1146,13 @@ function tallyProgram(tallies, result, subject, fields) {
 	});
 }
 /**
-* Assemble one batch {@link AggregateResult} from its per-subject and aggregate
+* Assembles one batch {@link AggregateResult} from its per-subject and aggregate
 * parts.
 *
 * @remarks
 * `count` is the subject count, `trace` / `errors` accumulate every subject's
 * plus the batch aggregate-gate evaluation's (`options.gates`), and `success`
-* requires every subject execution to succeed AND the gate evaluation to have
+* requires every subject execution to succeed and the gate evaluation to have
 * produced no errors. A fired aggregate gate contributes a `limit`
 * determination, never a technical failure (a non-logical gate result is a
 * caller-facing `MISMATCH` thrown by `Program` before this assembles).
@@ -1180,11 +1192,14 @@ function buildAggregateResult(definition, subjects, determinations, groups, tall
 	};
 }
 /**
-* Build a {@link ProgramDefinition}.
+* Builds a fresh {@link ProgramDefinition}.
 *
 * @remarks
-* Copies every collection and omits absent optional keys, so the returned
-* definition is a fresh, JSON-serializable value that never aliases its inputs.
+* Omits absent optional keys. `metadata` is deep-copied with `structuredClone`.
+* `notices` is copied as a fresh array whose elements are shared with the
+* input. `qualification`, `rating`, `authority`, and `aggregate` are stored
+* by reference. The {@link Program} constructor later snapshots and seals
+* the whole graph.
 *
 * @param id - The program id
 * @param name - The display name
@@ -1195,12 +1210,12 @@ function buildAggregateResult(definition, subjects, determinations, groups, tall
 *
 * @example
 * ```ts
-* import { programDefinition } from '@orkestrel/program'
+* import { buildProgramDefinition } from '@orkestrel/program'
 *
-* programDefinition('standard', 'Standard', qualification, rating, { notices: [notice] })
+* buildProgramDefinition('standard', 'Standard', qualification, rating, { notices: [notice] })
 * ```
 */
-function programDefinition(id, name, qualification, rating, input) {
+function buildProgramDefinition(id, name, qualification, rating, input) {
 	return {
 		id,
 		name,
@@ -1210,25 +1225,28 @@ function programDefinition(id, name, qualification, rating, input) {
 		...input?.notices === void 0 ? {} : { notices: [...input.notices] },
 		...input?.authority === void 0 ? {} : { authority: input.authority },
 		...input?.aggregate === void 0 ? {} : { aggregate: input.aggregate },
-		...input?.metadata === void 0 ? {} : { metadata: copyJSONValue(input.metadata) }
+		...input?.metadata === void 0 ? {} : { metadata: structuredClone(input.metadata) }
 	};
 }
 /**
-* Build a {@link Notice}.
+* Builds a fresh {@link Notice}.
+*
+* @remarks
+* An absent `scope` is omitted entirely rather than stored as `undefined`.
 *
 * @param id - The notice id
-* @param message - The message template, carrying optional `{{token}}`s
+* @param message - The message template, carrying optional `{{token}}` placeholders
 * @param input - Optional presentation scope
 * @returns A fresh notice
 *
 * @example
 * ```ts
-* import { noticeDefinition } from '@orkestrel/program'
+* import { buildNotice } from '@orkestrel/program'
 *
-* noticeDefinition('minimum', 'Minimum earned premium applies')
+* buildNotice('minimum', 'Minimum earned premium applies')
 * ```
 */
-function noticeDefinition(id, message, input) {
+function buildNotice(id, message, input) {
 	return {
 		id,
 		message,
@@ -1236,7 +1254,11 @@ function noticeDefinition(id, message, input) {
 	};
 }
 /**
-* Build an {@link AggregateDefinition}.
+* Builds a fresh {@link AggregateDefinition}.
+*
+* @remarks
+* `fields` is copied into a fresh array; an absent `partition` or `gates` is
+* omitted entirely rather than stored as `undefined`.
 *
 * @param fields - The aggregate fields to sum across a batch
 * @param input - Optional partition field and aggregate gates
@@ -1244,30 +1266,30 @@ function noticeDefinition(id, message, input) {
 *
 * @example
 * ```ts
-* import { aggregateDefinition } from '@orkestrel/program'
+* import { buildAggregateDefinition } from '@orkestrel/program'
 *
-* aggregateDefinition(['amount'], { by: 'location' })
+* buildAggregateDefinition(['amount'], { partition: 'location' })
 * ```
 */
-function aggregateDefinition(fields, input) {
+function buildAggregateDefinition(fields, input) {
 	return {
 		fields: [...fields],
-		...input?.by === void 0 ? {} : { by: input.by },
+		...input?.partition === void 0 ? {} : { partition: input.partition },
 		...input?.gates === void 0 ? {} : { gates: input.gates }
 	};
 }
 //#endregion
 //#region src/core/programs/Program.ts
 /**
-* One compiled program — composes one qualifier and one rater over a shared
-* reason engine and executes single subjects or aggregate-aware batches.
+* Composes one qualifier and one rater over a shared reason engine, compiling one
+* authored definition and executing single subjects or aggregate-aware batches.
 *
 * @remarks
 * Qualification decides whether rating happens: a globally ineligible, referred,
 * or failed subject never reaches the rater, and a scoped ineligibility removes
 * only its line before the first rating call. The rater always receives the
-* ORIGINAL subject; the qualifier's aggregate projection stays private. When no
-* qualifier, rater, or engine is injected the program creates ONE shared
+* original subject; the qualifier's aggregate projection stays private. When no
+* qualifier, rater, or engine is injected the program creates one shared
 * quantitative-plus-logical engine, injects it into the qualifier and rater it
 * creates, and destroys only what it owns. A definition failure during
 * construction (an invalid definition under `options.validate`) tears down
@@ -1277,8 +1299,8 @@ function aggregateDefinition(fields, input) {
 * or `Date` reached through a reason `Check.value` is cloned but remains mutable
 * because its contents live in internal slots. Uncloneable values and non-empty
 * typed arrays are refused with `ProgramError('DEFINITION')` and the host error
-* as its cause. `destroy()` is idempotent and REENTRANCY-SAFE — the destroyed
-* flag is set BEFORE any teardown or the `destroy` event fires, so a listener
+* as its cause. `destroy()` is idempotent and reentrancy-safe — the destroyed
+* flag is set before any teardown or the `destroy` event fires, so a listener
 * that re-enters `destroy()` is a no-op — and tears the emitter down last.
 */
 var Program = class {
@@ -1293,21 +1315,31 @@ var Program = class {
 	#validate;
 	#labels;
 	#destroyed = false;
+	/** Holds the authored id of the definition this program compiled. */
 	id;
+	/** Holds the authored display name of the definition this program compiled. */
 	name;
+	/** Holds the sealed snapshot of the authored definition this program compiled. */
 	definition;
+	/**
+	* Compiles one program from an authored definition.
+	*
+	* @param definition - The authored program definition
+	* @param options - Optional injected qualifier, rater, engine, validation, labels, and emitter hooks
+	* @throws {@link ProgramError} Thrown when the definition cannot be cloned or
+	* sealed, or when validation is enabled and the definition fails
+	* (`'DEFINITION'`).
+	* @throws {@link ProgramError} Thrown when a ruling or notice scope names no
+	* rating line (`'MISSING'`).
+	* @throws {@link ProgramError} Thrown when the definition repeats a rating-line
+	* or notice id (`'DUPLICATE'`).
+	*/
 	constructor(definition, options) {
 		let snapshot;
 		try {
 			snapshot = structuredClone(definition);
 		} catch (cause) {
-			const error = new ProgramError("DEFINITION", "Program definition could not be cloned");
-			Object.defineProperty(error, "cause", {
-				configurable: true,
-				value: cause,
-				writable: true
-			});
-			throw error;
+			throw new ProgramError("DEFINITION", "Program definition could not be cloned", void 0, cause);
 		}
 		assertProgramDefinition(snapshot);
 		this.id = snapshot.id;
@@ -1316,13 +1348,7 @@ var Program = class {
 		try {
 			this.#seal();
 		} catch (cause) {
-			const error = new ProgramError("DEFINITION", "Program definition could not be sealed", snapshot.id);
-			Object.defineProperty(error, "cause", {
-				configurable: true,
-				value: cause,
-				writable: true
-			});
-			throw error;
+			throw new ProgramError("DEFINITION", "Program definition could not be sealed", snapshot.id, cause);
 		}
 		this.#emitter = new Emitter({
 			...options?.on === void 0 ? {} : { on: options.on },
@@ -1348,6 +1374,21 @@ var Program = class {
 			}
 		}
 	}
+	/**
+	* Holds the typed observation surface carrying `qualify`, `rate`, `determine`,
+	* `decide`, `execute`, `aggregate`, and `destroy`.
+	*
+	* @returns The emitter this program owns
+	*
+	* @example
+	* ```ts
+	* import { createProgram } from '@orkestrel/program'
+	*
+	* const program = createProgram(definition)
+	* program.emitter.on('execute', (result) => result.status)
+	* program.destroy()
+	* ```
+	*/
 	get emitter() {
 		return this.#emitter;
 	}
@@ -1356,10 +1397,51 @@ var Program = class {
 		if (isArray(input)) return this.#aggregate(input);
 		return this.#subject(input);
 	}
+	/**
+	* Validates this program's definition and every nested definition.
+	*
+	* @remarks
+	* Exact shape is `isProgramDefinition`'s job. This checks the meaning: non-empty id
+	* and name, every ruling and notice scope naming a rating line, unique non-empty
+	* aggregate fields, and a non-empty partition field when present. Nested
+	* qualification validation is delegated to the injected qualifier, and authority
+	* and aggregate-gate validation to the shared reason engine.
+	*
+	* @returns A fresh validation result carrying `valid`, `errors`, and `warnings`
+	* @throws {@link ProgramError} Thrown when the program has been destroyed
+	* (`'DESTROYED'`).
+	*
+	* @example
+	* ```ts
+	* import { createProgram } from '@orkestrel/program'
+	*
+	* const program = createProgram(definition, { validate: false })
+	* program.validate().valid // true
+	* program.destroy()
+	* ```
+	*/
 	validate() {
 		this.#alive();
 		return validateProgramDefinition(this.definition, this.#qualifier, this.#engine);
 	}
+	/**
+	* Destroys this program, idempotently.
+	*
+	* @remarks
+	* The destroyed flag is set before any teardown or the `destroy` event, so a
+	* listener re-entering `destroy` is a no-op. An owned qualifier, rater, and reason
+	* engine are destroyed; an injected one stays caller-owned. The emitter is torn
+	* down last, and stays reachable afterwards.
+	*
+	* @example
+	* ```ts
+	* import { createProgram } from '@orkestrel/program'
+	*
+	* const program = createProgram(definition)
+	* program.destroy()
+	* program.destroy() // a second call is a no-op
+	* ```
+	*/
 	destroy() {
 		if (this.#destroyed) return;
 		this.#destroyed = true;
@@ -1385,7 +1467,7 @@ var Program = class {
 		return this.#finish(subject, qualification, rating);
 	}
 	#finish(subject, qualification, rating) {
-		const notices = buildNotices(this.definition.notices ?? [], subject);
+		const notices = buildNoticeDeterminations(this.definition.notices ?? [], subject);
 		for (const notice of notices) this.#emitter.emit("determine", notice);
 		const status = deriveStatus(this.definition, qualification, rating);
 		let result = buildProgramResult(this.definition, qualification, rating, notices, status);
@@ -1397,7 +1479,7 @@ var Program = class {
 		const outcome = { [OUTCOME_KEY]: buildOutcomeProjection(result) };
 		const resolved = this.#engine.reason(outcome, authority);
 		if (!isLogicalResult(resolved)) throw new ProgramError("MISMATCH", "Authority returned invalid logical result", authority.id);
-		const limits = buildLimits(authority, resolved, outcome, this.#evaluator, this.#labels);
+		const limits = buildLimitDeterminations(authority, resolved, outcome, this.#evaluator, this.#labels);
 		for (const limit of limits) this.#emitter.emit("determine", limit);
 		result = buildProgramResult(this.definition, qualification, rating, [...notices, ...limits], status, { authority: resolved });
 		if (result.decision !== void 0) this.#emitter.emit("decide", result.decision, result);
@@ -1409,12 +1491,12 @@ var Program = class {
 		const definition = this.definition.aggregate;
 		const fields = [...definition?.fields ?? []];
 		const sums = aggregateSums(subjects, fields);
-		const groups = aggregateGroups(subjects, fields, definition?.by);
-		let tallies = emptyTallies(fields);
+		const groups = aggregateGroups(subjects, fields, definition?.partition);
+		let tallies = buildEmptyTallies(fields);
 		const results = subjects.map((subject) => {
-			const projection = definition === void 0 ? void 0 : buildAggregateProjection(subject, subjects.length, sums, groups, definition.by);
+			const projection = definition === void 0 ? void 0 : buildAggregateProjection(subject, subjects.length, sums, groups, definition.partition);
 			const result = this.#subject(subject, projection);
-			tallies = tallyProgram(tallies, result, subject, fields);
+			tallies = tallySubject(tallies, result, subject, fields);
 			return result;
 		});
 		const gates = this.#aggregateLimits(subjects.length, sums, groups);
@@ -1428,7 +1510,7 @@ var Program = class {
 		const record = buildAggregateRecord(count, sums, groups);
 		const resolved = this.#engine.reason(record, gates);
 		if (!isLogicalResult(resolved)) throw new ProgramError("MISMATCH", "Aggregate gates returned invalid logical result", gates.id);
-		const determinations = buildLimits(gates, resolved, record, this.#evaluator, this.#labels);
+		const determinations = buildLimitDeterminations(gates, resolved, record, this.#evaluator, this.#labels);
 		for (const determination of determinations) this.#emitter.emit("determine", determination);
 		return {
 			determinations,
@@ -1451,18 +1533,18 @@ var Program = class {
 //#endregion
 //#region src/core/programs/ProgramManager.ts
 /**
-* An ordered manager over compiled {@link ProgramInterface}s (AGENTS §9), sharing
-* one qualifier, rater, and reason engine across every program it compiles.
+* Manages compiled {@link ProgramInterface} programs in order, sharing one
+* qualifier, rater, and reason engine across every program it compiles.
 *
 * @remarks
-* OWNS its ordered `#programs` collection and its own {@link Emitter} over
+* owns its ordered `#programs` collection and its own {@link Emitter} over
 * {@link ProgramManagerEventMap}. Creates or borrows one shared engine, qualifier,
 * and rater and injects the same instances into every compiled program. `remove`
 * destroys the programs it removes; `destroy()` removes all programs, then
-* destroys only the owned shared dependencies, and tears the emitter down LAST.
+* destroys only the owned shared dependencies, and tears the emitter down last.
 * A seed-program failure during construction tears the manager down (destroying
 * whatever had already been compiled) before rethrowing the original error.
-* `destroy()` is REENTRANCY-SAFE — the destroyed flag is set BEFORE any teardown
+* `destroy()` is reentrancy-safe — the destroyed flag is set before any teardown
 * or the `remove` / `destroy` events fire, so a `remove` listener that re-enters
 * `destroy()` is a no-op. Every call after `destroy()` throws {@link ProgramError}
 * `'DESTROYED'`.
@@ -1479,6 +1561,13 @@ var ProgramManager = class {
 	#validate;
 	#labels;
 	#destroyed = false;
+	/**
+	* Creates one manager and compiles every seed definition in order.
+	*
+	* @param options - Optional injected qualifier, rater, engine, seed programs, validation, labels, and emitter hooks
+	* @throws {@link ProgramError} Thrown when a seed definition fails to compile,
+	* after the manager destroys whatever it had already compiled.
+	*/
 	constructor(options) {
 		this.#emitter = new Emitter({
 			...options?.on === void 0 ? {} : { on: options.on },
@@ -1502,25 +1591,138 @@ var ProgramManager = class {
 			throw error;
 		}
 	}
+	/**
+	* Holds the typed observation surface carrying `add`, `remove`, and `destroy`.
+	*
+	* @returns The emitter this manager owns
+	*
+	* @example
+	* ```ts
+	* import { createProgramManager } from '@orkestrel/program'
+	*
+	* const manager = createProgramManager()
+	* manager.emitter.on('add', (id) => id)
+	* manager.destroy()
+	* ```
+	*/
 	get emitter() {
 		return this.#emitter;
 	}
-	get size() {
+	/**
+	* Holds how many programs the manager has compiled.
+	*
+	* @returns The number of compiled programs
+	* @throws {@link ProgramError} Thrown when the manager has been destroyed
+	* (`'DESTROYED'`).
+	*
+	* @example
+	* ```ts
+	* import { createProgramManager } from '@orkestrel/program'
+	*
+	* const manager = createProgramManager({ programs: [definition] })
+	* manager.count // 1
+	* manager.destroy()
+	* ```
+	*/
+	get count() {
 		this.#alive();
 		return this.#programs.length;
 	}
+	/**
+	* Reports whether an id names a compiled program.
+	*
+	* @param id - The program id to look for
+	* @returns True if a compiled program carries the id; false otherwise
+	* @throws {@link ProgramError} Thrown when the manager has been destroyed
+	* (`'DESTROYED'`).
+	*
+	* @example
+	* ```ts
+	* import { createProgramManager } from '@orkestrel/program'
+	*
+	* const manager = createProgramManager({ programs: [definition] })
+	* manager.has('standard') // true
+	* manager.destroy()
+	* ```
+	*/
 	has(id) {
 		this.#alive();
 		return this.#programs.some((program) => program.id === id);
 	}
+	/**
+	* Looks one compiled program up by id.
+	*
+	* @param id - The program id to look up
+	* @returns The compiled program, or `undefined` when no program carries the id
+	* @throws {@link ProgramError} Thrown when the manager has been destroyed
+	* (`'DESTROYED'`).
+	*
+	* @example
+	* ```ts
+	* import { createProgramManager } from '@orkestrel/program'
+	*
+	* const manager = createProgramManager({ programs: [definition] })
+	* manager.program('standard')?.execute({ id: 'risk-1', licensed: true })
+	* manager.destroy()
+	* ```
+	*/
 	program(id) {
 		this.#alive();
 		return this.#programs.find((program) => program.id === id);
 	}
+	/**
+	* Returns every compiled program, in insertion order.
+	*
+	* @remarks
+	* The returned array is a fresh copy, so mutating it never reaches the manager's
+	* own collection.
+	*
+	* @returns A fresh array of compiled programs, in insertion order
+	* @throws {@link ProgramError} Thrown when the manager has been destroyed
+	* (`'DESTROYED'`).
+	*
+	* @example
+	* ```ts
+	* import { createProgramManager } from '@orkestrel/program'
+	*
+	* const manager = createProgramManager({ programs: [definition] })
+	* manager.programs().map((program) => program.id) // ['standard']
+	* manager.destroy()
+	* ```
+	*/
 	programs() {
 		this.#alive();
 		return [...this.#programs];
 	}
+	/**
+	* Compiles one definition and appends it to the collection.
+	*
+	* @remarks
+	* The compiled program borrows the manager's shared qualifier, rater, and reason
+	* engine, and inherits the manager's `validate` and `labels` options. After
+	* appending the program, the `add` event fires with its id.
+	*
+	* @param definition - The authored program definition to compile
+	* @returns The compiled program
+	* @throws {@link ProgramError} Thrown when the manager has been destroyed
+	* (`'DESTROYED'`).
+	* @throws {@link ProgramError} Thrown when the manager already carries the
+	* definition's id, or the definition repeats a rating-line or notice id
+	* (`'DUPLICATE'`).
+	* @throws {@link ProgramError} Thrown when a ruling or notice scope names no
+	* rating line (`'MISSING'`).
+	* @throws {@link ProgramError} Thrown when validation is enabled and the
+	* definition fails (`'DEFINITION'`).
+	*
+	* @example
+	* ```ts
+	* import { createProgramManager } from '@orkestrel/program'
+	*
+	* const manager = createProgramManager()
+	* manager.add(definition).id // 'standard'
+	* manager.destroy()
+	* ```
+	*/
 	add(definition) {
 		this.#alive();
 		if (this.has(definition.id)) throw new ProgramError("DUPLICATE", `Program "${definition.id}" already exists`, definition.id);
@@ -1548,6 +1750,25 @@ var ProgramManager = class {
 		}
 		if (typeof input === "string") return this.#removeOne(input);
 	}
+	/**
+	* Destroys this manager, idempotently.
+	*
+	* @remarks
+	* The destroyed flag is set before any teardown or the `remove` and `destroy`
+	* events, so a `remove` listener re-entering `destroy` is a no-op. Compiled
+	* programs are destroyed first, then an owned qualifier, rater, and reason engine;
+	* an injected one stays caller-owned. The emitter is torn down last, and stays
+	* reachable afterwards.
+	*
+	* @example
+	* ```ts
+	* import { createProgramManager } from '@orkestrel/program'
+	*
+	* const manager = createProgramManager({ programs: [definition] })
+	* manager.destroy()
+	* manager.destroy() // a second call is a no-op
+	* ```
+	*/
 	destroy() {
 		if (this.#destroyed) return;
 		this.#destroyed = true;
@@ -1580,32 +1801,39 @@ var ProgramManager = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create one compiled program over a qualifier and rater.
+* Creates one compiled {@link ProgramInterface} over a qualifier and rater.
 *
 * @remarks
-* Validates the definition at construction when `options.validate` is left at
-* its {@link DEFAULT_PROGRAM_VALIDATE} default. A standalone program creates and
-* OWNS one shared quantitative-plus-logical reason engine and injects it into the
-* qualifier and rater it creates; injected dependencies remain caller-owned.
+* If `options.validate` is `true`, the program validates the definition at
+* construction; if `false`, it compiles the definition unvalidated. Default:
+* {@link DEFAULT_PROGRAM_VALIDATE}. A standalone program creates and owns one
+* shared quantitative-plus-logical reason engine and injects it into the qualifier
+* and rater it creates; injected dependencies remain caller-owned.
 *
 * @param definition - The authored program definition
 * @param options - Optional injected qualifier, rater, engine, validation, labels, and emitter hooks
 * @returns A {@link ProgramInterface}
 *
-* @example
+* @example Compile a program and a manager
 * ```ts
-* import { createProgram, programDefinition } from '@orkestrel/program'
+* import { buildProgramDefinition, createProgram, createProgramManager } from '@orkestrel/program'
+*
+* const definition = buildProgramDefinition('standard', 'Standard', qualification, rating)
+*
+* const program = createProgram(definition)
+* const manager = createProgramManager({ programs: [definition] })
 *
-* const program = createProgram(programDefinition('standard', 'Standard', qualification, rating))
 * program.execute({ id: 'risk-1' })
+*
 * program.destroy()
+* manager.destroy()
 * ```
 */
 function createProgram(definition, options) {
 	return new Program(definition, options);
 }
 /**
-* Create one ordered manager over compiled programs.
+* Creates one ordered {@link ProgramManagerInterface} over compiled programs.
 *
 * @remarks
 * Creates or borrows one shared reason engine, qualifier, and rater and injects
@@ -1628,6 +1856,6 @@ function createProgramManager(options) {
 	return new ProgramManager(options);
 }
 //#endregion
-export { AGGREGATE_KEY, DEFAULT_PROGRAM_VALIDATE, ELIGIBILITY_DECISIONS, OUTCOME_KEY, Program, ProgramError, ProgramManager, STATUS_PRECEDENCE, aggregateDefinition, aggregateGroups, aggregateSums, assertProgramDefinition, assertProgramSubject, buildAggregateProjection, buildAggregateRecord, buildAggregateResult, buildLimits, buildNotices, buildOutcomeProjection, buildProgramResult, buildQualificationSubject, completeTallies, copyJSONValue, createProgram, createProgramManager, decideEligibility, deriveStatus, emptySums, emptyTallies, findMissingScopes, formatGroupKey, hasReservedKey, isAggregateDefinition, isAggregateGroup, isAggregateResult, isDecision, isDetermination, isNotice, isProgramDefinition, isProgramEffect, isProgramError, isProgramResult, isProgramSums, isProgramValidationResult, isStatus, isTallies, isTally, noticeDefinition, programDefinition, selectProgramLines, sumFields, tallyProgram, validateProgramDefinition };
+export { AGGREGATE_KEY, DEFAULT_PROGRAM_VALIDATE, ELIGIBILITY_DECISIONS, OUTCOME_KEY, Program, ProgramError, ProgramManager, STATUSES, aggregateGroups, aggregateSums, assertProgramDefinition, assertProgramSubject, buildAggregateDefinition, buildAggregateProjection, buildAggregateRecord, buildAggregateResult, buildEmptySums, buildEmptyTallies, buildLimitDeterminations, buildNotice, buildNoticeDeterminations, buildOutcomeProjection, buildProgramDefinition, buildProgramResult, buildQualificationSubject, completeTallies, createProgram, createProgramManager, decideEligibility, deriveStatus, findMissingScopes, formatGroupKey, hasReservedKey, isAggregateDefinition, isAggregateGroup, isAggregateResult, isDecision, isDetermination, isNotice, isProgramDefinition, isProgramEffect, isProgramError, isProgramResult, isProgramSums, isProgramValidationResult, isStatus, isTallies, isTally, selectProgramLines, sumFields, tallySubject, validateProgramDefinition };
 
 //# sourceMappingURL=index.js.map