@orkestrel/reason 0.0.9 → 0.0.10

package/dist/src/core/index.js

@@ -47,7 +47,7 @@ var DEFAULT_PRIORITY = 0;
 * 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.
 */
 var CONFIDENCE_PRECISION = 4;
@@ -93,8 +93,8 @@ var DEFINITION_BUILDER_BRAND = Symbol("reasons.definitionBuilder");
 *
 * @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.
 */
 var SUBJECT_BUILDER_BRAND = Symbol("reasons.subjectBuilder");
 //#endregion
@@ -151,7 +151,7 @@ function isReasonError(value) {
 * 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
@@ -196,7 +196,7 @@ var isMathOperation = literalOf("add", "subtract", "multiply", "divide", "percen
 * 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
@@ -211,7 +211,7 @@ var isAggregation = literalOf("sum", "product", "average", "minimum", "maximum")
 * 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
@@ -226,7 +226,7 @@ var isComparison = literalOf("equals", "not", "above", "below", "from", "to", "a
 * 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
@@ -248,7 +248,7 @@ var isLogicalOperator = literalOf("and", "or", "not", "implies", "xor");
 * ```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
 * ```
@@ -275,8 +275,8 @@ var isNumberRecord = whereOf(isRecord, (record) => Object.values(record).every(i
 * 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
@@ -360,8 +360,8 @@ function isFactorRange(value) {
 	}, ["bounds"])(value);
 }
 /**
-* 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
@@ -472,9 +472,9 @@ function isFactorGroup(value) {
 * 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
@@ -534,9 +534,9 @@ function isRule(value) {
 * `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
@@ -755,8 +755,8 @@ function isInferentialDefinition(value) {
 	}, ["description", "depth"])(value);
 }
 /**
-* 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
@@ -864,6 +864,12 @@ function isResultFact(value) {
 /**
 * 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
 *
@@ -885,6 +891,10 @@ function isCheckResult(value) {
 /**
 * 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
 *
@@ -1056,7 +1066,7 @@ function isLogicalResult(value) {
 * 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.
 *
@@ -1134,13 +1144,13 @@ function isReasonValidationResult(value) {
 	})(value);
 }
 /**
-* 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
@@ -1164,12 +1174,12 @@ function isDefinitionBuilder(value) {
 	return isObject(value) && Reflect.get(value, DEFINITION_BUILDER_BRAND) === true;
 }
 /**
-* 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.
 *
@@ -1197,7 +1207,7 @@ function isSubjectBuilder(value) {
 *
 * @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
@@ -1242,7 +1252,7 @@ function clamp(value, limit) {
 *
 * @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.
@@ -1306,9 +1316,9 @@ function emptyAggregate(aggregation) {
 * 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.
 *
@@ -1358,9 +1368,9 @@ function resolveSource(source, subject, fallback) {
 * @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`)
@@ -1388,7 +1398,7 @@ function roundTo(value, precision = 0) {
 * @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.
@@ -1415,7 +1425,7 @@ function equalValues(left, right) {
 * @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.
 *
@@ -1439,12 +1449,12 @@ function sortByPriority(items) {
 	return usable.sort((left, right) => (left.priority ?? 0) - (right.priority ?? 0));
 }
 /**
-* 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.
 *
@@ -1470,7 +1480,7 @@ function findDuplicates(items) {
 * @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
@@ -1499,7 +1509,7 @@ function factToArityKey(fact) {
 * @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"
@@ -1535,9 +1545,9 @@ function indexByArity(facts) {
 * 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)
@@ -1564,14 +1574,14 @@ function termToKey(term, identities) {
 }
 /**
 * 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).
@@ -1602,10 +1612,10 @@ function factToKey(fact, identities) {
 *
 * @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.
 *
@@ -1647,7 +1657,7 @@ function matchFacts(pattern, candidate) {
 * @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.
 *
@@ -1674,7 +1684,7 @@ function instantiateFact(fact, bindings) {
 }
 /**
 * 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
@@ -1715,7 +1725,7 @@ function computePremiseConfidence(premises, index, bindings) {
 * 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
@@ -1793,21 +1803,21 @@ function findUnboundVariables(inference) {
 	return unbound;
 }
 /**
-* 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
@@ -1833,7 +1843,7 @@ function containsVariable(expression, target, bindings) {
 	return false;
 }
 /**
-* 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
@@ -1868,7 +1878,7 @@ function invertLeft(operator, value, rightValue) {
 	}
 }
 /**
-* 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
@@ -1910,7 +1920,7 @@ function invertRight(operator, value, leftValue) {
 * 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.
 *
@@ -1981,7 +1991,7 @@ function resolveOperand(operation, operand) {
 * 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.
 *
@@ -2016,13 +2026,13 @@ function extractAtoms(expression) {
 }
 /**
 * 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).
@@ -2049,13 +2059,13 @@ function extractConclusions(expression) {
 *
 * @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
@@ -2197,15 +2207,15 @@ function definitionToEnvelope(definition) {
 }
 /**
 * 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
@@ -2240,7 +2250,7 @@ function appendById(items, item, target) {
 }
 /**
 * 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
@@ -2280,7 +2290,7 @@ function prependById(items, item, target) {
 	];
 }
 /**
-* 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
@@ -2337,11 +2347,11 @@ function removeById(items, id) {
 *
 * @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
@@ -2380,7 +2390,7 @@ function mergeById(base, incoming, resolve) {
 * 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))`.
 *
@@ -2427,8 +2437,8 @@ function prependGroup(definition, group, target) {
 	};
 }
 /**
-* 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
@@ -2475,9 +2485,9 @@ function removeGroup(definition, id) {
 * 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
@@ -2523,8 +2533,8 @@ function prependFactor(group, factor, target) {
 	};
 }
 /**
-* 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
@@ -2570,7 +2580,7 @@ function removeFactor(group, id) {
 * 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.
 *
@@ -2617,8 +2627,8 @@ function prependRule(definition, rule, target) {
 	};
 }
 /**
-* 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
@@ -2665,8 +2675,8 @@ function removeRule(definition, id) {
 * 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
@@ -2711,8 +2721,8 @@ function prependEquation(definition, equation, target) {
 	};
 }
 /**
-* 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
@@ -2786,7 +2796,7 @@ function addVariable(definition, name, value) {
 * 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.
 *
@@ -2813,7 +2823,7 @@ function removeVariable(definition, name) {
 * 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.
 *
@@ -2860,8 +2870,8 @@ function prependFact(definition, fact, target) {
 	};
 }
 /**
-* 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
@@ -2908,7 +2918,7 @@ function removeFact(definition, id) {
 * 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
@@ -2961,7 +2971,7 @@ function prependInference(definition, inference, target) {
 }
 /**
 * 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
@@ -3008,10 +3018,10 @@ function removeInference(definition, id) {
 * 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.
@@ -3049,7 +3059,7 @@ function mergeQuantitativeDefinition(base, incoming) {
 * 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
@@ -3082,7 +3092,7 @@ function mergeLogicalDefinition(base, incoming) {
 * 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
@@ -3122,7 +3132,7 @@ function mergeSymbolicDefinition(base, incoming) {
 * 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
@@ -3233,7 +3243,7 @@ function clearInferentialDefinition(definition, key) {
 * 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.
@@ -3260,7 +3270,7 @@ function assignField(subject, key, value) {
 * 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
@@ -3315,8 +3325,8 @@ function mergeSubjects(base, incoming) {
 * 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
@@ -3346,8 +3356,8 @@ function repeatSubject(subject, count) {
 *
 * @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).
@@ -3374,16 +3384,16 @@ function parseDefinition(json) {
 * {@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.
 *
@@ -3502,14 +3512,14 @@ var Reason = class {
 * 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
@@ -3573,7 +3583,7 @@ var Evaluator = class {
 * 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
@@ -3613,11 +3623,11 @@ var Transformer = class {
 * 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.
@@ -3663,21 +3673,21 @@ var Aggregator = class {
 * 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
@@ -3909,18 +3919,18 @@ var QuantitativeReasoner = class {
 * @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
@@ -4253,16 +4263,16 @@ var LogicalReasoner = class {
 * @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.
 *
@@ -4455,7 +4465,7 @@ var SymbolicReasoner = class {
 *
 * @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
@@ -4466,8 +4476,8 @@ var SymbolicReasoner = class {
 * 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.
@@ -4799,17 +4809,17 @@ var Collection = class {
 * 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
@@ -4892,17 +4902,17 @@ var EquationManager = class {
 * 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
@@ -4976,24 +4986,25 @@ var FactManager = class {
 //#endregion
 //#region src/core/builders/managers/FactorManager.ts
 /**
-* 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
@@ -5092,16 +5103,16 @@ var FactorManager = class {
 * 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
@@ -5180,16 +5191,16 @@ var GroupManager = class {
 * 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
@@ -5278,17 +5289,17 @@ var InferenceManager = class {
 * 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
@@ -5370,17 +5381,17 @@ var RuleManager = class {
 * 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
@@ -5461,22 +5472,22 @@ var VariableManager = class {
 //#region src/core/builders/DefinitionBuilder.ts
 /**
 * 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
@@ -5658,27 +5669,26 @@ var DefinitionBuilder = class {
 * 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
@@ -5687,7 +5697,7 @@ var DefinitionBuilder = class {
 * 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'
@@ -5956,7 +5966,7 @@ function createInferentialReasoner(options) {
 *
 * @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
@@ -5966,16 +5976,32 @@ function createInferentialReasoner(options) {
 * @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
 * ```
 */
 function createReason(options) {
@@ -5987,15 +6013,14 @@ function createReason(options) {
 * `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}
 *
@@ -6017,8 +6042,8 @@ function createDefinitionBuilder(seed, options) {
 * {@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
@@ -6202,7 +6227,7 @@ function createInferenceManager(options) {
 /**
 * 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
@@ -6272,7 +6297,7 @@ function createCompound(operator, operands) {
 * `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
@@ -6297,7 +6322,7 @@ function createRule(id, premises, conclusion, overrides) {
 * 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).
 *
@@ -6323,7 +6348,7 @@ function createTransform(operator, operand) {
 * 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
@@ -6386,7 +6411,7 @@ function createConstant(value) {
 * 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`.
 *
@@ -6483,7 +6508,7 @@ function createFact(id, predicate, terms, confidence) {
 * `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