@orkestrel/program 0.0.1

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

@@ -0,0 +1,1137 @@
+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';
+
+/** The reserved working-subject key a batch's aggregate projection is written under. */
+export declare const AGGREGATE_KEY = "aggregate";
+
+/** Batch aggregate fields, an optional partition key, and optional gates. */
+export declare interface AggregateDefinition {
+    readonly fields: readonly FieldPath[];
+    readonly by?: FieldPath;
+    readonly gates?: LogicalDefinition;
+}
+
+/**
+ * Build an {@link AggregateDefinition}.
+ *
+ * @param fields - The aggregate fields to sum across a batch
+ * @param input - Optional partition field and aggregate gates
+ * @returns A fresh aggregate definition
+ *
+ * @example
+ * ```ts
+ * import { aggregateDefinition } from '@orkestrel/program'
+ *
+ * aggregateDefinition(['amount'], { by: 'location' })
+ * ```
+ */
+export declare function aggregateDefinition(fields: readonly FieldPath[], input?: AggregateInput): AggregateDefinition;
+
+/** One batch aggregate partition. */
+export declare interface AggregateGroup {
+    readonly key: string;
+    readonly count: number;
+    readonly sums: Readonly<Record<string, number>>;
+}
+
+/**
+ * Partition a batch of subjects by a field, summing aggregate fields per key.
+ *
+ * @remarks
+ * The partition key is derived by {@link formatGroupKey}. Group order follows
+ * first appearance in the subject array.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * import { aggregateGroups } from '@orkestrel/program'
+ *
+ * aggregateGroups([{ location: 'east', amount: 5 }], ['amount'], 'location')
+ * ```
+ */
+export declare function aggregateGroups(subjects: readonly Subject[], fields: readonly FieldPath[], by?: FieldPath): readonly AggregateGroup[];
+
+/**
+ * Optional fields accepted by `aggregateDefinition`.
+ *
+ * @remarks
+ * `by` — the partition key field; omitted skips partitioning. `gates` — a
+ * logical definition evaluated once over the whole batch to derive `limit`
+ * determinations.
+ */
+export declare interface AggregateInput {
+    readonly by?: FieldPath;
+    readonly gates?: LogicalDefinition;
+}
+
+/** One subject's private aggregate working projection. */
+export declare interface AggregateProjection {
+    readonly count: number;
+    readonly sums: Readonly<Record<string, number>>;
+    readonly group?: AggregateGroup;
+}
+
+/** A batch program outcome across every subject. */
+export declare interface AggregateResult {
+    readonly id: string;
+    readonly name: string;
+    readonly subjects: readonly ProgramResult[];
+    readonly determinations: readonly Determination[];
+    readonly groups: readonly AggregateGroup[];
+    readonly tallies: Readonly<Record<Status, Tally>>;
+    readonly count: number;
+    readonly sums: Readonly<Record<string, number>>;
+    readonly success: boolean;
+    readonly trace: readonly string[];
+    readonly errors: readonly string[];
+}
+
+/**
+ * Sum aggregate fields across a batch of subjects.
+ *
+ * @remarks
+ * A {@link FieldPath} may be nested — a nested path sums a nested subject field
+ * exactly like a top-level one, and `formatField` renders the dot-joined key the
+ * returned record is keyed by. Only finite numbers contribute; a non-numeric or
+ * absent value contributes zero (never a coercion).
+ *
+ * @param subjects - The batch of subjects
+ * @param fields - The fields to sum
+ * @returns A fresh record of dot-joined field to summed finite value
+ *
+ * @example
+ * ```ts
+ * import { aggregateSums } from '@orkestrel/program'
+ *
+ * aggregateSums([{ amount: 5 }, { amount: 3 }], ['amount']) // { amount: 8 }
+ * ```
+ */
+export declare function aggregateSums(subjects: readonly Subject[], fields: readonly FieldPath[]): Readonly<Record<string, number>>;
+
+/**
+ * Assert a program definition's always-on construction invariants — missing
+ * scope references and duplicate rating-line or notice ids.
+ *
+ * @remarks
+ * These checks run at construction regardless of `options.validate` (unlike
+ * {@link validateProgramDefinition}, the standalone report-shaped validator) —
+ * 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
+         *
+         * @example
+         * ```ts
+         * import { assertProgramDefinition } from '@orkestrel/program'
+         *
+         * assertProgramDefinition(definition) // does not throw
+         * ```
+         */
+     export declare function assertProgramDefinition(definition: ProgramDefinition): void;
+
+     /**
+      * Assert 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
+          *
+          * @example
+          * ```ts
+          * import { assertProgramSubject } from '@orkestrel/program'
+          *
+          * assertProgramSubject({ id: 'r1' }) // does not throw
+          * ```
+          */
+      export declare function assertProgramSubject(subject: unknown): asserts subject is Subject;
+
+      /**
+       * Build 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
+       * {@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
+       * @returns A fresh aggregate projection
+       *
+       * @example
+       * ```ts
+       * import { buildAggregateProjection } from '@orkestrel/program'
+       *
+       * buildAggregateProjection(subject, 2, { amount: 8 }, groups, 'location')
+       * ```
+       */
+      export declare function buildAggregateProjection(subject: Subject, count: number, sums: Readonly<Record<string, number>>, groups: readonly AggregateGroup[], by?: FieldPath): AggregateProjection;
+
+      /**
+       * Build the reserved-key record a batch aggregate-gate definition runs against.
+       *
+       * @remarks
+       * Unlike a per-subject {@link buildAggregateProjection}, the batch record carries
+       * every `group` (a `groups` array) under {@link AGGREGATE_KEY} so a gate rule can
+       * read `aggregate.sums.<field>` (overall) or a partition inside `aggregate.groups`.
+       *
+       * @param count - The whole-batch subject count
+       * @param sums - The whole-batch summed aggregate fields
+       * @param groups - The batch partitions
+       * @returns A fresh record carrying the batch aggregate under {@link AGGREGATE_KEY}
+       *
+       * @example
+       * ```ts
+       * import { buildAggregateRecord } from '@orkestrel/program'
+       *
+       * buildAggregateRecord(2, { amount: 8 }, [])
+       * ```
+       */
+      export declare function buildAggregateRecord(count: number, sums: Readonly<Record<string, number>>, groups: readonly AggregateGroup[]): Readonly<Record<string, unknown>>;
+
+      /**
+       * Assemble 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
+       * 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).
+       *
+       * @param definition - The authored program definition
+       * @param subjects - The per-subject program results, in input order
+       * @param determinations - The batch aggregate-gate `limit` determinations
+       * @param groups - The batch partitions
+       * @param tallies - The completed status tallies
+       * @param sums - The whole-batch summed aggregate fields
+       * @param options - Optional resolved aggregate-gate result
+       * @returns A fresh aggregate result
+       *
+       * @example
+       * ```ts
+       * import { buildAggregateResult } from '@orkestrel/program'
+       *
+       * buildAggregateResult(definition, subjects, [], [], tallies, { amount: 8 })
+       * ```
+       */
+      export declare function buildAggregateResult(definition: ProgramDefinition, subjects: readonly ProgramResult[], determinations: readonly Determination[], groups: readonly AggregateGroup[], tallies: Readonly<Record<Status, Tally>>, sums: Readonly<Record<string, number>>, options?: {
+          readonly gates?: LogicalResult;
+      }): AggregateResult;
+
+      /**
+       * Convert a logical result's applied rules into `limit` {@link Determination}s.
+       *
+       * @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
+       * 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
+       * fires produces no determination — program has no authored ruling map to keep
+       * evidence for.
+       *
+       * @param definition - The authority or aggregate-gate logical definition
+       * @param result - The evaluated logical result
+       * @param working - The working record the definition ran against
+       * @param evaluator - The shared reason check evaluator
+       * @param labels - Optional field-to-label overrides, keyed by dot-joined field
+       * @returns A fresh list of `limit` determinations
+       *
+       * @example
+       * ```ts
+       * import { buildLimits } from '@orkestrel/program'
+       *
+       * buildLimits(authority, resolved, outcome, evaluator)
+       * ```
+       */
+      export declare function buildLimits(definition: LogicalDefinition, result: LogicalResult, working: Readonly<Record<string, unknown>>, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>): readonly Determination[];
+
+      /**
+       * Resolve authored {@link Notice}s into unconditionally-applied `notice`
+       * {@link Determination}s.
+       *
+       * @remarks
+       * Notices are program output only — they never affect eligibility, status, line
+       * selection, or the decision. Each message interpolates against the original
+       * subject.
+       *
+       * @param notices - The authored notices
+       * @param subject - The original subject notices interpolate against
+       * @returns A fresh list of notice determinations
+       *
+       * @example
+       * ```ts
+       * import { buildNotices } from '@orkestrel/program'
+       *
+       * buildNotices([{ id: 'min', message: 'Minimum applies' }], { id: 'r1' })
+       * ```
+       */
+      export declare function buildNotices(notices: readonly Notice[], subject: Readonly<Record<string, unknown>>): readonly Determination[];
+
+      /**
+       * Build the private authority outcome projection from an assembled program result.
+       *
+       * @remarks
+       * The authority reads this record under {@link OUTCOME_KEY}; it never receives
+       * the mutable internal state of either sibling engine. `total` is carried from
+       * the nested rating result when rating occurred.
+       *
+       * @param result - The preliminary program result computed before authority runs
+       * @returns A record shaped for the authority's `outcome` projection
+       *
+       * @example
+       * ```ts
+       * import { buildOutcomeProjection } from '@orkestrel/program'
+       *
+       * buildOutcomeProjection(result) // { id, eligibility, status, rated, scopes }
+       * ```
+       */
+      export declare function buildOutcomeProjection(result: ProgramResult): Readonly<Record<string, unknown>>;
+
+      /**
+       * Assemble a {@link ProgramResult} from its qualification, rating, and
+       * determination parts — before or after authority.
+       *
+       * @remarks
+       * `eligibility` mirrors the qualification. `success` is execution integrity: the
+       * 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`),
+       * no `limit` determination applied, and status is not `unrated`.
+       *
+       * @param definition - The authored program definition
+       * @param qualification - The subject's qualification result
+       * @param rating - The subject's rating result, when rating occurred
+       * @param determinations - The program-scoped determinations (notices, then limits)
+       * @param status - The already-derived status
+       * @param options - Optional authority result driving the decision projection
+       * @returns A fresh program result
+       *
+       * @example
+       * ```ts
+       * import { buildProgramResult } from '@orkestrel/program'
+       *
+       * buildProgramResult(definition, qualification, rating, [], 'eligible')
+       * ```
+       */
+      export declare function buildProgramResult(definition: ProgramDefinition, qualification: QualificationResult, rating: RatingResult | undefined, determinations: readonly Determination[], status: Status, options?: {
+          readonly authority?: LogicalResult;
+      }): ProgramResult;
+
+      /**
+       * Add optional aggregate context to a private subject copy for qualification.
+       *
+       * @remarks
+       * The original subject is returned unchanged when no aggregate context exists.
+       * When context exists the helper creates a private copy under {@link AGGREGATE_KEY}
+       * and defensively copies every nested record — the rater still receives the
+       * original subject, never this copy.
+       *
+       * @param subject - The original caller subject
+       * @param aggregate - The subject's aggregate projection, when a batch supplies one
+       * @returns The subject, or a private copy carrying the aggregate projection
+       *
+       * @example
+       * ```ts
+       * import { buildQualificationSubject } from '@orkestrel/program'
+       *
+       * buildQualificationSubject({ id: 'r1' }) // { id: 'r1' }
+       * ```
+       */
+      export declare function buildQualificationSubject(subject: Subject, aggregate?: AggregateProjection): Subject;
+
+      /**
+       * Complete a partial status tally record with zero entries for every missing
+       * {@link Status}.
+       *
+       * @param entries - The partial tally entries to complete
+       * @returns A record with all five statuses present
+       *
+       * @example
+       * ```ts
+       * import { completeTallies } from '@orkestrel/program'
+       *
+       * completeTallies({ eligible: { count: 1, sums: {} } })
+       * ```
+       */
+      export declare function completeTallies(entries: Partial<Record<Status, Tally>>): Readonly<Record<Status, Tally>>;
+
+      /**
+       * 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
+       * ```
+       */
+      export declare function copyJSONValue(value: JSONValue): JSONValue;
+
+      /**
+       * Create one compiled program 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.
+       *
+       * @param definition - The authored program definition
+       * @param options - Optional injected qualifier, rater, engine, validation, labels, and emitter hooks
+       * @returns A {@link ProgramInterface}
+       *
+       * @example
+       * ```ts
+       * import { createProgram, programDefinition } from '@orkestrel/program'
+       *
+       * const program = createProgram(programDefinition('standard', 'Standard', qualification, rating))
+       * program.execute({ id: 'risk-1' })
+       * program.destroy()
+       * ```
+       */
+      export declare function createProgram(definition: ProgramDefinition, options?: ProgramOptions): ProgramInterface;
+
+      /**
+       * Create one ordered manager over compiled programs.
+       *
+       * @remarks
+       * Creates or borrows one shared reason engine, qualifier, and rater and injects
+       * them into every compiled program, so a batch of definitions shares one engine.
+       * Seed definitions are compiled in order.
+       *
+       * @param options - Optional injected qualifier, rater, engine, seed programs, validation, labels, and emitter hooks
+       * @returns A {@link ProgramManagerInterface}
+       *
+       * @example
+       * ```ts
+       * import { createProgramManager } from '@orkestrel/program'
+       *
+       * const manager = createProgramManager({ programs: [definition] })
+       * manager.program('standard')?.execute(subject)
+       * manager.destroy()
+       * ```
+       */
+      export declare function createProgramManager(options?: ProgramManagerOptions): ProgramManagerInterface;
+
+      /**
+       * Map a global {@link Eligibility} to its deterministic authority {@link Decision}.
+       *
+       * @param eligibility - The global eligibility
+       * @returns The matching decision
+       *
+       * @example
+       * ```ts
+       * import { decideEligibility } from '@orkestrel/program'
+       *
+       * decideEligibility('eligible') // 'approved'
+       * decideEligibility('referral') // 'submitted'
+       * ```
+       */
+      export declare function decideEligibility(eligibility: Eligibility): Decision;
+
+      /** A final authority outcome, derived from global eligibility. */
+      export declare type Decision = 'approved' | 'denied' | 'submitted';
+
+      /** Default definition validation policy for `createProgram` / `ProgramManager.add`. */
+      export declare const DEFAULT_PROGRAM_VALIDATE = true;
+
+      /**
+       * Derive 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
+       * 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
+       * `rating` the program is eligibility-only — status resolves to `conditional`
+       * or `eligible` and is NEVER `unrated`. Otherwise a subject with no successful
+       * rating is `unrated`.
+       *
+       * @param definition - The authored program definition
+       * @param qualification - The subject's qualification result
+       * @param rating - The subject's rating result, when rating occurred
+       * @returns The derived status
+       *
+       * @example
+       * ```ts
+       * import { deriveStatus } from '@orkestrel/program'
+       *
+       * deriveStatus(definition, qualification, rating) // 'eligible'
+       * ```
+       */
+      export declare function deriveStatus(definition: ProgramDefinition, qualification: QualificationResult, rating?: RatingResult): Status;
+
+      /** One resolved notice or authority-limit outcome. */
+      export declare interface Determination {
+          readonly id: string;
+          readonly effect: ProgramEffect;
+          readonly applied: boolean;
+          readonly scope?: string;
+          readonly message?: string;
+          readonly premises: readonly Premise[];
+      }
+
+      /** The deterministic authority decision for each global eligibility. */
+      export declare const ELIGIBILITY_DECISIONS: Readonly<Record<Eligibility, Decision>>;
+
+      /**
+       * Build 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'
+       *
+       * emptySums(['amount']) // { amount: 0 }
+       * ```
+       */
+      export declare function emptySums(fields: readonly FieldPath[]): Readonly<Record<string, number>>;
+
+      /**
+       * Build complete zero status tallies in {@link STATUS_PRECEDENCE} 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'
+       *
+       * emptyTallies(['amount'])
+       * ```
+       */
+      export declare function emptyTallies(fields: readonly FieldPath[]): Readonly<Record<Status, Tally>>;
+
+      /**
+       * Return authored scopes (qualification ruling scopes or notice scopes) that
+       * name no rating line on the program.
+       *
+       * @remarks
+       * A scope is an opaque string to the qualifier — program alone matches it to a
+       * rating-line id. A scope naming no line is a hard authoring error surfaced as
+       * {@link ProgramError} `'MISSING'` at construction, regardless of the validate
+       * option.
+       *
+       * @param definition - The program definition to check
+       * @returns A fresh, deduped list of missing scope references
+       *
+       * @example
+       * ```ts
+       * import { findMissingScopes } from '@orkestrel/program'
+       *
+       * findMissingScopes(definition) // []
+       * ```
+       */
+      export declare function findMissingScopes(definition: ProgramDefinition): readonly string[];
+
+      /**
+       * Coerce 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`
+       * collides with the string `'1'`.
+       *
+       * @param subject - The subject to key
+       * @param by - The partition key field
+       * @returns The subject's group key
+       *
+       * @example
+       * ```ts
+       * import { formatGroupKey } from '@orkestrel/program'
+       *
+       * formatGroupKey({ location: 'east' }, 'location') // 'east'
+       * ```
+       */
+      export declare function formatGroupKey(subject: Subject, by: FieldPath): string;
+
+      /**
+       * Determine whether a caller subject already carries a reserved program key.
+       *
+       * @remarks
+       * `aggregate` and `outcome` are program-private working-subject namespaces — the
+       * batch aggregate projection and the authority outcome projection are written
+       * under them. A caller subject that already owns either key would silently
+       * 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`
+       *
+       * @example
+       * ```ts
+       * import { hasReservedKey } from '@orkestrel/program'
+       *
+       * hasReservedKey({ id: 'r1' }) // false
+       * hasReservedKey({ id: 'r1', aggregate: {} }) // true
+       * ```
+       */
+      export declare function hasReservedKey(subject: Readonly<Record<string, unknown>>): boolean;
+
+      /**
+       * Determine whether a value is an exact {@link AggregateDefinition} record.
+       *
+       * @param value - The candidate value
+       * @returns `true` when `value` is an {@link AggregateDefinition}
+       *
+       * @example
+       * ```ts
+       * import { isAggregateDefinition } from '@orkestrel/program'
+       *
+       * isAggregateDefinition({ fields: ['amount'] }) // true
+       * ```
+       */
+      export declare function isAggregateDefinition(value: unknown): value is AggregateDefinition;
+
+      /**
+       * Determine whether a value is a {@link Decision} literal.
+       *
+       * @param value - The candidate value
+       * @returns `true` when `value` is a {@link Decision}
+       *
+       * @example
+       * ```ts
+       * import { isDecision } from '@orkestrel/program'
+       *
+       * isDecision('approved') // true
+       * ```
+       */
+      export declare const isDecision: Guard<Decision>;
+
+      /**
+       * Determine whether a value is an exact {@link Notice} record.
+       *
+       * @param value - The candidate value
+       * @returns `true` when `value` is a {@link Notice}
+       *
+       * @example
+       * ```ts
+       * import { isNotice } from '@orkestrel/program'
+       *
+       * isNotice({ id: 'minimum', message: 'Minimum applies' }) // true
+       * ```
+       */
+      export declare function isNotice(value: unknown): value is Notice;
+
+      /**
+       * Determine 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}
+       *
+       * @example
+       * ```ts
+       * import { isProgramDefinition } from '@orkestrel/program'
+       *
+       * isProgramDefinition({ id: 'p', name: 'P', qualification }) // true
+       * ```
+       */
+      export declare function isProgramDefinition(value: unknown): value is ProgramDefinition;
+
+      /**
+       * Determine whether a value is a {@link ProgramEffect} literal.
+       *
+       * @param value - The candidate value
+       * @returns `true` when `value` is a {@link ProgramEffect}
+       *
+       * @example
+       * ```ts
+       * import { isProgramEffect } from '@orkestrel/program'
+       *
+       * isProgramEffect('notice') // true
+       * ```
+       */
+      export declare const isProgramEffect: Guard<ProgramEffect>;
+
+      /** Narrow a caught value to a {@link ProgramError}. */
+      export declare function isProgramError(value: unknown): value is ProgramError;
+
+      /**
+       * Determine whether a value is a {@link Status} literal.
+       *
+       * @param value - The candidate value
+       * @returns `true` when `value` is a {@link Status}
+       *
+       * @example
+       * ```ts
+       * import { isStatus } from '@orkestrel/program'
+       *
+       * isStatus('eligible') // true
+       * ```
+       */
+      export declare const isStatus: Guard<Status>;
+
+      /** An authored, unconditional program notice. */
+      export declare interface Notice {
+          readonly id: string;
+          readonly message: string;
+          readonly scope?: string;
+      }
+
+      /**
+       * Build a {@link Notice}.
+       *
+       * @param id - The notice id
+       * @param message - The message template, carrying optional `{{token}}`s
+       * @param input - Optional presentation scope
+       * @returns A fresh notice
+       *
+       * @example
+       * ```ts
+       * import { noticeDefinition } from '@orkestrel/program'
+       *
+       * noticeDefinition('minimum', 'Minimum earned premium applies')
+       * ```
+       */
+      export declare function noticeDefinition(id: string, message: string, input?: NoticeInput): Notice;
+
+      /**
+       * Optional fields accepted by `noticeDefinition`.
+       *
+       * @remarks
+       * `scope` — the rating-line id the notice presents against; omitted for an
+       * unscoped, program-wide notice.
+       */
+      export declare interface NoticeInput {
+          readonly scope?: string;
+      }
+
+      /** The reserved working-subject key the authority's outcome projection is written under. */
+      export declare const OUTCOME_KEY = "outcome";
+
+      /**
+       * One compiled program — composes one qualifier and one rater over a shared
+       * reason engine and executes 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
+       * 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
+       * whatever the constructor had already allocated before throwing. `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 {
+          #private;
+          readonly id: string;
+          readonly name: string;
+          readonly definition: ProgramDefinition;
+          constructor(definition: ProgramDefinition, options?: ProgramOptions);
+          get emitter(): EmitterInterface<ProgramEventMap>;
+          execute(subjects: readonly Subject[]): AggregateResult;
+          execute(subject: Subject): ProgramResult;
+          validate(): ProgramValidationResult;
+          destroy(): void;
+      }
+
+      /**
+       * A pure authored program definition.
+       *
+       * @remarks
+       * `qualification` runs first through `@orkestrel/qualifier`; `rating` runs only
+       * 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
+       * 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`.
+       */
+      export declare interface ProgramDefinition {
+          readonly id: string;
+          readonly name: string;
+          readonly description?: string;
+          readonly qualification: QualificationDefinition;
+          readonly rating?: RatingDefinition;
+          readonly notices?: readonly Notice[];
+          readonly authority?: LogicalDefinition;
+          readonly aggregate?: AggregateDefinition;
+          readonly metadata?: JSONValue;
+      }
+
+      /**
+       * Build a {@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.
+       *
+       * @param id - The program id
+       * @param name - The display name
+       * @param qualification - The nested qualification definition
+       * @param rating - The nested rating definition; omit for an eligibility-only program
+       * @param input - Optional description, notices, authority, aggregate, and metadata
+       * @returns A fresh program definition
+       *
+       * @example
+       * ```ts
+       * import { programDefinition } from '@orkestrel/program'
+       *
+       * programDefinition('standard', 'Standard', qualification, rating, { notices: [notice] })
+       * ```
+       */
+      export declare function programDefinition(id: string, name: string, qualification: QualificationDefinition, rating?: RatingDefinition, input?: ProgramInput): ProgramDefinition;
+
+      /** A post-qualification program determination effect. */
+      export declare type ProgramEffect = 'notice' | 'limit';
+
+      /**
+       * A coded programmer error thrown by the program layer.
+       *
+       * @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.
+       * `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.
+       */
+      export declare class ProgramError extends Error {
+          readonly code: ProgramErrorCode;
+          readonly context?: unknown;
+          constructor(code: ProgramErrorCode, message: string, context?: unknown);
+      }
+
+      /** A coded {@link ProgramError} programmer-error code. */
+      export declare type ProgramErrorCode = 'DUPLICATE' | 'MISSING' | 'DEFINITION' | 'MISMATCH' | 'RESERVED' | 'DESTROYED';
+
+      /**
+       * The push observation surface of a {@link ProgramInterface} (AGENTS §13).
+       *
+       * @remarks
+       * `rate` fires only when at least one line was selected. `determine` fires once
+       * per notice, then once per applied limit. `decide` fires only when a decision
+       * was reached.
+       */
+      export declare type ProgramEventMap = {
+          readonly qualify: readonly [result: QualificationResult];
+          readonly rate: readonly [result: RatingResult];
+          readonly determine: readonly [result: Determination];
+          readonly decide: readonly [decision: Decision, result: ProgramResult];
+          readonly execute: readonly [result: ProgramResult];
+          readonly aggregate: readonly [result: AggregateResult];
+          readonly destroy: readonly [];
+      };
+
+      /**
+       * Optional fields accepted by `programDefinition`.
+       *
+       * @remarks
+       * `description` — a free-text summary. `notices` — authored unconditional
+       * notices. `authority` — a logical definition evaluated per subject to derive
+       * limit determinations and the decision. `aggregate` — batch aggregate fields,
+       * partition key, and gates. `metadata` — opaque caller data, copied fresh.
+       */
+      export declare interface ProgramInput {
+          readonly description?: string;
+          readonly notices?: readonly Notice[];
+          readonly authority?: LogicalDefinition;
+          readonly aggregate?: AggregateDefinition;
+          readonly metadata?: JSONValue;
+      }
+
+      /**
+       * One compiled program — composes one qualifier and one rater over a shared
+       * reason engine.
+       *
+       * @remarks
+       * The array-of-subjects `execute` overload is declared FIRST (AGENTS §9.2) so a
+       * subject list resolves to one aggregate-aware batch execution.
+       */
+      export declare interface ProgramInterface {
+          readonly id: string;
+          readonly name: string;
+          readonly definition: ProgramDefinition;
+          readonly emitter: EmitterInterface<ProgramEventMap>;
+          execute(subjects: readonly Subject[]): AggregateResult;
+          execute(subject: Subject): ProgramResult;
+          validate(): ProgramValidationResult;
+          destroy(): void;
+      }
+
+      /**
+       * An ordered manager over compiled {@link ProgramInterface}s (AGENTS §9), sharing
+       * one qualifier, rater, and reason engine across every program it compiles.
+       *
+       * @remarks
+       * 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.
+       * 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
+       * 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'`.
+       */
+      export declare class ProgramManager implements ProgramManagerInterface {
+          #private;
+          constructor(options?: ProgramManagerOptions);
+          get emitter(): EmitterInterface<ProgramManagerEventMap>;
+          get size(): number;
+          has(id: string): boolean;
+          program(id: string): ProgramInterface | undefined;
+          programs(): readonly ProgramInterface[];
+          add(definition: ProgramDefinition): ProgramInterface;
+          remove(ids: readonly string[]): boolean;
+          remove(id: string): boolean;
+          remove(): void;
+          destroy(): void;
+      }
+
+      /** The push observation surface of a {@link ProgramManagerInterface} (AGENTS §13). */
+      export declare type ProgramManagerEventMap = {
+          readonly add: readonly [id: string];
+          readonly remove: readonly [id: string];
+          readonly destroy: readonly [];
+      };
+
+      /** An ordered manager over compiled programs (AGENTS §9), sharing one qualifier and rater. */
+      export declare interface ProgramManagerInterface {
+          readonly emitter: EmitterInterface<ProgramManagerEventMap>;
+          readonly size: number;
+          has(id: string): boolean;
+          program(id: string): ProgramInterface | undefined;
+          programs(): readonly ProgramInterface[];
+          add(definition: ProgramDefinition): ProgramInterface;
+          remove(ids: readonly string[]): boolean;
+          remove(id: string): boolean;
+          remove(): void;
+          destroy(): void;
+      }
+
+      /**
+       * Options for `createProgramManager` / the `ProgramManager` constructor.
+       *
+       * @remarks
+       * `qualifier` — an injected, caller-owned qualifier; created and owned when
+       * omitted. `rater` — an injected, caller-owned rater; created and owned when
+       * omitted. `engine` — an injected, caller-owned reason engine; created and
+       * owned when omitted. `programs` — seed definitions compiled in order.
+       * `validate` — validate each seeded/added definition at construction (default
+       * {@link DEFAULT_PROGRAM_VALIDATE}). `labels` — field-to-label overrides for
+       * determination premises, keyed by dot-joined field. `on` — initial emitter
+       * hooks. `error` — the emitter's listener-error handler.
+       */
+      export declare interface ProgramManagerOptions {
+          readonly qualifier?: QualifierInterface;
+          readonly rater?: RaterInterface;
+          readonly engine?: ReasonInterface;
+          readonly programs?: readonly ProgramDefinition[];
+          readonly validate?: boolean;
+          readonly labels?: Readonly<Record<string, string>>;
+          readonly on?: EmitterHooks<ProgramManagerEventMap>;
+          readonly error?: EmitterErrorHandler;
+      }
+
+      /**
+       * Options for `createProgram` / the `Program` constructor.
+       *
+       * @remarks
+       * `qualifier` — an injected, caller-owned qualifier; created and owned by the
+       * program when omitted. `rater` — an injected, caller-owned rater; created and
+       * owned when omitted. `engine` — an injected, caller-owned reason engine;
+       * created and owned when omitted. `validate` — validate the definition at
+       * construction (default {@link DEFAULT_PROGRAM_VALIDATE}). `labels` —
+       * field-to-label overrides for determination premises, keyed by dot-joined
+       * field. `on` — initial emitter hooks. `error` — the emitter's listener-error
+       * handler.
+       */
+      export declare interface ProgramOptions {
+          readonly qualifier?: QualifierInterface;
+          readonly rater?: RaterInterface;
+          readonly engine?: ReasonInterface;
+          readonly validate?: boolean;
+          readonly labels?: Readonly<Record<string, string>>;
+          readonly on?: EmitterHooks<ProgramEventMap>;
+          readonly error?: EmitterErrorHandler;
+      }
+
+      /** One subject's complete program outcome. */
+      export declare interface ProgramResult {
+          readonly id: string;
+          readonly name: string;
+          readonly eligibility: Eligibility;
+          readonly status: Status;
+          /**
+           * @remarks
+           * 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`.
+           */
+          readonly decision?: Decision;
+          readonly qualification: QualificationResult;
+          readonly rating?: RatingResult;
+          readonly determinations: readonly Determination[];
+          readonly success: boolean;
+          readonly trace: readonly string[];
+          readonly errors: readonly string[];
+      }
+
+      /** Semantic definition validation. */
+      export declare interface ProgramValidationResult {
+          readonly valid: boolean;
+          readonly errors: readonly string[];
+          readonly warnings: readonly string[];
+      }
+
+      /**
+       * Select 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
+       * evaluated merely to discard its amount.
+       *
+       * @param lines - The program's authored rating lines
+       * @param scopes - The qualification's per-scope eligibility
+       * @returns The surviving line definitions, in authored order
+       *
+       * @example
+       * ```ts
+       * import { selectProgramLines } from '@orkestrel/program'
+       *
+       * selectProgramLines(lines, { wind: 'ineligible' }) // every line except 'wind'
+       * ```
+       */
+      export declare function selectProgramLines(lines: readonly LineDefinition[], scopes: Readonly<Record<string, Eligibility>>): readonly LineDefinition[];
+
+      /** The presentation and tally status derived from eligibility, conditions, and rating success. */
+      export declare type Status = 'ineligible' | 'referral' | 'conditional' | 'unrated' | 'eligible';
+
+      /** Status tally precedence order — least to most resolved. */
+      export declare const STATUS_PRECEDENCE: readonly Status[];
+
+      /**
+       * Fold one subject's finite aggregate field values into a sums record.
+       *
+       * @remarks
+       * 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.
+       *
+       * @param sums - The sums record to fold into
+       * @param subject - The subject to fold in
+       * @param fields - The fields to sum
+       * @returns A fresh sums record with `subject`'s contribution added
+       *
+       * @example
+       * ```ts
+       * import { sumFields } from '@orkestrel/program'
+       *
+       * sumFields({ amount: 0 }, { amount: 5 }, ['amount']) // { amount: 5 }
+       * ```
+       */
+      export declare function sumFields(sums: Readonly<Record<string, number>>, subject: Subject, fields: readonly FieldPath[]): Readonly<Record<string, number>>;
+
+      /** A status tally — a count plus summed aggregate fields. */
+      export declare interface Tally {
+          readonly count: number;
+          readonly sums: Readonly<Record<string, number>>;
+      }
+
+      /**
+       * Add 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)
+       * @param subject - The subject to fold in
+       * @param fields - The fields to sum
+       * @returns A fresh, complete tally record with the subject folded in
+       *
+       * @example
+       * ```ts
+       * import { tallyProgram } from '@orkestrel/program'
+       *
+       * tallyProgram(tallies, result, { id: 'r1', amount: 5 }, ['amount'])
+       * ```
+       */
+      export declare function tallyProgram(tallies: Readonly<Record<Status, Tally>>, result: ProgramResult, subject: Subject, fields: readonly FieldPath[]): Readonly<Record<Status, Tally>>;
+
+      /**
+       * Validate a program definition's shape, references, and nested definitions.
+       *
+       * @remarks
+       * The single semantic-validation implementation used by `Program.validate`. It
+       * establishes exact shape through {@link isProgramDefinition}, validates the
+       * rating structurally through the rater's {@link isRatingDefinition} guard (the
+       * rater exposes no `validate`), delegates qualification validation to the
+       * injected qualifier and authority / aggregate-gate validation to the shared
+       * reason engine, and checks scope, notice, and aggregate-field references here.
+       *
+       * @param definition - The program definition to validate
+       * @param qualifier - The qualifier that validates the nested qualification
+       * @param engine - The reason engine that validates authority and aggregate gates
+       * @returns A structured validation result
+       *
+       * @example
+       * ```ts
+       * import { validateProgramDefinition } from '@orkestrel/program'
+       *
+       * validateProgramDefinition(definition, qualifier, engine) // { valid: true, ... }
+       * ```
+       */
+      export declare function validateProgramDefinition(definition: ProgramDefinition, qualifier: QualifierInterface, engine: ReasonInterface): ProgramValidationResult;
+
+      export { }