@orkestrel/reason 0.0.9 → 0.0.10

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

@@ -1,8 +1,8 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { FieldPath } from '@orkestrel/contract';
-import { Guard } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { FieldPath } from '@orkestrel/contract';
+import type { Guard } from '@orkestrel/contract';
 
 /**
  * Upserts one entry of a {@link SymbolicDefinition}'s `variables`.
@@ -40,11 +40,11 @@ export declare type Aggregation = 'sum' | 'product' | 'average' | 'minimum' | 'm
  * reasoner's group and definition combiner.
  *
  * @remarks
- * TOTAL: never throws. Empty-input identities: `sum` / `average` → `0`,
+ * Total: never throws. Empty-input identities: `sum` / `average` → `0`,
  * `product` → `1`, `minimum` / `maximum` → `NaN` (the deliberate "no data"
- * signal). Weights are honored ONLY when their length matches `values` exactly
+ * signal). Weights are honored only when their length matches `values` exactly
  * (otherwise silently unweighted): a weight multiplies into a `sum`, acts as an
- * EXPONENT for a `product`, is the weight of a weighted mean for `average`
+ * exponent for a `product`, is the weight of a weighted mean for `average`
  * (a zero total weight yields `0`, never a division blow-up), and is ignored by
  * `minimum` / `maximum`. An unknown aggregation yields `0`. Stateless and
  * deterministic.
@@ -72,11 +72,15 @@ export declare const AGGREGATOR_ID = "aggregator";
  *
  * @remarks
  * Total: never throws. Empty-input identities: `sum` / `average` → `0`,
- * `product` → `1`, `minimum` / `maximum` → `NaN`. `weights` are honored ONLY
+ * `product` → `1`, `minimum` / `maximum` → `NaN`. `weights` are honored only
  * when their length matches `values` exactly (otherwise silently unweighted).
  */
 export declare interface AggregatorInterface {
     readonly id: string;
+    /**
+     * Reduces the values per aggregation; `weights` are honored only on an exact length match,
+     * and `minimum` / `maximum` ignore them.
+     */
     aggregate(values: readonly number[], aggregation: Aggregation, weights?: readonly number[]): number;
 }
 
@@ -92,15 +96,15 @@ export declare interface AggregatorOptions {
 
 /**
  * Inserts `item` into an id-keyed collection, deduping any existing element
- * sharing its id, then placing it at the END (or immediately AFTER `target`).
+ * sharing its id, then placing it at the end, or immediately after `target`.
  *
  * @remarks
- * Insertion DEDUPES on the id first: `filtered` is `items` with every `item.id`
+ * Insertion dedupes on the id first: `filtered` is `items` with every `item.id`
  * twin removed, because an input array may already carry same-id twins.
- * Re-appending an existing id therefore REPOSITIONS it rather than updating it
+ * Re-appending an existing id therefore repositions it rather than updating it
  * in place — {@link replaceById} is the position-preserving alternative. With
  * no `target`, `item` lands at the end; with a `target`, it lands immediately
- * after the element whose `id === target` (searched in the DEDUPED array). A
+ * after the element whose `id === target` (searched in the deduped array). A
  * `target` naming no element throws {@link ReasonError} (`'TARGET'`).
  *
  * @typeParam T - An id-carrying element type
@@ -127,8 +131,8 @@ export declare interface AggregatorOptions {
   * then-insert at the end, or immediately after `target`.
   *
   * @remarks
-  * Order is STRONGLY load-bearing: equations solve strictly in order and each
-  * rounded solution feeds forward.
+  * Order is load-bearing: equations solve strictly in order and each rounded
+  * solution feeds forward.
   *
   * @param definition - The definition to insert into
   * @param equation - The equation to insert
@@ -150,7 +154,7 @@ export declare interface AggregatorOptions {
    * insert at the end, or immediately after `target`.
    *
    * @remarks
-   * `Fact.id` is an AUTHORING label — the runtime content-dedups facts by
+   * `Fact.id` is an authoring label — the runtime content-dedups facts by
    * predicate+arity+terms ({@link factToKey}), independently of this helper's
    * id-keyed dedup.
    *
@@ -174,9 +178,9 @@ export declare interface AggregatorOptions {
     * at the end, or immediately after `target`.
     *
     * @remarks
-    * Factor order is LOAD-BEARING: the same-priority tiebreak is declaration
+    * Factor order is load-bearing: the same-priority tiebreak is declaration
     * order ({@link sortByPriority} is a stable ascending sort). Operates on the
-    * factor's DIRECT container — compose into a definition through
+    * factor's direct container — compose into a definition through
     * `appendGroup(def, appendFactor(group, factor))`.
     *
     * @param group - The group to insert into
@@ -199,7 +203,7 @@ export declare interface AggregatorOptions {
      * insert at the end, or immediately after `target`.
      *
      * @remarks
-     * Group order is COSMETIC (group aggregation is order-independent) but honored
+     * Group order is cosmetic (group aggregation is order-independent) but honored
      * uniformly, same as every `append*` helper. Composes with {@link appendFactor}:
      * `appendGroup(def, appendFactor(group, factor))`.
      *
@@ -223,7 +227,7 @@ export declare interface AggregatorOptions {
       * dedup-then-insert at the end, or immediately after `target`.
       *
       * @remarks
-      * Order is LOAD-BEARING: backward proving iterates in declaration order and
+      * Order is load-bearing: backward proving iterates in declaration order and
       * returns on first success.
       *
       * @param definition - The definition to insert into
@@ -249,7 +253,7 @@ export declare interface AggregatorOptions {
        * at the end, or immediately after `target`.
        *
        * @remarks
-       * Order is LOAD-BEARING: the forward conclusion is the LAST declared
+       * Order is load-bearing: the forward conclusion is the last declared
        * non-disabled rule, so `appendRule` without a `target` makes the new rule the
        * conclusion.
        *
@@ -277,7 +281,7 @@ export declare interface AggregatorOptions {
         * by zero is `NaN` (never a throw), the unary operations (`round` / `ceil` /
         * `floor` / `abs`) ignore `right`, and `percentage` is `left * (right / 100)`.
         * `operator` is typed `string` because untrusted definitions reach here
-        * unchecked; the ONE throwing path is the unknown-operator default, which
+        * unchecked; the only throwing path is the unknown-operator default, which
         * throws `ReasonError('OPERATOR', …, { operator })` and is caught per equation
         * upstream.
         *
@@ -301,7 +305,7 @@ export declare interface AggregatorOptions {
          * Upserts one field of a {@link Subject} — copy-on-write spread.
          *
          * @remarks
-         * Named `assignField` rather than `setField` because it RETURNS a fresh subject
+         * Named `assignField` rather than `setField` because it returns a fresh subject
          * instead of writing into the one it is given — `set*` reads as an in-place
          * write. Id-agnostic: overwrites an `id` key like any other field — id
          * protection is an entity's job, not this helper's.
@@ -371,7 +375,7 @@ export declare interface AggregatorOptions {
          * to `value` with `operator`.
          *
          * @remarks
-         * `field` follows the {@link FieldPath} idiom — a string is ONE key (never
+         * `field` follows the {@link FieldPath} idiom — a string is a single key (never
          * dot-split), an array descends into nested objects. `value` is unconstrained
          * (`unknown`): the operator decides what shapes are meaningful.
          */
@@ -386,7 +390,7 @@ export declare interface AggregatorOptions {
          *
          * @remarks
          * `actual` is the resolved subject value (possibly `undefined`); `error` is set
-         * ONLY when evaluation itself failed (an unknown operator) — a merely-unmet
+         * only when evaluation itself failed (an unknown operator) — a merely-unmet
          * check carries no `error`.
          */
         export declare interface CheckResult {
@@ -491,12 +495,12 @@ export declare interface AggregatorOptions {
          *
          * @remarks
          * `equals` / `not` — strict `===` / `!==` (no coercion). `above` / `below` /
-         * `from` / `to` — `>` / `<` / `>=` / `<=`, requiring numbers on BOTH sides
+         * `from` / `to` — `>` / `<` / `>=` / `<=`, requiring a number on each side
          * (anything else is not met). `any` / `none` — array membership / non-membership
-         * (a non-array expected value is not met for BOTH — `none` is not the raw
+         * (a non-array expected value is met by neither — `none` is not the raw
          * complement of `any` on malformed input). `between` / `outside` — inclusive
          * range test on the first two numeric elements of the expected array; `outside`
-         * IS the pure negation of `between`, so a malformed range is `outside`.
+         * is the pure negation of `between`, so a malformed range is `outside`.
          */
         export declare type Comparison = 'equals' | 'not' | 'above' | 'below' | 'from' | 'to' | 'any' | 'none' | 'between' | 'outside';
 
@@ -509,7 +513,7 @@ export declare interface AggregatorOptions {
 
         /**
          * Computes the confidence a set of matched premises contributes to a derived
-         * fact — the product of each premise's FIRST matching fact's confidence.
+         * fact — the product of each premise's first matching fact's confidence.
          *
          * @remarks
          * The confidence half of the inferential reasoner's forward derivation: each
@@ -541,7 +545,7 @@ export declare interface AggregatorOptions {
          * inferential chaining.
          *
          * @remarks
-         * Fixed — unlike {@link DEFAULT_PRECISION} it is NOT overridable per
+         * Fixed — unlike {@link DEFAULT_PRECISION} it is not overridable per
          * definition, so confidence products stay comparable across derivations.
          */
         export declare const CONFIDENCE_PRECISION = 4;
@@ -553,21 +557,21 @@ export declare interface AggregatorOptions {
         }
 
         /**
-         * Determines whether a symbolic expression contains an UNBOUND occurrence of a
+         * Determines whether a symbolic expression contains an unbound occurrence of a
          * target variable.
          *
          * @remarks
          * The variable-presence probe of the symbolic reasoner's isolation: a `variable`
-         * node matches only when its name is `target` AND `target` is not already in
+         * node matches only when its name is `target` and `target` is not already in
          * `bindings` (a pre-bound target is a known value, not an unknown to isolate); a
          * `constant` never matches; an `operation` recurses into both operands (the
-         * `right` operand may be absent on a unary node). The walk is an ITERATIVE
+         * `right` operand may be absent on a unary node). The walk is an iterative
          * worklist (never recursive) with short-circuit `true` on the first hit, so it
          * stays total on pathologically deep expression trees.
          *
          * @param expression - The expression to probe
          * @param target - The variable name being sought
-         * @param bindings - The known bindings (a bound target does NOT count as present)
+         * @param bindings - The known bindings (a bound target does not count as present)
          * @returns True if an unbound `target` occurs in the expression; false otherwise
          *
          * @example
@@ -620,7 +624,7 @@ export declare interface AggregatorOptions {
          * Creates a {@link Bounds} — an inclusive numeric clamp.
          *
          * @remarks
-         * Absent sides are OMITTED (never set to `undefined`) — an absent bound is
+         * Absent sides are omitted (never set to `undefined`) — an absent bound is
          * unbounded on that side.
          *
          * @param minimum - The inclusive lower bound
@@ -640,7 +644,7 @@ export declare interface AggregatorOptions {
         /**
          * Creates a {@link Check} — one field predicate.
          *
-         * @param field - The subject field to resolve (a string is ONE key; an array descends)
+         * @param field - The subject field to resolve (a string is a single key; an array descends)
          * @param operator - The comparison to apply
          * @param value - The expected value (any type — the operator decides what is meaningful)
          * @returns A fresh check
@@ -692,15 +696,14 @@ export declare interface AggregatorOptions {
          * `variables`, `facts`, and `inferences` self-owning manager properties.
          *
          * @remarks
-         * `id`. Default: `seed.id`. Each manager slot is BRING-YOUR-OWN (a supplied
-         * one is reused, else a fresh one is seeded from the seed's matching
-         * collection). `on` — initial event listeners. `error` — the emitter's
-         * listener-error handler. Mutate through the manager
-         * properties (`groups` / `factors` / `rules` / `equations` / `variables` /
-         * `facts` / `inferences`) and `merge` / `clear`, then call `build()` to produce
-         * a fresh, plain {@link Definition} snapshot.
-         *
-         * @param seed - The starting definition (any of the four reasoning kinds)
+         * `id`. Default: `seed.id`. Each manager slot takes the manager the caller
+         * supplies, or a fresh one seeded from the seed's matching collection. `on` —
+         * initial event listeners. `error` — the emitter's listener-error handler.
+         * Mutate through the manager properties (`groups` / `factors` / `rules` /
+         * `equations` / `variables` / `facts` / `inferences`) and `merge` / `clear`,
+         * then call `build()` to produce a fresh, plain {@link Definition} snapshot.
+         *
+         * @param seed - The starting definition, of any reasoning
          * @param options - Optional `id` override, manager injections, and emitter hooks
          * @returns A {@link DefinitionBuilderInterface}
          *
@@ -932,7 +935,7 @@ export declare interface AggregatorOptions {
          * `enabled` through `overrides`.
          *
          * @param id - The inference id
-         * @param premises - The fact patterns that must ALL unify
+         * @param premises - The fact patterns that must all unify
          * @param conclusion - The fact pattern derived when they do
          * @param overrides - Optional {@link Inference} fields merged over the defaults
          * @returns A fresh inference
@@ -1102,7 +1105,7 @@ export declare interface AggregatorOptions {
          * Creates an operation {@link SymbolicExpression} node.
          *
          * @remarks
-         * The `right` key is OMITTED when absent — correct for the unary operations
+         * The `right` key is omitted when absent — correct for the unary operations
          * (`round` / `ceil` / `floor` / `abs`); a binary operation with no `right`
          * treats it as the constant `0`.
          *
@@ -1213,7 +1216,7 @@ export declare interface AggregatorOptions {
          *
          * @remarks
          * `reasoners` — the initial registry (a later entry of the same reasoning
-         * replaces an earlier one; the orchestrator ships with NO defaults). `bail` —
+         * replaces an earlier one; the orchestrator ships with no defaults). `bail` —
          * `true` (the default) rethrows a reasoner throw after the `error` emit;
          * `false` converts it to a failure result. `validate` — validate every
          * definition before running it, throwing `INVALID` on failure (default
@@ -1223,16 +1226,32 @@ export declare interface AggregatorOptions {
          * @param options - Optional registry, policies, and emitter hooks
          * @returns A {@link ReasonInterface}
          *
-         * @example
+         * @example Create an orchestrator and score a subject
          * ```ts
-         * import { createLogicalReasoner, createQuantitativeReasoner, createReason } from '@src/core'
+         * import {
+         * 	createFactorGroup,
+         * 	createFieldFactor,
+         * 	createQuantitativeDefinition,
+         * 	createQuantitativeReasoner,
+         * 	createReason,
+         * 	createStaticFactor,
+         * } from '@orkestrel/reason'
          *
-         * const reason = createReason({
-         * 	reasoners: [createQuantitativeReasoner(), createLogicalReasoner()],
-         * 	on: { reason: (result) => console.log(result.success) },
-         * })
-         * const result = reason.reason({ age: 25 }, definition)
-         * reason.destroy()
+         * const reason = createReason({ reasoners: [createQuantitativeReasoner()] })
+         *
+         * const definition = createQuantitativeDefinition('risk', 'Risk score', [
+         * 	createFactorGroup('drivers', 'sum', [
+         * 		createFieldFactor('age', 'age'), // reads subject.age, parseNumber-coerced
+         * 		createStaticFactor('floor', 10), // a fixed contribution
+         * 	]),
+         * ])
+         *
+         * const result = reason.reason({ age: 25 }, definition) // one subject → one result
+         * if (result.reasoning === 'quantitative') result.value // 35 — narrow by the discriminant
+         * result.trace // the step-by-step account of how the value came to be
+         *
+         * reason.supports('quantitative') // true — a reasoner is registered for this reasoning
+         * reason.reasoner('quantitative')?.supports(definition) // the reasoner's own guard, same check
          * ```
          */
         export declare function createReason(options?: ReasonOptions): ReasonInterface;
@@ -1245,7 +1264,7 @@ export declare interface AggregatorOptions {
          * `enabled` through `overrides`.
          *
          * @param id - The rule id
-         * @param premises - The expressions that must ALL hold
+         * @param premises - The expressions that must all hold
          * @param conclusion - The expression whose atoms are asserted when they do
          * @param overrides - Optional {@link Rule} fields merged over the defaults
          * @returns A fresh rule
@@ -1322,8 +1341,8 @@ export declare interface AggregatorOptions {
          * {@link Subject}.
          *
          * @remarks
-         * `id`. Default: `seed.id`; OPTIONAL — when neither `options.id` nor
-         * a string `seed.id` is present the builder is ANONYMOUS (`.id` is
+         * `id`. Default: `seed.id`; it is optional — when neither `options.id` nor
+         * a string `seed.id` is present the builder is anonymous (`.id` is
          * `undefined`, `build()` emits no `id` key). `on` — initial event listeners.
          * `error` — the emitter's listener-error handler.
          * Mutate through `set` / `remove` / `merge` / `clear`, then call `build()` to
@@ -1396,7 +1415,7 @@ export declare interface AggregatorOptions {
          * Creates a {@link Transform} — one math step.
          *
          * @remarks
-         * The `operand` key is OMITTED when absent (never set to `undefined`), so the
+         * The `operand` key is omitted when absent (never set to `undefined`), so the
          * transform stays exact-record valid; the transformer then applies its
          * per-operation default (`1` for `multiply` / `divide` / `power`, `0` otherwise).
          *
@@ -1535,22 +1554,22 @@ export declare interface AggregatorOptions {
 
         /**
          * Implements a stateful workspace builder accumulating a {@link Definition}
-         * through always-present self-owning manager properties: a private SCALAR
-         * ENVELOPE (reasoning / id / name plus the kind's scalars) composed with each
+         * through always-present self-owning manager properties: a private scalar
+         * envelope (reasoning / id / name plus the kind's scalars) composed with each
          * collection read from its manager.
          *
          * @remarks
-         * Each manager is BRING-YOUR-OWN (a supplied one is reused) or a fresh one
-         * seeded from the seed's matching collection (empty for off-kind collections).
-         * Managers are KIND-FREE — an off-kind manager is ignored by `build()`,
-         * never a `MISMATCH`. `build()` is TOTAL, deterministic, and returns a FRESH
-         * plain {@link Definition} each call. `merge(incoming)` requires the SAME
+         * Each manager is the one the caller supplies, or a fresh one seeded from the
+         * seed's matching collection (empty for off-kind collections). Managers are
+         * kind-free — `build()` ignores an off-kind manager, never a `MISMATCH`.
+         * `build()` is total, deterministic, and returns a fresh plain
+         * {@link Definition} each call. `merge(incoming)` requires the same
          * `reasoning` (else `MISMATCH`) and distributes incoming scalars into the
          * envelope and collections into the managers through the matching `merge*`
          * helper. `clear(key)` deletes one optional field of the envelope for the
          * instance's `reasoning` (a non-clearable key throws `MISMATCH`). `destroy()`
          * cascades to every manager, emits `destroy`, then tears the builder emitter
-         * down LAST; it is idempotent, and post-destroy mutation / build throws
+         * down last; it is idempotent, and post-destroy mutation / build throws
          * `ReasonError('DESTROYED', …)`.
          *
          * @example
@@ -1618,17 +1637,17 @@ export declare interface AggregatorOptions {
          * envelope plus one manager per collection.
          *
          * @remarks
-         * `build()` is TOTAL, deterministic, and returns a FRESH plain
+         * `build()` is total, deterministic, and returns a fresh plain
          * {@link Definition} each call (the scalar envelope composed with the kind's
          * collections, read from the relevant managers' plural accessors — off-kind
-         * managers are ignored). `merge(incoming)` requires the SAME `reasoning`,
+         * managers are ignored). `merge(incoming)` requires the same `reasoning`,
          * distributes incoming scalars into the envelope and collections into the
          * managers through the matching `merge*` helper (a cross-reasoning `incoming`
          * throws `ReasonError('MISMATCH', …)`). `clear(key)` is the uniform
          * optional-key selector over the scalar envelope; a `key` that
          * is not a clearable optional field for the current kind throws
          * `ReasonError('MISMATCH', …, { key, reasoning })`. `destroy()` cascades to
-         * every manager, emits `destroy`, then tears the builder emitter down LAST;
+         * every manager, emits `destroy`, then tears the builder emitter down last;
          * it is idempotent, and post-destroy mutation / build throws
          * `ReasonError('DESTROYED', …)` — only the `emitter` / manager getters and
          * `destroy` keep working.
@@ -1645,9 +1664,25 @@ export declare interface AggregatorOptions {
             readonly variables: VariableManagerInterface;
             readonly facts: FactManagerInterface;
             readonly inferences: InferenceManagerInterface;
+            /**
+             * Returns a fresh plain `Definition` snapshot — the envelope plus the kind's managers —
+             * total and deterministic on every call.
+             */
             build(): Definition;
+            /**
+             * Reconciles with an incoming plain `Definition` of the same `reasoning`, distributing
+             * scalars into the envelope and collections into the managers.
+             */
             merge(incoming: Definition): void;
+            /**
+             * Deletes one optional envelope field for the instance's `reasoning`; a key the reasoning
+             * cannot clear throws `MISMATCH`.
+             */
             clear(key: string): void;
+            /**
+             * Tears the builder down idempotently — cascades `destroy` to every manager, then destroys
+             * the builder emitter last.
+             */
             destroy(): void;
         }
 
@@ -1656,10 +1691,9 @@ export declare interface AggregatorOptions {
          *
          * @remarks
          * `id` — overrides the seed definition's `id`. Default: `seed.id`. Every
-         * manager slot is BRING-YOUR-OWN — a supplied manager is reused,
-         * else one is constructed and seeded from the seed's matching collection. `on`
-         * — initial event listeners. `error` — the emitter's
-         * listener-error handler.
+         * manager slot takes the manager the caller supplies, or one constructed and
+         * seeded from the seed's matching collection. `on` — initial event listeners.
+         * `error` — the emitter's listener-error handler.
          */
         export declare interface DefinitionBuilderOptions {
             readonly id?: string;
@@ -1734,7 +1768,7 @@ export declare interface AggregatorOptions {
          * @remarks
          * This is the derivation-bookkeeping equality of the chaining reasoners: the
          * logical overlay and the inferential fact-dedupe compare with it so a
-         * NaN-valued conclusion or fact term derives exactly ONCE and the fixpoint
+         * NaN-valued conclusion or fact term derives exactly once and the fixpoint
          * converges (raw `===` would re-derive it every iteration, never converging).
          * It matches `Array.prototype.includes` semantics — the same membership test
          * the `any` / `none` comparisons use.
@@ -1776,17 +1810,17 @@ export declare interface AggregatorOptions {
          * kind-free manager over a symbolic definition's `equations`.
          *
          * @remarks
-         * OWNS its `equations` as a private {@link Collection} — copy-on-write state
+         * Owns its `equations` as a private {@link Collection} — copy-on-write state
          * shared by composition with the other list managers — plus its own
          * {@link Emitter} over {@link EquationManagerEventMap}. Equation order is
-         * STRONGLY load-bearing — equations solve strictly in order and each rounded
-         * solution feeds forward. `remove` is the batch family (array form declared
-         * FIRST): no argument removes every equation, one id removes that equation, an
+         * load-bearing — equations solve strictly in order and each rounded solution
+         * feeds forward. `remove` is the batch family (array form declared
+         * first): no argument removes every equation, one id removes that equation, an
          * id list removes those equations and returns true only when every named id
          * existed. It emits one `remove` per equation actually removed.
          * `seat` is the owning builder's silent bulk re-seat
          * channel (used by `merge`). `destroy()` is idempotent and tears the emitter
-         * down LAST; any other call after it throws `ReasonError('DESTROYED', …)`.
+         * down last; any other call after it throws `ReasonError('DESTROYED', …)`.
          *
          * @example
          * ```ts
@@ -1852,15 +1886,42 @@ export declare interface AggregatorOptions {
          */
         export declare interface EquationManagerInterface {
             readonly emitter: EmitterInterface<EquationManagerEventMap>;
+            /**
+             * Returns the one equation carrying an id, or `undefined` when none does.
+             */
             equation(id: string): Equation | undefined;
+            /**
+             * Lists every equation in solve order.
+             */
             equations(): readonly Equation[];
+            /**
+             * Inserts an equation at the end, or after `target`, removing a same-id equation first.
+             */
             append(equation: Equation, target?: string): void;
+            /**
+             * Inserts an equation at the start, or before `target`, removing a same-id equation first.
+             */
             prepend(equation: Equation, target?: string): void;
+            /**
+             * Swaps a same-id equation in place, appending it when the collection carries none.
+             */
             replace(equation: Equation): void;
+            /**
+             * Removes equations: every equation with no argument, one equation by id, or the equations
+             * an id list names; the id forms report whether every named id existed.
+             */
             remove(ids: readonly string[]): boolean;
             remove(id: string): boolean;
             remove(): void;
+            /**
+             * Replaces the whole collection in one silent call — the owning builder's bulk re-seat
+             * channel.
+             */
             seat(equations: readonly Equation[]): void;
+            /**
+             * Tears the manager down idempotently — emits the `destroy` event, then destroys the
+             * emitter last.
+             */
             destroy(): void;
         }
 
@@ -1882,14 +1943,14 @@ export declare interface AggregatorOptions {
          * quantitative and logical reasoners.
          *
          * @remarks
-         * TOTAL and strict: `evaluate` never throws (an unknown operator is caught and
+         * Total and strict: `evaluate` never throws (an unknown operator is caught and
          * surfaced as `CheckResult.error` with `met: false`) and never coerces —
          * `equals` / `not` are raw `===` / `!==`, the ordering operators demand numbers
-         * on BOTH sides, `any` / `none` demand an array expected value (a non-array is
-         * not met for either — `none` is NOT the raw complement of `any` on malformed
-         * input), while `outside` IS the pure negation of `between` (so a malformed
+         * on each side, `any` / `none` demand an array expected value (a non-array is
+         * not met for either — `none` is not the raw complement of `any` on malformed
+         * input), while `outside` is the pure negation of `between` (so a malformed
          * range is `outside`). Fields resolve through the core `resolveField` — a string
-         * is ONE key, an array descends. Stateless and deterministic.
+         * is a single key, an array descends. Stateless and deterministic.
          *
          * @example
          * ```ts
@@ -1921,7 +1982,14 @@ export declare interface AggregatorOptions {
          */
         export declare interface EvaluatorInterface {
             readonly id: string;
+            /**
+             * Resolves `check.field` from the subject and compares it; an unknown operator becomes an
+             * in-result `error`.
+             */
             evaluate(check: Check, subject: Subject): CheckResult;
+            /**
+             * Evaluates many checks positionally against one subject.
+             */
             batch(checks: readonly Check[], subject: Subject): readonly CheckResult[];
         }
 
@@ -1945,7 +2013,7 @@ export declare interface AggregatorOptions {
          * The shared atom-walk behind both {@link extractConclusions} and the raters'
          * conclusion merge: an `atom` yields itself; a compound flattens its operands in
          * authored order, so a later operand's atoms follow an earlier one's. The walk is
-         * an ITERATIVE explicit-stack traversal (never recursive), so it stays total on
+         * an iterative explicit-stack traversal (never recursive), so it stays total on
          * pathologically deep expression trees; a hole in an `operands` array is skipped,
          * matching `flatMap`'s hole-skipping behavior.
          *
@@ -1964,13 +2032,13 @@ export declare interface AggregatorOptions {
 
         /**
          * Flattens a logical conclusion expression into its asserted `field = value`
-         * pairs — connectives IGNORED.
+         * pairs, ignoring the connectives.
          *
          * @remarks
          * The conclusion-extraction step of the logical reasoner's chaining: every
          * `atom` inside the expression asserts its `formatField(check.field) =
          * check.value` pair, and compounds are walked without regard to the connective
-         * (an atom under `not` / `or` is asserted the same way). Later operands WIN on
+         * (an atom under `not` / `or` is asserted the same way). A later operand wins on
          * a key clash (`Object.assign` order). Recursion runs through this exported
          * function itself; the derived-overlay keys are `formatField` strings (an array
          * field path flattens to its dot-joined form).
@@ -2008,17 +2076,17 @@ export declare interface AggregatorOptions {
          * manager over an inferential definition's `facts`.
          *
          * @remarks
-         * OWNS its `facts` as a private {@link Collection} — copy-on-write state shared
+         * Owns its `facts` as a private {@link Collection} — copy-on-write state shared
          * by composition with the other list managers — plus its own {@link Emitter}
-         * over {@link FactManagerEventMap}. `Fact.id` is an AUTHORING label — the
+         * over {@link FactManagerEventMap}. `Fact.id` is an authoring label — the
          * runtime content-dedups facts by predicate+arity+terms, independently of this
          * manager's id-keyed dedup. `remove` is the batch family (array form declared
-         * FIRST): no argument removes every fact, one id removes that fact, an id list
+         * first): no argument removes every fact, one id removes that fact, an id list
          * removes those facts and returns true only when every named id existed. It
          * emits one `remove` per fact actually removed.
          * `seat` is the owning builder's silent bulk re-seat
          * channel (used by `merge`). `destroy()` is idempotent and tears the emitter
-         * down LAST; any other call after it throws `ReasonError('DESTROYED', …)`.
+         * down last; any other call after it throws `ReasonError('DESTROYED', …)`.
          *
          * @example
          * ```ts
@@ -2077,15 +2145,42 @@ export declare interface AggregatorOptions {
          */
         export declare interface FactManagerInterface {
             readonly emitter: EmitterInterface<FactManagerEventMap>;
+            /**
+             * Returns the one fact carrying an id, or `undefined` when none does.
+             */
             fact(id: string): Fact | undefined;
+            /**
+             * Lists every fact in order.
+             */
             facts(): readonly Fact[];
+            /**
+             * Inserts a fact at the end, or after `target`, removing a same-id fact first.
+             */
             append(fact: Fact, target?: string): void;
+            /**
+             * Inserts a fact at the start, or before `target`, removing a same-id fact first.
+             */
             prepend(fact: Fact, target?: string): void;
+            /**
+             * Swaps a same-id fact in place, appending it when the collection carries none.
+             */
             replace(fact: Fact): void;
+            /**
+             * Removes facts: every fact with no argument, one fact by id, or the facts an id list
+             * names; the id forms report whether every named id existed.
+             */
             remove(ids: readonly string[]): boolean;
             remove(id: string): boolean;
             remove(): void;
+            /**
+             * Replaces the whole collection in one silent call — the owning builder's bulk re-seat
+             * channel.
+             */
             seat(facts: readonly Fact[]): void;
+            /**
+             * Tears the manager down idempotently — emits the `destroy` event, then destroys the
+             * emitter last.
+             */
             destroy(): void;
         }
 
@@ -2106,13 +2201,13 @@ export declare interface AggregatorOptions {
          * Represents one scored input of a quantitative group.
          *
          * @remarks
-         * Evaluated as a pipeline: `checks` gate (ALL must be met) → `source` resolve
-         * (`fallback` when unresolvable) → finite check → `transforms` chain →
-         * `bounds` clamp → finite recheck. `weight` participates only at group
-         * aggregation. Default: `1`. `priority` orders evaluation ascending, stable.
-         * Default: `0`. `enabled: false` skips the factor entirely (omitted from
-         * results); `required: true` promotes a gate / resolution failure to a result
-         * error (making `success` false) without aborting the run.
+         * Evaluated as a pipeline: `checks` gate (every check must be met) →
+         * `source` resolve (`fallback` when unresolvable) → finite check →
+         * `transforms` chain → `bounds` clamp → finite recheck. `weight` participates
+         * only at group aggregation. Default: `1`. `priority` orders evaluation
+         * ascending, stable. Default: `0`. `enabled: false` skips the factor entirely
+         * (omitted from results); `required: true` promotes a gate / resolution failure
+         * to a result error (making `success` false) without aborting the run.
          */
         export declare interface Factor {
             readonly id: string;
@@ -2134,7 +2229,7 @@ export declare interface AggregatorOptions {
          *
          * @remarks
          * `base` is added before aggregation. Default: `0`.
-         * The group value is `base` plus the aggregation of its APPLIED
+         * The group value is `base` plus the aggregation of its applied
          * factors' values (with per-factor weights), clamped to `bounds` — never
          * rounded. `strict: true` makes the group all-or-nothing: if any evaluated
          * factor did not apply, the group contributes only its `base` and reports
@@ -2154,24 +2249,25 @@ export declare interface AggregatorOptions {
         }
 
         /**
-         * Implements the {@link FactorManagerInterface} — the sole DIVERGENT
-         * manager: factors nest inside groups, so it holds NO collection state of its
+         * Implements the {@link FactorManagerInterface} — the one divergent
+         * manager: factors nest inside groups, so it holds no collection state of its
          * own and threads a required `groupId` locator.
          *
          * @remarks
          * Constructor-injected with the sibling {@link GroupManagerInterface}: each
          * write verb reads the located group (`groups.group(groupId)`), applies the
-         * factor-level pure helper ({@link appendFactor} etc.), and writes the updated
+         * factor-level pure helper ({@link appendFactor}, {@link prependFactor},
+         * {@link replaceFactor}, or {@link removeFactor}), and writes the updated
          * group back through `groups.replace(…)`. A `groupId` naming no existing group
-         * throws `ReasonError('TARGET', …, { groupId })`. It still owns its OWN
+         * throws `ReasonError('TARGET', …, { groupId })`. It still owns its own
          * {@link Emitter} over {@link FactorManagerEventMap} (factor-id payloads).
          * `remove` is the batch family behind the leading `groupId` locator (array form
-         * declared FIRST): the locator alone removes every factor of that group, a
+         * declared first): the locator alone removes every factor of that group, a
          * further id removes that factor, a further id list removes those factors and
          * returns true only when every named id existed. It emits one `remove` per
          * factor actually removed, each paired with a `replace` on the sibling
          * `GroupManagerInterface` for the containing group.
-         * `destroy()` is idempotent and tears the emitter down LAST; any other call
+         * `destroy()` is idempotent and tears the emitter down last; any other call
          * after it throws `ReasonError('DESTROYED', …)`.
          *
          * @example
@@ -2231,12 +2327,12 @@ export declare interface AggregatorOptions {
          *
          * @remarks
          * Divergent from the other managers: factors nest inside groups, so this
-         * manager holds NO collection state of its own — it reads and writes through
+         * manager holds no collection state of its own — it reads and writes through
          * the sibling {@link GroupManagerInterface} (`groups.group(groupId)` then
          * `groups.replace(…)`). A `groupId` naming no existing group throws
          * `ReasonError('TARGET', …, { groupId })`. `append` / `prepend` additionally
          * take an optional `target` factor id (a naming miss throws
-         * `ReasonError('TARGET', …)`). It still owns its OWN emitter (factor-id
+         * `ReasonError('TARGET', …)`). It still owns its own emitter (factor-id
          * payloads). `remove` is the batch family behind the leading `groupId`
          * locator: the locator alone removes every factor of that group, a further id
          * removes that factor, a further id list removes those factors and returns
@@ -2246,14 +2342,41 @@ export declare interface AggregatorOptions {
          */
         export declare interface FactorManagerInterface {
             readonly emitter: EmitterInterface<FactorManagerEventMap>;
+            /**
+             * Returns the one factor of a named group carrying an id, or `undefined` when none does.
+             */
             factor(groupId: string, id: string): Factor | undefined;
+            /**
+             * Lists every factor of one named group in order.
+             */
             factors(groupId: string): readonly Factor[];
+            /**
+             * Inserts a factor into the named group at the end, or after `target`, removing a same-id
+             * factor first.
+             */
             append(groupId: string, factor: Factor, target?: string): void;
+            /**
+             * Inserts a factor into the named group at the start, or before `target`, removing a
+             * same-id factor first.
+             */
             prepend(groupId: string, factor: Factor, target?: string): void;
+            /**
+             * Swaps a same-id factor in place within the named group, appending it when the group
+             * carries none.
+             */
             replace(groupId: string, factor: Factor): void;
+            /**
+             * Removes factors of the named group: every factor with the locator alone, one factor by a
+             * further id, or the factors a further id list names; the id forms report whether every
+             * named id existed.
+             */
             remove(groupId: string, ids: readonly string[]): boolean;
             remove(groupId: string, id: string): boolean;
             remove(groupId: string): void;
+            /**
+             * Tears the manager down idempotently — emits the `destroy` event, then destroys the
+             * emitter last.
+             */
             destroy(): void;
         }
 
@@ -2300,7 +2423,7 @@ export declare interface AggregatorOptions {
          * @remarks
          * Keys both stored facts and premise patterns (both are `Fact`-shaped) for
          * {@link indexByArity}: `matchFacts` already rejects an arity mismatch, so
-         * narrowing a same-predicate bucket to same-predicate-AND-same-arity only
+         * narrowing a same-predicate bucket to one of the same predicate and arity only
          * excludes candidates that could never unify anyway. Only `predicate` — the
          * one free-form, adversary-controlled part — is length-prefixed
          * (`length + ':' + predicate`), mirroring {@link factToKey}'s framing so a
@@ -2323,14 +2446,14 @@ export declare interface AggregatorOptions {
 
         /**
          * Derives a fact's canonical dedup key — predicate + arity + per-term
-         * SameValueZero identity (confidence is NOT part of it).
+         * SameValueZero identity, with confidence excluded from it.
          *
          * @remarks
          * The dedup key of the inferential reasoner's forward fixpoint: two facts with
          * the same predicate, arity, and SameValueZero-equal terms share a key (so a
          * NaN-term fact derives once and ±0 collapse keeping the first), while
          * confidence never enters the key. Each part — the predicate, the stringified
-         * arity, and every {@link termToKey} — is LENGTH-PREFIXED (`length + ':' + part`)
+         * arity, and every {@link termToKey} — is length-prefixed (`length + ':' + part`)
          * before joining, so the delimiter can never be forged by an adversarial string
          * term embedding it: two distinct facts always produce distinct keys, even when
          * a term string contains the delimiter (an injective framing raw joining lacked).
@@ -2365,12 +2488,12 @@ export declare interface AggregatorOptions {
         }
 
         /**
-         * Collects the ids that appear MORE THAN ONCE in an id-carrying list — each
+         * Collects the ids that appear more than once in an id-carrying list — each
          * duplicated id reported once, in first-occurrence order.
          *
          * @remarks
          * The shared uniqueness scan behind every reasoner's `validate()` duplicate-id
-         * WARNINGS (rules, groups, factors, equations, inferences). Runtime stays
+         * warnings (rules, groups, factors, equations, inferences). Runtime stays
          * permissive about duplicates (first/last-wins artifacts) — this helper only
          * surfaces them.
          *
@@ -2394,13 +2517,13 @@ export declare interface AggregatorOptions {
          *
          * @remarks
          * The reported keys are the `formatField`-flattened overlay keys an array-path
-         * conclusion atom writes ANYWHERE among `rules` that an array-path premise atom
-         * also reads ANYWHERE among `rules`. The cross-rule authoring-time footgun
+         * conclusion atom writes anywhere among `rules` that an array-path premise atom
+         * also reads anywhere among `rules`. The cross-rule authoring-time footgun
          * probe behind `LogicalReasoner.validate`'s overlay-key-mismatch warning: a
-         * logical conclusion's derived overlay is a FLAT record keyed by
+         * logical conclusion's derived overlay is a flat record keyed by
          * `formatField(check.field)` — an array `FieldPath` dot-joins into one string
-         * key. A premise that reads the same field through a DOTTED-STRING path resolves
-         * that flat key correctly, but a premise that reads it through an ARRAY path
+         * key. A premise that reads the same field through a dotted-string path resolves
+         * that flat key correctly, but a premise that reads it through an array path
          * calls `resolveField`, which descends key-by-key into nesting the flat
          * overlay never created, so the chain silently fails to connect. Collects the
          * flattened keys of every array-path conclusion atom across `rules` (once
@@ -2458,7 +2581,7 @@ export declare interface AggregatorOptions {
          *
          * @remarks
          * Display-only: the joined form is how a field appears in traces and derived
-         * overlays; it is NOT re-parsed into a path (a string stays ONE key).
+         * overlays; it is never re-parsed into a path (a string stays a single key).
          *
          * @param field - The field path to format
          * @returns The display string
@@ -2476,16 +2599,16 @@ export declare interface AggregatorOptions {
          * manager over a quantitative definition's `groups`.
          *
          * @remarks
-         * OWNS its `groups` as a private {@link Collection} — copy-on-write state
+         * Owns its `groups` as a private {@link Collection} — copy-on-write state
          * shared by composition with the other list managers — plus its own
          * {@link Emitter} over {@link GroupManagerEventMap}. Every write verb delegates
-         * to the collection, then emits (the affected group id) AFTER the mutation.
-         * `remove` is the batch family (array form declared FIRST): no argument removes
+         * to the collection, then emits (the affected group id) after the mutation.
+         * `remove` is the batch family (array form declared first): no argument removes
          * every group, one id removes that group, an id list removes those groups and
          * returns true only when every named id existed. It emits one `remove` per
          * group actually removed.
          * `seat` is the owning builder's silent bulk re-seat channel (used by `merge`).
-         * `destroy()` is idempotent and tears the emitter down LAST; any other call
+         * `destroy()` is idempotent and tears the emitter down last; any other call
          * after it throws `ReasonError('DESTROYED', …)`.
          *
          * @example
@@ -2548,15 +2671,47 @@ export declare interface AggregatorOptions {
          */
         export declare interface GroupManagerInterface {
             readonly emitter: EmitterInterface<GroupManagerEventMap>;
+            /**
+             * Returns the one group carrying an id, or `undefined` when none does.
+             */
             group(id: string): FactorGroup | undefined;
+            /**
+             * Lists every group in order.
+             */
             groups(): readonly FactorGroup[];
+            /**
+             * Inserts a group at the end, or after `target`, removing a same-id group first; a `target`
+             * naming no group throws `TARGET`.
+             */
             append(group: FactorGroup, target?: string): void;
+            /**
+             * Inserts a group at the start, or before `target`, removing a same-id group first; a
+             * `target` naming no group throws `TARGET`.
+             */
             prepend(group: FactorGroup, target?: string): void;
+            /**
+             * Swaps a same-id group in place, appending it when the collection carries none.
+             */
             replace(group: FactorGroup): void;
+            /**
+             * Removes groups: every group with no argument, one group by id, or the groups an id list
+             * names; the id forms report whether every named id existed.
+             *
+             * @remarks
+             * Each removal emits one `remove` event carrying the group id.
+             */
             remove(ids: readonly string[]): boolean;
             remove(id: string): boolean;
             remove(): void;
+            /**
+             * Replaces the whole collection in one silent call — the owning builder's bulk re-seat
+             * channel.
+             */
             seat(groups: readonly FactorGroup[]): void;
+            /**
+             * Tears the manager down idempotently — emits the `destroy` event, then destroys the
+             * emitter last.
+             */
             destroy(): void;
         }
 
@@ -2578,9 +2733,9 @@ export declare interface AggregatorOptions {
          * results (disabled factors omitted entirely).
          *
          * @remarks
-         * An UNAPPLIED group's `value` may be non-finite (a `minimum` / `maximum`
+         * An unapplied group's `value` may be non-finite (a `minimum` / `maximum`
          * aggregation over zero applied factors is `base + NaN`) — it is excluded from
-         * the definition-level aggregation, so only an APPLIED non-finite value reaches
+         * the definition-level aggregation, so only an applied non-finite value reaches
          * the definition-level finite check.
          */
         export declare interface GroupResult {
@@ -2596,7 +2751,7 @@ export declare interface AggregatorOptions {
          * @remarks
          * The index behind the inferential reasoner's same-predicate-and-arity join
          * scans (`#findAllBindings` / `#calculatePremiseConfidence`): `matchFacts`
-         * already rejects a predicate OR arity mismatch, so restricting a premise's
+         * already rejects a predicate or an arity mismatch, so restricting a premise's
          * search to its own predicate+arity bucket changes nothing but the cost — the
          * surviving matches and their append order are identical to a predicate-only
          * index. Append order within a bucket is preserved, so a "first match wins"
@@ -2640,16 +2795,16 @@ export declare interface AggregatorOptions {
          * kind-free manager over an inferential definition's `inferences`.
          *
          * @remarks
-         * OWNS its `inferences` as a private {@link Collection} — copy-on-write state
+         * Owns its `inferences` as a private {@link Collection} — copy-on-write state
          * shared by composition with the other list managers — plus its own
          * {@link Emitter} over {@link InferenceManagerEventMap}. Inference order is
-         * LOAD-BEARING — backward proving iterates in declaration order and returns on
-         * first success. `remove` is the batch family (array form declared FIRST): no
+         * load-bearing — backward proving iterates in declaration order and returns on
+         * first success. `remove` is the batch family (array form declared first): no
          * argument removes every inference, one id removes that inference, an id list
          * removes those inferences and returns true only when every named id existed.
          * It emits one `remove` per inference actually removed.
          * `seat` is the owning builder's silent bulk re-seat channel
-         * (used by `merge`). `destroy()` is idempotent and tears the emitter down LAST;
+         * (used by `merge`). `destroy()` is idempotent and tears the emitter down last;
          * any other call after it throws `ReasonError('DESTROYED', …)`.
          *
          * @example
@@ -2721,15 +2876,43 @@ export declare interface AggregatorOptions {
          */
         export declare interface InferenceManagerInterface {
             readonly emitter: EmitterInterface<InferenceManagerEventMap>;
+            /**
+             * Returns the one inference carrying an id, or `undefined` when none does.
+             */
             inference(id: string): Inference | undefined;
+            /**
+             * Lists every inference in order.
+             */
             inferences(): readonly Inference[];
+            /**
+             * Inserts an inference at the end, or after `target`, removing a same-id inference first.
+             */
             append(inference: Inference, target?: string): void;
+            /**
+             * Inserts an inference at the start, or before `target`, removing a same-id inference
+             * first.
+             */
             prepend(inference: Inference, target?: string): void;
+            /**
+             * Swaps a same-id inference in place, appending it when the collection carries none.
+             */
             replace(inference: Inference): void;
+            /**
+             * Removes inferences: every inference with no argument, one inference by id, or the
+             * inferences an id list names; the id forms report whether every named id existed.
+             */
             remove(ids: readonly string[]): boolean;
             remove(id: string): boolean;
             remove(): void;
+            /**
+             * Replaces the whole collection in one silent call — the owning builder's bulk re-seat
+             * channel.
+             */
             seat(inferences: readonly Inference[]): void;
+            /**
+             * Tears the manager down idempotently — emits the `destroy` event, then destroys the
+             * emitter last.
+             */
             destroy(): void;
         }
 
@@ -2795,7 +2978,7 @@ export declare interface AggregatorOptions {
          *
          * @remarks
          * A string term starting with `?` is a unification variable — matching is
-         * positional and BIDIRECTIONAL (variables may sit in facts as well as
+         * positional and bidirectional (variables may sit in facts as well as
          * patterns), with binding consistency enforced within one match and across
          * premises through pre-instantiation. Scalar subject fields (except `id`;
          * `null` / `undefined` / objects / arrays skipped) inject as
@@ -2806,8 +2989,8 @@ export declare interface AggregatorOptions {
          * duplicate facts (same predicate, arity, and SameValueZero-equal terms — a
          * NaN term derives once and converges) are never re-derived. Backward chaining
          * proves each inference's conclusion in
-         * declaration order and RETURNS ON THE FIRST SUCCESS with one derived fact
-         * (confidence = the inference's own — premise confidences are NOT propagated)
+         * declaration order and returns on the first success with one derived fact
+         * (confidence = the inference's own — premise confidences are not propagated)
          * plus its {@link ProofNode} tree; recursion is guarded only by the depth cap.
          * Deriving nothing is still success. Nothing mutates its inputs; fully
          * deterministic.
@@ -2885,7 +3068,7 @@ export declare interface AggregatorOptions {
          * @remarks
          * The pattern-instantiation step of the inferential reasoner: a `'?'`-prefixed
          * string term that is present in `bindings` is replaced by its bound value;
-         * every other term (constants and UNBOUND variables alike) is kept verbatim. The
+         * every other term (constants and unbound variables alike) is kept verbatim. The
          * returned fact is a fresh copy (`{ ...fact, terms }`) — the input is never
          * mutated.
          *
@@ -2910,7 +3093,7 @@ export declare interface AggregatorOptions {
         export declare const INVERTIBLE_OPERATIONS: ReadonlySet<MathOperation>;
 
         /**
-         * Inverts a `x op right = value` step, solving for the LEFT operand `x`.
+         * Inverts a `x op right = value` step, solving for the left operand `x`.
          *
          * @remarks
          * The left-operand inverse of the symbolic reasoner's isolation: `add` inverts
@@ -2938,7 +3121,7 @@ export declare interface AggregatorOptions {
          export declare function invertLeft(operator: MathOperation, value: number, rightValue: number): number;
 
          /**
-          * Inverts a `left op x = value` step, solving for the RIGHT operand `x`.
+          * Inverts a `left op x = value` step, solving for the right operand `x`.
           *
           * @remarks
           * The right-operand inverse of the symbolic reasoner's isolation: `add` inverts
@@ -2968,7 +3151,7 @@ export declare interface AggregatorOptions {
            * Determines whether a value is an {@link Aggregation} literal.
            *
            * @param value - The value to test
-           * @returns True if `value` is one of the five aggregations; false otherwise
+           * @returns True if `value` names an aggregation; false otherwise
            *
            * @example
            * ```ts
@@ -3018,8 +3201,8 @@ export declare interface AggregatorOptions {
            * predicate.
            *
            * @remarks
-           * `value` may be ANYTHING (including `null` / `undefined`) but the key must be
-           * PRESENT — exact-record semantics reject a check that lost its `value` key.
+           * `value` may be anything (including `null` / `undefined`) but the key must be
+           * present — exact-record semantics reject a check that lost its `value` key.
            *
            * @param value - The value to test
            * @returns True if `value` is a well-formed check; false otherwise
@@ -3037,6 +3220,12 @@ export declare interface AggregatorOptions {
           /**
            * Determines whether a value is a {@link CheckResult}.
            *
+           * @remarks
+           * `actual` must be present and may hold anything, including `undefined` — the
+           * guard reads its presence, never its value. A result whose `actual` is
+           * `undefined` therefore does not survive a JSON round trip: `JSON.stringify`
+           * drops the key, and the parsed record is refused here.
+           *
            * @param value - The value to test
            * @returns True if every published check-result member is valid; false otherwise
            *
@@ -3054,7 +3243,7 @@ export declare interface AggregatorOptions {
            * Determines whether a value is a {@link Comparison} literal.
            *
            * @param value - The value to test
-           * @returns True if `value` is one of the ten comparison operators; false otherwise
+           * @returns True if `value` names a comparison operator; false otherwise
            *
            * @example
            * ```ts
@@ -3067,8 +3256,8 @@ export declare interface AggregatorOptions {
           export declare const isComparison: Guard<Comparison>;
 
           /**
-           * Determines whether a value is a {@link Definition} — any of the four
-           * definition shapes, discriminated by `reasoning`.
+           * Determines whether a value is a {@link Definition} — a quantitative, logical,
+           * symbolic, or inferential definition shape, discriminated by `reasoning`.
            *
            * @param value - The value to test
            * @returns True if `value` is a well-formed definition of any reasoning; false otherwise
@@ -3084,13 +3273,13 @@ export declare interface AggregatorOptions {
           export declare function isDefinition(value: unknown): value is Definition;
 
           /**
-           * Determines whether a value is a `DefinitionBuilder` ENTITY — the brand-guarded
+           * Determines whether a value is a `DefinitionBuilder` entity — the brand-guarded
            * stateful workspace, not the plain {@link Definition} data union.
            *
            * @remarks
            * A `unique symbol` brand check (`Reflect.get`): a plain subject
            * is an open record whose values may legally be functions, so a
-           * method-presence check (`typeof value.build === 'function'`) is FORGEABLE —
+           * method-presence check (`typeof value.build === 'function'`) is forgeable —
            * this guard is not. A module-owned `unique symbol` cannot be produced by
            * `JSON.parse` or written by any consumer that does not import
            * `DEFINITION_BUILDER_BRAND`, so plain data can never forge it. Total: a
@@ -3134,9 +3323,9 @@ export declare interface AggregatorOptions {
            * tree of atoms and compounds, discriminated by `form`.
            *
            * @remarks
-           * Recursive through `lazyOf` — recursion is STACK-BOUNDED, not
+           * Recursive through `lazyOf` — recursion is bounded by the stack, not
            * unbounded: nesting beyond the engine's stack budget (roughly 1000 levels)
-           * and cyclic input are CONTAINED as `false`, never a throw. Input past that
+           * and cyclic input are contained as `false`, never a throw. Input past that
            * bound is rejected, not validated.
            *
            * @param value - The value to test
@@ -3228,6 +3417,10 @@ export declare interface AggregatorOptions {
           /**
            * Determines whether a value is a {@link FactorResult}.
            *
+           * @remarks
+           * The optional `raw` and `checks` members are absent-or-valid: an absent key
+           * passes, a present key is checked in full.
+           *
            * @param value - The value to test
            * @returns True if every published factor-result member is valid; false otherwise
            *
@@ -3252,7 +3445,7 @@ export declare interface AggregatorOptions {
            * ```ts
            * import { isFieldPath } from '@src/core'
            *
-           * isFieldPath('age')               // true — ONE key (never dot-split)
+           * isFieldPath('age')               // true — a single key (never dot-split)
            * isFieldPath(['address', 'city']) // true — descends
            * isFieldPath(42)                  // false
            * ```
@@ -3378,7 +3571,7 @@ export declare interface AggregatorOptions {
            * Determines whether a value is a {@link LogicalOperator} literal.
            *
            * @param value - The value to test
-           * @returns True if `value` is one of the five logical connectives; false otherwise
+           * @returns True if `value` names a logical connective; false otherwise
            *
            * @example
            * ```ts
@@ -3533,7 +3726,7 @@ export declare interface AggregatorOptions {
            * Determines whether a value is a {@link Reasoning} literal.
            *
            * @param value - The value to test
-           * @returns True if `value` is one of the four reasoning strategies; false otherwise
+           * @returns True if `value` names a reasoning strategy; false otherwise
            *
            * @example
            * ```ts
@@ -3630,8 +3823,8 @@ export declare interface AggregatorOptions {
           export declare function isRuleResult(value: unknown): value is RuleResult;
 
           /**
-           * Determines whether a value is a {@link Source} — any of the four factor
-           * sources, discriminated by `origin`.
+           * Determines whether a value is a {@link Source} — a static, field, lookup, or
+           * range factor source, discriminated by `origin`.
            *
            * @param value - The value to test
            * @returns True if `value` is a well-formed static / field / lookup / range source; false otherwise
@@ -3648,12 +3841,12 @@ export declare interface AggregatorOptions {
           export declare function isSource(value: unknown): value is Source;
 
           /**
-           * Determines whether a value is a `SubjectBuilder` ENTITY — the brand-guarded
+           * Determines whether a value is a `SubjectBuilder` entity — the brand-guarded
            * stateful workspace, not the plain {@link Subject} data record.
            *
            * @remarks
            * A `unique symbol` brand check (`Reflect.get`), distinct from
-           * {@link isDefinitionBuilder} — the two entities can never match each other's
+           * {@link isDefinitionBuilder} — neither entity can ever match the other's
            * guard. Total: a non-object, a missing brand, or a hostile prototype all
            * return `false`, never throw.
            *
@@ -3711,9 +3904,9 @@ export declare interface AggregatorOptions {
            * `form`.
            *
            * @remarks
-           * Recursive through `lazyOf` — recursion is STACK-BOUNDED, not
+           * Recursive through `lazyOf` — recursion is bounded by the stack, not
            * unbounded: nesting beyond the engine's stack budget (roughly 1000 levels)
-           * and cyclic input are CONTAINED as `false`, never a throw. Input past that
+           * and cyclic input are contained as `false`, never a throw. Input past that
            * bound is rejected, not validated.
            *
            * @param value - The value to test
@@ -3733,7 +3926,7 @@ export declare interface AggregatorOptions {
            * Determines whether a value is a {@link SymbolicResult}.
            *
            * @remarks
-           * `solutions` is checked across its OWN string-named members, enumerable or
+           * `solutions` is checked across its own string-named members, enumerable or
            * not. Inherited members are deliberately unread: they belong to the
            * accepted-prototype property, not to the record this guard certifies.
            *
@@ -3822,18 +4015,18 @@ export declare interface AggregatorOptions {
            * @remarks
            * Forward chaining is a naive fixpoint capped at `depth` iterations: rules run
            * in ascending `priority` order each pass, and a firing rule's conclusion atoms
-           * become a derived overlay that SHADOWS same-named subject fields on later
+           * become a derived overlay that shadows same-named subject fields on later
            * passes (derived keys are `formatField(check.field)` strings). Convergence —
            * one full pass with no new derivation — appends a trace containing
            * `converged`. Final rule results re-evaluate against the settled overlay in
-           * ORIGINAL rule order (forward) / priority-sorted order (backward), and the
-           * overall `conclusion` is whether the LAST result applied. Backward chaining
-           * proves EVERY rule goal-first: an unmet premise triggers sub-goal search
+           * original rule order (forward) / priority-sorted order (backward), and the
+           * overall `conclusion` is whether the last result applied. Backward chaining
+           * proves every rule goal-first: an unmet premise triggers sub-goal search
            * through rules whose conclusion atoms assert the needed `field = value` pair,
            * guarded by a visited-rule set (cycle-safe) plus the depth cap; `not` succeeds
            * when its operand cannot be established (negation-as-failure) and `implies` is
-           * vacuously true on an unprovable antecedent. Expression evaluation is EAGER
-           * (no short-circuit); conclusion extraction IGNORES connectives — every atom
+           * vacuously true on an unprovable antecedent. Expression evaluation is eager
+           * (no short-circuit); conclusion extraction ignores connectives — every atom
            * inside a conclusion is asserted, even under `not` / `or`. Overlay bookkeeping
            * compares with SameValueZero (`equalValues`), so a NaN-valued conclusion
            * derives once and the fixpoint converges. Nothing mutates its inputs; fully
@@ -3885,7 +4078,7 @@ export declare interface AggregatorOptions {
            * Represents the outcome of logical reasoning.
            *
            * @remarks
-           * `conclusion` is the LAST evaluated rule's `applied` (`false` when no rule
+           * `conclusion` is the last evaluated rule's `applied` (`false` when no rule
            * was evaluated); `count` tallies the applied rules; disabled rules are
            * omitted from `rules` entirely.
            */
@@ -3904,9 +4097,9 @@ export declare interface AggregatorOptions {
            *
            * @remarks
            * A missing or `null` field takes the factor's `fallback` directly (never the
-           * `''` table key); a PRESENT value is stringified into a `table` key (a numeric
-           * `42` finds the key `'42'`, a real `''` value may hit a `''` key). Only OWN
-           * table keys hit — an absent or inherited key falls back.
+           * `''` table key); a present value is stringified into a `table` key (a numeric
+           * `42` finds the key `'42'`, a real `''` value may hit a `''` key). Only the
+           * table's own keys hit — an absent or inherited key falls back.
            */
           export declare interface LookupSource {
               readonly origin: 'lookup';
@@ -3919,7 +4112,7 @@ export declare interface AggregatorOptions {
            *
            * @remarks
            * The range test behind the `between` and `outside` `Comparison` operators: only
-           * the FIRST TWO elements of `range` are read, both ends are inclusive, and a
+           * the first two elements of `range` are read, each end is inclusive, and a
            * non-numeric `value`, a non-array `range`, a `range` shorter than two
            * elements, or a non-numeric bound all report `false`. `outside` is the pure
            * negation of this predicate, so a malformed range reads as outside.
@@ -3944,10 +4137,10 @@ export declare interface AggregatorOptions {
            *
            * @remarks
            * The bidirectional unification of the inferential reasoner: a `'?'`-prefixed
-           * string term on EITHER side (pattern or candidate) is a variable that binds to
+           * string term on either side (pattern or candidate) is a variable that binds to
            * the opposite term (the `'?'` prefix is kept in the binding key), while
            * consistency is enforced within the match — a variable seen twice must bind the
-           * SAME value (raw `!==`) or the whole match fails. A predicate mismatch or an
+           * same value (raw `!==`) or the whole match fails. A predicate mismatch or an
            * arity (term-count) mismatch fails immediately; non-variable terms must be
            * strictly (`===`) equal.
            *
@@ -3981,11 +4174,11 @@ export declare interface AggregatorOptions {
            *
            * @remarks
            * A Strategic-Merge-Patch-style id-keyed upsert:
-           * the result is ordered by `incoming`'s id order FIRST (each element resolved
+           * the result is ordered by `incoming`'s id order first (each element resolved
            * through `resolve` when its id also exists in `base`, defaulting to
-           * incoming-wins-wholesale), THEN the `base`-only survivors in `base`'s own
+           * incoming-wins-wholesale), then the `base`-only survivors in `base`'s own
            * order (retained, never deleted — merge is additive). Same-id twins within
-           * EITHER input are deduped to their first occurrence.
+           * either input are deduped to their first occurrence.
            *
            * @typeParam T - An id-carrying element type
            * @param base - The base collection
@@ -4009,7 +4202,7 @@ export declare interface AggregatorOptions {
            * Reconciles two {@link InferentialDefinition}s onto `base`'s id.
            *
            * @remarks
-           * The merge is ADDITIVE: a base-only inference or fact survives into the result
+           * The merge is additive: a base-only inference or fact survives into the result
            * and is never deleted, and a scalar absent from `incoming` keeps its base
            * value — merge never clears a field, which is what
            * {@link clearInferentialDefinition} is for. `inferences` and `facts` each
@@ -4035,7 +4228,7 @@ export declare interface AggregatorOptions {
            * Reconciles two {@link LogicalDefinition}s onto `base`'s id.
            *
            * @remarks
-           * The merge is ADDITIVE: a base-only rule survives into the result and is never
+           * The merge is additive: a base-only rule survives into the result and is never
            * deleted, and a scalar absent from `incoming` keeps its base value — merge
            * never clears a field, which is what {@link clearLogicalDefinition} is for.
            * `rules` merges through {@link mergeById} (incoming-wins-wholesale on a matched
@@ -4060,10 +4253,10 @@ export declare interface AggregatorOptions {
            * Reconciles two {@link QuantitativeDefinition}s onto `base`'s id.
            *
            * @remarks
-           * The merge is ADDITIVE: a base-only group survives into the result and is
+           * The merge is additive: a base-only group survives into the result and is
            * never deleted, and a scalar absent from `incoming` keeps its base value —
            * merge never clears a field, which is what {@link clearQuantitativeDefinition}
-           * is for. `groups` merges through {@link mergeById}; a matched (same-id) PAIR of
+           * is for. `groups` merges through {@link mergeById}; a matched (same-id) pair of
            * groups recurses one level deeper — their `factors` also merge through
            * `mergeById` — the one exception to incoming-wins-wholesale. Every other
            * scalar / value-object field is incoming-wins-when-present, else base kept.
@@ -4109,7 +4302,7 @@ export declare interface AggregatorOptions {
            * Reconciles two {@link SymbolicDefinition}s onto `base`'s id.
            *
            * @remarks
-           * The merge is ADDITIVE: a base-only equation or variable survives into the
+           * The merge is additive: a base-only equation or variable survives into the
            * result and is never deleted, and a scalar absent from `incoming` keeps its
            * base value — merge never clears a field, which is what
            * {@link clearSymbolicDefinition} is for. `equations` merges through
@@ -4153,8 +4346,8 @@ export declare interface AggregatorOptions {
            *
            * @remarks
            * The safe inverse of the builders: `parseJSONAs` composed with the data guard
-           * {@link isDefinition}. A built definition body IS the durable JSON payload —
-           * `JSON.stringify(definition)` round-trips through `parseDefinition`. Two
+           * {@link isDefinition}. A built definition body is the durable JSON payload —
+           * `JSON.stringify(definition)` round-trips through `parseDefinition`. The
            * authoring hazards: a required `Check.value: undefined` drops its key on
            * `JSON.stringify` (author `null` instead), and a `Fact.terms` element of
            * `undefined` serializes to `null` (terms must be JSON-safe scalars/strings).
@@ -4175,7 +4368,7 @@ export declare interface AggregatorOptions {
 
           /**
            * Inserts `item` into an id-keyed collection, deduping any existing element
-           * sharing its id, then placing it at the START (or immediately BEFORE `target`).
+           * sharing its id, then placing it at the start, or immediately before `target`.
            *
            * @remarks
            * Mirrors {@link appendById}'s dedup-then-insert semantics exactly, only the
@@ -4351,7 +4544,7 @@ export declare interface AggregatorOptions {
                   * @remarks
                   * `base` is added before aggregation. Default: `0`.
                   * The final value is `base` plus the aggregation of the applied
-                  * groups' values (NO weights at this level), clamped to `bounds`, then rounded
+                  * groups' values (no weights at this level), clamped to `bounds`, then rounded
                   * to `precision` decimal places. Default: `4`.
                   */
                  export declare interface QuantitativeDefinition {
@@ -4370,21 +4563,21 @@ export declare interface AggregatorOptions {
                   * Performs factor-based numeric scoring.
                   *
                   * @remarks
-                  * Each factor runs a fixed pipeline: checks gate (ALL met) → source resolve
-                  * (`fallback` when unresolvable) → finite check → transforms chain → bounds
-                  * clamp → finite recheck. Factors evaluate in stable ascending `priority`
+                  * Each factor runs a fixed pipeline: checks gate (every check met) → source
+                  * resolve (`fallback` when unresolvable) → finite check → transforms chain →
+                  * bounds clamp → finite recheck. Factors evaluate in stable ascending `priority`
                   * order; a `strict` group is all-or-nothing; a group's value is its `base` plus
-                  * the weighted aggregation of its APPLIED factors, clamped (never rounded); the
+                  * the weighted aggregation of its applied factors, clamped (never rounded); the
                   * definition's value is its `base` plus the unweighted aggregation of the
-                  * APPLIED groups' values, clamped, then rounded to `precision`. A
+                  * applied groups' values, clamped, then rounded to `precision`. A
                   * required-factor failure or non-finite value appends an error (`success:
                   * false`) without aborting — the numeric `value` is always computed. The
-                  * definition-level value is finite-checked AFTER rounding: a non-finite
+                  * definition-level value is finite-checked after rounding: a non-finite
                   * aggregate (a `minimum` / `maximum` over zero applied groups) appends an error
                   * while the `NaN` stays visible in `value`. Field sources coerce through the
                   * contracts `parseNumberField`: a non-finite subject number or a non-numeric
                   * string is unresolvable and takes the fallback path. Lookup sources read only
-                  * OWN table keys, and a missing / `null` field falls back directly. Nothing
+                  * the table's own keys, and a missing / `null` field falls back directly. Nothing
                   * mutates its inputs; fully deterministic.
                   *
                   * @example
@@ -4454,7 +4647,7 @@ export declare interface AggregatorOptions {
                   * Represents a factor source banding a numeric subject field through ordered ranges.
                   *
                   * @remarks
-                  * Ranges are scanned in order and the FIRST match wins. A range without
+                  * Ranges are scanned in order and the first match wins. A range without
                   * `bounds` matches anything (a catch-all); an absent bound side is open. No
                   * match falls back to the factor's `fallback`.
                   */
@@ -4469,16 +4662,16 @@ export declare interface AggregatorOptions {
                   * {@link ReasonerInterface}s.
                   *
                   * @remarks
-                  * Holds NO strategy-specific logic: dispatch is purely a registry lookup by
+                  * Holds no strategy-specific logic: dispatch is purely a registry lookup by
                   * `definition.reasoning` (one reasoner per reasoning; re-registration
                   * replaces). A missing reasoner throws `MISSING` and a pre-run validation
-                  * failure (when the `validate` option is on) throws `INVALID` — both BYPASS
-                  * `bail` and emit nothing. A reasoner throw emits `error` with the raw thrown
+                  * failure (when the `validate` option is on) throws `INVALID` — each bypasses
+                  * `bail` and emits nothing. A reasoner throw emits `error` with the raw thrown
                   * value, then rethrows under `bail: true` (the default) or converts to a
-                  * type-shaped failure result under `bail: false`; only SUCCESSFUL results emit
+                  * type-shaped failure result under `bail: false`; only a successful result emits
                   * `reason` (synchronously, before returning). The batch overload maps subjects
                   * in order (validation, when on, repeats per subject). `destroy()` clears the
-                  * registry, emits `destroy`, then destroys the emitter LAST and is
+                  * registry, emits `destroy`, then destroys the emitter last and is
                   * idempotent; every other method afterwards throws `DESTROYED` — only the
                   * {@link emitter} getter keeps working.
                   *
@@ -4529,7 +4722,7 @@ export declare interface AggregatorOptions {
                   *
                   * @remarks
                   * `reason` throws a `ReasonError` (`MISMATCH`) when handed a definition of a
-                  * different reasoning; every other malformation yields a failure RESULT, not a
+                  * different reasoning; every other malformation yields a failure result, not a
                   * throw — the runtime never assumes `validate` ran. `supports` / `validate` /
                   * `reason` each take plain data only — a {@link DefinitionBuilderInterface} /
                   * {@link SubjectBuilderInterface}'s `build()` output is passed instead, by the
@@ -4538,8 +4731,18 @@ export declare interface AggregatorOptions {
                  export declare interface ReasonerInterface {
                      readonly id: string;
                      readonly reasoning: Reasoning;
+                     /**
+                      * Reports whether the definition's `reasoning` equals this adapter's own.
+                      */
                      supports(definition: Definition): boolean;
+                     /**
+                      * Reports a definition's structural errors and soft warnings, evaluating nothing.
+                      */
                      validate(definition: Definition): ReasonValidationResult;
+                     /**
+                      * Evaluates one subject against a definition, throwing only `MISMATCH` for a wrong
+                      * reasoning — a malformed definition yields a failure result.
+                      */
                      reason(subject: Subject, definition: Definition): ReasonResult;
                  }
 
@@ -4592,11 +4795,12 @@ export declare interface AggregatorOptions {
                   *
                   * @remarks
                   * `register` fires when a reasoner is registered (carrying its reasoning);
-                  * `reason` fires once per SUCCESSFUL result, synchronously before it returns
+                  * `reason` fires once per successful result, synchronously before it returns
                   * (bail-suppressed failure results do not fire it); `error` fires with the raw
                   * thrown value when a reasoner throws (regardless of `bail`); `destroy` fires
                   * once on teardown. Listener isolation is the emitter's own — a throwing
-                  * listener routes to the `error` OPTION handler, never onto this map.
+                  * listener routes to the handler passed as the `error` option, never onto
+                  * this map.
                   */
                  export declare type ReasonEventMap = {
                      /** Fires when a reasoner is registered — carries its reasoning. */
@@ -4610,8 +4814,8 @@ export declare interface AggregatorOptions {
                  };
 
                  /**
-                  * Names the four reasoning strategies — the axis a {@link Definition} /
-                  * {@link ReasonResult} discriminates on.
+                  * Names the reasoning strategies — the axis a {@link Definition} and a
+                  * {@link ReasonResult} discriminate on.
                   *
                   * @remarks
                   * `quantitative` — factor-based numeric scoring. `logical` — rule-based boolean
@@ -4628,7 +4832,7 @@ export declare interface AggregatorOptions {
                   * @remarks
                   * Dispatch is purely by `definition.reasoning` registry lookup; a missing
                   * reasoner throws `MISSING` (never subject to `bail`, no `error` emit). The
-                  * batch `reason` overload maps subjects in order to an equal-length result
+                  * batch `reason` overload maps subjects in order onto an equal-length result
                   * array. After `destroy()` every method except the `emitter` getter and
                   * `destroy` itself throws `DESTROYED`. `reason` and `validate` each take
                   * plain data only — a {@link DefinitionBuilderInterface} /
@@ -4637,13 +4841,40 @@ export declare interface AggregatorOptions {
                   */
                  export declare interface ReasonInterface {
                      readonly emitter: EmitterInterface<ReasonEventMap>;
+                     /**
+                      * Dispatches one subject — or maps a subject array in order — to the registered reasoner.
+                      *
+                      * @remarks
+                      * A reasoning with no registered reasoner throws `MISSING`.
+                      */
                      reason(subjects: readonly Subject[], definition: Definition): readonly ReasonResult[];
                      reason(subject: Subject, definition: Definition): ReasonResult;
+                     /**
+                      * Registers a reasoner, replacing one already registered for the same reasoning, and emits
+                      * the `register` event.
+                      */
                      register(reasoner: ReasonerInterface): void;
+                     /**
+                      * Returns the one reasoner registered for a reasoning, or `undefined` when none is.
+                      */
                      reasoner(reasoning: Reasoning): ReasonerInterface | undefined;
+                     /**
+                      * Lists every registered reasoner as a fresh array.
+                      */
                      reasoners(): readonly ReasonerInterface[];
+                     /**
+                      * Reports whether a reasoner is registered for a reasoning.
+                      */
                      supports(reasoning: Reasoning): boolean;
+                     /**
+                      * Delegates validation to the registered reasoner — a missing reasoner is an invalid result
+                      * here rather than a throw.
+                      */
                      validate(definition: Definition): ReasonValidationResult;
+                     /**
+                      * Clears the registry, emits the `destroy` event, and destroys the emitter last; the call
+                      * is idempotent.
+                      */
                      destroy(): void;
                  }
 
@@ -4769,7 +5000,7 @@ export declare interface AggregatorOptions {
                   * Deletes one field of a {@link Subject} — destructure-rest omit.
                   *
                   * @remarks
-                  * The key is DELETED entirely (never set to `undefined`), keeping the result
+                  * The key is deleted entirely (never set to `undefined`), keeping the result
                   * exact-record valid. A no-op (fresh copy) when `key` is absent.
                   *
                   * @param subject - The subject to update
@@ -4843,7 +5074,7 @@ export declare interface AggregatorOptions {
                   * Removes one entry of a {@link SymbolicDefinition}'s `variables`.
                   *
                   * @remarks
-                  * The destructure-rest form OMITS the key entirely (never sets it to
+                  * The destructure-rest form omits the key entirely (never sets it to
                   * `undefined`), keeping the result exact-record valid. A no-op (fresh copy)
                   * when `name` is absent.
                   *
@@ -4867,8 +5098,8 @@ export declare interface AggregatorOptions {
                   * When `subject.id` is a string, each clone's id is minted
                   * `` `${baseId}-${index}` `` (index from `0`); with no string `id`, the clones
                   * pass through unchanged (still fresh copies). Pure and deterministic — the
-                  * same input always produces the same output (run-twice equality) — and does
-                  * NOT emit. `count <= 0` yields an empty array.
+                  * same input always produces the same output (run-twice equality) — and emits
+                  * nothing. `count <= 0` yields an empty array.
                   *
                   * @param subject - The subject to clone
                   * @param count - How many clones to produce
@@ -4885,7 +5116,7 @@ export declare interface AggregatorOptions {
                  export declare function repeatSubject(subject: Subject, count: number): readonly Subject[];
 
                  /**
-                  * Swaps the element sharing `item.id` IN PLACE, preserving its position.
+                  * Swaps the element sharing `item.id` in place, preserving its position.
                   *
                   * @remarks
                   * The position-preserving update primitive — unlike {@link appendById}, which
@@ -4910,8 +5141,8 @@ export declare interface AggregatorOptions {
                  }>(items: readonly T[], item: T): readonly T[];
 
                  /**
-                  * Swaps the equation sharing `equation.id` in a {@link SymbolicDefinition} IN
-                  * PLACE, preserving its position (appends when absent).
+                  * Swaps the equation sharing `equation.id` in a {@link SymbolicDefinition} in
+                  * place, preserving its position (appended when absent).
                   *
                   * @param definition - The definition to update
                   * @param equation - The replacement equation
@@ -4928,8 +5159,8 @@ export declare interface AggregatorOptions {
                  export declare function replaceEquation(definition: SymbolicDefinition, equation: Equation): SymbolicDefinition;
 
                  /**
-                  * Swaps the fact sharing `fact.id` in an {@link InferentialDefinition} IN
-                  * PLACE, preserving its position (appends when absent).
+                  * Swaps the fact sharing `fact.id` in an {@link InferentialDefinition} in
+                  * place, preserving its position (appended when absent).
                   *
                   * @param definition - The definition to update
                   * @param fact - The replacement fact
@@ -4946,8 +5177,8 @@ export declare interface AggregatorOptions {
                  export declare function replaceFact(definition: InferentialDefinition, fact: Fact): InferentialDefinition;
 
                  /**
-                  * Swaps the factor sharing `factor.id` in a {@link FactorGroup} IN PLACE,
-                  * preserving its position (appends when absent).
+                  * Swaps the factor sharing `factor.id` in a {@link FactorGroup} in place,
+                  * preserving its position (appended when absent).
                   *
                   * @param group - The group to update
                   * @param factor - The replacement factor
@@ -4964,8 +5195,8 @@ export declare interface AggregatorOptions {
                  export declare function replaceFactor(group: FactorGroup, factor: Factor): FactorGroup;
 
                  /**
-                  * Swaps the group sharing `group.id` in a {@link QuantitativeDefinition} IN
-                  * PLACE, preserving its position (appends when absent).
+                  * Swaps the group sharing `group.id` in a {@link QuantitativeDefinition} in
+                  * place, preserving its position (appended when absent).
                   *
                   * @param definition - The definition to update
                   * @param group - The replacement group
@@ -4983,7 +5214,7 @@ export declare interface AggregatorOptions {
 
                  /**
                   * Swaps the inference sharing `inference.id` in an {@link InferentialDefinition}
-                  * IN PLACE, preserving its position (appends when absent).
+                  * in place, preserving its position (appended when absent).
                   *
                   * @param definition - The definition to update
                   * @param inference - The replacement inference
@@ -5001,8 +5232,8 @@ export declare interface AggregatorOptions {
                  export declare function replaceInference(definition: InferentialDefinition, inference: Inference): InferentialDefinition;
 
                  /**
-                  * Swaps the rule sharing `rule.id` in a {@link LogicalDefinition} IN PLACE,
-                  * preserving its position (appends when absent).
+                  * Swaps the rule sharing `rule.id` in a {@link LogicalDefinition} in place,
+                  * preserving its position (appended when absent).
                   *
                   * @param definition - The definition to update
                   * @param rule - The replacement rule
@@ -5052,9 +5283,9 @@ export declare interface AggregatorOptions {
                   * source passes its value through; `field` and `range` coerce through the
                   * contracts `parseNumberField`, so a non-finite subject number or a
                   * non-numeric string is unresolvable and takes `fallback`; `lookup` reads only
-                  * OWN table keys, and a missing or `null` field takes `fallback` directly
+                  * the table's own keys, and a missing or `null` field takes `fallback` directly
                   * rather than letting a `''` key intercept absent data. A `range` scans its
-                  * bands in order and the FIRST match wins — a band without `bounds` is a
+                  * bands in order and the first match wins — a band without `bounds` is a
                   * catch-all and an absent bound side is open. A malformed factor carrying no
                   * source at all takes `fallback` rather than crashing.
                   *
@@ -5079,9 +5310,9 @@ export declare interface AggregatorOptions {
                   * @remarks
                   * `Math.round` semantics — halves round toward `+∞` (`2.5` → `3`, `-2.5` → `-2`).
                   * A negative precision rounds at whole-number scales (`-1` → tens, `-2` →
-                  * hundreds). An EXTREME precision whose scale factor overflows the double range
+                  * hundreds). A precision whose scale factor overflows the double range
                   * (`10^p` → `Infinity` at roughly `p > 308`, `0` at roughly `p < -323`) returns
-                  * the value UNCHANGED — passthrough, never `NaN`.
+                  * the value unchanged — passthrough, never `NaN`.
                   *
                   * @param value - The number to round
                   * @param precision - Decimal places to keep (defaults to `0`)
@@ -5100,13 +5331,13 @@ export declare interface AggregatorOptions {
                  export declare function roundTo(value: number, precision?: number): number;
 
                  /**
-                  * Represents one deduction rule: when ALL `premises` hold, the `conclusion`'s atoms are
+                  * Represents one deduction rule: when every premise holds, the `conclusion`'s atoms are
                   * asserted as derived facts.
                   *
                   * @remarks
                   * `priority` orders evaluation ascending, lower first. Default: `0`.
                   * `enabled: false` skips the rule (omitted from results). Conclusion extraction
-                  * ignores connectives — EVERY atom inside the conclusion is asserted as a
+                  * ignores connectives — every atom inside the conclusion is asserted as a
                   * `field = value` fact, even under `not` / `or`.
                   */
                  export declare interface Rule {
@@ -5124,17 +5355,17 @@ export declare interface AggregatorOptions {
                   * manager over a logical definition's `rules`.
                   *
                   * @remarks
-                  * OWNS its `rules` as a private {@link Collection} — copy-on-write state shared
+                  * Owns its `rules` as a private {@link Collection} — copy-on-write state shared
                   * by composition with the other list managers — plus its own {@link Emitter}
-                  * over {@link RuleManagerEventMap}. Rule order is LOAD-BEARING — the forward
-                  * conclusion is the LAST declared non-disabled rule, so `append` without a
+                  * over {@link RuleManagerEventMap}. Rule order is load-bearing — the forward
+                  * conclusion is the last declared non-disabled rule, so `append` without a
                   * `target` makes the new rule the conclusion. `remove` is the batch family
-                  * (array form declared FIRST): no argument removes every rule, one id removes
+                  * (array form declared first): no argument removes every rule, one id removes
                   * that rule, an id list removes those rules and returns true only when every
                   * named id existed. It emits one `remove` per rule actually removed. `seat` is
                   * the owning builder's
                   * silent bulk re-seat channel (used by `merge`). `destroy()` is idempotent and
-                  * tears the emitter down LAST; any other call after it throws
+                  * tears the emitter down last; any other call after it throws
                   * `ReasonError('DESTROYED', …)`.
                   *
                   * @example
@@ -5189,7 +5420,7 @@ export declare interface AggregatorOptions {
                   * `rules` — a self-owning, kind-free collection manager.
                   *
                   * @remarks
-                  * Rule order is load-bearing — the forward conclusion is the LAST declared
+                  * Rule order is load-bearing — the forward conclusion is the last declared
                   * non-disabled rule, so `append` without a `target` makes a new rule the
                   * conclusion. `remove` is the batch family: no argument removes every rule,
                   * one id removes that rule, an id list removes those rules and returns true
@@ -5198,15 +5429,43 @@ export declare interface AggregatorOptions {
                   */
                  export declare interface RuleManagerInterface {
                      readonly emitter: EmitterInterface<RuleManagerEventMap>;
+                     /**
+                      * Returns the one rule carrying an id, or `undefined` when none does.
+                      */
                      rule(id: string): Rule | undefined;
+                     /**
+                      * Lists every rule in order.
+                      */
                      rules(): readonly Rule[];
+                     /**
+                      * Inserts a rule at the end, or after `target`, removing a same-id rule first — an absent
+                      * `target` makes it the new forward conclusion.
+                      */
                      append(rule: Rule, target?: string): void;
+                     /**
+                      * Inserts a rule at the start, or before `target`, removing a same-id rule first.
+                      */
                      prepend(rule: Rule, target?: string): void;
+                     /**
+                      * Swaps a same-id rule in place, appending it when the collection carries none.
+                      */
                      replace(rule: Rule): void;
+                     /**
+                      * Removes rules: every rule with no argument, one rule by id, or the rules an id list
+                      * names; the id forms report whether every named id existed.
+                      */
                      remove(ids: readonly string[]): boolean;
                      remove(id: string): boolean;
                      remove(): void;
+                     /**
+                      * Replaces the whole collection in one silent call — the owning builder's bulk re-seat
+                      * channel.
+                      */
                      seat(rules: readonly Rule[]): void;
+                     /**
+                      * Tears the manager down idempotently — emits the `destroy` event, then destroys the
+                      * emitter last.
+                      */
                      destroy(): void;
                  }
 
@@ -5242,7 +5501,7 @@ export declare interface AggregatorOptions {
                   * @remarks
                   * The shared evaluation-order helper of the quantitative (factors) and logical
                   * (rules) reasoners: lower priorities run first, an absent `priority` defaults
-                  * to `0`, equal priorities keep DECLARATION order (stable), and the input array
+                  * to `0`, equal priorities keep declaration order (stable), and the input array
                   * is never mutated. An array hole, `null`, or other non-record entry is dropped
                   * rather than sorted — the output may be shorter than the input.
                   *
@@ -5261,7 +5520,7 @@ export declare interface AggregatorOptions {
                      readonly priority?: number;
                  }>(items: readonly T[]): readonly T[];
 
-                 /** Represents the four factor sources, discriminated by `origin`. */
+                 /** Represents a static, field, lookup, or range factor source, discriminated by `origin`. */
                  export declare type Source = StaticSource | FieldSource | LookupSource | RangeSource;
 
                  /** Represents a factor source yielding a fixed number. */
@@ -5282,8 +5541,8 @@ export declare interface AggregatorOptions {
                   *
                   * @remarks
                   * Only `isSubjectBuilder` (`validators.ts`) reads this key, through `Reflect.get`.
-                  * Distinct from {@link DEFINITION_BUILDER_BRAND}, so the two entities can never
-                  * match each other's guard.
+                  * Distinct from {@link DEFINITION_BUILDER_BRAND}, so neither entity can ever
+                  * match the other's guard.
                   */
                  export declare const SUBJECT_BUILDER_BRAND: unique symbol;
 
@@ -5292,27 +5551,26 @@ export declare interface AggregatorOptions {
                   * flat key-value collection, no managers.
                   *
                   * @remarks
-                  * `id` is OPTIONAL (`options?.id ?? seed.id`). When present, the builder is
+                  * `id` is optional (`options?.id ?? seed.id`). When present, the builder is
                   * id-ful: `build()` carries that `id` and `clear()` restores it. When absent,
-                  * the builder is ANONYMOUS —
-                  * `.id` is `undefined` and the accumulated subject carries no `id` key.
-                  * `field(key)` / `fields()` are the singular / plural accessor pair over
-                  * TOP-LEVEL keys only. `set(key, value)` delegates to `assignField`;
-                  * `set('id', …)` throws `ReasonError('MISMATCH', …)` — id is immutable through the entity,
-                  * id-ful or anonymous alike. `remove` is the batch family (array form
-                  * declared first): no argument removes every non-id field and emits one
-                  * `remove` per key in key order, one key removes that field, and a key list
-                  * removes those fields. Removing `'id'` through a keyed form throws the same
-                  * `MISMATCH` for the same reason. `merge(incoming)` delegates to `mergeSubjects`
-                  * (incoming-wins, base `id` preserved — plain {@link Subject} data only).
-                  * `clear()` removes every non-id field, restoring `{ id }` when id-ful or
-                  * an empty record when anonymous. `repeat(count)` returns `count`
-                  * deterministic minted-id clones as PLAIN payloads — a pure read that does
-                  * NOT emit. `build(): Subject` is total, deterministic, and returns a fresh
-                  * durable payload each call. Post-destroy mutation throws
+                  * the builder is anonymous — `.id` is `undefined` and the accumulated subject
+                  * carries no `id` key. `field(key)` / `fields()` are the singular / plural
+                  * accessor pair over top-level keys only. `set(key, value)` delegates to
+                  * `assignField`; setting `id` throws `ReasonError('MISMATCH', …)`, because the
+                  * id is immutable through the entity, id-ful or anonymous alike. `remove` is
+                  * the batch family (array form declared first): no argument removes every
+                  * non-id field and emits one `remove` per key in key order, one key removes
+                  * that field, and a key list removes those fields. Removing `'id'` through a
+                  * keyed form throws the same `MISMATCH` for the same reason. `merge(incoming)`
+                  * delegates to `mergeSubjects` (incoming-wins, base `id` preserved — plain
+                  * {@link Subject} data only). `clear()` removes every non-id field, restoring
+                  * `{ id }` when id-ful or an empty record when anonymous. `repeat(count)`
+                  * returns `count` deterministic minted-id clones as plain payloads — a pure
+                  * read that emits nothing. `build(): Subject` is total, deterministic, and
+                  * returns a fresh durable payload each call. Post-destroy mutation throws
                   * `ReasonError('DESTROYED', …)` — only the `emitter` getter and `destroy`
                   * itself keep working, mirroring `Reason`. `destroy()` is idempotent and
-                  * tears the emitter down LAST.
+                  * tears the emitter down last.
                   *
                   * @example
                   * ```ts
@@ -5321,7 +5579,7 @@ export declare interface AggregatorOptions {
                   * const applicant = createSubjectBuilder({ id: 'alice', age: 25 })
                   * applicant.set('region', 'CA')
                   * applicant.merge({ licensed: true, accidents: 0 }) // incoming wins, id kept
-                  * applicant.remove(['accidents']) // batch form first — true when ALL existed
+                  * applicant.remove(['accidents']) // batch form first — true when every key existed
                   * applicant.field('region') // 'CA'
                   * applicant.fields() // the live record
                   * applicant.repeat(2) // ids 'alice-0', 'alice-1'
@@ -5350,8 +5608,9 @@ export declare interface AggregatorOptions {
                  }
 
                  /**
-                  * Represents the push observation surface of a {@link SubjectBuilderInterface} — five
-                  * verb-named events, no generic `change` / `status`.
+                  * Represents the push observation surface of a {@link SubjectBuilderInterface} — the
+                  * verb-named `set`, `remove`, `merge`, `clear`, and `destroy` events, no generic
+                  * `change` / `status`.
                   */
                  export declare type SubjectBuilderEventMap = {
                      /** Fires when a field is upserted — carries its key and new value. */
@@ -5371,41 +5630,80 @@ export declare interface AggregatorOptions {
                   * flat key-value collection, no managers.
                   *
                   * @remarks
-                  * `id` is OPTIONAL on the entity (`options?.id ?? seed.id`). When present,
+                  * `id` is optional on the entity (`options?.id ?? seed.id`). When present,
                   * the builder is id-ful — `build()`'s output carries that `id` and `clear()`
-                  * restores it. When absent, the builder is ANONYMOUS — `.id` is `undefined`,
-                  * `build()`'s output carries NO `id` key, and `clear()` empties the record
+                  * restores it. When absent, the builder is anonymous — `.id` is `undefined`,
+                  * `build()`'s output carries no `id` key, and `clear()` empties the record
                   * entirely. `field` / `fields` are the singular / plural accessor pair over
-                  * TOP-LEVEL keys only. `set(key, value)` delegates to `assignField`;
-                  * `set('id', …)` throws — id is immutable through the entity, id-ful or
+                  * top-level keys only. `set(key, value)` delegates to `assignField`; setting
+                  * `id` throws, because the id is immutable through the entity, id-ful or
                   * anonymous alike. `remove` is the batch family: no argument removes every
                   * non-id field and emits one `remove` per key in the builder's key order, one
                   * key removes that field, and a key list removes those fields and returns true
-                  * only when every named key existed. The array form is declared FIRST.
+                  * only when every named key existed. The array form is declared first.
                   * `merge(incoming)` delegates to `mergeSubjects` (incoming-wins, base `id`
                   * preserved — plain {@link Subject} data only). `clear()` removes every
                   * non-id field. `repeat(count)` returns `count`
-                  * deterministic minted-id clones as PLAIN payloads — a pure read that does
-                  * NOT emit. `build(): Subject` is total, deterministic, and returns a fresh
+                  * deterministic minted-id clones as plain payloads — a pure read that emits
+                  * nothing. `build(): Subject` is total, deterministic, and returns a fresh
                   * durable payload each call — `fields()` returns the live record and `build()`
                   * returns a fresh copy of it. Post-destroy
                   * mutation throws `ReasonError('DESTROYED', …)`; `destroy()` is idempotent
-                  * and tears the emitter down LAST.
+                  * and tears the emitter down last.
                   */
                  export declare interface SubjectBuilderInterface {
                      readonly [SUBJECT_BUILDER_BRAND]: true;
                      readonly id: string | undefined;
                      readonly emitter: EmitterInterface<SubjectBuilderEventMap>;
+                     /**
+                      * Reads one top-level field by key.
+                      */
                      field(key: string): unknown;
+                     /**
+                      * Reads the whole current record live.
+                      */
                      fields(): Subject;
+                     /**
+                      * Upserts one field; setting `id` throws, because the id is immutable for an id-ful and
+                      * an anonymous builder alike.
+                      *
+                      * @remarks
+                      * The write goes through the exported `assignField` helper, so the builder and the pure
+                      * helper family agree on what a field write is.
+                      */
                      set(key: string, value: unknown): void;
+                     /**
+                      * Removes non-id fields: every field with no argument, one field by key, or the fields a
+                      * key list names; the keyed forms report whether every named key existed.
+                      *
+                      * @remarks
+                      * The no-argument form emits one `remove` event per key, in the builder's key order.
+                      */
                      remove(keys: readonly string[]): boolean;
                      remove(key: string): boolean;
                      remove(): void;
+                     /**
+                      * Reconciles with an incoming plain `Subject`; the incoming record wins and the base `id`
+                      * is kept.
+                      */
                      merge(incoming: Subject): void;
+                     /**
+                      * Removes every non-id field.
+                      */
                      clear(): void;
+                     /**
+                      * Produces `count` deterministic minted-id clones as plain payloads — a pure read that
+                      * emits nothing.
+                      */
                      repeat(count: number): readonly Subject[];
+                     /**
+                      * Returns a fresh durable payload snapshot of the current state — total and deterministic
+                      * on every call.
+                      */
                      build(): Subject;
+                     /**
+                      * Tears the builder down idempotently — destroys the emitter last.
+                      */
                      destroy(): void;
                  }
 
@@ -5413,9 +5711,9 @@ export declare interface AggregatorOptions {
                   * Configures `createSubjectBuilder` / the `SubjectBuilder` constructor.
                   *
                   * @remarks
-                  * `id` — overrides the seed subject's `id`. Default: `seed.id`. OPTIONAL
+                  * `id` — overrides the seed subject's `id`. Default: `seed.id`. It is optional
                   * — when neither `options.id` nor a string `seed.id` is present the builder
-                  * is ANONYMOUS (`.id` is `undefined`, `build()` emits no `id` key). `on` —
+                  * is anonymous (`.id` is `undefined`, `build()` emits no `id` key). `on` —
                   * initial event listeners. `error` — the emitter's listener-error handler.
                   */
                  export declare interface SubjectBuilderOptions {
@@ -5429,7 +5727,7 @@ export declare interface AggregatorOptions {
                   * inferential reasoner's subject-injection step.
                   *
                   * @remarks
-                  * Every own subject field EXCEPT `id` becomes a `has(key, value)` fact at full
+                  * Every own subject field except `id` becomes a `has(key, value)` fact at full
                   * `DEFAULT_CONFIDENCE`; `null` / `undefined` and any `object` (including arrays)
                   * value is skipped. The returned `trace` carries one line per injection plus a
                   * final count when at least one fact was produced, so no caller-owned
@@ -5463,9 +5761,9 @@ export declare interface AggregatorOptions {
                   * Defines equation-solving.
                   *
                   * @remarks
-                  * `variables` seeds the bindings; numeric subject fields OVERRIDE same-named
+                  * `variables` seeds the bindings; numeric subject fields override same-named
                   * variables. Equations solve strictly in order, each solution rounded to
-                  * `precision` decimal places BEFORE feeding forward into later equations.
+                  * `precision` decimal places before feeding forward into later equations.
                   * Default: `4`.
                   */
                  export declare interface SymbolicDefinition {
@@ -5487,16 +5785,16 @@ export declare interface AggregatorOptions {
                   * @remarks
                   * Bindings seed from `definition.variables`, then numeric subject fields (a
                   * finite number or a numeric string, coerced through the contracts
-                  * `parseNumber`) OVERRIDE same-named variables — the `id` field is skipped.
+                  * `parseNumber`) override same-named variables — the `id` field is skipped.
                   * Equations solve strictly in order: when the `target` is unbound and appears
-                  * on exactly ONE side, it is isolated by peeling invertible operations (`add` /
+                  * on exactly one side, it is isolated by peeling invertible operations (`add` /
                   * `subtract` / `multiply` / `divide`); a non-invertible operation, a target on
                   * both sides of an operation, or an unbound variable throws internally — the
-                  * throw is caught PER EQUATION and surfaced as a result error (`Equation
+                  * throw is caught per equation and surfaced as a result error (`Equation
                   * "<id>": <message>` plus a `FAILED` trace) while later equations still run.
                   * Inversion or division by zero yields `NaN`, caught by the non-finite check.
-                  * A solved value is rounded to `precision` BEFORE binding, so later equations
-                  * see the rounded value; `solutions` reads FINAL bindings keyed by each
+                  * A solved value is rounded to `precision` before binding, so later equations
+                  * see the rounded value; `solutions` reads the settled bindings keyed by each
                   * equation's target (a failed equation's target still appears when bound
                   * elsewhere). Nothing mutates its inputs; fully deterministic.
                   *
@@ -5561,9 +5859,9 @@ export declare interface AggregatorOptions {
                   * forward-chaining dedupe. Primitives (and `null`) key by value, typeof-prefixed
                   * so `1` (`number:1`) never collides with `'1'` (`string:1`); `-0` folds to `+0`
                   * (both `number:0`) and `NaN` is self-consistent (`number:NaN`), matching
-                  * SameValueZero. Objects and functions key by REFERENCE through `identities` — a
+                  * SameValueZero. Objects and functions key by reference through `identities` — a
                   * first sighting is assigned the map's current size as its id, so distinct
-                  * objects never collide and the SAME reference always reproduces its key.
+                  * objects never collide and the same reference always reproduces its key.
                   *
                   * @param term - The term to key
                   * @param identities - The caller-created reference-identity ledger, threaded across a dedupe pass (a newly seen object/function is registered in it)
@@ -5598,7 +5896,7 @@ export declare interface AggregatorOptions {
                   * per-factor pipeline stage.
                   *
                   * @remarks
-                  * TOTAL: never throws. Absent-`operand` defaults are operation-specific —
+                  * Total: never throws. Absent-`operand` defaults are operation-specific —
                   * identity-preserving `1` for `multiply` / `divide` / `power`, `0` for every
                   * other binary operation; `round` / `ceil` / `floor` / `abs` are unary and
                   * ignore the operand. `divide` by zero yields `NaN` (deliberately not JS's
@@ -5637,7 +5935,14 @@ export declare interface AggregatorOptions {
                   */
                  export declare interface TransformerInterface {
                      readonly id: string;
+                     /**
+                      * Applies one math step — an absent operand defaults to `1` for `multiply` / `divide` /
+                      * `power`, and to `0` otherwise.
+                      */
                      apply(value: number, transform: Transform): number;
+                     /**
+                      * Left-folds a transform list over the value; `NaN` flows through and no step is skipped.
+                      */
                      chain(value: number, transforms: readonly Transform[]): number;
                  }
 
@@ -5663,17 +5968,17 @@ export declare interface AggregatorOptions {
                   * unordered record.
                   *
                   * @remarks
-                  * OWNS its `#variables` record as private copy-on-write state and its own
+                  * Owns its `#variables` record as private copy-on-write state and its own
                   * {@link Emitter} over {@link VariableManagerEventMap}. The record has no
                   * placement, so only `add` / `remove` exist (no `append` / `prepend`): `add`
                   * upserts and emits `add(name)`, `remove` omits the key entirely (never sets
                   * `undefined`) and emits `remove(name)`. `remove` is the batch family over
-                  * NAMES (array form declared FIRST): no argument removes every variable, one
+                  * names (array form declared first): no argument removes every variable, one
                   * name removes that variable, a name list removes those variables and returns
                   * true only when every named variable existed. It emits one `remove` per
                   * variable actually removed. `seat` is the owning builder's silent
                   * bulk re-seat channel (used by `merge`). `destroy()` is idempotent and tears
-                  * the emitter down LAST; any other call after it throws
+                  * the emitter down last; any other call after it throws
                   * `ReasonError('DESTROYED', …)`.
                   *
                   * @example
@@ -5709,7 +6014,7 @@ export declare interface AggregatorOptions {
                   *
                   * @remarks
                   * `variables` is a name-keyed record with no placement, so the honest verbs
-                  * are `add` / `remove` — each carries the variable NAME.
+                  * are `add` / `remove` — each carries the variable name.
                   */
                  export declare type VariableManagerEventMap = {
                      /** Fires when a variable is upserted — carries its name. */
@@ -5726,7 +6031,7 @@ export declare interface AggregatorOptions {
                   * only write verbs (no placement). A self-owning, kind-free manager.
                   *
                   * @remarks
-                  * The record is keyed by NAME, so `remove`'s batch family is over names: no
+                  * The record is keyed by name, so `remove`'s batch family is over names: no
                   * argument removes every variable, one name removes that variable, a name list
                   * removes those variables and returns true only when every named variable
                   * existed. It emits one `remove` per variable actually removed — a name
@@ -5734,13 +6039,37 @@ export declare interface AggregatorOptions {
                   */
                  export declare interface VariableManagerInterface {
                      readonly emitter: EmitterInterface<VariableManagerEventMap>;
+                     /**
+                      * Returns the one variable's value carrying a name, or `undefined` when none does.
+                      */
                      variable(name: string): number | undefined;
+                     /**
+                      * Returns the whole name-keyed record.
+                      */
                      variables(): Readonly<Record<string, number>>;
+                     /**
+                      * Upserts one entry and emits the `add` event with the variable name.
+                      */
                      add(name: string, value: number): void;
+                     /**
+                      * Removes variables: every variable with no argument, one variable by name, or the
+                      * variables a name list names; the name forms report whether every named variable existed.
+                      *
+                      * @remarks
+                      * Each removal omits the key rather than setting it to `undefined`, and emits the `remove`
+                      * event carrying the variable name.
+                      */
                      remove(names: readonly string[]): boolean;
                      remove(name: string): boolean;
                      remove(): void;
+                     /**
+                      * Replaces the whole record in one silent call — the owning builder's bulk re-seat channel.
+                      */
                      seat(variables: Readonly<Record<string, number>>): void;
+                     /**
+                      * Tears the manager down idempotently — emits the `destroy` event, then destroys the
+                      * emitter last.
+                      */
                      destroy(): void;
                  }