@orkestrel/program 0.0.12 → 0.0.13

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

@@ -1,25 +1,28 @@
-import { Eligibility } from '@orkestrel/qualifier';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { EvaluatorInterface } from '@orkestrel/reason';
-import { FieldPath } from '@orkestrel/contract';
-import { Guard } from '@orkestrel/contract';
-import { JSONValue } from '@orkestrel/contract';
-import { LineDefinition } from '@orkestrel/rater';
-import { LogicalDefinition } from '@orkestrel/reason';
-import { LogicalResult } from '@orkestrel/reason';
-import { Premise } from '@orkestrel/qualifier';
-import { QualificationDefinition } from '@orkestrel/qualifier';
-import { QualificationResult } from '@orkestrel/qualifier';
-import { QualifierInterface } from '@orkestrel/qualifier';
-import { RaterInterface } from '@orkestrel/rater';
-import { RatingDefinition } from '@orkestrel/rater';
-import { RatingResult } from '@orkestrel/rater';
-import { ReasonInterface } from '@orkestrel/reason';
-import { Subject } from '@orkestrel/reason';
-
-/** Names the reserved working-subject key a batch's aggregate projection is written under. */
+import type { Eligibility } from '@orkestrel/qualifier';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { EvaluatorInterface } from '@orkestrel/reason';
+import type { FieldPath } from '@orkestrel/contract';
+import type { Guard } from '@orkestrel/contract';
+import type { JSONValue } from '@orkestrel/contract';
+import type { LineDefinition } from '@orkestrel/rater';
+import type { LogicalDefinition } from '@orkestrel/reason';
+import type { LogicalResult } from '@orkestrel/reason';
+import type { Premise } from '@orkestrel/qualifier';
+import type { QualificationDefinition } from '@orkestrel/qualifier';
+import type { QualificationResult } from '@orkestrel/qualifier';
+import type { QualifierInterface } from '@orkestrel/qualifier';
+import type { RaterInterface } from '@orkestrel/rater';
+import type { RatingDefinition } from '@orkestrel/rater';
+import type { RatingResult } from '@orkestrel/rater';
+import type { ReasonInterface } from '@orkestrel/reason';
+import type { Subject } from '@orkestrel/reason';
+
+/**
+ * Names the reserved working-subject key a batch's aggregate projection is written
+ * under, `'aggregate'`.
+ */
 export declare const AGGREGATE_KEY = "aggregate";
 
 /** Describes batch aggregate fields, an optional partition field, and optional gates. */
@@ -158,6 +161,10 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
           /**
            * 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
            * @returns A fresh aggregate definition
@@ -176,7 +183,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
            *
            * @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
@@ -224,7 +231,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
            * @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).
@@ -310,6 +317,9 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
           /**
            * 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}}` placeholders
            * @param input - Optional presentation scope
@@ -401,8 +411,8 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
            * 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
@@ -463,33 +473,38 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
           export declare function completeTallies(entries: Partial<Record<Status, Tally>>): Readonly<Record<Status, Tally>>;
 
           /**
-           * Creates one compiled program over a qualifier and rater.
+           * Creates one compiled {@link ProgramInterface} over a qualifier and rater.
            *
            * @remarks
            * 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.
+           * {@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 { buildProgramDefinition, createProgram } 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] })
+           *
            * program.execute({ id: 'risk-1' })
+           *
            * program.destroy()
+           * manager.destroy()
            * ```
            */
           export declare function createProgram(definition: ProgramDefinition, options?: ProgramOptions): ProgramInterface;
 
           /**
-           * Creates 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
@@ -529,7 +544,10 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
           /** Identifies a final authority outcome, derived from global eligibility. */
           export declare type Decision = 'approved' | 'denied' | 'submitted';
 
-          /** Names the default definition validation policy for `createProgram` / `ProgramManager.add`. */
+          /**
+           * Names the default definition validation policy, `true`, for `createProgram` /
+           * `ProgramManager.add`.
+           */
           export declare const DEFAULT_PROGRAM_VALIDATE = true;
 
           /**
@@ -540,9 +558,9 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
            * 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
@@ -600,7 +618,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
            * @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
@@ -924,19 +942,22 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
               readonly scope?: string;
           }
 
-          /** Names 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'`.
+           */
           export declare const OUTCOME_KEY = "outcome";
 
           /**
-           * 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
@@ -946,8 +967,8 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
            * 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.
            */
           export declare class Program implements ProgramInterface {
@@ -1026,7 +1047,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                  * 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. Notices, status, optional authority, and the optional
+                                 * original subject. Notices, status, optional authority, and the optional
                                  * decision follow, in that order.
                                  *
                                  * @param subject - The subject to execute
@@ -1078,7 +1099,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                            * Destroys this program, idempotently.
                                            *
                                            * @remarks
-                                           * The destroyed flag is set BEFORE any teardown or the `destroy` event, so a
+                                           * 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.
@@ -1103,7 +1124,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                           * over the lines scoped eligibility left standing, through `@orkestrel/rater`.
                                           * `authority` (a logical definition) runs last, over the assembled result
                                           * extended with an outcome projection, to derive limit determinations and the
-                                          * final decision. An omitted `rating` authors an ELIGIBILITY-ONLY program — the
+                                          * final decision. An omitted `rating` authors an eligibility-only program — the
                                           * rater is never invoked, an eligible subject resolves to `'eligible'` (or
                                           * `'conditional'` under an applied condition or scoped restriction), status is
                                           * never `'unrated'`, and decisions remain reachable through `authority`. Program
@@ -1130,12 +1151,13 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                          export declare type ProgramEffect = 'notice' | 'limit';
 
                                          /**
-                                          * Reports 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
@@ -1255,7 +1277,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                                        * 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. Notices, status, optional authority, and the optional
+                                                       * original subject. Notices, status, optional authority, and the optional
                                                        * decision follow, in that order.
                                                        *
                                                        * @param subject - The subject to execute
@@ -1307,7 +1329,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                                                  * Destroys this program, idempotently.
                                                                  *
                                                                  * @remarks
-                                                                 * The destroyed flag is set BEFORE any teardown or the `destroy` event, so a
+                                                                 * 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.
@@ -1329,14 +1351,14 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                                                 * 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'`.
@@ -1535,7 +1557,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                                                                          * Destroys this manager, idempotently.
                                                                                          *
                                                                                          * @remarks
-                                                                                         * The destroyed flag is set BEFORE any teardown or the `remove` and `destroy`
+                                                                                         * 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
@@ -1725,7 +1747,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                                                                                                 * Destroys this manager, idempotently.
                                                                                                                 *
                                                                                                                 * @remarks
-                                                                                                                * The destroyed flag is set BEFORE any teardown or the `remove` and `destroy`
+                                                                                                                * 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
@@ -1802,7 +1824,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                                                                                                    * Holds the final authority outcome.
                                                                                                                    *
                                                                                                                    * @remarks
-                                                                                                                   * Present ONLY when the program HAS an `authority`, the execution SUCCEEDED
+                                                                                                                   * Present only when the program has an `authority`, the execution succeeded
                                                                                                                    * (qualification, rating when it ran, and authority all produced no errors),
                                                                                                                    * no `limit` determination applied, and status is not `unrated`.
                                                                                                                    */
@@ -1829,7 +1851,7 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                                                                                                * 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
@@ -1848,14 +1870,17 @@ export declare function aggregateSums(subjects: readonly Subject[], fields: read
                                                                                                               /** Identifies the presentation and tally status derived from eligibility, conditions, and rating success. */
                                                                                                               export declare type Status = (typeof STATUSES)[number];
 
-                                                                                                              /** Lists every {@link Status} literal — the source the union and its guard derive from. */
+                                                                                                              /**
+                                                                                                               * Lists every {@link Status} literal in tally order — the source the union and its
+                                                                                                               * guard derive from.
+                                                                                                               */
                                                                                                               export declare const STATUSES: readonly ["ineligible", "referral", "conditional", "unrated", "eligible"];
 
                                                                                                               /**
                                                                                                                * 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.

package/dist/src/core/index.js

@@ -4,9 +4,15 @@ import { createRater, isRatingDefinition, isRatingResult } from "@orkestrel/rate
 import { createEvaluator, createLogicalReasoner, createQuantitativeReasoner, createReason, findDuplicates, formatField, isFieldPath, isLogicalDefinition, isLogicalResult, isReasonValidationResult } from "@orkestrel/reason";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
-/** Names the default definition validation policy for `createProgram` / `ProgramManager.add`. */
+/**
+* Names the default definition validation policy, `true`, for `createProgram` /
+* `ProgramManager.add`.
+*/
 var DEFAULT_PROGRAM_VALIDATE = true;
-/** Lists every {@link Status} literal — the source the union and its guard derive from. */
+/**
+* Lists every {@link Status} literal in tally order — the source the union and its
+* guard derive from.
+*/
 var STATUSES = Object.freeze([
 	"ineligible",
 	"referral",
@@ -20,19 +26,26 @@ var ELIGIBILITY_DECISIONS = Object.freeze({
 	ineligible: "denied",
 	referral: "submitted"
 });
-/** Names 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";
-/** Names 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
 /**
-* Reports 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
@@ -452,7 +465,7 @@ function assertProgramSubject(subject) {
 * 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
@@ -480,9 +493,9 @@ function selectProgramLines(lines, scopes) {
 * 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
@@ -633,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
@@ -864,7 +877,7 @@ function validateProgramDefinition(definition, qualifier, engine) {
 * @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
@@ -885,7 +898,7 @@ function formatGroupKey(subject, partition) {
 * 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.
@@ -975,7 +988,7 @@ function aggregateGroups(subjects, fields, partition) {
 *
 * @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
@@ -1139,7 +1152,7 @@ function tallySubject(tallies, result, subject, fields) {
 * @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).
@@ -1218,6 +1231,9 @@ function buildProgramDefinition(id, name, qualification, rating, input) {
 /**
 * 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}}` placeholders
 * @param input - Optional presentation scope
@@ -1240,6 +1256,10 @@ function buildNotice(id, message, input) {
 /**
 * 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
 * @returns A fresh aggregate definition
@@ -1261,15 +1281,15 @@ function buildAggregateDefinition(fields, input) {
 //#endregion
 //#region src/core/programs/Program.ts
 /**
-* 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
@@ -1279,8 +1299,8 @@ function buildAggregateDefinition(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 {
@@ -1408,7 +1428,7 @@ var Program = class {
 	* Destroys this program, idempotently.
 	*
 	* @remarks
-	* The destroyed flag is set BEFORE any teardown or the `destroy` event, so a
+	* 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.
@@ -1517,14 +1537,14 @@ var Program = class {
 * 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'`.
@@ -1734,7 +1754,7 @@ var ProgramManager = class {
 	* Destroys this manager, idempotently.
 	*
 	* @remarks
-	* The destroyed flag is set BEFORE any teardown or the `remove` and `destroy`
+	* 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
@@ -1781,34 +1801,39 @@ var ProgramManager = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Creates one compiled program over a qualifier and rater.
+* Creates one compiled {@link ProgramInterface} over a qualifier and rater.
 *
 * @remarks
 * 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.
+* {@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 { buildProgramDefinition, createProgram } 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] })
+*
 * program.execute({ id: 'risk-1' })
+*
 * program.destroy()
+* manager.destroy()
 * ```
 */
 function createProgram(definition, options) {
 	return new Program(definition, options);
 }
 /**
-* Creates 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