@orkestrel/program 0.0.12 → 0.0.13

package/README.md

@@ -1,17 +1,20 @@
 # @orkestrel/program
 
-A **program composition layer** over
-[`@orkestrel/qualifier`](https://github.com/orkestrel/qualifier) and
-[`@orkestrel/rater`](https://github.com/orkestrel/rater): a pure,
-JSON-serializable `ProgramDefinition` composes one qualification with an optional
-rating, plus optional notices, authority, and batch aggregate policy. `Program` executes
-the workflow in one direction — qualify the subject, stop on terminal
-qualification, select eligible rating lines, rate only those lines, derive status,
-then evaluate optional authority — returning a nested `ProgramResult` (or
-`AggregateResult` for batch `execute`). Globally ineligible or referred subjects
-never reach the rater. Execution never mutates its inputs — every result is a
-fresh object. Environment-agnostic — no I/O, no browser or server assumptions.
-Part of the `@orkestrel` line.
+> The program composition layer: a pure, JSON-serializable `ProgramDefinition`
+> that composes one qualification with an optional rating, plus notices,
+> authority, and batch aggregate policy, and a `Program` that executes that
+> definition in one direction — qualify, select, rate, derive status, then decide.
+
+Build a definition with the `buildProgramDefinition` function, compile it with
+`createProgram`, and call `execute` with one subject for a `ProgramResult` or
+with a subject array for an `AggregateResult`. Execution never mutates its
+inputs; every result is a fresh object. Injected qualifier, rater, and reason
+instances stay caller-owned, and a standalone program owns the engine it creates.
+Built over [`@orkestrel/qualifier`](https://github.com/orkestrel/qualifier),
+[`@orkestrel/rater`](https://github.com/orkestrel/rater), and the shared
+[`@orkestrel/reason`](https://github.com/orkestrel/reason) engine.
+Environment-agnostic — no I/O, no browser or server assumptions. Part of the
+`@orkestrel` line.
 
 ## Install
 

package/dist/src/core/index.cjs

@@ -5,9 +5,15 @@ let _orkestrel_rater = require("@orkestrel/rater");
 let _orkestrel_reason = require("@orkestrel/reason");
 let _orkestrel_emitter = require("@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",
@@ -21,19 +27,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
@@ -453,7 +466,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
@@ -481,9 +494,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
@@ -634,8 +647,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
@@ -865,7 +878,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
@@ -886,7 +899,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.
@@ -976,7 +989,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
@@ -1140,7 +1153,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).
@@ -1219,6 +1232,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
@@ -1241,6 +1257,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
@@ -1262,15 +1282,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
@@ -1280,8 +1300,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 {
@@ -1409,7 +1429,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.
@@ -1518,14 +1538,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'`.
@@ -1735,7 +1755,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
@@ -1782,34 +1802,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