@orkestrel/reason 0.0.1

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

@@ -0,0 +1,4852 @@
+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';
+
+/**
+ * Upsert one entry of a {@link SymbolicDefinition}'s `variables`.
+ *
+ * @remarks
+ * `variables` is a name-keyed unordered record, so `add`/`remove` (no
+ * placement) are the correct verbs — mirrored by {@link removeVariable}.
+ *
+ * @param definition - The definition to update
+ * @param name - The variable name
+ * @param value - The variable's value
+ * @returns A fresh definition with the variable set
+ *
+ * @example
+ * ```ts
+ * import { addVariable, symbolicDefinition } from '@src/core'
+ *
+ * addVariable(symbolicDefinition('e', 'E', []), 'x', 5).variables // { x: 5 }
+ * ```
+ */
+export declare function addVariable(definition: SymbolicDefinition, name: string, value: number): SymbolicDefinition;
+
+/**
+ * How the {@link AggregatorInterface} reduces a list of numbers to one.
+ *
+ * @remarks
+ * When weights apply: `sum` multiplies each value by its weight, `product`
+ * raises each value to its weight (weight-as-exponent), `average` is the
+ * weighted mean, and `minimum` / `maximum` ignore weights entirely.
+ */
+export declare type Aggregation = 'sum' | 'product' | 'average' | 'minimum' | 'maximum';
+
+/**
+ * Reduces number lists to one number per {@link Aggregation} — the quantitative
+ * reasoner's group and definition combiner.
+ *
+ * @remarks
+ * 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
+ * (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`
+ * (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.
+ */
+export declare class Aggregator implements AggregatorInterface {
+    #private;
+    constructor(options?: AggregatorOptions);
+    get id(): string;
+    aggregate(values: readonly number[], aggregation: Aggregation, weights?: readonly number[]): number;
+}
+
+/** Default `id` for an `Aggregator`. */
+export declare const AGGREGATOR_ID = "aggregator";
+
+/**
+ * Reduces number lists to one number per {@link Aggregation}.
+ *
+ * @remarks
+ * Total: never throws. Empty-input identities: `sum` / `average` → `0`,
+ * `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;
+    aggregate(values: readonly number[], aggregation: Aggregation, weights?: readonly number[]): number;
+}
+
+/**
+ * Options for `createAggregator` / the `Aggregator` constructor.
+ *
+ * @remarks
+ * `id` — the aggregator's identity string (defaults to `AGGREGATOR_ID`).
+ */
+export declare interface AggregatorOptions {
+    readonly id?: string;
+}
+
+/**
+ * Insert `item` into an id-keyed collection, deduping any existing element
+ * sharing its id, then placing it at the END (or immediately AFTER `target`).
+ *
+ * @remarks
+ * `filtered` is `items` with every `item.id` twin removed FIRST (dedup-on-
+ * insert — input arrays may already carry same-id twins per PROPOSAL.md §7).
+ * 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
+ * `target` naming no element throws {@link ReasonError} (`'TARGET'`).
+ *
+ * @typeParam T - An id-carrying element type
+ * @param items - The collection to insert into
+ * @param item - The element to insert
+ * @param target - Optional id to insert immediately after; appends at the end when absent
+ * @returns A fresh array with `item` inserted
+ * @throws {@link ReasonError} `'TARGET'` when `target` names no element in `items`
+     *
+     * @example
+     * ```ts
+     * import { appendById } from '@src/core'
+     *
+     * appendById([{ id: 'a' }, { id: 'b' }], { id: 'c' })         // [a, b, c]
+     * appendById([{ id: 'a' }, { id: 'b' }], { id: 'c' }, 'a')    // [a, c, b]
+     * ```
+     */
+ export declare function appendById<T extends {
+     readonly id: string;
+ }>(items: readonly T[], item: T, target?: string): readonly T[];
+
+ /**
+  * Insert `equation` into a {@link SymbolicDefinition}'s `equations` — dedup-
+  * 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.
+  *
+  * @param definition - The definition to insert into
+  * @param source - The equation to insert
+  * @param target - Optional equation id to insert immediately after
+  * @returns A fresh definition with `equation` inserted
+  * @throws {@link ReasonError} `'TARGET'` when `target` names no existing equation
+      *
+      * @example
+      * ```ts
+      * import { appendEquation, constant, equation, symbolicDefinition, variable } from '@src/core'
+      *
+      * appendEquation(symbolicDefinition('e', 'E', []), equation('e1', variable('x'), constant(1), 'x'))
+      * ```
+      */
+  export declare function appendEquation(definition: SymbolicDefinition, source: Equation, target?: string): SymbolicDefinition;
+
+  /**
+   * Insert `fact` into an {@link InferentialDefinition}'s `facts` — dedup-then-
+   * insert at the end, or immediately after `target`.
+   *
+   * @remarks
+   * `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.
+   *
+   * @param definition - The definition to insert into
+   * @param source - The fact to insert
+   * @param target - Optional fact id to insert immediately after
+   * @returns A fresh definition with `fact` inserted
+   * @throws {@link ReasonError} `'TARGET'` when `target` names no existing fact
+       *
+       * @example
+       * ```ts
+       * import { appendFact, fact, inferentialDefinition } from '@src/core'
+       *
+       * appendFact(inferentialDefinition('m', 'M', [], []), fact('f1', 'human', ['socrates']))
+       * ```
+       */
+   export declare function appendFact(definition: InferentialDefinition, source: Fact, target?: string): InferentialDefinition;
+
+   /**
+    * Insert `factor` into a {@link FactorGroup}'s `factors` — dedup-then-insert
+    * at the end, or immediately after `target`.
+    *
+    * @remarks
+    * 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 via
+    * `appendGroup(def, appendFactor(group, factor))`.
+    *
+    * @param group - The group to insert into
+    * @param factor - The factor to insert
+    * @param target - Optional factor id to insert immediately after
+    * @returns A fresh group with `factor` inserted
+    * @throws {@link ReasonError} `'TARGET'` when `target` names no existing factor
+        *
+        * @example
+        * ```ts
+        * import { appendFactor, factorGroup, staticFactor } from '@src/core'
+        *
+        * appendFactor(factorGroup('g1', 'sum', []), staticFactor('f1', 10))
+        * ```
+        */
+    export declare function appendFactor(group: FactorGroup, factor: Factor, target?: string): FactorGroup;
+
+    /**
+     * Insert `group` into a {@link QuantitativeDefinition}'s `groups` — dedup-then-
+     * insert at the end, or immediately after `target`.
+     *
+     * @remarks
+     * 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))`.
+     *
+     * @param definition - The definition to insert into
+     * @param group - The group to insert
+     * @param target - Optional group id to insert immediately after
+     * @returns A fresh definition with `group` inserted
+     * @throws {@link ReasonError} `'TARGET'` when `target` names no existing group
+         *
+         * @example
+         * ```ts
+         * import { appendGroup, factorGroup, quantitativeDefinition } from '@src/core'
+         *
+         * appendGroup(quantitativeDefinition('risk', 'Risk', []), factorGroup('g1', 'sum', []))
+         * ```
+         */
+     export declare function appendGroup(definition: QuantitativeDefinition, group: FactorGroup, target?: string): QuantitativeDefinition;
+
+     /**
+      * Insert `inference` into an {@link InferentialDefinition}'s `inferences` —
+      * dedup-then-insert at the end, or immediately after `target`.
+      *
+      * @remarks
+      * Order is LOAD-BEARING: backward proving iterates in declaration order and
+      * returns on first success.
+      *
+      * @param definition - The definition to insert into
+      * @param source - The inference to insert
+      * @param target - Optional inference id to insert immediately after
+      * @returns A fresh definition with `inference` inserted
+      * @throws {@link ReasonError} `'TARGET'` when `target` names no existing inference
+          *
+          * @example
+          * ```ts
+          * import { appendInference, fact, inference, inferentialDefinition } from '@src/core'
+          *
+          * appendInference(
+          * 	inferentialDefinition('m', 'M', [], []),
+          * 	inference('i1', [fact('p', 'human', ['?x'])], fact('c', 'mortal', ['?x'])),
+          * )
+          * ```
+          */
+      export declare function appendInference(definition: InferentialDefinition, source: Inference, target?: string): InferentialDefinition;
+
+      /**
+       * Insert `rule` into a {@link LogicalDefinition}'s `rules` — dedup-then-insert
+       * at the end, or immediately after `target`.
+       *
+       * @remarks
+       * 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.
+       *
+       * @param definition - The definition to insert into
+       * @param source - The rule to insert
+       * @param target - Optional rule id to insert immediately after
+       * @returns A fresh definition with `rule` inserted
+       * @throws {@link ReasonError} `'TARGET'` when `target` names no existing rule
+           *
+           * @example
+           * ```ts
+           * import { appendRule, atom, logicalDefinition, rule } from '@src/core'
+           *
+           * appendRule(logicalDefinition('e', 'E', []), rule('r1', [], atom('a', 'equals', true)))
+           * ```
+           */
+       export declare function appendRule(definition: LogicalDefinition, source: Rule, target?: string): LogicalDefinition;
+
+       /**
+        * Apply one binary/unary math operation to already-evaluated operands.
+        *
+        * @remarks
+        * The arithmetic core of the symbolic reasoner's expression evaluation: the full
+        * {@link MathOperation} vocabulary plus its zero / unary conventions — `divide`
+        * 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 (caught per
+        * equation upstream).
+        *
+        * @param operator - The operation name (untrusted — an unknown one throws)
+        * @param left - The left operand
+        * @param right - The right operand (ignored by the unary operations)
+        * @returns The operation's result (`NaN` on divide-by-zero)
+        *
+        * @example
+        * ```ts
+        * import { applyOperation } from '@src/core'
+        *
+        * applyOperation('add', 2, 3)     // 5
+        * applyOperation('divide', 1, 0)  // NaN
+        * ```
+        */
+       export declare function applyOperation(operator: string, left: number, right: number): number;
+
+       /**
+        * Upsert one field of a {@link Subject} — copy-on-write spread.
+        *
+        * @remarks
+        * Id-agnostic: overwrites an `id` key like any other field — id protection is
+        * an entity's job, not this helper's.
+        *
+        * @param subject - The subject to update
+        * @param key - The field to set
+        * @param value - The value to set it to
+        * @returns A fresh subject with `key` set to `value`
+        *
+        * @example
+        * ```ts
+        * import { assignField } from '@src/core'
+        *
+        * assignField({ id: 's1', age: 30 }, 'age', 31) // { id: 's1', age: 31 }
+        * ```
+        */
+       export declare function assignField(subject: Subject, key: string, value: unknown): Subject;
+
+       /** A leaf boolean expression — one {@link Check} against the subject. */
+       export declare interface Atom {
+           readonly form: 'atom';
+           readonly check: Check;
+       }
+
+       /**
+        * Build an atom {@link Expression} — a leaf wrapping one {@link Check}.
+        *
+        * @param field - The subject field to resolve
+        * @param operator - The comparison to apply
+        * @param value - The expected value
+        * @returns A fresh atom expression
+        *
+        * @example
+        * ```ts
+        * import { atom } from '@src/core'
+        *
+        * atom('age', 'from', 18) // { form: 'atom', check: { field: 'age', operator: 'from', value: 18 } }
+        * ```
+        */
+       export declare function atom(field: FieldPath, operator: Comparison, value: unknown): Expression;
+
+       /**
+        * An inclusive numeric clamp — either side may be absent (unbounded).
+        */
+       export declare interface Bounds {
+           readonly minimum?: number;
+           readonly maximum?: number;
+       }
+
+       /**
+        * Build a {@link Bounds} — an inclusive numeric clamp.
+        *
+        * @remarks
+        * Absent sides are OMITTED (never set to `undefined`) — an absent bound is
+        * unbounded on that side.
+        *
+        * @param minimum - The inclusive lower bound
+        * @param maximum - The inclusive upper bound
+        * @returns A fresh bounds record
+        *
+        * @example
+        * ```ts
+        * import { bounds } from '@src/core'
+        *
+        * bounds(0, 100)          // { minimum: 0, maximum: 100 }
+        * bounds(undefined, 100)  // { maximum: 100 }
+        * ```
+        */
+       export declare function bounds(minimum?: number, maximum?: number): Bounds;
+
+       /**
+        * Build the empty, type-shaped failure {@link ReasonResult} matching a
+        * definition's reasoning.
+        *
+        * @remarks
+        * The `bail: false` fallback of the `Reason` orchestrator: when a reasoner
+        * throws and bail is off, the throw becomes an empty failure result carrying the
+        * message as its sole `errors` entry. Each reasoning gets its own zero-valued
+        * shape (`quantitative` → `value: 0` / empty `groups`; `logical` → `conclusion:
+        * false` / empty `rules`; `symbolic` → empty `solutions`; `inferential` → empty
+        * `derived`), always with `success: false` and an empty `trace`.
+        *
+        * @param definition - The definition whose reasoning selects the result shape
+        * @param message - The error message to carry as the result's sole `errors` entry
+        * @returns A fresh failure result of the matching reasoning
+        *
+        * @example
+        * ```ts
+        * import { buildErrorResult, logicalDefinition } from '@src/core'
+        *
+        * const result = buildErrorResult(logicalDefinition('e', 'E', []), 'boom')
+        * // { reasoning: 'logical', conclusion: false, rules: [], count: 0, success: false, trace: [], errors: ['boom'] }
+        * ```
+        */
+       export declare function buildErrorResult(definition: Definition, message: string): ReasonResult;
+
+       /**
+        * How a chaining reasoner walks its rules: `forward` (data-driven fixpoint) or
+        * `backward` (goal-driven proving).
+        */
+       export declare type ChainingStrategy = 'forward' | 'backward';
+
+       /**
+        * A single field predicate: resolve `field` from the subject and compare it to
+        * `value` with `operator`.
+        *
+        * @remarks
+        * `field` follows the {@link FieldPath} idiom — a string is ONE key (never
+        * dot-split), an array descends into nested objects. `value` is unconstrained
+        * (`unknown`): the operator decides what shapes are meaningful.
+        */
+       export declare interface Check {
+           readonly field: FieldPath;
+           readonly operator: Comparison;
+           readonly value: unknown;
+       }
+
+       /**
+        * Build a {@link Check} — one field predicate.
+        *
+        * @param field - The subject field to resolve (a string is ONE 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
+        *
+        * @example
+        * ```ts
+        * import { check } from '@src/core'
+        *
+        * check('age', 'from', 18) // { field: 'age', operator: 'from', value: 18 }
+        * ```
+        */
+       export declare function check(field: FieldPath, operator: Comparison, value: unknown): Check;
+
+       /**
+        * The outcome of one {@link Check} evaluation.
+        *
+        * @remarks
+        * `actual` is the resolved subject value (possibly `undefined`); `error` is set
+        * ONLY when evaluation itself failed (an unknown operator) — a merely-unmet
+        * check carries no `error`.
+        */
+       export declare interface CheckResult {
+           readonly field: FieldPath;
+           readonly met: boolean;
+           readonly actual: unknown;
+           readonly error?: string;
+       }
+
+       /**
+        * Clamp a number to inclusive {@link Bounds}.
+        *
+        * @remarks
+        * An absent bound (or absent `bounds` entirely) never constrains that side.
+        * `NaN` flows through unchanged (every comparison with `NaN` is false).
+        *
+        * @param value - The number to clamp
+        * @param limit - The inclusive bounds (either side optional)
+        * @returns The clamped number
+        *
+        * @example
+        * ```ts
+        * import { clamp } from '@src/core'
+        *
+        * clamp(150, { minimum: 0, maximum: 100 }) // 100
+        * clamp(150)                               // 150 — unbounded
+        * ```
+        */
+       export declare function clamp(value: number, limit?: Bounds): number;
+
+       /**
+        * Delete one optional field of an {@link InferentialDefinition}.
+        *
+        * @param definition - The definition to update
+        * @param key - The optional field to clear
+        * @returns A fresh definition with `key` omitted
+        *
+        * @example
+        * ```ts
+        * import { clearInferentialDefinition, inferentialDefinition } from '@src/core'
+        *
+        * const definition = inferentialDefinition('m', 'M', [], [], { depth: 5 })
+        * 'depth' in clearInferentialDefinition(definition, 'depth') // false
+        * ```
+        */
+       export declare function clearInferentialDefinition(definition: InferentialDefinition, key: 'description' | 'depth'): InferentialDefinition;
+
+       /**
+        * Delete one optional field of a {@link LogicalDefinition}.
+        *
+        * @param definition - The definition to update
+        * @param key - The optional field to clear
+        * @returns A fresh definition with `key` omitted
+        *
+        * @example
+        * ```ts
+        * import { clearLogicalDefinition, logicalDefinition } from '@src/core'
+        *
+        * const definition = logicalDefinition('e', 'E', [], { depth: 5 })
+        * 'depth' in clearLogicalDefinition(definition, 'depth') // false
+        * ```
+        */
+       export declare function clearLogicalDefinition(definition: LogicalDefinition, key: 'description' | 'depth'): LogicalDefinition;
+
+       /**
+        * Delete one optional field of a {@link QuantitativeDefinition}.
+        *
+        * @param definition - The definition to update
+        * @param key - The optional field to clear
+        * @returns A fresh definition with `key` omitted
+        *
+        * @example
+        * ```ts
+        * import { clearQuantitativeDefinition, quantitativeDefinition } from '@src/core'
+        *
+        * const definition = quantitativeDefinition('risk', 'Risk', [], { precision: 2 })
+        * 'precision' in clearQuantitativeDefinition(definition, 'precision') // false
+        * ```
+        */
+       export declare function clearQuantitativeDefinition(definition: QuantitativeDefinition, key: 'description' | 'base' | 'bounds' | 'precision'): QuantitativeDefinition;
+
+       /**
+        * Delete one optional field of a {@link SymbolicDefinition}.
+        *
+        * @param definition - The definition to update
+        * @param key - The optional field to clear
+        * @returns A fresh definition with `key` omitted
+        *
+        * @example
+        * ```ts
+        * import { clearSymbolicDefinition, symbolicDefinition } from '@src/core'
+        *
+        * const definition = symbolicDefinition('e', 'E', [], { precision: 2 })
+        * 'precision' in clearSymbolicDefinition(definition, 'precision') // false
+        * ```
+        */
+       export declare function clearSymbolicDefinition(definition: SymbolicDefinition, key: 'description' | 'precision'): SymbolicDefinition;
+
+       /**
+        * The comparison a {@link Check} applies between a resolved subject field and
+        * its expected value.
+        *
+        * @remarks
+        * `equals` / `not` — strict `===` / `!==` (no coercion). `above` / `below` /
+        * `from` / `to` — `>` / `<` / `>=` / `<=`, requiring numbers on BOTH sides
+        * (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
+        * 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`.
+        */
+       export declare type Comparison = 'equals' | 'not' | 'above' | 'below' | 'from' | 'to' | 'any' | 'none' | 'between' | 'outside';
+
+       /** A compound boolean expression — a {@link LogicalOperator} over nested operands. */
+       export declare interface Compound {
+           readonly form: 'compound';
+           readonly operator: LogicalOperator;
+           readonly operands: readonly Expression[];
+       }
+
+       /**
+        * Build a compound {@link Expression} — a logical connective over nested
+        * operands.
+        *
+        * @param operator - The logical connective
+        * @param operands - The nested expressions it combines
+        * @returns A fresh compound expression
+        *
+        * @example
+        * ```ts
+        * import { atom, compound } from '@src/core'
+        *
+        * compound('and', [atom('age', 'from', 18), atom('state', 'equals', 'CA')])
+        * ```
+        */
+       export declare function compound(operator: LogicalOperator, operands: readonly Expression[]): Expression;
+
+       /**
+        * Decimal places a derived fact's confidence is rounded to during forward
+        * inferential chaining.
+        *
+        * @remarks
+        * Fixed — unlike {@link DEFAULT_PRECISION} it is NOT overridable per
+        * definition, so confidence products stay comparable across derivations.
+        */
+       export declare const CONFIDENCE_PRECISION = 4;
+
+       /** A symbolic expression leaf holding a fixed number. */
+       export declare interface Constant {
+           readonly form: 'constant';
+           readonly value: number;
+       }
+
+       /**
+        * Build a constant {@link SymbolicExpression} leaf.
+        *
+        * @param value - The fixed number
+        * @returns A fresh constant node
+        *
+        * @example
+        * ```ts
+        * import { constant } from '@src/core'
+        *
+        * constant(42) // { form: 'constant', value: 42 }
+        * ```
+        */
+       export declare function constant(value: number): SymbolicExpression;
+
+       /**
+        * Determine 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
+        * `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
+        * 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)
+        * @returns `true` when an unbound `target` occurs in the expression
+        *
+        * @example
+        * ```ts
+        * import { containsVariable, operation, variable, constant } from '@src/core'
+        *
+        * containsVariable(operation('add', variable('x'), constant(1)), 'x', {})        // true
+        * containsVariable(operation('add', variable('x'), constant(1)), 'x', { x: 5 })  // false — pre-bound
+        * ```
+        */
+       export declare function containsVariable(expression: SymbolicExpression, target: string, bindings: Record<string, number>): boolean;
+
+       /**
+        * Create a number aggregator.
+        *
+        * @remarks
+        * `id` — the aggregator's identity string (defaults to `'aggregator'`).
+        *
+        * @param options - Optional `id`
+        * @returns A stateless {@link AggregatorInterface}
+        *
+        * @example
+        * ```ts
+        * import { createAggregator } from '@src/core'
+        *
+        * const aggregator = createAggregator()
+        * aggregator.aggregate([10, 20], 'average', [1, 3]) // 17.5 — weighted mean
+        * ```
+        */
+       export declare function createAggregator(options?: AggregatorOptions): AggregatorInterface;
+
+       /**
+        * Create a `DefinitionBuilder` — a stateful workspace builder accumulating a
+        * {@link Definition} through seven self-owning manager properties.
+        *
+        * @remarks
+        * `id` defaults to `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 (AGENTS §8). `error` — the
+        * emitter's listener-error handler (AGENTS §13). 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)
+        * @param options - Optional `id` override, manager injections, and emitter hooks
+        * @returns A {@link DefinitionBuilderInterface}
+        *
+        * @example
+        * ```ts
+        * import { createDefinitionBuilder, quantitativeDefinition } from '@src/core'
+        *
+        * const definition = createDefinitionBuilder(quantitativeDefinition('risk', 'Risk', []))
+        * definition.groups.append({ id: 'g1', name: 'g1', aggregation: 'sum', factors: [] })
+        * definition.build() // a fresh QuantitativeDefinition with the group applied
+        * definition.destroy()
+        * ```
+        */
+       export declare function createDefinitionBuilder(seed: Definition, options?: DefinitionBuilderOptions): DefinitionBuilderInterface;
+
+       /**
+        * Create an `EquationManager` — a self-owning manager over a symbolic
+        * definition's `equations`.
+        *
+        * @remarks
+        * `equations` — the initial collection (defaults to empty). `on` / `error` —
+        * emitter hooks (AGENTS §8 / §13). Equation order is strongly load-bearing.
+        *
+        * @param options - Optional seed collection and emitter hooks
+        * @returns An {@link EquationManagerInterface}
+        *
+        * @example
+        * ```ts
+        * import { constant, createEquationManager, equation, variable } from '@src/core'
+        *
+        * const equations = createEquationManager()
+        * equations.append(equation('e1', variable('y'), constant(2), 'y'))
+        * ```
+        */
+       export declare function createEquationManager(options?: EquationManagerOptions): EquationManagerInterface;
+
+       /**
+        * Create a check evaluator.
+        *
+        * @remarks
+        * `id` — the evaluator's identity string (defaults to `'evaluator'`).
+        *
+        * @param options - Optional `id`
+        * @returns A stateless {@link EvaluatorInterface}
+        *
+        * @example
+        * ```ts
+        * import { createEvaluator } from '@src/core'
+        *
+        * const evaluator = createEvaluator()
+        * evaluator.evaluate({ field: 'age', operator: 'above', value: 18 }, { age: 25 })
+        * // { field: 'age', met: true, actual: 25 }
+        * ```
+        */
+       export declare function createEvaluator(options?: EvaluatorOptions): EvaluatorInterface;
+
+       /**
+        * Create a `FactManager` — a self-owning manager over an inferential
+        * definition's `facts`.
+        *
+        * @remarks
+        * `facts` — the initial collection (defaults to empty). `on` / `error` —
+        * emitter hooks (AGENTS §8 / §13).
+        *
+        * @param options - Optional seed collection and emitter hooks
+        * @returns A {@link FactManagerInterface}
+        *
+        * @example
+        * ```ts
+        * import { createFactManager, fact } from '@src/core'
+        *
+        * const facts = createFactManager()
+        * facts.append(fact('f1', 'human', ['socrates']))
+        * ```
+        */
+       export declare function createFactManager(options?: FactManagerOptions): FactManagerInterface;
+
+       /**
+        * Create a `FactorManager` — the divergent manager over a group's `factors`,
+        * threaded through a required `groupId` locator.
+        *
+        * @remarks
+        * Holds no collection state of its own — it reads and writes factors through
+        * the injected sibling {@link GroupManagerInterface}. `on` / `error` — emitter
+        * hooks (AGENTS §8 / §13).
+        *
+        * @param groups - The sibling group manager factors are located within
+        * @param options - Optional emitter hooks
+        * @returns A {@link FactorManagerInterface}
+        *
+        * @example
+        * ```ts
+        * import { createFactorManager, createGroupManager, factorGroup, staticFactor } from '@src/core'
+        *
+        * const groups = createGroupManager({ groups: [factorGroup('g1', 'sum', [])] })
+        * const factors = createFactorManager(groups)
+        * factors.append('g1', staticFactor('f1', 10))
+        * ```
+        */
+       export declare function createFactorManager(groups: GroupManagerInterface, options?: FactorManagerOptions): FactorManagerInterface;
+
+       /**
+        * Create a `GroupManager` — a self-owning manager over a quantitative
+        * definition's `groups`.
+        *
+        * @remarks
+        * `groups` — the initial collection (defaults to empty). `on` / `error` —
+        * emitter hooks (AGENTS §8 / §13). Kind-free: hand it to a
+        * {@link createDefinitionBuilder} `groups` slot regardless of reasoning.
+        *
+        * @param options - Optional seed collection and emitter hooks
+        * @returns A {@link GroupManagerInterface}
+        *
+        * @example
+        * ```ts
+        * import { createGroupManager, factorGroup } from '@src/core'
+        *
+        * const groups = createGroupManager({ groups: [factorGroup('g1', 'sum', [])] })
+        * groups.append(factorGroup('g2', 'sum', []))
+        * ```
+        */
+       export declare function createGroupManager(options?: GroupManagerOptions): GroupManagerInterface;
+
+       /**
+        * Create an `InferenceManager` — a self-owning manager over an inferential
+        * definition's `inferences`.
+        *
+        * @remarks
+        * `inferences` — the initial collection (defaults to empty). `on` / `error` —
+        * emitter hooks (AGENTS §8 / §13). Inference order is load-bearing.
+        *
+        * @param options - Optional seed collection and emitter hooks
+        * @returns An {@link InferenceManagerInterface}
+        *
+        * @example
+        * ```ts
+        * import { createInferenceManager, fact, inference } from '@src/core'
+        *
+        * const inferences = createInferenceManager()
+        * inferences.append(inference('m', [fact('p', 'human', ['?x'])], fact('c', 'mortal', ['?x'])))
+        * ```
+        */
+       export declare function createInferenceManager(options?: InferenceManagerOptions): InferenceManagerInterface;
+
+       /**
+        * Create the inferential reasoner — fact derivation with unification variables
+        * and proof trees.
+        *
+        * @remarks
+        * `id` — the reasoner's identity string (defaults to `'inferential'`).
+        *
+        * @param options - Optional `id`
+        * @returns A {@link ReasonerInterface} with reasoning `'inferential'`
+        *
+        * @example
+        * ```ts
+        * import { createInferentialReasoner, fact, inference, inferentialDefinition } from '@src/core'
+        *
+        * const reasoner = createInferentialReasoner()
+        * const definition = inferentialDefinition('mortality', 'Mortality',
+        * 	[fact('f1', 'human', ['socrates'])],
+        * 	[inference('mortal', [fact('p1', 'human', ['?x'])], fact('c1', 'mortal', ['?x']))],
+        * )
+        * reasoner.reason({}, definition) // derives mortal(socrates)
+        * ```
+        */
+       export declare function createInferentialReasoner(options?: InferentialReasonerOptions): ReasonerInterface;
+
+       /**
+        * Create the logical reasoner — rule-based deduction with forward / backward
+        * chaining.
+        *
+        * @remarks
+        * `id` — the reasoner's identity string (defaults to `'logical'`). `evaluator`
+        * — the injectable check evaluator (defaults to a fresh instance).
+        *
+        * @param options - Optional `id` and evaluator injection
+        * @returns A {@link ReasonerInterface} with reasoning `'logical'`
+        *
+        * @example
+        * ```ts
+        * import { atom, createLogicalReasoner, logicalDefinition, rule } from '@src/core'
+        *
+        * const reasoner = createLogicalReasoner()
+        * const definition = logicalDefinition('eligibility', 'Eligibility', [
+        * 	rule('adult', [atom('age', 'from', 18)], atom('adult', 'equals', true)),
+        * ])
+        * reasoner.reason({ age: 25 }, definition) // conclusion true
+        * ```
+        */
+       export declare function createLogicalReasoner(options?: LogicalReasonerOptions): ReasonerInterface;
+
+       /**
+        * Create the quantitative reasoner — factor-based numeric scoring.
+        *
+        * @remarks
+        * `id` — the reasoner's identity string (defaults to `'quantitative'`).
+        * `evaluator` / `transformer` / `aggregator` — injectable operators, each
+        * defaulting to a fresh default-constructed instance.
+        *
+        * @param options - Optional `id` and operator injections
+        * @returns A {@link ReasonerInterface} with reasoning `'quantitative'`
+        *
+        * @example
+        * ```ts
+        * import { createQuantitativeReasoner, fieldFactor, factorGroup, quantitativeDefinition } from '@src/core'
+        *
+        * const reasoner = createQuantitativeReasoner()
+        * const definition = quantitativeDefinition('risk', 'Risk', [
+        * 	factorGroup('g1', 'sum', [fieldFactor('age', 'age')]),
+        * ], { base: 100 })
+        * reasoner.reason({ age: 25 }, definition) // value 125
+        * ```
+        */
+       export declare function createQuantitativeReasoner(options?: QuantitativeReasonerOptions): ReasonerInterface;
+
+       /**
+        * Create the reasoning orchestrator.
+        *
+        * @remarks
+        * `reasoners` — the initial registry (a later entry of the same reasoning
+        * 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
+        * `false`). `on` — initial event listeners (AGENTS §8). `error` — the
+        * emitter's listener-error handler (AGENTS §13).
+        *
+        * @param options - Optional registry, policies, and emitter hooks
+        * @returns A {@link ReasonInterface}
+        *
+        * @example
+        * ```ts
+        * import { createLogicalReasoner, createQuantitativeReasoner, createReason } from '@src/core'
+        *
+        * const reason = createReason({
+        * 	reasoners: [createQuantitativeReasoner(), createLogicalReasoner()],
+        * 	on: { reason: (result) => console.log(result.success) },
+        * })
+        * const result = reason.reason({ age: 25 }, definition)
+        * reason.destroy()
+        * ```
+        */
+       export declare function createReason(options?: ReasonOptions): ReasonInterface;
+
+       /**
+        * Create a `RuleManager` — a self-owning manager over a logical definition's
+        * `rules`.
+        *
+        * @remarks
+        * `rules` — the initial collection (defaults to empty). `on` / `error` —
+        * emitter hooks (AGENTS §8 / §13). Rule order is load-bearing.
+        *
+        * @param options - Optional seed collection and emitter hooks
+        * @returns A {@link RuleManagerInterface}
+        *
+        * @example
+        * ```ts
+        * import { atom, createRuleManager, rule } from '@src/core'
+        *
+        * const rules = createRuleManager()
+        * rules.append(rule('adult', [atom('age', 'from', 18)], atom('adult', 'equals', true)))
+        * ```
+        */
+       export declare function createRuleManager(options?: RuleManagerOptions): RuleManagerInterface;
+
+       /**
+        * Create a `SubjectBuilder` — a stateful workspace builder accumulating a
+        * {@link Subject}.
+        *
+        * @remarks
+        * `id` defaults to `seed.id` and 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
+        * (AGENTS §8). `error` — the emitter's listener-error handler (AGENTS §13).
+        * Mutate through `set` / `remove` / `merge` / `clear`, then call `build()` to
+        * produce a fresh, plain {@link Subject} snapshot.
+        *
+        * @param seed - The starting subject
+        * @param options - Optional `id` override and emitter hooks
+        * @returns A {@link SubjectBuilderInterface}
+        *
+        * @example
+        * ```ts
+        * import { createSubjectBuilder } from '@src/core'
+        *
+        * const subject = createSubjectBuilder({ id: 's1', age: 30 })
+        * subject.set('age', 31)
+        * subject.build() // { id: 's1', age: 31 }
+        * subject.destroy()
+        * ```
+        */
+       export declare function createSubjectBuilder(seed: Subject, options?: SubjectBuilderOptions): SubjectBuilderInterface;
+
+       /**
+        * Create the symbolic reasoner — algebraic equation solving by variable
+        * isolation.
+        *
+        * @remarks
+        * `id` — the reasoner's identity string (defaults to `'symbolic'`).
+        *
+        * @param options - Optional `id`
+        * @returns A {@link ReasonerInterface} with reasoning `'symbolic'`
+        *
+        * @example
+        * ```ts
+        * import { constant, createSymbolicReasoner, equation, operation, symbolicDefinition, variable } from '@src/core'
+        *
+        * const reasoner = createSymbolicReasoner()
+        * const definition = symbolicDefinition('double', 'Double', [
+        * 	equation('e1', variable('y'), operation('multiply', variable('x'), constant(2)), 'y'),
+        * ])
+        * reasoner.reason({ x: 21 }, definition) // solutions.y === 42
+        * ```
+        */
+       export declare function createSymbolicReasoner(options?: SymbolicReasonerOptions): ReasonerInterface;
+
+       /**
+        * Create a math transformer.
+        *
+        * @remarks
+        * `id` — the transformer's identity string (defaults to `'transformer'`).
+        *
+        * @param options - Optional `id`
+        * @returns A stateless {@link TransformerInterface}
+        *
+        * @example
+        * ```ts
+        * import { createTransformer, transform } from '@src/core'
+        *
+        * const transformer = createTransformer()
+        * transformer.chain(100, [transform('add', 50), transform('multiply', 2)]) // 300
+        * ```
+        */
+       export declare function createTransformer(options?: TransformerOptions): TransformerInterface;
+
+       /**
+        * Create a `VariableManager` — a self-owning manager over a symbolic
+        * definition's `variables` (a name-keyed record; `add` / `remove` only).
+        *
+        * @remarks
+        * `variables` — the initial record (defaults to empty). `on` / `error` —
+        * emitter hooks (AGENTS §8 / §13).
+        *
+        * @param options - Optional seed record and emitter hooks
+        * @returns A {@link VariableManagerInterface}
+        *
+        * @example
+        * ```ts
+        * import { createVariableManager } from '@src/core'
+        *
+        * const variables = createVariableManager({ variables: { x: 1 } })
+        * variables.add('y', 2)
+        * ```
+        */
+       export declare function createVariableManager(options?: VariableManagerOptions): VariableManagerInterface;
+
+       /** Default `base` added before aggregation, at both group and definition level. */
+       export declare const DEFAULT_BASE = 0;
+
+       /** Default `confidence` for facts, inferences, and injected subject facts. */
+       export declare const DEFAULT_CONFIDENCE = 1;
+
+       /**
+        * Default `depth` for chaining definitions — the forward-iteration /
+        * backward-recursion cap of the logical and inferential reasoners.
+        */
+       export declare const DEFAULT_DEPTH = 10;
+
+       /** Default `precision` (decimal places) for quantitative values and symbolic solutions. */
+       export declare const DEFAULT_PRECISION = 4;
+
+       /** Default factor / rule `priority` — evaluation order is ascending and stable. */
+       export declare const DEFAULT_PRIORITY = 0;
+
+       /**
+        * Default `bail` for the `Reason` orchestrator — a reasoner throw is rethrown
+        * after the `error` emit.
+        *
+        * @remarks
+        * Named with the domain qualifier so the generic `DEFAULT_BAIL` stays free for
+        * other modules' bail defaults on the shared `@src/core` barrel.
+        */
+       export declare const DEFAULT_REASON_BAIL = true;
+
+       /** Default `validate` for the `Reason` orchestrator — per-call validation is skipped. */
+       export declare const DEFAULT_VALIDATE = false;
+
+       /** Default factor `weight` at group aggregation. */
+       export declare const DEFAULT_WEIGHT = 1;
+
+       /** Any reasoning definition, discriminated by `reasoning`. */
+       export declare type Definition = QuantitativeDefinition | LogicalDefinition | SymbolicDefinition | InferentialDefinition;
+
+       /**
+        * The `DefinitionBuilder` entity brand — a `unique symbol` key carrying
+        * `readonly true` on every `DefinitionBuilderInterface` instance.
+        *
+        * @remarks
+        * Only `isDefinitionBuilder` (`validators.ts`) reads this key, via
+        * `Reflect.get`. A module-owned `unique symbol` cannot be produced by
+        * `JSON.parse` or written by any consumer that does not import this constant,
+        * so plain data can never forge the brand.
+        */
+       export declare const DEFINITION_BUILDER_BRAND: unique symbol;
+
+       /**
+        * A stateful workspace builder accumulating a {@link Definition} through seven
+        * always-present self-owning manager properties, shaped like `AgentContext`
+        * (AGENTS §4.2.2): 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 simply ignored by `build()`,
+        * 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 via 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
+        * all seven managers, emits `destroy`, then tears the builder emitter down LAST
+        * (AGENTS §13); it is idempotent, and post-destroy mutation / build throws
+        * `ReasonError('DESTROYED', …)`.
+        */
+       export declare class DefinitionBuilder implements DefinitionBuilderInterface {
+           #private;
+           readonly [DEFINITION_BUILDER_BRAND]: true;
+           readonly groups: GroupManagerInterface;
+           readonly factors: FactorManagerInterface;
+           readonly rules: RuleManagerInterface;
+           readonly equations: EquationManagerInterface;
+           readonly variables: VariableManagerInterface;
+           readonly facts: FactManagerInterface;
+           readonly inferences: InferenceManagerInterface;
+           constructor(seed: Definition, options?: DefinitionBuilderOptions);
+           get id(): string;
+           get reasoning(): Reasoning;
+           get emitter(): EmitterInterface<DefinitionBuilderEventMap>;
+           build(): Definition;
+           merge(incoming: Definition): void;
+           clear(key: string): void;
+           destroy(): void;
+       }
+
+       /**
+        * The push observation surface of a {@link DefinitionBuilderInterface}
+        * (AGENTS §13) — the builder-level lifecycle events; per-element mutation
+        * events live on the individual managers' own emitters.
+        *
+        * @remarks
+        * `merge` carries the definition's `reasoning`; `clear` carries the cleared
+        * key; `destroy` fires once on teardown.
+        */
+       export declare type DefinitionBuilderEventMap = {
+           /** The definition was reconciled with an incoming definition — carries the reasoning. */
+           readonly merge: readonly [reasoning: Reasoning];
+           /** An optional field was cleared — carries the field key. */
+           readonly clear: readonly [key: string];
+           /** The entity was destroyed. */
+           readonly destroy: readonly [];
+       };
+
+       /**
+        * A stateful workspace builder accumulating a {@link Definition} through seven
+        * always-present self-owning manager properties, taverna `AgentContext`-shaped
+        * (AGENTS §4.2.2): a private scalar envelope plus one manager per collection.
+        *
+        * @remarks
+        * `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`,
+        * distributes incoming scalars into the envelope and collections into the
+        * managers via the matching `merge*` helper (a cross-reasoning `incoming`
+        * throws `ReasonError('MISMATCH', …)`). `clear(key)` is the uniform
+        * optional-key selector (AGENTS §4.2.4) 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 all
+        * seven managers, 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.
+        */
+       export declare interface DefinitionBuilderInterface {
+           readonly [DEFINITION_BUILDER_BRAND]: true;
+           readonly id: string;
+           readonly reasoning: Reasoning;
+           readonly emitter: EmitterInterface<DefinitionBuilderEventMap>;
+           readonly groups: GroupManagerInterface;
+           readonly factors: FactorManagerInterface;
+           readonly rules: RuleManagerInterface;
+           readonly equations: EquationManagerInterface;
+           readonly variables: VariableManagerInterface;
+           readonly facts: FactManagerInterface;
+           readonly inferences: InferenceManagerInterface;
+           build(): Definition;
+           merge(incoming: Definition): void;
+           clear(key: string): void;
+           destroy(): void;
+       }
+
+       /**
+        * Options for `createDefinitionBuilder` / the `DefinitionBuilder` constructor.
+        *
+        * @remarks
+        * `id` — overrides the seed definition's `id` (defaults to `seed.id`). Each of
+        * the seven manager slots 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 (AGENTS §8). `error` — the emitter's
+        * listener-error handler (AGENTS §13).
+        */
+       export declare interface DefinitionBuilderOptions {
+           readonly id?: string;
+           readonly groups?: GroupManagerInterface;
+           readonly factors?: FactorManagerInterface;
+           readonly rules?: RuleManagerInterface;
+           readonly equations?: EquationManagerInterface;
+           readonly variables?: VariableManagerInterface;
+           readonly facts?: FactManagerInterface;
+           readonly inferences?: InferenceManagerInterface;
+           readonly on?: EmitterHooks<DefinitionBuilderEventMap>;
+           readonly error?: EmitterErrorHandler;
+       }
+
+       /**
+        * The scalar-only projection of each definition kind — the {@link DefinitionBuilderInterface}
+        * implementation's private envelope holds the non-collection fields; `build()` re-composes
+        * the kind's collections from the managers' plural accessors.
+        */
+       export declare type DefinitionEnvelope = Omit<QuantitativeDefinition, 'groups'> | Omit<LogicalDefinition, 'rules'> | Omit<SymbolicDefinition, 'equations' | 'variables'> | Omit<InferentialDefinition, 'facts' | 'inferences'>;
+
+       /**
+        * Determine whether two values are SameValueZero-equal — strict `===` with
+        * `NaN` equal to itself (and, unlike `Object.is`, `+0` equal to `-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
+        * 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.
+        *
+        * @param left - The first value
+        * @param right - The second value
+        * @returns `true` when the values are SameValueZero-equal
+        *
+        * @example
+        * ```ts
+        * import { equalValues } from '@src/core'
+        *
+        * equalValues(Number.NaN, Number.NaN) // true — unlike ===
+        * equalValues(0, -0)                  // true — unlike Object.is
+        * equalValues(1, '1')                 // false — no coercion
+        * ```
+        */
+       export declare function equalValues(left: unknown, right: unknown): boolean;
+
+       /**
+        * One equation `left = right`, solved for the `target` variable.
+        *
+        * @remarks
+        * When `target` is unbound and appears on exactly one side, it is isolated
+        * algebraically through invertible operations (`add` / `subtract` / `multiply`
+        * / `divide`); otherwise the right side is evaluated directly.
+        */
+       export declare interface Equation {
+           readonly id: string;
+           readonly name: string;
+           readonly description?: string;
+           readonly left: SymbolicExpression;
+           readonly right: SymbolicExpression;
+           readonly target: string;
+       }
+
+       /**
+        * Build an {@link Equation} — `left = right`, solved for `target`.
+        *
+        * @remarks
+        * `name` defaults to the `id`; set `name` or `description` through `overrides`.
+        *
+        * @param id - The equation id
+        * @param left - The left side
+        * @param right - The right side
+        * @param target - The variable name to solve for
+        * @param overrides - Optional {@link Equation} fields merged over the defaults
+        * @returns A fresh equation
+        *
+        * @example
+        * ```ts
+        * import { constant, equation, operation, variable } from '@src/core'
+        *
+        * // 2x + 3 = 11 — solved for x
+        * equation('e1', operation('add', operation('multiply', constant(2), variable('x')), constant(3)), constant(11), 'x')
+        * ```
+        */
+       export declare function equation(id: string, left: SymbolicExpression, right: SymbolicExpression, target: string, overrides?: Partial<Omit<Equation, 'id' | 'left' | 'right' | 'target'>>): Equation;
+
+       /**
+        * The {@link EquationManagerInterface} implementation — a self-owning,
+        * kind-free manager over a symbolic definition's `equations`.
+        *
+        * @remarks
+        * OWNS its `#equations` collection as private copy-on-write state and its own
+        * {@link Emitter} over {@link EquationManagerEventMap}. Equation order is
+        * STRONGLY load-bearing — equations solve strictly in order and each rounded
+        * solution feeds forward. The write-only `collection` setter 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', …)`.
+        */
+       export declare class EquationManager implements EquationManagerInterface {
+           #private;
+           constructor(options?: EquationManagerOptions);
+           get emitter(): EmitterInterface<EquationManagerEventMap>;
+           set collection(value: readonly Equation[]);
+           equation(id: string): Equation | undefined;
+           equations(): readonly Equation[];
+           append(equation: Equation, target?: string): void;
+           prepend(equation: Equation, target?: string): void;
+           replace(equation: Equation): void;
+           remove(id: string): void;
+           destroy(): void;
+       }
+
+       /** The push observation surface of an {@link EquationManagerInterface} (AGENTS §13). */
+       export declare type EquationManagerEventMap = {
+           /** An equation was appended — carries its id. */
+           readonly append: readonly [id: string];
+           /** An equation was prepended — carries its id. */
+           readonly prepend: readonly [id: string];
+           /** An equation was replaced in place — carries its id. */
+           readonly replace: readonly [id: string];
+           /** An equation was removed — carries its id. */
+           readonly remove: readonly [id: string];
+           /** The manager was destroyed. */
+           readonly destroy: readonly [];
+       };
+
+       /**
+        * The {@link DefinitionBuilderInterface} manager over a symbolic definition's
+        * `equations` — a self-owning, kind-free collection manager.
+        *
+        * @remarks
+        * Equation order is strongly load-bearing — equations solve strictly in
+        * order and each rounded solution feeds forward.
+        */
+       export declare interface EquationManagerInterface {
+           readonly emitter: EmitterInterface<EquationManagerEventMap>;
+           set collection(value: readonly Equation[]);
+           equation(id: string): Equation | undefined;
+           equations(): readonly Equation[];
+           append(equation: Equation, target?: string): void;
+           prepend(equation: Equation, target?: string): void;
+           replace(equation: Equation): void;
+           remove(id: string): void;
+           destroy(): void;
+       }
+
+       /**
+        * Options for `createEquationManager` / the `EquationManager` constructor.
+        *
+        * @remarks
+        * `equations` — the initial collection (defaults to empty). `on` — initial
+        * event listeners (AGENTS §8). `error` — the emitter's listener-error handler
+        * (AGENTS §13).
+        */
+       export declare interface EquationManagerOptions {
+           readonly equations?: readonly Equation[];
+           readonly on?: EmitterHooks<EquationManagerEventMap>;
+           readonly error?: EmitterErrorHandler;
+       }
+
+       /**
+        * Evaluates {@link Check}s against subjects — the shared predicate engine of the
+        * quantitative and logical reasoners.
+        *
+        * @remarks
+        * 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
+        * range is `outside`). Fields resolve through the core `resolveField` — a string
+        * is ONE key, an array descends. Stateless and deterministic.
+        */
+       export declare class Evaluator implements EvaluatorInterface {
+           #private;
+           constructor(options?: EvaluatorOptions);
+           get id(): string;
+           evaluate(check: Check, subject: Subject): CheckResult;
+           batch(checks: readonly Check[], subject: Subject): readonly CheckResult[];
+       }
+
+       /** Default `id` for an `Evaluator`. */
+       export declare const EVALUATOR_ID = "evaluator";
+
+       /**
+        * Evaluates {@link Check}s against subjects.
+        *
+        * @remarks
+        * Total: `evaluate` never throws — an unknown operator surfaces as
+        * `CheckResult.error` with `met: false`, and errors are isolated per item in
+        * `batch`.
+        */
+       export declare interface EvaluatorInterface {
+           readonly id: string;
+           evaluate(check: Check, subject: Subject): CheckResult;
+           batch(checks: readonly Check[], subject: Subject): readonly CheckResult[];
+       }
+
+       /**
+        * Options for `createEvaluator` / the `Evaluator` constructor.
+        *
+        * @remarks
+        * `id` — the evaluator's identity string (defaults to `EVALUATOR_ID`).
+        */
+       export declare interface EvaluatorOptions {
+           readonly id?: string;
+       }
+
+       /** A boolean expression tree, discriminated by `form`. */
+       export declare type Expression = Atom | Compound;
+
+       /**
+        * Return every atom leaf of an expression tree, depth-first, left-to-right.
+        *
+        * @remarks
+        * 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
+        * pathologically deep expression trees; a hole in an `operands` array is skipped,
+        * matching `flatMap`'s hole-skipping behavior.
+        *
+        * @param expression - The expression tree to walk
+        * @returns A fresh, ordered list of the atom leaves
+        *
+        * @example
+        * ```ts
+        * import { atom, compound, extractAtoms } from '@src/core'
+        *
+        * extractAtoms(atom('a', 'equals', 1)).length                                   // 1
+        * extractAtoms(compound('and', [atom('a', 'equals', 1), atom('b', 'equals', 2)])).length // 2
+        * ```
+        */
+       export declare function extractAtoms(expression: Expression): readonly Atom[];
+
+       /**
+        * Flatten a logical conclusion expression into its asserted `field = value`
+        * pairs — connectives IGNORED.
+        *
+        * @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 just the same). Later operands WIN 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).
+        *
+        * @param expression - The conclusion expression to flatten
+        * @returns A fresh record of asserted `field → value` pairs
+        *
+        * @example
+        * ```ts
+        * import { atom, compound, extractConclusions } from '@src/core'
+        *
+        * extractConclusions(atom('adult', 'equals', true))                              // { adult: true }
+        * extractConclusions(compound('and', [atom('a', 'equals', 1), atom('b', 'equals', 2)])) // { a: 1, b: 2 }
+        * ```
+        */
+       export declare function extractConclusions(expression: Expression): Record<string, unknown>;
+
+       /**
+        * One fact: a `predicate` over positional `terms`.
+        *
+        * @remarks
+        * A string term starting with `?` is a unification variable (the prefix is
+        * part of its name). `confidence` is `0–1` and propagates multiplicatively
+        * through derivations (default `1`).
+        */
+       export declare interface Fact {
+           readonly id: string;
+           readonly predicate: string;
+           readonly terms: readonly unknown[];
+           readonly confidence?: number;
+       }
+
+       /**
+        * Build a {@link Fact} — a predicate over positional terms.
+        *
+        * @remarks
+        * `confidence` defaults to `1` (the key is always set). A string term starting
+        * with `?` is a unification variable.
+        *
+        * @param id - The fact id
+        * @param predicate - The predicate name
+        * @param terms - The positional terms
+        * @param confidence - The fact's confidence (`0–1`, defaults to `1`)
+        * @returns A fresh fact
+        *
+        * @example
+        * ```ts
+        * import { fact } from '@src/core'
+        *
+        * fact('f1', 'human', ['socrates'])        // confidence 1
+        * fact('f2', 'laysEggs', ['tweety'], 0.9)  // explicit confidence
+        * ```
+        */
+       export declare function fact(id: string, predicate: string, terms: readonly unknown[], confidence?: number): Fact;
+
+       /**
+        * The {@link FactManagerInterface} implementation — a self-owning, kind-free
+        * manager over an inferential definition's `facts`.
+        *
+        * @remarks
+        * OWNS its `#facts` collection as private copy-on-write state and its own
+        * {@link Emitter} 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. The write-only `collection`
+        * setter 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', …)`.
+        */
+       export declare class FactManager implements FactManagerInterface {
+           #private;
+           constructor(options?: FactManagerOptions);
+           get emitter(): EmitterInterface<FactManagerEventMap>;
+           set collection(value: readonly Fact[]);
+           fact(id: string): Fact | undefined;
+           facts(): readonly Fact[];
+           append(fact: Fact, target?: string): void;
+           prepend(fact: Fact, target?: string): void;
+           replace(fact: Fact): void;
+           remove(id: string): void;
+           destroy(): void;
+       }
+
+       /** The push observation surface of a {@link FactManagerInterface} (AGENTS §13). */
+       export declare type FactManagerEventMap = {
+           /** A fact was appended — carries its id. */
+           readonly append: readonly [id: string];
+           /** A fact was prepended — carries its id. */
+           readonly prepend: readonly [id: string];
+           /** A fact was replaced in place — carries its id. */
+           readonly replace: readonly [id: string];
+           /** A fact was removed — carries its id. */
+           readonly remove: readonly [id: string];
+           /** The manager was destroyed. */
+           readonly destroy: readonly [];
+       };
+
+       /**
+        * The {@link DefinitionBuilderInterface} manager over an inferential
+        * definition's `facts` — a self-owning, kind-free collection manager.
+        */
+       export declare interface FactManagerInterface {
+           readonly emitter: EmitterInterface<FactManagerEventMap>;
+           set collection(value: readonly Fact[]);
+           fact(id: string): Fact | undefined;
+           facts(): readonly Fact[];
+           append(fact: Fact, target?: string): void;
+           prepend(fact: Fact, target?: string): void;
+           replace(fact: Fact): void;
+           remove(id: string): void;
+           destroy(): void;
+       }
+
+       /**
+        * Options for `createFactManager` / the `FactManager` constructor.
+        *
+        * @remarks
+        * `facts` — the initial collection (defaults to empty). `on` — initial event
+        * listeners (AGENTS §8). `error` — the emitter's listener-error handler
+        * (AGENTS §13).
+        */
+       export declare interface FactManagerOptions {
+           readonly facts?: readonly Fact[];
+           readonly on?: EmitterHooks<FactManagerEventMap>;
+           readonly error?: EmitterErrorHandler;
+       }
+
+       /**
+        * 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 (default
+        * `0`, stable); `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;
+           readonly name: string;
+           readonly description?: string;
+           readonly source: Source;
+           readonly fallback?: number;
+           readonly checks?: readonly Check[];
+           readonly transforms?: readonly Transform[];
+           readonly bounds?: Bounds;
+           readonly weight?: number;
+           readonly priority?: number;
+           readonly enabled?: boolean;
+           readonly required?: boolean;
+       }
+
+       /**
+        * A group of factors aggregated into one value.
+        *
+        * @remarks
+        * The group value is `base` (default `0`) 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
+        * `applied: false`. A group with zero applied factors is excluded from the
+        * definition-level aggregation.
+        */
+       export declare interface FactorGroup {
+           readonly id: string;
+           readonly name: string;
+           readonly description?: string;
+           readonly factors: readonly Factor[];
+           readonly aggregation: Aggregation;
+           readonly base?: number;
+           readonly bounds?: Bounds;
+           readonly enabled?: boolean;
+           readonly strict?: boolean;
+       }
+
+       /**
+        * Build a {@link FactorGroup}.
+        *
+        * @remarks
+        * `name` defaults to the `id`; set `name`, `description`, `base`, `bounds`,
+        * `enabled`, or `strict` through `overrides`.
+        *
+        * @param id - The group id
+        * @param aggregation - How the applied factors' values reduce to one
+        * @param factors - The group's factors
+        * @param overrides - Optional {@link FactorGroup} fields merged over the defaults
+        * @returns A fresh factor group
+        *
+        * @example
+        * ```ts
+        * import { factorGroup, staticFactor } from '@src/core'
+        *
+        * factorGroup('g1', 'sum', [staticFactor('f1', 10)], { base: 100 })
+        * ```
+        */
+       export declare function factorGroup(id: string, aggregation: Aggregation, factors: readonly Factor[], overrides?: Partial<Omit<FactorGroup, 'id' | 'aggregation' | 'factors'>>): FactorGroup;
+
+       /**
+        * The {@link FactorManagerInterface} implementation — the sole 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
+        * group back via `groups.replace(…)`. A `groupId` naming no existing group
+        * throws `ReasonError('TARGET', …, { groupId })`. It still owns its OWN
+        * {@link Emitter} over {@link FactorManagerEventMap} (factor-id payloads).
+        * `destroy()` is idempotent and tears the emitter down LAST; any other call
+        * after it throws `ReasonError('DESTROYED', …)`.
+        */
+       export declare class FactorManager implements FactorManagerInterface {
+           #private;
+           constructor(groups: GroupManagerInterface, options?: FactorManagerOptions);
+           get emitter(): EmitterInterface<FactorManagerEventMap>;
+           factor(groupId: string, id: string): Factor | undefined;
+           factors(groupId: string): readonly Factor[];
+           append(groupId: string, factor: Factor, target?: string): void;
+           prepend(groupId: string, factor: Factor, target?: string): void;
+           replace(groupId: string, factor: Factor): void;
+           remove(groupId: string, id: string): void;
+           destroy(): void;
+       }
+
+       /** The push observation surface of a {@link FactorManagerInterface} (AGENTS §13). */
+       export declare type FactorManagerEventMap = {
+           /** A factor was appended — carries its id. */
+           readonly append: readonly [id: string];
+           /** A factor was prepended — carries its id. */
+           readonly prepend: readonly [id: string];
+           /** A factor was replaced in place — carries its id. */
+           readonly replace: readonly [id: string];
+           /** A factor was removed — carries its id. */
+           readonly remove: readonly [id: string];
+           /** The manager was destroyed. */
+           readonly destroy: readonly [];
+       };
+
+       /**
+        * The {@link DefinitionBuilderInterface} manager over a `FactorGroup`'s
+        * `factors`, threaded through the required `groupId` locator (a factor lives
+        * inside its group).
+        *
+        * @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
+        * 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
+        * payloads).
+        */
+       export declare interface FactorManagerInterface {
+           readonly emitter: EmitterInterface<FactorManagerEventMap>;
+           factor(groupId: string, id: string): Factor | undefined;
+           factors(groupId: string): readonly Factor[];
+           append(groupId: string, factor: Factor, target?: string): void;
+           prepend(groupId: string, factor: Factor, target?: string): void;
+           replace(groupId: string, factor: Factor): void;
+           remove(groupId: string, id: string): void;
+           destroy(): void;
+       }
+
+       /**
+        * Options for `createFactorManager` / the `FactorManager` constructor.
+        *
+        * @remarks
+        * The sibling `GroupManagerInterface` reference is a constructor argument, not
+        * an option. `on` — initial event listeners (AGENTS §8). `error` — the
+        * emitter's listener-error handler (AGENTS §13).
+        */
+       export declare interface FactorManagerOptions {
+           readonly on?: EmitterHooks<FactorManagerEventMap>;
+           readonly error?: EmitterErrorHandler;
+       }
+
+       /** One band of a {@link RangeSource} — an optional inclusive bounds test and the value it yields. */
+       export declare interface FactorRange {
+           readonly bounds?: Bounds;
+           readonly value: number;
+       }
+
+       /**
+        * One factor's evaluation outcome.
+        *
+        * @remarks
+        * `raw` is the resolved source value before transforms / clamping (absent when
+        * the source never resolved); `checks` is present only when the factor
+        * declared checks and they gated it out. An unapplied factor carries
+        * `value: 0`.
+        */
+       export declare interface FactorResult {
+           readonly id: string;
+           readonly applied: boolean;
+           readonly value: number;
+           readonly raw?: number;
+           readonly checks?: readonly CheckResult[];
+       }
+
+       /**
+        * Derive a fact's predicate+arity bucket key — length-prefixed so the
+        * delimiter cannot be forged.
+        *
+        * @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
+        * 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
+        * predicate string embedding the `' '` delimiter can never be mistaken for a
+        * different predicate+arity pairing; `terms.length` is always a plain
+        * non-negative integer (never itself contains a space) so it needs no prefix.
+        *
+        * @param source - The fact (or premise pattern) to key
+        * @returns The predicate+arity key string
+        *
+        * @example
+        * ```ts
+        * import { fact, factToArityKey } from '@src/core'
+        *
+        * factToArityKey(fact('a', 'human', ['x']))          // arity 1
+        * factToArityKey(fact('b', 'human', ['x', 'y'])) // arity 2 — distinct key
+        * ```
+        */
+       export declare function factToArityKey(source: Fact): string;
+
+       /**
+        * Derive a fact's canonical dedup key — predicate + arity + per-term
+        * SameValueZero identity (confidence is NOT part of 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`)
+        * 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).
+        *
+        * @param source - The fact to key
+        * @param identities - The reference-identity map threaded across the dedupe pass (see {@link termToKey})
+        * @returns The fact's canonical key string
+        *
+        * @example
+        * ```ts
+        * import { fact, factToKey } from '@src/core'
+        *
+        * const identities = new Map<object, number>()
+        * // Same predicate + terms → same key regardless of confidence:
+        * factToKey(fact('a', 'p', ['x'], 1), identities) === factToKey(fact('b', 'p', ['x'], 0.5), identities)
+        * ```
+        */
+       export declare function factToKey(source: Fact, identities: Map<object, number>): string;
+
+       /**
+        * Build a {@link Factor} over a field {@link Source}.
+        *
+        * @param id - The factor id
+        * @param field - The subject field to resolve as a number
+        * @param overrides - Optional {@link Factor} fields merged over the defaults
+        * @returns A fresh factor
+        *
+        * @example
+        * ```ts
+        * import { fieldFactor, transform } from '@src/core'
+        *
+        * fieldFactor('income-score', 'income', { transforms: [transform('divide', 1000)], fallback: 0 })
+        * ```
+        */
+       export declare function fieldFactor(id: string, field: FieldPath, overrides?: Partial<Omit<Factor, 'id' | 'source'>>): Factor;
+
+       /**
+        * A factor source reading a subject field as a number.
+        *
+        * @remarks
+        * The field is coerced with the contracts `parseNumber` — a finite number
+        * passes through, a numeric string coerces, and everything else (including
+        * `NaN` / `±Infinity`) is unresolvable, falling back to the factor's
+        * `fallback`.
+        */
+       export declare interface FieldSource {
+           readonly origin: 'field';
+           readonly field: FieldPath;
+       }
+
+       /**
+        * Build a field {@link Source} — a subject field read as a number.
+        *
+        * @param field - The subject field to resolve
+        * @returns A fresh field source
+        *
+        * @example
+        * ```ts
+        * import { fieldSource } from '@src/core'
+        *
+        * fieldSource(['profile', 'score']) // descends into nested objects
+        * ```
+        */
+       export declare function fieldSource(field: FieldPath): Source;
+
+       /**
+        * Collect 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
+        * permissive about duplicates (first/last-wins artifacts) — this helper only
+        * surfaces them.
+        *
+        * @param items - The id-carrying items to scan
+        * @returns The duplicated ids, once each
+        *
+        * @example
+        * ```ts
+        * import { findDuplicates } from '@src/core'
+        *
+        * findDuplicates([{ id: 'a' }, { id: 'b' }, { id: 'a' }, { id: 'a' }]) // ['a']
+        * ```
+        */
+       export declare function findDuplicates(items: readonly {
+           readonly id: string;
+       }[]): readonly string[];
+
+       /**
+        * 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`.
+        *
+        * @remarks
+        * 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
+        * `formatField(check.field)` — an array `FieldPath` dot-joins into one string
+        * key. A premise that reads the same field via a DOTTED-STRING path resolves
+        * that flat key correctly, but a premise that reads it via 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
+        * each, authored order), then returns the ones that also appear as the
+        * flattened key of some array-path premise atom anywhere in `rules` — a
+        * single pass over every rule's conclusion and premise atoms, so the cost is
+        * linear in total atom count, never quadratic.
+        *
+        * @param rules - The rules to scan for the array-path write/read overlap
+        * @returns The mismatched overlay keys, once each, authored order
+        *
+        * @example
+        * ```ts
+        * import { atom, findOverlayMismatches, rule } from '@src/core'
+        *
+        * findOverlayMismatches([
+        * 	rule('a', [], atom(['address', 'city'], 'equals', 'NYC')),
+        * 	rule('b', [atom(['address', 'city'], 'equals', 'NYC')], atom('eligible', 'equals', true)),
+        * ]) // ['address.city']
+        * ```
+        */
+       export declare function findOverlayMismatches(rules: readonly Rule[]): readonly string[];
+
+       /**
+        * The `'?'`-prefixed variables an inference's conclusion introduces that no
+        * premise binds.
+        *
+        * @remarks
+        * The authoring-time footgun probe behind `InferentialReasoner.validate`'s
+        * unbound-variable warning: backward proving establishes each premise
+        * independently with no cross-premise binding consistency, so a conclusion
+        * term that no premise's `terms` ever names stays uninstantiated in the
+        * derived fact. Gathers the `?`-prefixed string terms of `conclusion.terms`,
+        * subtracts every `?`-prefixed string term appearing in any premise's
+        * `terms`, and returns the remainder once each, in the conclusion's authored
+        * order.
+        *
+        * @param source - The inference whose conclusion is checked against its premises
+        * @returns The unbound conclusion variable names, once each, authored order
+        *
+        * @example
+        * ```ts
+        * import { fact, findUnboundVariables, inference } from '@src/core'
+        *
+        * findUnboundVariables(
+        * 	inference('i', 'I', [fact('p', 'human', ['?x'])], fact('c', 'mortal', ['?x', '?y'])),
+        * ) // ['?y'] — '?x' is bound by the premise, '?y' is not
+        * ```
+        */
+       export declare function findUnboundVariables(source: Inference): readonly string[];
+
+       /**
+        * Format a {@link FieldPath} for display — the single string key itself, or the
+        * array segments joined with `.`.
+        *
+        * @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).
+        *
+        * @param field - The field path to format
+        * @returns The display string
+        *
+        * @example
+        * ```ts
+        * formatField('age')               // 'age'
+        * formatField(['address', 'city']) // 'address.city'
+        * ```
+        */
+       export declare function formatField(field: FieldPath): string;
+
+       /**
+        * The {@link GroupManagerInterface} implementation — a self-owning, kind-free
+        * manager over a quantitative definition's `groups`.
+        *
+        * @remarks
+        * OWNS its `#groups` collection as private copy-on-write state and its own
+        * {@link Emitter} over {@link GroupManagerEventMap}. Every write verb delegates
+        * to the matching collection-level pure helper ({@link appendById} etc.),
+        * reassigns the fresh array, then emits (the affected group id) AFTER the
+        * mutation. The write-only `collection` setter 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', …)`.
+        */
+       export declare class GroupManager implements GroupManagerInterface {
+           #private;
+           constructor(options?: GroupManagerOptions);
+           get emitter(): EmitterInterface<GroupManagerEventMap>;
+           set collection(value: readonly FactorGroup[]);
+           group(id: string): FactorGroup | undefined;
+           groups(): readonly FactorGroup[];
+           append(group: FactorGroup, target?: string): void;
+           prepend(group: FactorGroup, target?: string): void;
+           replace(group: FactorGroup): void;
+           remove(id: string): void;
+           destroy(): void;
+       }
+
+       /** The push observation surface of a {@link GroupManagerInterface} (AGENTS §13). */
+       export declare type GroupManagerEventMap = {
+           /** A group was appended — carries its id. */
+           readonly append: readonly [id: string];
+           /** A group was prepended — carries its id. */
+           readonly prepend: readonly [id: string];
+           /** A group was replaced in place — carries its id. */
+           readonly replace: readonly [id: string];
+           /** A group was removed — carries its id. */
+           readonly remove: readonly [id: string];
+           /** The manager was destroyed. */
+           readonly destroy: readonly [];
+       };
+
+       /**
+        * The {@link DefinitionBuilderInterface} manager over a quantitative
+        * definition's `groups` — a self-owning, kind-free collection manager.
+        *
+        * @remarks
+        * `append` / `prepend` place a group relative to an optional `target` id (a
+        * naming miss throws `ReasonError('TARGET', …)`); `replace` swaps a same-id
+        * group in place; `remove` filters a group out (no-op when absent).
+        */
+       export declare interface GroupManagerInterface {
+           readonly emitter: EmitterInterface<GroupManagerEventMap>;
+           set collection(value: readonly FactorGroup[]);
+           group(id: string): FactorGroup | undefined;
+           groups(): readonly FactorGroup[];
+           append(group: FactorGroup, target?: string): void;
+           prepend(group: FactorGroup, target?: string): void;
+           replace(group: FactorGroup): void;
+           remove(id: string): void;
+           destroy(): void;
+       }
+
+       /**
+        * Options for `createGroupManager` / the `GroupManager` constructor.
+        *
+        * @remarks
+        * `groups` — the initial collection (defaults to empty). `on` — initial event
+        * listeners (AGENTS §8). `error` — the emitter's listener-error handler
+        * (AGENTS §13).
+        */
+       export declare interface GroupManagerOptions {
+           readonly groups?: readonly FactorGroup[];
+           readonly on?: EmitterHooks<GroupManagerEventMap>;
+           readonly error?: EmitterErrorHandler;
+       }
+
+       /**
+        * One group's evaluation outcome — its clamped value and the per-factor
+        * results (disabled factors omitted entirely).
+        *
+        * @remarks
+        * 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 finite check.
+        */
+       export declare interface GroupResult {
+           readonly id: string;
+           readonly applied: boolean;
+           readonly value: number;
+           readonly factors: readonly FactorResult[];
+       }
+
+       /**
+        * Bucket facts by predicate+arity, preserving append order within each bucket.
+        *
+        * @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
+        * 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"
+        * scan finds the same fact a full linear pass would.
+        *
+        * @param facts - The facts to index
+        * @returns A fresh `Map` from {@link factToArityKey} to its facts, in append order
+        *
+        * @example
+        * ```ts
+        * import { fact, indexByArity } from '@src/core'
+        *
+        * const index = indexByArity([fact('a', 'human', ['x']), fact('b', 'human', ['y'])])
+        * index.get(factToArityKey(fact('c', 'human', ['z'])))?.length // 2
+        * ```
+        */
+       export declare function indexByArity(facts: readonly Fact[]): Map<string, Fact[]>;
+
+       /**
+        * One inference rule: when every premise pattern unifies against known facts
+        * (with consistent variable bindings), the instantiated `conclusion` is
+        * derived.
+        *
+        * @remarks
+        * A derived fact's confidence is the product of its matched premise facts'
+        * confidences times the inference's own `confidence` (default `1`), rounded to
+        * four decimal places. `enabled: false` skips the inference silently.
+        */
+       export declare interface Inference {
+           readonly id: string;
+           readonly name: string;
+           readonly description?: string;
+           readonly premises: readonly Fact[];
+           readonly conclusion: Fact;
+           readonly confidence?: number;
+           readonly enabled?: boolean;
+       }
+
+       /**
+        * Build an {@link Inference} — premise patterns and a conclusion pattern.
+        *
+        * @remarks
+        * `name` defaults to the `id`; set `name`, `description`, `confidence`, or
+        * `enabled` through `overrides`.
+        *
+        * @param id - The inference id
+        * @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
+        *
+        * @example
+        * ```ts
+        * import { fact, inference } from '@src/core'
+        *
+        * inference('mortal', [fact('p1', 'human', ['?x'])], fact('c1', 'mortal', ['?x']), { confidence: 0.8 })
+        * ```
+        */
+       export declare function inference(id: string, premises: readonly Fact[], conclusion: Fact, overrides?: Partial<Omit<Inference, 'id' | 'premises' | 'conclusion'>>): Inference;
+
+       /**
+        * The {@link InferenceManagerInterface} implementation — a self-owning,
+        * kind-free manager over an inferential definition's `inferences`.
+        *
+        * @remarks
+        * OWNS its `#inferences` collection as private copy-on-write state and its own
+        * {@link Emitter} over {@link InferenceManagerEventMap}. Inference order is
+        * LOAD-BEARING — backward proving iterates in declaration order and returns on
+        * first success. The write-only `collection` setter 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', …)`.
+        */
+       export declare class InferenceManager implements InferenceManagerInterface {
+           #private;
+           constructor(options?: InferenceManagerOptions);
+           get emitter(): EmitterInterface<InferenceManagerEventMap>;
+           set collection(value: readonly Inference[]);
+           inference(id: string): Inference | undefined;
+           inferences(): readonly Inference[];
+           append(inference: Inference, target?: string): void;
+           prepend(inference: Inference, target?: string): void;
+           replace(inference: Inference): void;
+           remove(id: string): void;
+           destroy(): void;
+       }
+
+       /** The push observation surface of an {@link InferenceManagerInterface} (AGENTS §13). */
+       export declare type InferenceManagerEventMap = {
+           /** An inference was appended — carries its id. */
+           readonly append: readonly [id: string];
+           /** An inference was prepended — carries its id. */
+           readonly prepend: readonly [id: string];
+           /** An inference was replaced in place — carries its id. */
+           readonly replace: readonly [id: string];
+           /** An inference was removed — carries its id. */
+           readonly remove: readonly [id: string];
+           /** The manager was destroyed. */
+           readonly destroy: readonly [];
+       };
+
+       /**
+        * The {@link DefinitionBuilderInterface} manager over an inferential
+        * definition's `inferences` — a self-owning, kind-free collection manager.
+        *
+        * @remarks
+        * Inference order is load-bearing — backward proving iterates in declaration
+        * order and returns on first success.
+        */
+       export declare interface InferenceManagerInterface {
+           readonly emitter: EmitterInterface<InferenceManagerEventMap>;
+           set collection(value: readonly Inference[]);
+           inference(id: string): Inference | undefined;
+           inferences(): readonly Inference[];
+           append(inference: Inference, target?: string): void;
+           prepend(inference: Inference, target?: string): void;
+           replace(inference: Inference): void;
+           remove(id: string): void;
+           destroy(): void;
+       }
+
+       /**
+        * Options for `createInferenceManager` / the `InferenceManager` constructor.
+        *
+        * @remarks
+        * `inferences` — the initial collection (defaults to empty). `on` — initial
+        * event listeners (AGENTS §8). `error` — the emitter's listener-error handler
+        * (AGENTS §13).
+        */
+       export declare interface InferenceManagerOptions {
+           readonly inferences?: readonly Inference[];
+           readonly on?: EmitterHooks<InferenceManagerEventMap>;
+           readonly error?: EmitterErrorHandler;
+       }
+
+       /** Default `id` for an `InferentialReasoner`. */
+       export declare const INFERENTIAL_ID = "inferential";
+
+       /**
+        * An inferential (fact-derivation) definition.
+        *
+        * @remarks
+        * `facts` is the base knowledge; scalar subject fields are additionally
+        * injected as `has(key, value)` facts. `strategy` picks a forward fixpoint
+        * (derive everything) or backward proving (first provable conclusion wins,
+        * returning a proof tree); `depth` caps iterations / recursion (default `10`).
+        */
+       export declare interface InferentialDefinition {
+           readonly reasoning: 'inferential';
+           readonly id: string;
+           readonly name: string;
+           readonly description?: string;
+           readonly inferences: readonly Inference[];
+           readonly facts: readonly Fact[];
+           readonly strategy: ChainingStrategy;
+           readonly depth?: number;
+       }
+
+       /**
+        * Build an {@link InferentialDefinition}.
+        *
+        * @remarks
+        * `strategy` defaults to `'forward'`; set `strategy`, `description`, or `depth`
+        * through `overrides`.
+        *
+        * @param id - The definition id
+        * @param name - The display name
+        * @param facts - The base knowledge
+        * @param inferences - The inference rules
+        * @param overrides - Optional {@link InferentialDefinition} fields merged over the defaults
+        * @returns A fresh inferential definition
+        *
+        * @example
+        * ```ts
+        * import { fact, inference, inferentialDefinition } from '@src/core'
+        *
+        * inferentialDefinition('mortality', 'Mortality', [fact('f1', 'human', ['socrates'])], [
+        * 	inference('mortal', [fact('p1', 'human', ['?x'])], fact('c1', 'mortal', ['?x'])),
+        * ])
+        * ```
+        */
+       export declare function inferentialDefinition(id: string, name: string, facts: readonly Fact[], inferences: readonly Inference[], overrides?: Partial<Omit<InferentialDefinition, 'reasoning' | 'id' | 'name' | 'facts' | 'inferences'>>): InferentialDefinition;
+
+       /**
+        * The inferential reasoner — fact derivation with unification variables and
+        * proof trees.
+        *
+        * @remarks
+        * A string term starting with `?` is a unification variable — matching is
+        * 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
+        * `has(key, value)` facts. Forward chaining is a naive fixpoint capped at
+        * `depth` iterations: every consistent premise unification derives the
+        * instantiated conclusion, with confidence = Π matched premise-fact confidences
+        * × the inference's own `confidence`, rounded to four decimal places, and
+        * 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)
+        * plus its {@link ProofNode} tree; recursion is guarded only by the depth cap.
+        * Deriving nothing is still success. Nothing mutates its inputs; fully
+        * deterministic (AGENTS §11).
+        */
+       export declare class InferentialReasoner implements ReasonerInterface {
+           #private;
+           constructor(options?: InferentialReasonerOptions);
+           get id(): string;
+           get reasoning(): Reasoning;
+           supports(definition: Definition): boolean;
+           validate(definition: Definition): ReasonValidationResult;
+           reason(subject: Subject, definition: Definition): ReasonResult;
+       }
+
+       /**
+        * Options for `createInferentialReasoner` / the `InferentialReasoner`
+        * constructor.
+        *
+        * @remarks
+        * `id` — the reasoner's identity string (defaults to `INFERENTIAL_ID`).
+        */
+       export declare interface InferentialReasonerOptions {
+           readonly id?: string;
+       }
+
+       /**
+        * The outcome of inferential reasoning.
+        *
+        * @remarks
+        * `derived` lists the newly derived facts (deriving nothing is still success);
+        * `proof` is produced only by the backward strategy, and only when a
+        * conclusion was proved.
+        */
+       export declare interface InferentialResult {
+           readonly reasoning: 'inferential';
+           readonly derived: readonly Fact[];
+           readonly proof?: ProofNode;
+           readonly success: boolean;
+           readonly trace: readonly string[];
+           readonly errors: readonly string[];
+       }
+
+       /**
+        * Substitute a fact's bound `'?'`-variables with their values — a fresh fact
+        * with unbound terms passed through unchanged.
+        *
+        * @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
+        * returned fact is a fresh copy (`{ ...fact, terms }`) — the input is never
+        * mutated (AGENTS §11).
+        *
+        * @param source - The fact (or pattern) to instantiate
+        * @param bindings - The variable bindings to apply
+        * @returns A fresh fact with bound variables substituted
+        *
+        * @example
+        * ```ts
+        * import { fact, instantiateFact } from '@src/core'
+        *
+        * instantiateFact(fact('c', 'mortal', ['?x']), { '?x': 'socrates' }).terms // ['socrates']
+        * ```
+        */
+       export declare function instantiateFact(source: Fact, bindings: Record<string, unknown>): Fact;
+
+       /**
+        * The math operations the symbolic reasoner can invert while isolating a
+        * target variable — anything else (a `power`, an `abs`) fails the equation
+        * with a non-invertible error.
+        */
+       export declare const INVERTIBLE_OPERATIONS: ReadonlySet<MathOperation>;
+
+       /**
+        * Invert 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
+        * to subtraction, `subtract` to addition, `multiply` to division, `divide` to
+        * multiplication. Inversion by zero yields `NaN` (never a throw) — a `multiply`
+        * with a zero `right` has no unique solution, and `x / 0 = value` has none
+        * either, so both surface `NaN` for the non-finite check to report rather than a
+        * bogus value. A non-invertible operator throws (caught per equation upstream).
+        *
+        * @param operator - The math operation to invert
+        * @param value - The known result of `x op right`
+        * @param rightValue - The known right operand
+        * @returns The isolated left operand (`NaN` on a zero-division inverse)
+        *
+        * @example
+        * ```ts
+        * import { invertLeft } from '@src/core'
+        *
+        * invertLeft('add', 10, 3)      // 7  — x + 3 = 10
+        * invertLeft('multiply', 10, 0) // NaN — x * 0 = 10 has no solution
+        * ```
+        */
+       export declare function invertLeft(operator: MathOperation, value: number, rightValue: number): number;
+
+       /**
+        * Invert 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
+        * to `value - left`, `subtract` to `left - value`, `multiply` to `value / left`
+        * (with a zero `left` yielding `NaN`), `divide` to `left / value` (with a zero
+        * `value` yielding `NaN`). Inversion by zero yields `NaN`, never a throw; a
+        * non-invertible operator throws (caught per equation upstream).
+        *
+        * @param operator - The math operation to invert
+        * @param value - The known result of `left op x`
+        * @param leftValue - The known left operand
+        * @returns The isolated right operand (`NaN` on a zero-division inverse)
+        *
+        * @example
+        * ```ts
+        * import { invertRight } from '@src/core'
+        *
+        * invertRight('subtract', 4, 10) // 6  — 10 - x = 4
+        * invertRight('divide', 0, 10)   // NaN — 10 / x = 0 has no finite solution
+        * ```
+        */
+       export declare function invertRight(operator: MathOperation, value: number, leftValue: number): number;
+
+       /**
+        * Determine whether a value is an {@link Aggregation} literal.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is one of the five aggregations
+        *
+        * @example
+        * ```ts
+        * import { isAggregation } from '@src/core'
+        *
+        * isAggregation('sum')    // true
+        * isAggregation('median') // false
+        * ```
+        */
+       export declare const isAggregation: Guard<Aggregation>;
+
+       /**
+        * Determine whether a value is a {@link Bounds} — an inclusive numeric clamp.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed bounds record (both sides optional)
+        *
+        * @example
+        * ```ts
+        * import { isBounds } from '@src/core'
+        *
+        * isBounds({ minimum: 0, maximum: 100 }) // true
+        * isBounds({})                           // true — unbounded
+        * isBounds({ minimum: NaN })             // false — non-finite
+        * ```
+        */
+       export declare function isBounds(value: unknown): value is Bounds;
+
+       /**
+        * Determine whether a value is a {@link ChainingStrategy} literal.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is `'forward'` or `'backward'`
+        *
+        * @example
+        * ```ts
+        * import { isChainingStrategy } from '@src/core'
+        *
+        * isChainingStrategy('forward') // true
+        * isChainingStrategy('upward')  // false
+        * ```
+        */
+       export declare const isChainingStrategy: Guard<ChainingStrategy>;
+
+       /**
+        * Determine whether a value is a {@link Check} — a field / operator / value
+        * 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.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed check
+        *
+        * @example
+        * ```ts
+        * import { isCheck } from '@src/core'
+        *
+        * isCheck({ field: 'age', operator: 'above', value: 18 }) // true
+        * isCheck({ field: 'age', operator: 'over', value: 18 })  // false — unknown operator
+        * ```
+        */
+       export declare function isCheck(value: unknown): value is Check;
+
+       /**
+        * Determine whether a value is a {@link Comparison} literal.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is one of the ten comparison operators
+        *
+        * @example
+        * ```ts
+        * import { isComparison } from '@src/core'
+        *
+        * isComparison('between')     // true
+        * isComparison('greaterThan') // false — the operator vocabulary is single-word
+        * ```
+        */
+       export declare const isComparison: Guard<Comparison>;
+
+       /**
+        * Determine whether a value is a {@link Definition} — any of the four
+        * definition shapes, discriminated by `reasoning`.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed definition of any reasoning
+        *
+        * @example
+        * ```ts
+        * import { isDefinition, logicalDefinition } from '@src/core'
+        *
+        * isDefinition(logicalDefinition('eligibility', 'Eligibility', [])) // true
+        * isDefinition({ reasoning: 'quantum' })                            // false
+        * ```
+        */
+       export declare function isDefinition(value: unknown): value is Definition;
+
+       /**
+        * Determine 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`, AGENTS §14): a plain subject
+        * is an open record whose values may legally be functions, so a
+        * 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
+        * non-object, a missing brand, or a hostile prototype all return `false`,
+        * never throw.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` carries the `DefinitionBuilder` entity brand
+        *
+        * @example
+        * ```ts
+        * import { createDefinitionBuilder, isDefinitionBuilder, quantitativeDefinition } from '@src/core'
+        *
+        * const definition = createDefinitionBuilder(quantitativeDefinition('risk', 'Risk', []))
+        * isDefinitionBuilder(definition)                       // true
+        * isDefinitionBuilder({ build: () => undefined })       // false — forged build field
+        * isDefinitionBuilder(quantitativeDefinition('r', 'R', []))  // false — plain data, not the entity
+        * ```
+        */
+       export declare function isDefinitionBuilder(value: unknown): value is DefinitionBuilderInterface;
+
+       /**
+        * Determine whether a value is an {@link Equation} — `left = right`, solved for
+        * `target`.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed equation
+        *
+        * @example
+        * ```ts
+        * import { constant, equation, isEquation, variable } from '@src/core'
+        *
+        * isEquation(equation('e1', variable('x'), constant(42), 'x')) // true
+        * isEquation({ id: 'e1', target: 'x' })                        // false — sides missing
+        * ```
+        */
+       export declare function isEquation(value: unknown): value is Equation;
+
+       /**
+        * Determine whether a value is an {@link Expression} — a boolean expression
+        * tree of atoms and compounds, discriminated by `form`.
+        *
+        * @remarks
+        * Recursive through `lazyOf` (AGENTS §14) — recursion is STACK-BOUNDED, 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
+        * bound is rejected, not validated.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed expression tree
+        *
+        * @example
+        * ```ts
+        * import { atom, compound, isExpression } from '@src/core'
+        *
+        * isExpression(atom('age', 'from', 18))                    // true
+        * isExpression(compound('and', [atom('age', 'from', 18)])) // true
+        * isExpression({ form: 'compound', operator: 'and' })      // false — operands missing
+        * ```
+        */
+       export declare function isExpression(value: unknown): value is Expression;
+
+       /**
+        * Determine whether a value is a {@link Fact} — a predicate over positional
+        * terms.
+        *
+        * @remarks
+        * `terms` elements are unconstrained (`unknown`) — a `'?'`-prefixed string term
+        * is a unification variable, anything else a constant.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed fact
+        *
+        * @example
+        * ```ts
+        * import { isFact } from '@src/core'
+        *
+        * isFact({ id: 'f1', predicate: 'human', terms: ['socrates'] }) // true
+        * isFact({ id: 'f1', predicate: 'human' })                      // false — terms missing
+        * ```
+        */
+       export declare function isFact(value: unknown): value is Fact;
+
+       /**
+        * Determine whether a value is a {@link Factor} — one scored input of a
+        * quantitative group.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed factor
+        *
+        * @example
+        * ```ts
+        * import { isFactor } from '@src/core'
+        *
+        * isFactor({ id: 'age', name: 'Age', source: { origin: 'field', field: 'age' } }) // true
+        * isFactor({ id: 'age', name: 'Age' })                                            // false — no source
+        * ```
+        */
+       export declare function isFactor(value: unknown): value is Factor;
+
+       /**
+        * Determine whether a value is a {@link FactorGroup} — a group of factors
+        * aggregated into one value.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed factor group
+        *
+        * @example
+        * ```ts
+        * import { isFactorGroup, staticFactor } from '@src/core'
+        *
+        * isFactorGroup({ id: 'g1', name: 'g1', aggregation: 'sum', factors: [staticFactor('f1', 10)] }) // true
+        * isFactorGroup({ id: 'g1', name: 'g1', aggregation: 'median', factors: [] })                    // false
+        * ```
+        */
+       export declare function isFactorGroup(value: unknown): value is FactorGroup;
+
+       /**
+        * Determine whether a value is a {@link FactorRange} — one band of a range
+        * source.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed factor range
+        *
+        * @example
+        * ```ts
+        * import { isFactorRange } from '@src/core'
+        *
+        * isFactorRange({ bounds: { maximum: 25 }, value: 1.5 }) // true
+        * isFactorRange({ value: 42 })                           // true — a catch-all band
+        * ```
+        */
+       export declare function isFactorRange(value: unknown): value is FactorRange;
+
+       /**
+        * Determine whether a value is a {@link FieldPath} — a single string key or an
+        * array of keys descending into nested objects.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a string or an array of strings
+        *
+        * @example
+        * ```ts
+        * import { isFieldPath } from '@src/core'
+        *
+        * isFieldPath('age')               // true — ONE key (never dot-split)
+        * isFieldPath(['address', 'city']) // true — descends
+        * isFieldPath(42)                  // false
+        * ```
+        */
+       export declare const isFieldPath: Guard<FieldPath>;
+
+       /**
+        * Determine whether a value is an {@link Inference} — premise patterns and a
+        * conclusion pattern.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed inference
+        *
+        * @example
+        * ```ts
+        * import { fact, inference, isInference } from '@src/core'
+        *
+        * isInference(inference('mortal', [fact('p1', 'human', ['?x'])], fact('c1', 'mortal', ['?x']))) // true
+        * isInference({ id: 'mortal' })                                                                 // false
+        * ```
+        */
+       export declare function isInference(value: unknown): value is Inference;
+
+       /**
+        * Determine whether a value is an {@link InferentialDefinition}.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed inferential definition
+        *
+        * @example
+        * ```ts
+        * import { inferentialDefinition, isInferentialDefinition } from '@src/core'
+        *
+        * isInferentialDefinition(inferentialDefinition('birds', 'Birds', [], [])) // true
+        * isInferentialDefinition({ reasoning: 'inferential', id: 'birds' })       // false
+        * ```
+        */
+       export declare function isInferentialDefinition(value: unknown): value is InferentialDefinition;
+
+       /**
+        * Determine whether a value is a {@link LogicalDefinition}.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed logical definition
+        *
+        * @example
+        * ```ts
+        * import { isLogicalDefinition, logicalDefinition } from '@src/core'
+        *
+        * isLogicalDefinition(logicalDefinition('eligibility', 'Eligibility', [])) // true
+        * isLogicalDefinition({ reasoning: 'logical', id: 'eligibility' })         // false
+        * ```
+        */
+       export declare function isLogicalDefinition(value: unknown): value is LogicalDefinition;
+
+       /**
+        * Determine whether a value is a {@link LogicalOperator} literal.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is one of the five logical connectives
+        *
+        * @example
+        * ```ts
+        * import { isLogicalOperator } from '@src/core'
+        *
+        * isLogicalOperator('implies') // true
+        * isLogicalOperator('nand')    // false
+        * ```
+        */
+       export declare const isLogicalOperator: Guard<LogicalOperator>;
+
+       /**
+        * Determine whether a value is a {@link MathOperation} literal.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is one of the thirteen math operations
+        *
+        * @example
+        * ```ts
+        * import { isMathOperation } from '@src/core'
+        *
+        * isMathOperation('multiply') // true
+        * isMathOperation('modulo')   // false
+        * ```
+        */
+       export declare const isMathOperation: Guard<MathOperation>;
+
+       /**
+        * Determine whether a value is a record whose every value is a finite number —
+        * the shape of a `LookupSource.table` and a `SymbolicDefinition.variables`.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a plain record of finite numbers
+        *
+        * @example
+        * ```ts
+        * import { isNumberRecord } from '@src/core'
+        *
+        * isNumberRecord({ CA: 1.2, NY: 0.8 }) // true
+        * isNumberRecord({ CA: '1.2' })        // false — strings do not coerce here
+        * ```
+        */
+       export declare const isNumberRecord: Guard<Readonly<Record<string, number>>>;
+
+       /**
+        * Determine whether a value is a {@link QuantitativeDefinition}.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed quantitative definition
+        *
+        * @example
+        * ```ts
+        * import { isQuantitativeDefinition, quantitativeDefinition } from '@src/core'
+        *
+        * isQuantitativeDefinition(quantitativeDefinition('risk', 'Risk', [])) // true
+        * isQuantitativeDefinition({ reasoning: 'quantitative', id: 'risk' })  // false
+        * ```
+        */
+       export declare function isQuantitativeDefinition(value: unknown): value is QuantitativeDefinition;
+
+       /**
+        * Narrow an unknown caught value to a {@link ReasonError}.
+        *
+        * @param value - The value to test (typically a `catch` binding)
+        * @returns `true` when `value` is a {@link ReasonError}
+        *
+        * @example
+        * ```ts
+        * try {
+        * 	reason.reason(subject, definition)
+        * } catch (error) {
+        * 	if (isReasonError(error) && error.code === 'MISSING') registerFallback()
+        * }
+        * ```
+        */
+       export declare function isReasonError(value: unknown): value is ReasonError;
+
+       /**
+        * Determine whether a value is a {@link Reasoning} literal.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is one of the four reasoning strategies
+        *
+        * @example
+        * ```ts
+        * import { isReasoning } from '@src/core'
+        *
+        * isReasoning('logical') // true
+        * isReasoning('fuzzy')   // false
+        * ```
+        */
+       export declare const isReasoning: Guard<Reasoning>;
+
+       /**
+        * Determine whether a value is a {@link Rule} — premises and a conclusion.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed rule
+        *
+        * @example
+        * ```ts
+        * import { atom, isRule, rule } from '@src/core'
+        *
+        * isRule(rule('adult', [atom('age', 'from', 18)], atom('adult', 'equals', true))) // true
+        * isRule({ id: 'adult' })                                                         // false
+        * ```
+        */
+       export declare function isRule(value: unknown): value is Rule;
+
+       /**
+        * Determine whether a value is a {@link Source} — any of the four factor
+        * sources, discriminated by `origin`.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed static / field / lookup / range source
+        *
+        * @example
+        * ```ts
+        * import { isSource } from '@src/core'
+        *
+        * isSource({ origin: 'static', value: 42 })                        // true
+        * isSource({ origin: 'lookup', field: 'state', table: { CA: 5 } }) // true
+        * isSource({ origin: 'random' })                                   // false
+        * ```
+        */
+       export declare function isSource(value: unknown): value is Source;
+
+       /**
+        * Determine whether a value is a `Subject` — a plain record of fields to reason
+        * about.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a plain record (arrays and class instances fail)
+        *
+        * @example
+        * ```ts
+        * import { isSubject } from '@src/core'
+        *
+        * isSubject({ age: 30 }) // true
+        * isSubject([1, 2, 3])   // false — an array is not a subject
+        * ```
+        */
+       export declare const isSubject: Guard<Readonly<Record<string, unknown>>>;
+
+       /**
+        * Determine 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`, AGENTS §14), distinct from
+        * {@link isDefinitionBuilder} — the two entities can never match each other's
+        * guard. Total: a non-object, a missing brand, or a hostile prototype all
+        * return `false`, never throw.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` carries the `SubjectBuilder` entity brand
+        *
+        * @example
+        * ```ts
+        * import { createSubjectBuilder, isSubjectBuilder } from '@src/core'
+        *
+        * const subject = createSubjectBuilder({ id: 's1', age: 30 })
+        * isSubjectBuilder(subject)               // true
+        * isSubjectBuilder({ build: () => ({}) }) // false — forged build field
+        * isSubjectBuilder({ id: 's1', age: 30 }) // false — plain data, not the entity
+        * ```
+        */
+       export declare function isSubjectBuilder(value: unknown): value is SubjectBuilderInterface;
+
+       /**
+        * Determine whether a value is a {@link SymbolicDefinition}.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed symbolic definition
+        *
+        * @example
+        * ```ts
+        * import { isSymbolicDefinition, symbolicDefinition } from '@src/core'
+        *
+        * isSymbolicDefinition(symbolicDefinition('rate', 'Rate', [])) // true
+        * isSymbolicDefinition({ reasoning: 'symbolic', id: 'rate' })  // false
+        * ```
+        */
+       export declare function isSymbolicDefinition(value: unknown): value is SymbolicDefinition;
+
+       /**
+        * Determine whether a value is a {@link SymbolicExpression} — an algebraic
+        * expression tree of variables, constants, and operations, discriminated by
+        * `form`.
+        *
+        * @remarks
+        * Recursive through `lazyOf` (AGENTS §14) — recursion is STACK-BOUNDED, 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
+        * bound is rejected, not validated.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed symbolic expression tree
+        *
+        * @example
+        * ```ts
+        * import { constant, isSymbolicExpression, operation, variable } from '@src/core'
+        *
+        * isSymbolicExpression(operation('add', variable('x'), constant(1))) // true
+        * isSymbolicExpression({ form: 'variable' })                         // false — name missing
+        * ```
+        */
+       export declare function isSymbolicExpression(value: unknown): value is SymbolicExpression;
+
+       /**
+        * Determine whether a value is a {@link Transform} — one math step.
+        *
+        * @param value - The value to test
+        * @returns `true` when `value` is a well-formed transform
+        *
+        * @example
+        * ```ts
+        * import { isTransform } from '@src/core'
+        *
+        * isTransform({ operation: 'multiply', operand: 2 }) // true
+        * isTransform({ operation: 'round' })                // true — operand is optional
+        * isTransform({ operation: 'multiply', by: 2 })      // false — extra key
+        * ```
+        */
+       export declare function isTransform(value: unknown): value is Transform;
+
+       /** Default `id` for a `LogicalReasoner`. */
+       export declare const LOGICAL_ID = "logical";
+
+       /**
+        * A logical (rule-based deduction) definition.
+        *
+        * @remarks
+        * `strategy` picks forward fixpoint chaining or backward goal-driven proving;
+        * `depth` caps forward iterations / backward recursion (default `10`).
+        */
+       export declare interface LogicalDefinition {
+           readonly reasoning: 'logical';
+           readonly id: string;
+           readonly name: string;
+           readonly description?: string;
+           readonly rules: readonly Rule[];
+           readonly strategy: ChainingStrategy;
+           readonly depth?: number;
+       }
+
+       /**
+        * Build a {@link LogicalDefinition}.
+        *
+        * @remarks
+        * `strategy` defaults to `'forward'`; set `strategy`, `description`, or `depth`
+        * through `overrides`.
+        *
+        * @param id - The definition id
+        * @param name - The display name
+        * @param rules - The deduction rules
+        * @param overrides - Optional {@link LogicalDefinition} fields merged over the defaults
+        * @returns A fresh logical definition
+        *
+        * @example
+        * ```ts
+        * import { atom, logicalDefinition, rule } from '@src/core'
+        *
+        * logicalDefinition('eligibility', 'Eligibility', [
+        * 	rule('adult', [atom('age', 'from', 18)], atom('adult', 'equals', true)),
+        * ])
+        * ```
+        */
+       export declare function logicalDefinition(id: string, name: string, rules: readonly Rule[], overrides?: Partial<Omit<LogicalDefinition, 'reasoning' | 'id' | 'name' | 'rules'>>): LogicalDefinition;
+
+       /**
+        * A logical connective inside a compound {@link Expression}.
+        *
+        * @remarks
+        * `not` reads only its first operand (empty operands are vacuously true);
+        * `implies` and `xor` read their first two (`implies` is vacuously true below
+        * two operands, `xor` is false).
+        */
+       export declare type LogicalOperator = 'and' | 'or' | 'not' | 'implies' | 'xor';
+
+       /**
+        * The logical reasoner — rule-based boolean deduction with forward or backward
+        * chaining.
+        *
+        * @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
+        * 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 the LAST result's conclusion. 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
+        * 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
+        * deterministic (AGENTS §11).
+        */
+       export declare class LogicalReasoner implements ReasonerInterface {
+           #private;
+           constructor(options?: LogicalReasonerOptions);
+           get id(): string;
+           get reasoning(): Reasoning;
+           supports(definition: Definition): boolean;
+           validate(definition: Definition): ReasonValidationResult;
+           reason(subject: Subject, definition: Definition): ReasonResult;
+       }
+
+       /**
+        * Options for `createLogicalReasoner` / the `LogicalReasoner` constructor.
+        *
+        * @remarks
+        * `id` — the reasoner's identity string (defaults to `LOGICAL_ID`).
+        * `evaluator` — the injectable check evaluator (defaults to a fresh
+        * default-constructed instance).
+        */
+       export declare interface LogicalReasonerOptions {
+           readonly id?: string;
+           readonly evaluator?: EvaluatorInterface;
+       }
+
+       /**
+        * The outcome of logical reasoning.
+        *
+        * @remarks
+        * `conclusion` is the LAST evaluated rule's conclusion (`false` when no rule
+        * was evaluated); `count` tallies the applied rules; disabled rules are
+        * omitted from `rules` entirely.
+        */
+       export declare interface LogicalResult {
+           readonly reasoning: 'logical';
+           readonly conclusion: boolean;
+           readonly rules: readonly RuleResult[];
+           readonly count: number;
+           readonly success: boolean;
+           readonly trace: readonly string[];
+           readonly errors: readonly string[];
+       }
+
+       /**
+        * Build a {@link Factor} over a lookup {@link Source}.
+        *
+        * @param id - The factor id
+        * @param field - The subject field to resolve (stringified into a table key)
+        * @param table - The lookup table
+        * @param overrides - Optional {@link Factor} fields merged over the defaults
+        * @returns A fresh factor
+        *
+        * @example
+        * ```ts
+        * import { lookupFactor } from '@src/core'
+        *
+        * lookupFactor('state-score', 'state', { CA: 5, NY: 8 }, { fallback: 1 })
+        * ```
+        */
+       export declare function lookupFactor(id: string, field: FieldPath, table: Readonly<Record<string, number>>, overrides?: Partial<Omit<Factor, 'id' | 'source'>>): Factor;
+
+       /**
+        * A factor source mapping a subject field through a lookup table.
+        *
+        * @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.
+        */
+       export declare interface LookupSource {
+           readonly origin: 'lookup';
+           readonly field: FieldPath;
+           readonly table: Readonly<Record<string, number>>;
+       }
+
+       /**
+        * Build a lookup {@link Source} — a subject field mapped through a table.
+        *
+        * @param field - The subject field to resolve (stringified into a table key)
+        * @param table - The lookup table
+        * @returns A fresh lookup source
+        *
+        * @example
+        * ```ts
+        * import { lookupSource } from '@src/core'
+        *
+        * lookupSource('state', { CA: 5, NY: 8, TX: 2 })
+        * ```
+        */
+       export declare function lookupSource(field: FieldPath, table: Readonly<Record<string, number>>): Source;
+
+       /**
+        * Positionally unify a pattern fact against a candidate fact — returning the
+        * variable bindings on success, `undefined` on mismatch.
+        *
+        * @remarks
+        * The bidirectional unification of the inferential reasoner: a `'?'`-prefixed
+        * 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
+        * arity (term-count) mismatch fails immediately; non-variable terms must be
+        * strictly (`===`) equal.
+        *
+        * @param pattern - The pattern fact (may carry `'?'` variables)
+        * @param candidate - The candidate fact to unify against (may also carry `'?'` variables)
+        * @returns A fresh bindings record, or `undefined` when they do not unify
+        *
+        * @example
+        * ```ts
+        * import { fact, matchFacts } from '@src/core'
+        *
+        * matchFacts(fact('p', 'parent', ['?x', 'bob']), fact('f', 'parent', ['alice', 'bob'])) // { '?x': 'alice' }
+        * matchFacts(fact('p', 'parent', ['?x']), fact('f', 'human', ['x']))                     // undefined — predicate
+        * ```
+        */
+       export declare function matchFacts(pattern: Fact, candidate: Fact): Record<string, unknown> | undefined;
+
+       /**
+        * A math operation applied by the {@link TransformerInterface} and inside
+        * {@link SymbolicExpression} trees.
+        *
+        * @remarks
+        * `round` / `ceil` / `floor` / `abs` are unary — they ignore the operand /
+        * right side. All others are binary.
+        */
+       export declare type MathOperation = 'add' | 'subtract' | 'multiply' | 'divide' | 'percentage' | 'minimum' | 'maximum' | 'average' | 'power' | 'round' | 'ceil' | 'floor' | 'abs';
+
+       /**
+        * Reconcile two id-keyed collections — an incoming-order upsert with
+        * base-only survivors appended after.
+        *
+        * @remarks
+        * The Strategic-Merge-Patch-style id-keyed upsert of PROPOSAL.md §6-§7:
+        * 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
+        * order (retained, never deleted — merge is additive). Same-id twins within
+        * EITHER input are deduped to their first occurrence.
+        *
+        * @typeParam T - An id-carrying element type
+        * @param base - The base collection
+        * @param incoming - The incoming collection (its order and matches take priority)
+        * @param resolve - How to reconcile a matched (same-id) pair; defaults to keeping the incoming element wholesale
+        * @returns A fresh, deduped, incoming-ordered-then-base-survivors array
+        *
+        * @example
+        * ```ts
+        * import { mergeById } from '@src/core'
+        *
+        * mergeById([{ id: 'a', v: 1 }, { id: 'b', v: 2 }], [{ id: 'a', v: 9 }])
+        * // [{ id: 'a', v: 9 }, { id: 'b', v: 2 }] — incoming order first, base-only survivor after
+        * ```
+        */
+       export declare function mergeById<T extends {
+           readonly id: string;
+       }>(base: readonly T[], incoming: readonly T[], resolve?: (base: T, incoming: T) => T): readonly T[];
+
+       /**
+        * Reconcile two {@link InferentialDefinition}s onto `base`'s id.
+        *
+        * @remarks
+        * `inferences` and `facts` each merge via {@link mergeById}
+        * (incoming-wins-wholesale on a matched id). Every other scalar field is
+        * incoming-wins-when-present, else base kept.
+        *
+        * @param base - The definition merge targets (its `id` is preserved)
+        * @param incoming - The definition merged in (its order and matches take priority)
+        * @returns A fresh, reconciled definition
+        *
+        * @example
+        * ```ts
+        * import { fact, inferentialDefinition, mergeInferentialDefinition } from '@src/core'
+        *
+        * const base = inferentialDefinition('m', 'M', [fact('f1', 'human', ['a'])], [])
+        * const incoming = inferentialDefinition('m', 'M2', [fact('f2', 'human', ['b'])], [])
+        * mergeInferentialDefinition(base, incoming).facts.map((f) => f.id) // ['f2', 'f1']
+        * ```
+        */
+       export declare function mergeInferentialDefinition(base: InferentialDefinition, incoming: InferentialDefinition): InferentialDefinition;
+
+       /**
+        * Reconcile two {@link LogicalDefinition}s onto `base`'s id.
+        *
+        * @remarks
+        * `rules` merges via {@link mergeById} (incoming-wins-wholesale on a matched
+        * id). Every other scalar field is incoming-wins-when-present, else base kept.
+        *
+        * @param base - The definition merge targets (its `id` is preserved)
+        * @param incoming - The definition merged in (its order and matches take priority)
+        * @returns A fresh, reconciled definition
+        *
+        * @example
+        * ```ts
+        * import { atom, logicalDefinition, mergeLogicalDefinition, rule } from '@src/core'
+        *
+        * const base = logicalDefinition('e', 'E', [rule('r1', [], atom('a', 'equals', true))])
+        * const incoming = logicalDefinition('e', 'E2', [rule('r2', [], atom('b', 'equals', true))])
+        * mergeLogicalDefinition(base, incoming).rules.map((r) => r.id) // ['r2', 'r1']
+        * ```
+        */
+       export declare function mergeLogicalDefinition(base: LogicalDefinition, incoming: LogicalDefinition): LogicalDefinition;
+
+       /**
+        * Reconcile two {@link QuantitativeDefinition}s onto `base`'s id.
+        *
+        * @remarks
+        * `groups` merges via {@link mergeById}; a matched (same-id) PAIR of groups
+        * recurses one level deeper — their `factors` also merge via `mergeById` — the
+        * one exception to incoming-wins-wholesale (PROPOSAL.md §9). Every other
+        * scalar / value-object field is incoming-wins-when-present, else base kept.
+        *
+        * @param base - The definition merge targets (its `id` is preserved)
+        * @param incoming - The definition merged in (its order and matches take priority)
+        * @returns A fresh, reconciled definition
+        *
+        * @example
+        * ```ts
+        * import { factorGroup, mergeQuantitativeDefinition, quantitativeDefinition } from '@src/core'
+        *
+        * const base = quantitativeDefinition('risk', 'Risk', [factorGroup('g1', 'sum', [])])
+        * const incoming = quantitativeDefinition('risk', 'Risk v2', [factorGroup('g2', 'sum', [])])
+        * mergeQuantitativeDefinition(base, incoming).groups.map((g) => g.id) // ['g2', 'g1']
+        * ```
+        */
+       export declare function mergeQuantitativeDefinition(base: QuantitativeDefinition, incoming: QuantitativeDefinition): QuantitativeDefinition;
+
+       /**
+        * Reconcile two {@link Subject}s — incoming-wins spread, with the base `id`
+        * preserved when present.
+        *
+        * @remarks
+        * Mirrors the definition merge's base-id-wins rule: `{ ...base, ...incoming }`
+        * with `base.id` restored afterward when `base` carries an own `id`.
+        *
+        * @param base - The subject merge targets (its `id` is preserved when present)
+        * @param incoming - The subject merged in (its fields take priority)
+        * @returns A fresh, reconciled subject
+        *
+        * @example
+        * ```ts
+        * import { mergeSubjects } from '@src/core'
+        *
+        * mergeSubjects({ id: 's1', age: 30 }, { age: 31, name: 'Alice' })
+        * // { id: 's1', age: 31, name: 'Alice' }
+        * ```
+        */
+       export declare function mergeSubjects(base: Subject, incoming: Subject): Subject;
+
+       /**
+        * Reconcile two {@link SymbolicDefinition}s onto `base`'s id.
+        *
+        * @remarks
+        * `equations` merges via {@link mergeById} (incoming-wins-wholesale on a
+        * matched id); `variables` is a plain incoming-wins spread
+        * (`{ ...base.variables, ...incoming.variables }`). Every other scalar field
+        * is incoming-wins-when-present, else base kept.
+        *
+        * @param base - The definition merge targets (its `id` is preserved)
+        * @param incoming - The definition merged in (its order, matches, and variables take priority)
+        * @returns A fresh, reconciled definition
+        *
+        * @example
+        * ```ts
+        * import { constant, equation, mergeSymbolicDefinition, symbolicDefinition, variable } from '@src/core'
+        *
+        * const base = symbolicDefinition('e', 'E', [], { variables: { x: 1 } })
+        * const incoming = symbolicDefinition('e', 'E2', [equation('e1', variable('x'), constant(2), 'x')], {
+        * 	variables: { y: 2 },
+        * })
+        * mergeSymbolicDefinition(base, incoming).variables // { x: 1, y: 2 }
+        * ```
+        */
+       export declare function mergeSymbolicDefinition(base: SymbolicDefinition, incoming: SymbolicDefinition): SymbolicDefinition;
+
+       /**
+        * A symbolic operation node.
+        *
+        * @remarks
+        * `right` is absent for unary operators (`round` / `ceil` / `floor` / `abs`)
+        * and treated as the constant `0` when absent on a binary operator.
+        */
+       export declare interface Operation {
+           readonly form: 'operation';
+           readonly operator: MathOperation;
+           readonly left: SymbolicExpression;
+           readonly right?: SymbolicExpression;
+       }
+
+       /**
+        * Build an operation {@link SymbolicExpression} node.
+        *
+        * @remarks
+        * 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`.
+        *
+        * @param operator - The math operation
+        * @param left - The left operand
+        * @param right - The right operand (omit for unary operations)
+        * @returns A fresh operation node
+        *
+        * @example
+        * ```ts
+        * import { constant, operation, variable } from '@src/core'
+        *
+        * operation('add', variable('x'), constant(1))
+        * operation('abs', variable('x')) // unary — no right operand
+        * ```
+        */
+       export declare const operation: (operator: MathOperation, left: SymbolicExpression, right?: SymbolicExpression) => SymbolicExpression;
+
+       /**
+        * Parse a JSON string into a {@link Definition}, failing safe to `undefined`.
+        *
+        * @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
+        * 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).
+        *
+        * @param json - The JSON text to parse
+        * @returns A {@link Definition} of any reasoning, or `undefined` when malformed
+        *
+        * @example
+        * ```ts
+        * import { logicalDefinition, parseDefinition } from '@src/core'
+        *
+        * const text = JSON.stringify(logicalDefinition('e', 'E', []))
+        * parseDefinition(text)   // the definition, restored
+        * parseDefinition('{}')   // undefined — fails safe
+        * ```
+        */
+       export declare function parseDefinition(json: string): Definition | undefined;
+
+       /**
+        * Insert `item` into an id-keyed collection, deduping any existing element
+        * 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
+        * placement differs: no `target` lands `item` at the start; a `target` lands
+        * it immediately before 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
+        * @param items - The collection to insert into
+        * @param item - The element to insert
+        * @param target - Optional id to insert immediately before; prepends at the start when absent
+        * @returns A fresh array with `item` inserted
+        * @throws {@link ReasonError} `'TARGET'` when `target` names no element in `items`
+            *
+            * @example
+            * ```ts
+            * import { prependById } from '@src/core'
+            *
+            * prependById([{ id: 'a' }, { id: 'b' }], { id: 'c' })      // [c, a, b]
+            * prependById([{ id: 'a' }, { id: 'b' }], { id: 'c' }, 'b') // [a, c, b]
+            * ```
+            */
+        export declare function prependById<T extends {
+            readonly id: string;
+        }>(items: readonly T[], item: T, target?: string): readonly T[];
+
+        /**
+         * Insert `equation` into a {@link SymbolicDefinition}'s `equations` — dedup-
+         * then-insert at the start, or immediately before `target`.
+         *
+         * @param definition - The definition to insert into
+         * @param source - The equation to insert
+         * @param target - Optional equation id to insert immediately before
+         * @returns A fresh definition with `equation` inserted
+         * @throws {@link ReasonError} `'TARGET'` when `target` names no existing equation
+             *
+             * @example
+             * ```ts
+             * import { constant, equation, prependEquation, symbolicDefinition, variable } from '@src/core'
+             *
+             * prependEquation(symbolicDefinition('e', 'E', []), equation('e1', variable('x'), constant(1), 'x'))
+             * ```
+             */
+         export declare function prependEquation(definition: SymbolicDefinition, source: Equation, target?: string): SymbolicDefinition;
+
+         /**
+          * Insert `fact` into an {@link InferentialDefinition}'s `facts` — dedup-then-
+          * insert at the start, or immediately before `target`.
+          *
+          * @param definition - The definition to insert into
+          * @param source - The fact to insert
+          * @param target - Optional fact id to insert immediately before
+          * @returns A fresh definition with `fact` inserted
+          * @throws {@link ReasonError} `'TARGET'` when `target` names no existing fact
+              *
+              * @example
+              * ```ts
+              * import { fact, inferentialDefinition, prependFact } from '@src/core'
+              *
+              * prependFact(inferentialDefinition('m', 'M', [], []), fact('f1', 'human', ['socrates']))
+              * ```
+              */
+          export declare function prependFact(definition: InferentialDefinition, source: Fact, target?: string): InferentialDefinition;
+
+          /**
+           * Insert `factor` into a {@link FactorGroup}'s `factors` — dedup-then-insert
+           * at the start, or immediately before `target`.
+           *
+           * @param group - The group to insert into
+           * @param factor - The factor to insert
+           * @param target - Optional factor id to insert immediately before
+           * @returns A fresh group with `factor` inserted
+           * @throws {@link ReasonError} `'TARGET'` when `target` names no existing factor
+               *
+               * @example
+               * ```ts
+               * import { factorGroup, prependFactor, staticFactor } from '@src/core'
+               *
+               * prependFactor(factorGroup('g1', 'sum', []), staticFactor('f1', 10))
+               * ```
+               */
+           export declare function prependFactor(group: FactorGroup, factor: Factor, target?: string): FactorGroup;
+
+           /**
+            * Insert `group` into a {@link QuantitativeDefinition}'s `groups` — dedup-then-
+            * insert at the start, or immediately before `target`.
+            *
+            * @param definition - The definition to insert into
+            * @param group - The group to insert
+            * @param target - Optional group id to insert immediately before
+            * @returns A fresh definition with `group` inserted
+            * @throws {@link ReasonError} `'TARGET'` when `target` names no existing group
+                *
+                * @example
+                * ```ts
+                * import { factorGroup, prependGroup, quantitativeDefinition } from '@src/core'
+                *
+                * prependGroup(quantitativeDefinition('risk', 'Risk', []), factorGroup('g1', 'sum', []))
+                * ```
+                */
+            export declare function prependGroup(definition: QuantitativeDefinition, group: FactorGroup, target?: string): QuantitativeDefinition;
+
+            /**
+             * Insert `inference` into an {@link InferentialDefinition}'s `inferences` —
+             * dedup-then-insert at the start, or immediately before `target`.
+             *
+             * @param definition - The definition to insert into
+             * @param source - The inference to insert
+             * @param target - Optional inference id to insert immediately before
+             * @returns A fresh definition with `inference` inserted
+             * @throws {@link ReasonError} `'TARGET'` when `target` names no existing inference
+                 *
+                 * @example
+                 * ```ts
+                 * import { fact, inference, inferentialDefinition, prependInference } from '@src/core'
+                 *
+                 * prependInference(
+                 * 	inferentialDefinition('m', 'M', [], []),
+                 * 	inference('i1', [fact('p', 'human', ['?x'])], fact('c', 'mortal', ['?x'])),
+                 * )
+                 * ```
+                 */
+             export declare function prependInference(definition: InferentialDefinition, source: Inference, target?: string): InferentialDefinition;
+
+             /**
+              * Insert `rule` into a {@link LogicalDefinition}'s `rules` — dedup-then-insert
+              * at the start, or immediately before `target`.
+              *
+              * @param definition - The definition to insert into
+              * @param source - The rule to insert
+              * @param target - Optional rule id to insert immediately before
+              * @returns A fresh definition with `rule` inserted
+              * @throws {@link ReasonError} `'TARGET'` when `target` names no existing rule
+                  *
+                  * @example
+                  * ```ts
+                  * import { atom, logicalDefinition, prependRule, rule } from '@src/core'
+                  *
+                  * prependRule(logicalDefinition('e', 'E', []), rule('r1', [], atom('a', 'equals', true)))
+                  * ```
+                  */
+              export declare function prependRule(definition: LogicalDefinition, source: Rule, target?: string): LogicalDefinition;
+
+              /**
+               * One node of a backward-chaining proof tree.
+               *
+               * @remarks
+               * `fact` is the proved fact's / goal's id; `inference` is set when the node was
+               * derived through an inference (absent on a base-fact leaf); `children` are the
+               * sub-proofs of that inference's premises; `depth` is the recursion depth the
+               * node was proved at.
+               */
+              export declare interface ProofNode {
+                  readonly fact: string;
+                  readonly inference?: string;
+                  readonly children?: readonly ProofNode[];
+                  readonly depth: number;
+              }
+
+              /** Default `id` for a `QuantitativeReasoner`. */
+              export declare const QUANTITATIVE_ID = "quantitative";
+
+              /**
+               * A quantitative (factor-based numeric scoring) definition.
+               *
+               * @remarks
+               * The final value is `base` (default `0`) plus the aggregation of the applied
+               * groups' values (NO weights at this level), clamped to `bounds`, then rounded
+               * to `precision` decimal places (default `4`).
+               */
+              export declare interface QuantitativeDefinition {
+                  readonly reasoning: 'quantitative';
+                  readonly id: string;
+                  readonly name: string;
+                  readonly description?: string;
+                  readonly groups: readonly FactorGroup[];
+                  readonly aggregation: Aggregation;
+                  readonly base?: number;
+                  readonly bounds?: Bounds;
+                  readonly precision?: number;
+              }
+
+              /**
+               * Build a {@link QuantitativeDefinition}.
+               *
+               * @remarks
+               * `aggregation` defaults to `'sum'`; set `aggregation`, `description`, `base`,
+               * `bounds`, or `precision` through `overrides`.
+               *
+               * @param id - The definition id
+               * @param name - The display name
+               * @param groups - The factor groups
+               * @param overrides - Optional {@link QuantitativeDefinition} fields merged over the defaults
+               * @returns A fresh quantitative definition
+               *
+               * @example
+               * ```ts
+               * import { factorGroup, fieldFactor, quantitativeDefinition } from '@src/core'
+               *
+               * quantitativeDefinition('risk', 'Risk Score', [factorGroup('g1', 'sum', [fieldFactor('age', 'age')])], {
+               * 	base: 100,
+               * })
+               * ```
+               */
+              export declare function quantitativeDefinition(id: string, name: string, groups: readonly FactorGroup[], overrides?: Partial<Omit<QuantitativeDefinition, 'reasoning' | 'id' | 'name' | 'groups'>>): QuantitativeDefinition;
+
+              /**
+               * The quantitative reasoner — 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`
+               * 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
+               * definition's value is its `base` plus the unweighted aggregation of the
+               * 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
+               * 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
+               * mutates its inputs; fully deterministic (AGENTS §11).
+               */
+              export declare class QuantitativeReasoner implements ReasonerInterface {
+                  #private;
+                  constructor(options?: QuantitativeReasonerOptions);
+                  get id(): string;
+                  get reasoning(): Reasoning;
+                  supports(definition: Definition): boolean;
+                  validate(definition: Definition): ReasonValidationResult;
+                  reason(subject: Subject, definition: Definition): ReasonResult;
+              }
+
+              /**
+               * Options for `createQuantitativeReasoner` / the `QuantitativeReasoner`
+               * constructor.
+               *
+               * @remarks
+               * `id` — the reasoner's identity string (defaults to `QUANTITATIVE_ID`).
+               * `evaluator` / `transformer` / `aggregator` — injectable operators (each
+               * defaults to a fresh default-constructed instance).
+               */
+              export declare interface QuantitativeReasonerOptions {
+                  readonly id?: string;
+                  readonly evaluator?: EvaluatorInterface;
+                  readonly transformer?: TransformerInterface;
+                  readonly aggregator?: AggregatorInterface;
+              }
+
+              /**
+               * The outcome of quantitative reasoning.
+               *
+               * @remarks
+               * `count` tallies the applied groups. `success` is `false` whenever any error
+               * accumulated (a required-factor failure, a non-finite value) — the numeric
+               * `value` is still computed.
+               */
+              export declare interface QuantitativeResult {
+                  readonly reasoning: 'quantitative';
+                  readonly value: number;
+                  readonly groups: readonly GroupResult[];
+                  readonly count: number;
+                  readonly success: boolean;
+                  readonly trace: readonly string[];
+                  readonly errors: readonly string[];
+              }
+
+              /**
+               * Build a {@link Factor} over a range {@link Source}.
+               *
+               * @param id - The factor id
+               * @param field - The subject field to resolve as a number
+               * @param ranges - The bands, scanned in order (first match wins)
+               * @param overrides - Optional {@link Factor} fields merged over the defaults
+               * @returns A fresh factor
+               *
+               * @example
+               * ```ts
+               * import { bounds, rangeFactor } from '@src/core'
+               *
+               * rangeFactor('age-band', 'age', [{ bounds: bounds(undefined, 24), value: 30 }])
+               * ```
+               */
+              export declare function rangeFactor(id: string, field: FieldPath, ranges: readonly FactorRange[], overrides?: Partial<Omit<Factor, 'id' | 'source'>>): Factor;
+
+              /**
+               * 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
+               * `bounds` matches anything (a catch-all); an absent bound side is open. No
+               * match falls back to the factor's `fallback`.
+               */
+              export declare interface RangeSource {
+                  readonly origin: 'range';
+                  readonly field: FieldPath;
+                  readonly ranges: readonly FactorRange[];
+              }
+
+              /**
+               * Build a range {@link Source} — a numeric subject field banded through ordered
+               * ranges (first match wins).
+               *
+               * @param field - The subject field to resolve as a number
+               * @param ranges - The bands, scanned in order
+               * @returns A fresh range source
+               *
+               * @example
+               * ```ts
+               * import { bounds, rangeSource } from '@src/core'
+               *
+               * rangeSource('age', [
+               * 	{ bounds: bounds(undefined, 24), value: 30 },
+               * 	{ bounds: bounds(25, 64), value: 15 },
+               * 	{ bounds: bounds(65), value: 10 },
+               * ])
+               * ```
+               */
+              export declare function rangeSource(field: FieldPath, ranges: readonly FactorRange[]): Source;
+
+              /**
+               * The reasoning orchestrator — a thin router over registered
+               * {@link ReasonerInterface}s.
+               *
+               * @remarks
+               * 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
+               * value, then rethrows under `bail: true` (the default) or converts to a
+               * type-shaped failure result under `bail: false`; only SUCCESSFUL results emit
+               * `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 (AGENTS §13) and is
+               * idempotent; every other method afterwards throws `DESTROYED` — only the
+               * {@link emitter} getter keeps working.
+               */
+              export declare class Reason implements ReasonInterface {
+                  #private;
+                  constructor(options?: ReasonOptions);
+                  get emitter(): EmitterInterface<ReasonEventMap>;
+                  reason(subjects: readonly Subject[], definition: Definition): readonly ReasonResult[];
+                  reason(subject: Subject, definition: Definition): ReasonResult;
+                  register(reasoner: ReasonerInterface): void;
+                  reasoner(reasoning: Reasoning): ReasonerInterface | undefined;
+                  reasoners(): readonly ReasonerInterface[];
+                  supports(reasoning: Reasoning): boolean;
+                  validate(definition: Definition): ReasonValidationResult;
+                  destroy(): void;
+              }
+
+              /**
+               * A reasoning strategy adapter — one per {@link Reasoning}.
+               *
+               * @remarks
+               * `reason` throws a `ReasonError` (`MISMATCH`) when handed a definition of 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
+               * caller.
+               */
+              export declare interface ReasonerInterface {
+                  readonly id: string;
+                  readonly reasoning: Reasoning;
+                  supports(definition: Definition): boolean;
+                  validate(definition: Definition): ReasonValidationResult;
+                  reason(subject: Subject, definition: Definition): ReasonResult;
+              }
+
+              /**
+               * An error thrown by the reasons layer.
+               *
+               * @remarks
+               * Thrown for: dispatching a definition no registered reasoner handles
+               * (`MISSING`), a pre-run validation failure when the orchestrator's `validate`
+               * option is on (`INVALID`), handing a reasoner a definition of a different
+               * reasoning (`MISMATCH`), any use of a destroyed orchestrator (`DESTROYED`),
+               * and an `appendById` / `prependById` (or per-kind `append*` / `prepend*`)
+               * `target` id naming no existing element (`TARGET`). `context`, when present,
+               * carries the definition id and the reasoning involved (or, for `TARGET`, the
+               * offending `id` / `target`).
+               */
+              export declare class ReasonError extends Error {
+                  readonly code: ReasonErrorCode;
+                  readonly context?: Readonly<Record<string, unknown>>;
+                  constructor(code: ReasonErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+              }
+
+              /**
+               * A machine-readable `ReasonError` code.
+               *
+               * @remarks
+               * `MISSING` — no reasoner registered for the definition's reasoning.
+               * `INVALID` — pre-run validation failed (`validate: true`). `MISMATCH` — a
+               * reasoner was handed a definition of a different reasoning. `DESTROYED` — the
+               * orchestrator was used after `destroy()`. `TARGET` — a locator id names no
+               * element that exists in the collection it addresses: an optional `target` id
+               * passed to `appendById` / `prependById` (and the per-kind `append*` /
+               * `prepend*` helpers built on them) that names no existing element.
+               */
+              export declare type ReasonErrorCode = 'MISSING' | 'INVALID' | 'MISMATCH' | 'DESTROYED' | 'TARGET';
+
+              /**
+               * The push observation surface of a {@link ReasonInterface} (AGENTS §13).
+               *
+               * @remarks
+               * `register` fires when a reasoner is registered (carrying its reasoning);
+               * `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.
+               */
+              export declare type ReasonEventMap = {
+                  /** A reasoner was registered — carries its reasoning. */
+                  readonly register: readonly [reasoning: Reasoning];
+                  /** A reasoning run succeeded — carries the produced result. */
+                  readonly reason: readonly [result: ReasonResult];
+                  /** A reasoner threw — carries the raw thrown value. */
+                  readonly error: readonly [error: unknown];
+                  /** The orchestrator was destroyed. */
+                  readonly destroy: readonly [];
+              };
+
+              /**
+               * The four reasoning strategies — the axis a {@link Definition} /
+               * {@link ReasonResult} discriminates on.
+               *
+               * @remarks
+               * `quantitative` — factor-based numeric scoring. `logical` — rule-based boolean
+               * deduction with forward / backward chaining. `symbolic` — algebraic equation
+               * solving by variable isolation. `inferential` — fact derivation with
+               * unification variables and proof trees.
+               */
+              export declare type Reasoning = 'quantitative' | 'logical' | 'symbolic' | 'inferential';
+
+              /**
+               * The reasoning orchestrator — a thin router over registered
+               * {@link ReasonerInterface}s.
+               *
+               * @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
+               * 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} /
+               * {@link SubjectBuilderInterface}'s `build()` output is passed instead, by
+               * the caller.
+               */
+              export declare interface ReasonInterface {
+                  readonly emitter: EmitterInterface<ReasonEventMap>;
+                  reason(subjects: readonly Subject[], definition: Definition): readonly ReasonResult[];
+                  reason(subject: Subject, definition: Definition): ReasonResult;
+                  register(reasoner: ReasonerInterface): void;
+                  reasoner(reasoning: Reasoning): ReasonerInterface | undefined;
+                  reasoners(): readonly ReasonerInterface[];
+                  supports(reasoning: Reasoning): boolean;
+                  validate(definition: Definition): ReasonValidationResult;
+                  destroy(): void;
+              }
+
+              /**
+               * Options for `createReason` / the `Reason` constructor.
+               *
+               * @remarks
+               * `reasoners` — the initial registry (a later entry of the same reasoning
+               * replaces an earlier one). `bail` — when `true` (the default) a reasoner
+               * throw is rethrown after the `error` emit; when `false` it becomes a failure
+               * result. `validate` — when `true`, every `reason` call validates the
+               * definition first and throws `INVALID` on failure (default `false`). `on` —
+               * initial event listeners (AGENTS §8). `error` — the emitter's listener-error
+               * handler (AGENTS §13).
+               */
+              export declare interface ReasonOptions {
+                  readonly reasoners?: readonly ReasonerInterface[];
+                  readonly bail?: boolean;
+                  readonly validate?: boolean;
+                  readonly on?: EmitterHooks<ReasonEventMap>;
+                  readonly error?: EmitterErrorHandler;
+              }
+
+              /** Any reasoning result, discriminated by `reasoning`. */
+              export declare type ReasonResult = QuantitativeResult | LogicalResult | SymbolicResult | InferentialResult;
+
+              /**
+               * The outcome of validating a definition — hard `errors` (definition unusable)
+               * and soft `warnings` (suspicious but runnable). `valid` is `true` exactly when
+               * `errors` is empty.
+               *
+               * @remarks
+               * Warnings cover empty collections, duplicate ids (`Duplicate <noun> id`),
+               * inferential confidences outside `[0, 1]`, a logical conclusion's array-path
+               * overlay key also read via an array-path premise elsewhere (the flat overlay
+               * key will not resolve), and an inferential conclusion carrying a `?variable`
+               * unbound by all of its inference's premises — the runtime stays permissive
+               * about all of them.
+               */
+              export declare interface ReasonValidationResult {
+                  readonly valid: boolean;
+                  readonly errors: readonly string[];
+                  readonly warnings: readonly string[];
+              }
+
+              /**
+               * Filter every element sharing `id` out of an id-keyed collection.
+               *
+               * @remarks
+               * An absent `id` yields a same-length fresh copy — a no-op, never a throw.
+               *
+               * @typeParam T - An id-carrying element type
+               * @param items - The collection to remove from
+               * @param id - The id to remove every occurrence of
+               * @returns A fresh array with every `id`-matching element removed
+               *
+               * @example
+               * ```ts
+               * import { removeById } from '@src/core'
+               *
+               * removeById([{ id: 'a' }, { id: 'b' }], 'a') // [{ id: 'b' }]
+               * removeById([{ id: 'a' }], 'z')              // [{ id: 'a' }] — no-op
+               * ```
+               */
+              export declare function removeById<T extends {
+                  readonly id: string;
+              }>(items: readonly T[], id: string): readonly T[];
+
+              /**
+               * Remove every equation sharing `id` from a {@link SymbolicDefinition} (no-op
+               * when absent).
+               *
+               * @param definition - The definition to update
+               * @param id - The equation id to remove
+               * @returns A fresh definition with the equation removed
+               *
+               * @example
+               * ```ts
+               * import { constant, equation, removeEquation, symbolicDefinition, variable } from '@src/core'
+               *
+               * const definition = symbolicDefinition('e', 'E', [equation('e1', variable('x'), constant(1), 'x')])
+               * removeEquation(definition, 'e1').equations // []
+               * ```
+               */
+              export declare function removeEquation(definition: SymbolicDefinition, id: string): SymbolicDefinition;
+
+              /**
+               * Remove every fact sharing `id` from an {@link InferentialDefinition} (no-op
+               * when absent).
+               *
+               * @param definition - The definition to update
+               * @param id - The fact id to remove
+               * @returns A fresh definition with the fact removed
+               *
+               * @example
+               * ```ts
+               * import { fact, inferentialDefinition, removeFact } from '@src/core'
+               *
+               * const definition = inferentialDefinition('m', 'M', [fact('f1', 'human', ['socrates'])], [])
+               * removeFact(definition, 'f1').facts // []
+               * ```
+               */
+              export declare function removeFact(definition: InferentialDefinition, id: string): InferentialDefinition;
+
+              /**
+               * Remove every factor sharing `id` from a {@link FactorGroup} (no-op when
+               * absent).
+               *
+               * @param group - The group to update
+               * @param id - The factor id to remove
+               * @returns A fresh group with the factor removed
+               *
+               * @example
+               * ```ts
+               * import { factorGroup, removeFactor, staticFactor } from '@src/core'
+               *
+               * removeFactor(factorGroup('g1', 'sum', [staticFactor('f1', 10)]), 'f1').factors // []
+               * ```
+               */
+              export declare function removeFactor(group: FactorGroup, id: string): FactorGroup;
+
+              /**
+               * Delete one field of a {@link Subject} — destructure-rest omit.
+               *
+               * @remarks
+               * 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
+               * @param key - The field to delete
+               * @returns A fresh subject with `key` omitted
+               *
+               * @example
+               * ```ts
+               * import { removeField } from '@src/core'
+               *
+               * removeField({ id: 's1', age: 30 }, 'age') // { id: 's1' }
+               * ```
+               */
+              export declare function removeField(subject: Subject, key: string): Subject;
+
+              /**
+               * Remove every group sharing `id` from a {@link QuantitativeDefinition}
+               * (no-op when absent).
+               *
+               * @param definition - The definition to update
+               * @param id - The group id to remove
+               * @returns A fresh definition with the group removed
+               *
+               * @example
+               * ```ts
+               * import { factorGroup, quantitativeDefinition, removeGroup } from '@src/core'
+               *
+               * const definition = quantitativeDefinition('risk', 'Risk', [factorGroup('g1', 'sum', [])])
+               * removeGroup(definition, 'g1').groups // []
+               * ```
+               */
+              export declare function removeGroup(definition: QuantitativeDefinition, id: string): QuantitativeDefinition;
+
+              /**
+               * Remove every inference sharing `id` from an {@link InferentialDefinition}
+               * (no-op when absent).
+               *
+               * @param definition - The definition to update
+               * @param id - The inference id to remove
+               * @returns A fresh definition with the inference removed
+               *
+               * @example
+               * ```ts
+               * import { fact, inference, inferentialDefinition, removeInference } from '@src/core'
+               *
+               * const original = inference('i1', [fact('p', 'human', ['?x'])], fact('c', 'mortal', ['?x']))
+               * removeInference(inferentialDefinition('m', 'M', [], [original]), 'i1').inferences // []
+               * ```
+               */
+              export declare function removeInference(definition: InferentialDefinition, id: string): InferentialDefinition;
+
+              /**
+               * Remove every rule sharing `id` from a {@link LogicalDefinition} (no-op when
+               * absent).
+               *
+               * @param definition - The definition to update
+               * @param id - The rule id to remove
+               * @returns A fresh definition with the rule removed
+               *
+               * @example
+               * ```ts
+               * import { atom, logicalDefinition, removeRule, rule } from '@src/core'
+               *
+               * const definition = logicalDefinition('e', 'E', [rule('r1', [], atom('a', 'equals', true))])
+               * removeRule(definition, 'r1').rules // []
+               * ```
+               */
+              export declare function removeRule(definition: LogicalDefinition, id: string): LogicalDefinition;
+
+              /**
+               * Remove one entry of a {@link SymbolicDefinition}'s `variables`.
+               *
+               * @remarks
+               * 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.
+               *
+               * @param definition - The definition to update
+               * @param name - The variable name to remove
+               * @returns A fresh definition with the variable removed
+               *
+               * @example
+               * ```ts
+               * import { removeVariable, symbolicDefinition } from '@src/core'
+               *
+               * removeVariable(symbolicDefinition('e', 'E', [], { variables: { x: 5 } }), 'x').variables // {}
+               * ```
+               */
+              export declare function removeVariable(definition: SymbolicDefinition, name: string): SymbolicDefinition;
+
+              /**
+               * Produce `count` deterministic clones of a {@link Subject}.
+               *
+               * @remarks
+               * 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.
+               *
+               * @param subject - The subject to clone
+               * @param count - How many clones to produce
+               * @returns The `count`-long array of clones
+               *
+               * @example
+               * ```ts
+               * import { repeatSubject } from '@src/core'
+               *
+               * repeatSubject({ id: 's1', age: 30 }, 2) // [{ id: 's1-0', age: 30 }, { id: 's1-1', age: 30 }]
+               * repeatSubject({ age: 30 }, 2)           // [{ age: 30 }, { age: 30 }] — no id to mint from
+               * ```
+               */
+              export declare function repeatSubject(subject: Subject, count: number): readonly Subject[];
+
+              /**
+               * Swap the element sharing `item.id` IN PLACE, preserving its position.
+               *
+               * @remarks
+               * The position-preserving update primitive — unlike {@link appendById}, which
+               * repositions a re-inserted id to the end/target. Appends `item` at the end
+               * when no same-id element exists (never throws).
+               *
+               * @typeParam T - An id-carrying element type
+               * @param items - The collection to update
+               * @param item - The replacement element
+               * @returns A fresh array with the same-id element replaced (or `item` appended)
+               *
+               * @example
+               * ```ts
+               * import { replaceById } from '@src/core'
+               *
+               * replaceById([{ id: 'a', v: 1 }, { id: 'b', v: 2 }], { id: 'a', v: 9 }) // [{a,9}, {b,2}]
+               * replaceById([{ id: 'a' }], { id: 'z' })                                // [{a}, {z}] — appended
+               * ```
+               */
+              export declare function replaceById<T extends {
+                  readonly id: string;
+              }>(items: readonly T[], item: T): readonly T[];
+
+              /**
+               * Swap the equation sharing `equation.id` in a {@link SymbolicDefinition} IN
+               * PLACE, preserving its position (appends when absent).
+               *
+               * @param definition - The definition to update
+               * @param source - The replacement equation
+               * @returns A fresh definition with the equation replaced
+               *
+               * @example
+               * ```ts
+               * import { constant, equation, replaceEquation, symbolicDefinition, variable } from '@src/core'
+               *
+               * const definition = symbolicDefinition('e', 'E', [equation('e1', variable('x'), constant(1), 'x')])
+               * replaceEquation(definition, equation('e1', variable('x'), constant(2), 'x'))
+               * ```
+               */
+              export declare function replaceEquation(definition: SymbolicDefinition, source: Equation): SymbolicDefinition;
+
+              /**
+               * Swap the fact sharing `fact.id` in an {@link InferentialDefinition} IN
+               * PLACE, preserving its position (appends when absent).
+               *
+               * @param definition - The definition to update
+               * @param source - The replacement fact
+               * @returns A fresh definition with the fact replaced
+               *
+               * @example
+               * ```ts
+               * import { fact, inferentialDefinition, replaceFact } from '@src/core'
+               *
+               * const definition = inferentialDefinition('m', 'M', [fact('f1', 'human', ['socrates'])], [])
+               * replaceFact(definition, fact('f1', 'human', ['plato']))
+               * ```
+               */
+              export declare function replaceFact(definition: InferentialDefinition, source: Fact): InferentialDefinition;
+
+              /**
+               * Swap the factor sharing `factor.id` in a {@link FactorGroup} IN PLACE,
+               * preserving its position (appends when absent).
+               *
+               * @param group - The group to update
+               * @param factor - The replacement factor
+               * @returns A fresh group with the factor replaced
+               *
+               * @example
+               * ```ts
+               * import { factorGroup, replaceFactor, staticFactor } from '@src/core'
+               *
+               * const group = factorGroup('g1', 'sum', [staticFactor('f1', 10)])
+               * replaceFactor(group, staticFactor('f1', 20))
+               * ```
+               */
+              export declare function replaceFactor(group: FactorGroup, factor: Factor): FactorGroup;
+
+              /**
+               * Swap the group sharing `group.id` in a {@link QuantitativeDefinition} IN
+               * PLACE, preserving its position (appends when absent).
+               *
+               * @param definition - The definition to update
+               * @param group - The replacement group
+               * @returns A fresh definition with the group replaced
+               *
+               * @example
+               * ```ts
+               * import { factorGroup, quantitativeDefinition, replaceGroup } from '@src/core'
+               *
+               * const definition = quantitativeDefinition('risk', 'Risk', [factorGroup('g1', 'sum', [])])
+               * replaceGroup(definition, factorGroup('g1', 'product', []))
+               * ```
+               */
+              export declare function replaceGroup(definition: QuantitativeDefinition, group: FactorGroup): QuantitativeDefinition;
+
+              /**
+               * Swap the inference sharing `inference.id` in an {@link InferentialDefinition}
+               * IN PLACE, preserving its position (appends when absent).
+               *
+               * @param definition - The definition to update
+               * @param source - The replacement inference
+               * @returns A fresh definition with the inference replaced
+               *
+               * @example
+               * ```ts
+               * import { fact, inference, inferentialDefinition, replaceInference } from '@src/core'
+               *
+               * const original = inference('i1', [fact('p', 'human', ['?x'])], fact('c', 'mortal', ['?x']))
+               * const definition = inferentialDefinition('m', 'M', [], [original])
+               * replaceInference(definition, inference('i1', [], fact('c', 'mortal', ['?x'])))
+               * ```
+               */
+              export declare function replaceInference(definition: InferentialDefinition, source: Inference): InferentialDefinition;
+
+              /**
+               * Swap the rule sharing `rule.id` in a {@link LogicalDefinition} IN PLACE,
+               * preserving its position (appends when absent).
+               *
+               * @param definition - The definition to update
+               * @param source - The replacement rule
+               * @returns A fresh definition with the rule replaced
+               *
+               * @example
+               * ```ts
+               * import { atom, logicalDefinition, replaceRule, rule } from '@src/core'
+               *
+               * const definition = logicalDefinition('e', 'E', [rule('r1', [], atom('a', 'equals', true))])
+               * replaceRule(definition, rule('r1', [], atom('a', 'equals', false)))
+               * ```
+               */
+              export declare function replaceRule(definition: LogicalDefinition, source: Rule): LogicalDefinition;
+
+              /**
+               * Round a number to a fixed count of decimal places.
+               *
+               * @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
+               * (`10^p` → `Infinity` at roughly `p > 308`, `0` at roughly `p < -323`) returns
+               * the value UNCHANGED — passthrough, never `NaN`.
+               *
+               * @param value - The number to round
+               * @param precision - Decimal places to keep (defaults to `0`)
+               * @returns The rounded number
+               *
+               * @example
+               * ```ts
+               * import { roundTo } from '@src/core'
+               *
+               * roundTo(3.14159, 2) // 3.14
+               * roundTo(2.5)        // 3
+               * roundTo(1250, -2)   // 1300 — tens/hundreds scales
+               * roundTo(1.5, 400)   // 1.5 — overflow passthrough
+               * ```
+               */
+              export declare function roundTo(value: number, precision?: number): number;
+
+              /**
+               * One deduction rule: when ALL `premises` hold, the `conclusion`'s atoms are
+               * asserted as derived facts.
+               *
+               * @remarks
+               * `priority` orders evaluation ascending (default `0`, lower runs first);
+               * `enabled: false` skips the rule (omitted from results). Conclusion extraction
+               * ignores connectives — EVERY atom inside the conclusion is asserted as a
+               * `field = value` fact, even under `not` / `or`.
+               */
+              export declare interface Rule {
+                  readonly id: string;
+                  readonly name: string;
+                  readonly description?: string;
+                  readonly premises: readonly Expression[];
+                  readonly conclusion: Expression;
+                  readonly priority?: number;
+                  readonly enabled?: boolean;
+              }
+
+              /**
+               * Build a {@link Rule} — premises and a conclusion.
+               *
+               * @remarks
+               * `name` defaults to the `id`; set `name`, `description`, `priority`, or
+               * `enabled` through `overrides`.
+               *
+               * @param id - The rule id
+               * @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
+               *
+               * @example
+               * ```ts
+               * import { atom, rule } from '@src/core'
+               *
+               * rule('adult', [atom('age', 'from', 18)], atom('adult', 'equals', true), { priority: 1 })
+               * ```
+               */
+              export declare function rule(id: string, premises: readonly Expression[], conclusion: Expression, overrides?: Partial<Omit<Rule, 'id' | 'premises' | 'conclusion'>>): Rule;
+
+              /**
+               * The {@link RuleManagerInterface} implementation — a self-owning, kind-free
+               * manager over a logical definition's `rules`.
+               *
+               * @remarks
+               * OWNS its `#rules` collection as private copy-on-write state and 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 `target` makes the new rule the conclusion. The write-only
+               * `collection` setter 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', …)`.
+               */
+              export declare class RuleManager implements RuleManagerInterface {
+                  #private;
+                  constructor(options?: RuleManagerOptions);
+                  get emitter(): EmitterInterface<RuleManagerEventMap>;
+                  set collection(value: readonly Rule[]);
+                  rule(id: string): Rule | undefined;
+                  rules(): readonly Rule[];
+                  append(rule: Rule, target?: string): void;
+                  prepend(rule: Rule, target?: string): void;
+                  replace(rule: Rule): void;
+                  remove(id: string): void;
+                  destroy(): void;
+              }
+
+              /** The push observation surface of a {@link RuleManagerInterface} (AGENTS §13). */
+              export declare type RuleManagerEventMap = {
+                  /** A rule was appended — carries its id. */
+                  readonly append: readonly [id: string];
+                  /** A rule was prepended — carries its id. */
+                  readonly prepend: readonly [id: string];
+                  /** A rule was replaced in place — carries its id. */
+                  readonly replace: readonly [id: string];
+                  /** A rule was removed — carries its id. */
+                  readonly remove: readonly [id: string];
+                  /** The manager was destroyed. */
+                  readonly destroy: readonly [];
+              };
+
+              /**
+               * The {@link DefinitionBuilderInterface} manager over a logical definition's
+               * `rules` — a self-owning, kind-free collection manager.
+               *
+               * @remarks
+               * 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.
+               */
+              export declare interface RuleManagerInterface {
+                  readonly emitter: EmitterInterface<RuleManagerEventMap>;
+                  set collection(value: readonly Rule[]);
+                  rule(id: string): Rule | undefined;
+                  rules(): readonly Rule[];
+                  append(rule: Rule, target?: string): void;
+                  prepend(rule: Rule, target?: string): void;
+                  replace(rule: Rule): void;
+                  remove(id: string): void;
+                  destroy(): void;
+              }
+
+              /**
+               * Options for `createRuleManager` / the `RuleManager` constructor.
+               *
+               * @remarks
+               * `rules` — the initial collection (defaults to empty). `on` — initial event
+               * listeners (AGENTS §8). `error` — the emitter's listener-error handler
+               * (AGENTS §13).
+               */
+              export declare interface RuleManagerOptions {
+                  readonly rules?: readonly Rule[];
+                  readonly on?: EmitterHooks<RuleManagerEventMap>;
+                  readonly error?: EmitterErrorHandler;
+              }
+
+              /**
+               * One rule's evaluation outcome.
+               *
+               * @remarks
+               * `applied` and `conclusion` are always equal — both mean "all premises held".
+               * `premises` carries the per-premise truth values.
+               */
+              export declare interface RuleResult {
+                  readonly id: string;
+                  readonly applied: boolean;
+                  readonly premises: readonly boolean[];
+                  readonly conclusion: boolean;
+              }
+
+              /**
+               * Sort items ascending by `priority ?? DEFAULT_PRIORITY` — a stable copy sort.
+               *
+               * @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
+               * is never mutated (AGENTS §11). An array hole, `null`, or other non-record
+               * entry is dropped rather than sorted — the output may be shorter than the
+               * input.
+               *
+               * @param items - The priority-carrying items to order
+               * @returns A fresh array, sorted ascending by priority
+               *
+               * @example
+               * ```ts
+               * import { sortByPriority } from '@src/core'
+               *
+               * sortByPriority([{ priority: 5 }, {}, { priority: -1 }])
+               * // [{ priority: -1 }, {}, { priority: 5 }] — default 0 sits between
+               * ```
+               */
+              export declare function sortByPriority<T extends {
+                  readonly priority?: number;
+              }>(items: readonly T[]): readonly T[];
+
+              /** The four factor sources, discriminated by `origin`. */
+              export declare type Source = StaticSource | FieldSource | LookupSource | RangeSource;
+
+              /**
+               * Build a {@link Factor} over a static {@link Source}.
+               *
+               * @remarks
+               * `name` defaults to the `id`; every other {@link Factor} field (checks,
+               * transforms, bounds, weight, priority, enabled, required, fallback) comes
+               * through `overrides`.
+               *
+               * @param id - The factor id
+               * @param value - The fixed source value
+               * @param overrides - Optional {@link Factor} fields merged over the defaults
+               * @returns A fresh factor
+               *
+               * @example
+               * ```ts
+               * import { staticFactor } from '@src/core'
+               *
+               * staticFactor('base-rate', 10, { weight: 2 })
+               * ```
+               */
+              export declare function staticFactor(id: string, value: number, overrides?: Partial<Omit<Factor, 'id' | 'source'>>): Factor;
+
+              /** A factor source yielding a fixed number. */
+              export declare interface StaticSource {
+                  readonly origin: 'static';
+                  readonly value: number;
+              }
+
+              /**
+               * Build a static {@link Source} — a fixed number.
+               *
+               * @param value - The fixed value
+               * @returns A fresh static source
+               *
+               * @example
+               * ```ts
+               * import { staticSource } from '@src/core'
+               *
+               * staticSource(42) // { origin: 'static', value: 42 }
+               * ```
+               */
+              export declare function staticSource(value: number): Source;
+
+              /**
+               * The data record being reasoned about — a plain readonly bag of fields, read
+               * by {@link FieldPath}.
+               */
+              export declare type Subject = Readonly<Record<string, unknown>>;
+
+              /**
+               * The `SubjectBuilder` entity brand — a `unique symbol` key carrying
+               * `readonly true` on every `SubjectBuilderInterface` instance.
+               *
+               * @remarks
+               * Only `isSubjectBuilder` (`validators.ts`) reads this key, via `Reflect.get`.
+               * Distinct from {@link DEFINITION_BUILDER_BRAND}, so the two entities can never
+               * match each other's guard.
+               */
+              export declare const SUBJECT_BUILDER_BRAND: unique symbol;
+
+              /**
+               * A stateful workspace builder accumulating a {@link Subject}, taverna
+               * `Workspace`-shaped (AGENTS §4.2.2): a single flat collection, no managers —
+               * a flat sibling of `Reason.ts`.
+               *
+               * @remarks
+               * `id` is OPTIONAL (`options?.id ?? seed.id`). When present, the builder is
+               * id-ful and behaves as before. When absent, the builder is ANONYMOUS —
+               * `.id` is `undefined` and the accumulated subject carries no `id` key.
+               * `field(key)` / `fields()` are the AGENTS §9.1 accessor pair over TOP-LEVEL
+               * keys only. `set(key, value)` delegates to `assignField`; `set('id', …)`
+               * throws `ReasonError('MISMATCH', …)` — id is immutable via the entity,
+               * id-ful or anonymous alike. `remove` is the AGENTS §9.2 batch overload
+               * (array form declared first); removing `'id'` 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
+               * `ReasonError('DESTROYED', …)` — only the `emitter` getter and `destroy`
+               * itself keep working, mirroring `Reason`. `destroy()` is idempotent and
+               * tears the emitter down LAST (AGENTS §13).
+               */
+              export declare class SubjectBuilder implements SubjectBuilderInterface {
+                  #private;
+                  readonly [SUBJECT_BUILDER_BRAND]: true;
+                  constructor(seed: Subject, options?: SubjectBuilderOptions);
+                  get id(): string | undefined;
+                  get emitter(): EmitterInterface<SubjectBuilderEventMap>;
+                  field(key: string): unknown;
+                  fields(): Subject;
+                  set(key: string, value: unknown): void;
+                  remove(keys: readonly string[]): boolean;
+                  remove(key: string): boolean;
+                  merge(incoming: Subject): void;
+                  clear(): void;
+                  repeat(count: number): readonly Subject[];
+                  build(): Subject;
+                  destroy(): void;
+              }
+
+              /**
+               * The push observation surface of a {@link SubjectBuilderInterface} (AGENTS
+               * §13) — five verb-named events, no generic `change` / `status`.
+               */
+              export declare type SubjectBuilderEventMap = {
+                  /** A field was upserted — carries its key and new value. */
+                  readonly set: readonly [key: string, value: unknown];
+                  /** A field was removed — carries its key. */
+                  readonly remove: readonly [key: string];
+                  /** The subject was reconciled with an incoming subject — carries the incoming record. */
+                  readonly merge: readonly [incoming: Subject];
+                  /** Every non-id field was removed. */
+                  readonly clear: readonly [];
+                  /** The entity was destroyed. */
+                  readonly destroy: readonly [];
+              };
+
+              /**
+               * A stateful workspace builder accumulating a {@link Subject}, taverna
+               * `Workspace`-shaped (AGENTS §4.2.2): a single flat collection, no managers.
+               *
+               * @remarks
+               * `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
+               * entirely. `field` / `fields` are the AGENTS §9.1 accessor pair over
+               * TOP-LEVEL keys only. `set(key, value)` delegates to `assignField`;
+               * `set('id', …)` throws — id is immutable via the entity, id-ful or
+               * anonymous alike. `remove` is the AGENTS §9.2 batch overload, array form
+               * 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
+               * durable payload each call — distinct from `fields()` (a live inspection
+               * read) even though both currently return the whole record. Post-destroy
+               * mutation throws `ReasonError('DESTROYED', …)`; `destroy()` is idempotent
+               * and tears the emitter down LAST.
+               */
+              export declare interface SubjectBuilderInterface {
+                  readonly [SUBJECT_BUILDER_BRAND]: true;
+                  readonly id: string | undefined;
+                  readonly emitter: EmitterInterface<SubjectBuilderEventMap>;
+                  field(key: string): unknown;
+                  fields(): Subject;
+                  set(key: string, value: unknown): void;
+                  remove(keys: readonly string[]): boolean;
+                  remove(key: string): boolean;
+                  merge(incoming: Subject): void;
+                  clear(): void;
+                  repeat(count: number): readonly Subject[];
+                  build(): Subject;
+                  destroy(): void;
+              }
+
+              /**
+               * Options for `createSubjectBuilder` / the `SubjectBuilder` constructor.
+               *
+               * @remarks
+               * `id` — overrides the seed subject's `id` (defaults to `seed.id`); 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 (AGENTS §8). `error` — the emitter's listener-error
+               * handler (AGENTS §13).
+               */
+              export declare interface SubjectBuilderOptions {
+                  readonly id?: string;
+                  readonly on?: EmitterHooks<SubjectBuilderEventMap>;
+                  readonly error?: EmitterErrorHandler;
+              }
+
+              /**
+               * Project a subject's scalar fields into `has(key, value)` base facts — the
+               * inferential reasoner's subject-injection step.
+               *
+               * @remarks
+               * 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. Each injection appends a line to `trace` (mutated), plus a
+               * final count when at least one fact was produced. The injected fact ids are
+               * `subject:<key>`.
+               *
+               * @param subject - The subject to project
+               * @param trace - The trace accumulator to append to (mutated)
+               * @returns The fresh `has(...)` facts (in `Object.keys` order)
+               *
+               * @example
+               * ```ts
+               * import { subjectToFacts } from '@src/core'
+               *
+               * const trace: string[] = []
+               * subjectToFacts({ id: 'p1', age: 42, tags: ['a'] }, trace) // one fact: has('age', 42) — tags skipped
+               * ```
+               */
+              export declare function subjectToFacts(subject: Subject, trace: string[]): Fact[];
+
+              /** Default `id` for a `SymbolicReasoner`. */
+              export declare const SYMBOLIC_ID = "symbolic";
+
+              /**
+               * A symbolic (equation-solving) definition.
+               *
+               * @remarks
+               * `variables` seeds the bindings; numeric subject fields OVERRIDE same-named
+               * variables. Equations solve strictly in order, each solution rounded to
+               * `precision` decimal places (default `4`) BEFORE feeding forward into later
+               * equations.
+               */
+              export declare interface SymbolicDefinition {
+                  readonly reasoning: 'symbolic';
+                  readonly id: string;
+                  readonly name: string;
+                  readonly description?: string;
+                  readonly equations: readonly Equation[];
+                  readonly variables: Readonly<Record<string, number>>;
+                  readonly precision?: number;
+              }
+
+              /**
+               * Build a {@link SymbolicDefinition}.
+               *
+               * @remarks
+               * `variables` defaults to `{}`; set `variables`, `description`, or `precision`
+               * through `overrides`.
+               *
+               * @param id - The definition id
+               * @param name - The display name
+               * @param equations - The equations, solved in order
+               * @param overrides - Optional {@link SymbolicDefinition} fields merged over the defaults
+               * @returns A fresh symbolic definition
+               *
+               * @example
+               * ```ts
+               * import { constant, equation, symbolicDefinition, variable } from '@src/core'
+               *
+               * symbolicDefinition('rate', 'Rate', [equation('e1', variable('x'), constant(42), 'x')], {
+               * 	precision: 2,
+               * })
+               * ```
+               */
+              export declare function symbolicDefinition(id: string, name: string, equations: readonly Equation[], overrides?: Partial<Omit<SymbolicDefinition, 'reasoning' | 'id' | 'name' | 'equations'>>): SymbolicDefinition;
+
+              /** An algebraic expression tree, discriminated by `form`. */
+              export declare type SymbolicExpression = Variable | Constant | Operation;
+
+              /**
+               * The symbolic reasoner — algebraic equation solving by variable isolation.
+               *
+               * @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.
+               * Equations solve strictly in order: when the `target` is unbound and appears
+               * 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
+               * "<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
+               * equation's target (a failed equation's target still appears when bound
+               * elsewhere). Nothing mutates its inputs; fully deterministic (AGENTS §11).
+               */
+              export declare class SymbolicReasoner implements ReasonerInterface {
+                  #private;
+                  constructor(options?: SymbolicReasonerOptions);
+                  get id(): string;
+                  get reasoning(): Reasoning;
+                  supports(definition: Definition): boolean;
+                  validate(definition: Definition): ReasonValidationResult;
+                  reason(subject: Subject, definition: Definition): ReasonResult;
+              }
+
+              /**
+               * Options for `createSymbolicReasoner` / the `SymbolicReasoner` constructor.
+               *
+               * @remarks
+               * `id` — the reasoner's identity string (defaults to `SYMBOLIC_ID`).
+               */
+              export declare interface SymbolicReasonerOptions {
+                  readonly id?: string;
+              }
+
+              /**
+               * The outcome of symbolic reasoning — final bindings keyed by each equation's
+               * `target` (a failed equation's target still appears when bound elsewhere).
+               */
+              export declare interface SymbolicResult {
+                  readonly reasoning: 'symbolic';
+                  readonly solutions: Readonly<Record<string, number>>;
+                  readonly success: boolean;
+                  readonly trace: readonly string[];
+                  readonly errors: readonly string[];
+              }
+
+              /**
+               * Derive one fact term's contribution to a dedup key — reference identity for
+               * non-null objects / functions, a SameValueZero value string for primitives.
+               *
+               * @remarks
+               * The per-term half of {@link factToKey}, used by the inferential reasoner's
+               * 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
+               * 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.
+               *
+               * @param term - The term to key
+               * @param identities - The reference-identity map, threaded across a dedupe pass (mutated: a new object/function is registered)
+               * @returns The term's key string
+               *
+               * @example
+               * ```ts
+               * import { termToKey } from '@src/core'
+               *
+               * const identities = new Map<object, number>()
+               * termToKey(1, identities)   // 'number:1'
+               * termToKey('1', identities) // 'string:1' — never collides with the number
+               * ```
+               */
+              export declare function termToKey(term: unknown, identities: Map<object, number>): string;
+
+              /**
+               * One math step applied to a number by the {@link TransformerInterface}.
+               *
+               * @remarks
+               * The absent-`operand` default is operation-specific: `1` for `multiply` /
+               * `divide` / `power` (identity-preserving), `0` for every other binary
+               * operation; unary operations ignore it.
+               */
+              export declare interface Transform {
+                  readonly operation: MathOperation;
+                  readonly operand?: number;
+              }
+
+              /**
+               * Build a {@link Transform} — one math step.
+               *
+               * @remarks
+               * 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).
+               *
+               * @param operation - The math operation to apply
+               * @param operand - The operand (ignored by the unary operations)
+               * @returns A fresh transform
+               *
+               * @example
+               * ```ts
+               * import { transform } from '@src/core'
+               *
+               * transform('multiply', 2) // { operation: 'multiply', operand: 2 }
+               * transform('round')       // { operation: 'round' }
+               * ```
+               */
+              export declare function transform(operation: MathOperation, operand?: number): Transform;
+
+              /**
+               * Applies math {@link Transform}s to numbers — the quantitative reasoner's
+               * per-factor pipeline stage.
+               *
+               * @remarks
+               * 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
+               * `Infinity`), an unknown operation returns the value unchanged, and `chain` is
+               * a strict left fold — `NaN` flows through untouched. Stateless and
+               * deterministic.
+               */
+              export declare class Transformer implements TransformerInterface {
+                  #private;
+                  constructor(options?: TransformerOptions);
+                  get id(): string;
+                  apply(value: number, transform: Transform): number;
+                  chain(value: number, transforms: readonly Transform[]): number;
+              }
+
+              /** Default `id` for a `Transformer`. */
+              export declare const TRANSFORMER_ID = "transformer";
+
+              /**
+               * Applies math {@link Transform}s to numbers.
+               *
+               * @remarks
+               * Total: an unknown operation returns the value unchanged, and `divide` by
+               * zero yields `NaN` rather than throwing. `chain` is a strict left fold —
+               * `NaN` flows through.
+               */
+              export declare interface TransformerInterface {
+                  readonly id: string;
+                  apply(value: number, transform: Transform): number;
+                  chain(value: number, transforms: readonly Transform[]): number;
+              }
+
+              /**
+               * Options for `createTransformer` / the `Transformer` constructor.
+               *
+               * @remarks
+               * `id` — the transformer's identity string (defaults to `TRANSFORMER_ID`).
+               */
+              export declare interface TransformerOptions {
+                  readonly id?: string;
+              }
+
+              /** A symbolic expression leaf naming a variable. */
+              export declare interface Variable {
+                  readonly form: 'variable';
+                  readonly name: string;
+              }
+
+              /**
+               * Build a variable {@link SymbolicExpression} leaf.
+               *
+               * @param name - The variable name
+               * @returns A fresh variable node
+               *
+               * @example
+               * ```ts
+               * import { variable } from '@src/core'
+               *
+               * variable('x') // { form: 'variable', name: 'x' }
+               * ```
+               */
+              export declare function variable(name: string): SymbolicExpression;
+
+              /**
+               * The {@link VariableManagerInterface} implementation — a self-owning,
+               * kind-free manager over a symbolic definition's `variables`, a name-keyed
+               * unordered record.
+               *
+               * @remarks
+               * 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)`. The write-only `collection` setter 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', …)`.
+               */
+              export declare class VariableManager implements VariableManagerInterface {
+                  #private;
+                  constructor(options?: VariableManagerOptions);
+                  get emitter(): EmitterInterface<VariableManagerEventMap>;
+                  set collection(value: Readonly<Record<string, number>>);
+                  variable(name: string): number | undefined;
+                  variables(): Readonly<Record<string, number>>;
+                  add(name: string, value: number): void;
+                  remove(name: string): void;
+                  destroy(): void;
+              }
+
+              /**
+               * The push observation surface of a {@link VariableManagerInterface}
+               * (AGENTS §13).
+               *
+               * @remarks
+               * `variables` is a name-keyed record with no placement, so the honest verbs
+               * are `add` / `remove` — each carries the variable NAME.
+               */
+              export declare type VariableManagerEventMap = {
+                  /** A variable was upserted — carries its name. */
+                  readonly add: readonly [name: string];
+                  /** A variable was removed — carries its name. */
+                  readonly remove: readonly [name: string];
+                  /** The manager was destroyed. */
+                  readonly destroy: readonly [];
+              };
+
+              /**
+               * The {@link DefinitionBuilderInterface} manager over a symbolic definition's
+               * `variables` — a name-keyed unordered record, so `add` / `remove` are the
+               * only write verbs (no placement). A self-owning, kind-free manager.
+               */
+              export declare interface VariableManagerInterface {
+                  readonly emitter: EmitterInterface<VariableManagerEventMap>;
+                  set collection(value: Readonly<Record<string, number>>);
+                  variable(name: string): number | undefined;
+                  variables(): Readonly<Record<string, number>>;
+                  add(name: string, value: number): void;
+                  remove(name: string): void;
+                  destroy(): void;
+              }
+
+              /**
+               * Options for `createVariableManager` / the `VariableManager` constructor.
+               *
+               * @remarks
+               * `variables` — the initial record (defaults to empty). `on` — initial event
+               * listeners (AGENTS §8). `error` — the emitter's listener-error handler
+               * (AGENTS §13).
+               */
+              export declare interface VariableManagerOptions {
+                  readonly variables?: Readonly<Record<string, number>>;
+                  readonly on?: EmitterHooks<VariableManagerEventMap>;
+                  readonly error?: EmitterErrorHandler;
+              }
+
+              export { }