universal-physics-tensor 0.7.2 → 0.14.0

package/dist/composition/explain.d.ts

@@ -0,0 +1,102 @@
+/**
+ * "Explain this quantity" — the unified entry point over the three
+ * bridge-inference primitives (docs/planning/Bridge-Inference-Epistemics-
+ * Note.md). Given a target quantity and a set of knowns (names, or
+ * name→value), it composes:
+ *
+ *   1. the identifiability classifier — CAN the graph compute the target
+ *      from the knowns, and via how many independent derivations?
+ *   2. the retrodiction harness — when values are supplied, RECOVER the
+ *      value via each derivation and (for over-determined targets) check
+ *      they agree;
+ *   3. the Buckingham-π enumerator — is the known set even DIMENSIONALLY
+ *      sufficient to fix the target up to a constant, independent of the
+ *      graph's encoded edges?
+ *
+ * The three answer complementary questions, so the explanation is richer
+ * than any one alone: the graph may compute a target whose dimensional
+ * closure relies on constants baked into the evaluator (e.g. r_s = 2GM/c²
+ * — mass alone is not dimensionally sufficient), and the classifier +
+ * Buckingham layer make that explicit together.
+ *
+ * @module composition/explain
+ */
+import type { BridgeEdge } from './edge.js';
+import type { QuantityIdentification } from './compose.js';
+import type { IdentifiabilityResult } from './identifiability.js';
+import type { RetrodictionResult } from './retrodiction.js';
+import type { Dimension } from '../dimensional/types.js';
+import type { DimensionalDeterminationResult } from '../dimensional/buckingham.js';
+/** One structural derivation of the target, with the recovered value when
+ *  ground-truth values were supplied. @public */
+export interface DerivationExplanation {
+    readonly edge: string;
+    readonly label: string;
+    /** The edge's immediate (last-hop) source quantities. */
+    readonly sources: readonly string[];
+    /**
+     * The LEAF inputs this derivation ultimately depends on — its immediate
+     * sources traced back through every intermediate to the known set. The
+     * full-chain (leaf-to-target) view, vs `sources` (last-hop). A subset of
+     * the known set.
+     */
+    readonly leafInputs: readonly string[];
+    /**
+     * The target as a dimensionless-constant-times-monomial in the LEAF
+     * inputs, when those leaves dimensionally fix it (Buckingham-π over the
+     * full chain). Absent when the leaves rely on dimensionful constants
+     * baked into the evaluators (the common case for the bridge graph).
+     */
+    readonly dimensionalForm?: {
+        readonly monomial: Readonly<Record<string, number>>;
+        /** e.g. `period ∝ length^1·gravity^-1` (up to a dimensionless constant). */
+        readonly formula: string;
+    };
+    /** Value recovered via this derivation (only when values were given). */
+    readonly value?: number;
+}
+/** Options for {@link explainQuantity}. @public */
+export interface ExplainOptions {
+    readonly identifications?: readonly QuantityIdentification[];
+    /** Consistency tolerance forwarded to the retrodiction harness. */
+    readonly tolerance?: number;
+    /**
+     * Dimensions for known names that are not graph quantities (e.g. raw
+     * constants `G`, `c`, `hbar`) — lets the Buckingham layer test a known
+     * set richer than the graph's nodes.
+     */
+    readonly extraDimensions?: Readonly<Record<string, Dimension>>;
+}
+/** The unified explanation of one quantity. @public */
+export interface QuantityExplanation {
+    readonly target: string;
+    readonly known: readonly string[];
+    /** Structural verdict (under/exactly/over-determined or given). */
+    readonly identifiability: IdentifiabilityResult;
+    /** One entry per independent derivation the classifier found. */
+    readonly derivations: readonly DerivationExplanation[];
+    /** Retrodiction result, present when ≥2 derivations fired on values. */
+    readonly consistency?: RetrodictionResult;
+    /** Agreed recovered value (consistent or single), when values supplied. */
+    readonly recoveredValue?: number;
+    /** Whether the KNOWN set dimensionally fixes the target (Buckingham-π);
+     *  absent when the target has no resolvable dimension. */
+    readonly dimensional?: DimensionalDeterminationResult;
+    /** Upstream gaps for an under-determined target (from the classifier). */
+    readonly blockingFrontier: readonly string[];
+    /** Plain-language synthesis of the above. */
+    readonly summary: string;
+}
+/**
+ * Explain a quantity: synthesize the identifiability verdict, the
+ * recovered value + consistency (when values are supplied), and the
+ * dimensional sufficiency of the known set into one report.
+ *
+ * `known` may be a list of names (structural + dimensional analysis only)
+ * or a `name → value` map (adds value recovery and the over-determined
+ * consistency check).
+ *
+ * @public
+ */
+export declare function explainQuantity(edges: readonly BridgeEdge[], target: string, known: readonly string[] | Readonly<Record<string, number>>, opts?: ExplainOptions): QuantityExplanation;
+//# sourceMappingURL=explain.d.ts.map

package/dist/composition/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../src/composition/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAGnF;iDACiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE;QACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACpD,4EAA4E;QAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC7D,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;CAChE;AAED,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;IAChD,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACvD,wEAAwE;IACxE,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;8DAC0D;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,8BAA8B,CAAC;IACtD,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAmID;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC3D,IAAI,GAAE,cAAmB,GACxB,mBAAmB,CAoHrB"}

package/dist/composition/explain.js

@@ -0,0 +1,244 @@
+/**
+ * "Explain this quantity" — the unified entry point over the three
+ * bridge-inference primitives (docs/planning/Bridge-Inference-Epistemics-
+ * Note.md). Given a target quantity and a set of knowns (names, or
+ * name→value), it composes:
+ *
+ *   1. the identifiability classifier — CAN the graph compute the target
+ *      from the knowns, and via how many independent derivations?
+ *   2. the retrodiction harness — when values are supplied, RECOVER the
+ *      value via each derivation and (for over-determined targets) check
+ *      they agree;
+ *   3. the Buckingham-π enumerator — is the known set even DIMENSIONALLY
+ *      sufficient to fix the target up to a constant, independent of the
+ *      graph's encoded edges?
+ *
+ * The three answer complementary questions, so the explanation is richer
+ * than any one alone: the graph may compute a target whose dimensional
+ * closure relies on constants baked into the evaluator (e.g. r_s = 2GM/c²
+ * — mass alone is not dimensionally sufficient), and the classifier +
+ * Buckingham layer make that explicit together.
+ *
+ * @module composition/explain
+ */
+import { QUANTITY_IDENTIFICATIONS } from './compose.js';
+import { classifyIdentifiability, forwardClosure } from './identifiability.js';
+import { retrodictNode } from './retrodiction.js';
+import { dimensionallyDetermines } from '../dimensional/buckingham.js';
+function buildDimMap(edges, extra) {
+    const m = new Map();
+    for (const e of edges) {
+        for (const s of e.sources)
+            if (!m.has(s.name))
+                m.set(s.name, s.dim);
+        if (!m.has(e.target.name))
+            m.set(e.target.name, e.target.dim);
+    }
+    if (extra)
+        for (const [k, v] of Object.entries(extra))
+            m.set(k, v);
+    return m;
+}
+/**
+ * Trace `startSources` back through every intermediate to the leaf inputs
+ * — names in `known`, or terminals that no determinable edge produces.
+ * Never expands the target (a self-loop would be circular). The union over
+ * alternative sub-derivations of an over-determined intermediate.
+ */
+function traceLeaves(edges, known, determinable, startSources, idents, target) {
+    const leaves = new Set();
+    const visited = new Set([target]); // never expand the target itself
+    const stack = [...startSources];
+    while (stack.length) {
+        const q = stack.pop();
+        if (known.has(q)) {
+            leaves.add(q);
+            continue;
+        }
+        if (visited.has(q))
+            continue;
+        visited.add(q);
+        let expanded = false;
+        for (const e of edges) {
+            if (e.target.name !== q)
+                continue;
+            if (!e.sources.every((s) => determinable.has(s.name)))
+                continue;
+            for (const s of e.sources)
+                stack.push(s.name);
+            expanded = true;
+        }
+        if (!expanded) {
+            for (const id of idents) {
+                if (id.to === q && determinable.has(id.from)) {
+                    stack.push(id.from);
+                    expanded = true;
+                }
+            }
+        }
+        if (!expanded)
+            leaves.add(q); // a terminal we cannot expand
+    }
+    return [...leaves].sort();
+}
+function formatMonomial(m) {
+    const parts = Object.entries(m)
+        .filter(([, e]) => e !== 0)
+        .map(([n, e]) => (e === 1 ? n : `${n}^${e}`));
+    return parts.join('·') || '1';
+}
+function buildSummary(target, id, derivations, consistency, recoveredValue, dimensional, knownNames) {
+    const known = knownNames.length
+        ? `{${knownNames.join(', ')}}`
+        : '{} (no inputs)';
+    const ids = derivations.map((d) => d.edge).join(', ');
+    let s;
+    switch (id.verdict) {
+        case 'given':
+            s = `'${target}' is a supplied input.`;
+            if (derivations.length) {
+                s += ` ${derivations.length} graph derivation(s) (${ids}) can cross-check it`;
+                s += consistency
+                    ? consistency.outcome === 'consistent'
+                        ? `, and they are consistent (relative spread ${consistency.relativeSpread.toExponential(1)}).`
+                        : ` — and they are INCONSISTENT (relative spread ${consistency.relativeSpread.toExponential(1)}).`
+                    : '.';
+            }
+            break;
+        case 'under-determined':
+            s = `'${target}' cannot be determined from ${known}: the graph has no derivation path.`;
+            if (id.blockingFrontier.length) {
+                s += ` Knowing one of {${id.blockingFrontier.join(', ')}} would unblock it.`;
+            }
+            break;
+        case 'exactly-determined':
+            s = `'${target}' is determined from ${known} via ${derivations[0]?.edge} (${derivations[0]?.label}).`;
+            if (recoveredValue !== undefined) {
+                s += ` Recovered value: ${recoveredValue.toExponential(4)}.`;
+            }
+            break;
+        case 'over-determined':
+        default:
+            s = `'${target}' is over-determined from ${known}: ${derivations.length} independent derivations (${ids}).`;
+            if (consistency) {
+                s +=
+                    consistency.outcome === 'consistent'
+                        ? ` They agree (relative spread ${consistency.relativeSpread.toExponential(1)}) — a passing consistency check.`
+                        : ` They DISAGREE (relative spread ${consistency.relativeSpread.toExponential(1)}) — a falsification.`;
+            }
+            else {
+                s += ` The ${id.surplusConstraints} surplus derivation(s) are falsifiable consistency constraints (supply values to check them).`;
+            }
+            if (recoveredValue !== undefined) {
+                s += ` Recovered value: ${recoveredValue.toExponential(4)}.`;
+            }
+            break;
+    }
+    if (dimensional?.determined && dimensional.monomial) {
+        s += ` Dimensionally, ${known} fix it up to a dimensionless constant: ${target} ∝ ${formatMonomial(dimensional.monomial)}.`;
+    }
+    else if (dimensional && !dimensional.determined && knownNames.length) {
+        s += ` Dimensionally, those inputs alone do not fix it — the encoded formula carries dimensionful constants.`;
+    }
+    return s;
+}
+/**
+ * Explain a quantity: synthesize the identifiability verdict, the
+ * recovered value + consistency (when values are supplied), and the
+ * dimensional sufficiency of the known set into one report.
+ *
+ * `known` may be a list of names (structural + dimensional analysis only)
+ * or a `name → value` map (adds value recovery and the over-determined
+ * consistency check).
+ *
+ * @public
+ */
+export function explainQuantity(edges, target, known, opts = {}) {
+    const identifications = opts.identifications ?? QUANTITY_IDENTIFICATIONS;
+    const hasValues = !Array.isArray(known);
+    const values = hasValues ? known : null;
+    const knownNames = hasValues
+        ? Object.keys(values)
+        : [...new Set(known)];
+    const identifiability = classifyIdentifiability(edges, knownNames, target, {
+        identifications,
+    });
+    const byId = new Map(edges.map((e) => [e.id, e]));
+    let consistency;
+    let recoveredValue;
+    const valueByEdge = new Map();
+    if (values) {
+        const references = target in values ? { [target]: values[target] } : undefined;
+        const retro = retrodictNode(edges, values, target, {
+            identifications,
+            tolerance: opts.tolerance,
+            references,
+        });
+        for (const p of retro.predictions)
+            valueByEdge.set(p.edge, p.value);
+        if (retro.predictions.length >= 2)
+            consistency = retro;
+        if ((retro.outcome === 'consistent' || retro.outcome === 'single') &&
+            retro.predictions.length > 0) {
+            recoveredValue =
+                retro.predictions.reduce((a, p) => a + p.value, 0) /
+                    retro.predictions.length;
+        }
+    }
+    const dimMap = buildDimMap(edges, opts.extraDimensions);
+    const knownSet = new Set(knownNames);
+    const determinable = forwardClosure(edges, knownNames, identifications);
+    const derivations = identifiability.derivations.map((eid) => {
+        const e = byId.get(eid);
+        const sources = e ? e.sources.map((s) => s.name) : [];
+        // Full-chain: trace the immediate sources back to the leaf inputs.
+        const leafInputs = e
+            ? traceLeaves(edges, knownSet, determinable, sources, identifications, target)
+            : [];
+        // Dimensional form in terms of those leaves, when they fix the target.
+        let dimensionalForm;
+        const targetDimForChain = dimMap.get(target);
+        if (targetDimForChain && leafInputs.length) {
+            const governing = leafInputs
+                .filter((n) => n !== target && dimMap.has(n))
+                .map((n) => ({ name: n, dim: dimMap.get(n) }));
+            const det = dimensionallyDetermines({ name: target, dim: targetDimForChain }, governing);
+            if (det.determined && det.monomial) {
+                dimensionalForm = {
+                    monomial: det.monomial,
+                    formula: `${target} ∝ ${formatMonomial(det.monomial)}`,
+                };
+            }
+        }
+        return {
+            edge: eid,
+            label: e?.label ?? eid,
+            sources,
+            leafInputs,
+            ...(dimensionalForm ? { dimensionalForm } : {}),
+            ...(valueByEdge.has(eid) ? { value: valueByEdge.get(eid) } : {}),
+        };
+    });
+    // Dimensional sufficiency of the KNOWN set, independent of the graph.
+    let dimensional;
+    const targetDim = dimMap.get(target);
+    if (targetDim) {
+        const governing = knownNames
+            .filter((n) => n !== target && dimMap.has(n))
+            .map((n) => ({ name: n, dim: dimMap.get(n) }));
+        dimensional = dimensionallyDetermines({ name: target, dim: targetDim }, governing);
+    }
+    const summary = buildSummary(target, identifiability, derivations, consistency, recoveredValue, dimensional, knownNames);
+    return {
+        target,
+        known: knownNames,
+        identifiability,
+        derivations,
+        ...(consistency ? { consistency } : {}),
+        ...(recoveredValue !== undefined ? { recoveredValue } : {}),
+        ...(dimensional ? { dimensional } : {}),
+        blockingFrontier: identifiability.blockingFrontier,
+        summary,
+    };
+}
+//# sourceMappingURL=explain.js.map

package/dist/composition/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../src/composition/explain.ts"],"names":[],"mappings":"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"}

package/dist/composition/expr-eval.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Scalar `ExprNode` value evaluator (v0.12 symbolic composition).
+ *
+ * Numerically evaluates a SCALAR `ExprNode` (the `symbol` / `op` / `integral`
+ * / `derivative` arms) given leaf values. The dimensional validator infers
+ * dimensions but never computes values, and the formula parser evaluates a
+ * DIFFERENT AST — so this is the missing primitive that makes a bridge's
+ * `symbolic` form executable.
+ *
+ * Leaf resolution order (Adam A-1, A-5): caller `values` win, then the
+ * `CONSTANTS` registry, then a base-10 numeric-literal symbol (`'2'`, `'3'`);
+ * an unresolved or non-finite leaf throws. `^` reads its exponent from the
+ * second arg's `name` via `Number(...)` (matching validator.ts) and uses
+ * `Math.pow`. Tensor / integral / derivative arms are out of scope and throw.
+ *
+ * INTERNAL — not on the public surface.
+ *
+ * @module composition/expr-eval
+ */
+import type { ExprNode } from '../dimensional/validator.js';
+/** A scalar `ExprNode` could not be evaluated (unsupported arm / unresolved
+ *  leaf / non-finite result). @public */
+export declare class SymbolicEvalError extends Error {
+    constructor(message: string);
+}
+/**
+ * Evaluate a scalar `ExprNode` to a number. See module docs for the leaf
+ * resolution order and scope.
+ *
+ * @internal
+ */
+export declare function evalExpr(node: ExprNode, values?: Readonly<Record<string, number>>): number;
+//# sourceMappingURL=expr-eval.d.ts.map

package/dist/composition/expr-eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr-eval.d.ts","sourceRoot":"","sources":["../../src/composition/expr-eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAG5D;yCACyC;AACzC,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAeD;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,QAAQ,EACd,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAC5C,MAAM,CAyCR"}

package/dist/composition/expr-eval.js

@@ -0,0 +1,95 @@
+/**
+ * Scalar `ExprNode` value evaluator (v0.12 symbolic composition).
+ *
+ * Numerically evaluates a SCALAR `ExprNode` (the `symbol` / `op` / `integral`
+ * / `derivative` arms) given leaf values. The dimensional validator infers
+ * dimensions but never computes values, and the formula parser evaluates a
+ * DIFFERENT AST — so this is the missing primitive that makes a bridge's
+ * `symbolic` form executable.
+ *
+ * Leaf resolution order (Adam A-1, A-5): caller `values` win, then the
+ * `CONSTANTS` registry, then a base-10 numeric-literal symbol (`'2'`, `'3'`);
+ * an unresolved or non-finite leaf throws. `^` reads its exponent from the
+ * second arg's `name` via `Number(...)` (matching validator.ts) and uses
+ * `Math.pow`. Tensor / integral / derivative arms are out of scope and throw.
+ *
+ * INTERNAL — not on the public surface.
+ *
+ * @module composition/expr-eval
+ */
+import { CONSTANTS } from './symbolic-constants.js';
+/** A scalar `ExprNode` could not be evaluated (unsupported arm / unresolved
+ *  leaf / non-finite result). @public */
+export class SymbolicEvalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SymbolicEvalError';
+    }
+}
+/** Resolve a leaf symbol's numeric value: values → CONSTANTS → literal. */
+function resolveLeaf(name, values) {
+    if (Object.prototype.hasOwnProperty.call(values, name))
+        return values[name];
+    const constant = CONSTANTS[name];
+    if (constant !== undefined)
+        return constant.value;
+    const literal = Number(name);
+    if (Number.isFinite(literal))
+        return literal;
+    throw new SymbolicEvalError(`evalExpr: leaf symbol '${name}' has no value (not in inputs, not a ` +
+        `registered constant, not a numeric literal).`);
+}
+/**
+ * Evaluate a scalar `ExprNode` to a number. See module docs for the leaf
+ * resolution order and scope.
+ *
+ * @internal
+ */
+export function evalExpr(node, values = {}) {
+    switch (node.kind) {
+        case 'symbol':
+            return resolveLeaf(node.name, values);
+        case 'op': {
+            if (node.op === '^') {
+                if (node.args.length !== 2) {
+                    throw new SymbolicEvalError(`evalExpr: '^' needs exactly 2 args, got ${node.args.length}.`);
+                }
+                // The exponent may be a numeric-literal symbol (resolveLeaf returns its
+                // value) OR a general input-dependent expression (v0.13 — e.g. −1/z).
+                // `finite()` still catches a non-finite result (NaN/Inf).
+                const base = evalExpr(node.args[0], values);
+                const exp = evalExpr(node.args[1], values);
+                return finite(Math.pow(base, exp), node);
+            }
+            if (node.args.length === 0) {
+                // Mirrors the validator's empty-op convention: * / → 1, + - → 0.
+                return node.op === '*' || node.op === '/' ? 1 : 0;
+            }
+            let acc = evalExpr(node.args[0], values);
+            for (let i = 1; i < node.args.length; i++) {
+                const v = evalExpr(node.args[i], values);
+                if (node.op === '+')
+                    acc += v;
+                else if (node.op === '-')
+                    acc -= v;
+                else if (node.op === '*')
+                    acc *= v;
+                else
+                    acc /= v;
+            }
+            return finite(acc, node);
+        }
+        default:
+            throw new SymbolicEvalError(`evalExpr: node kind '${node.kind}' is out of scope (scalar ` +
+                `symbol/op only; integral/derivative/tensor nodes are not ` +
+                `numerically evaluable here).`);
+    }
+}
+function finite(value, node) {
+    if (!Number.isFinite(value)) {
+        throw new SymbolicEvalError(`evalExpr: '${node.op ?? node.kind}' produced a ` +
+            `non-finite value (${value}).`);
+    }
+    return value;
+}
+//# sourceMappingURL=expr-eval.js.map

package/dist/composition/expr-eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr-eval.js","sourceRoot":"","sources":["../../src/composition/expr-eval.ts"],"names":[],"mappings":"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"}

package/dist/composition/expr-simplify.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Symbolic simplification of a scalar `ExprNode` via MathTS (v0.12 — optional
+ * supplement to symbolic composition).
+ *
+ * Composing two bridges' symbolic forms leaves an UNSIMPLIFIED AST — CT-1 is
+ * `k_B·(ℏc³/8πG·mass·k_B)·ln2`, with `k_B` uncancelled. This folds it to the
+ * canonical `ℏc³·ln2/(8πG·mass)` using `@danielsimonjr/mathts-functions`'
+ * `simplify` (the same OPTIONAL peer the Path-A formula parser loads).
+ *
+ * Pipeline (Adam+Eve-vetted — docs/planning/v0.12.0-Symbolic-Simplification-
+ * Design.md): GENSYM every non-exponent leaf to a mathjs-safe identifier
+ * (shared by name, so repeated leaves cancel), render FULLY-PARENTHESIZED
+ * (EVE-A — no precedence ambiguity), `parse`+`simplify`, walk the result back
+ * (un-gensym, INTEGER-exponent-strict — EVE/Adam HIGH-1). Three guards make a
+ * black-box CAS safe to trust:
+ *   1. dimensional — `validate(simplified)` dim `equals` the original's;
+ *   2. structural — non-numeric symbols of the result ⊆ those of the original
+ *      (no leaf invented — Adam HIGH-2 / EVE-B);
+ *   3. numeric    — `evalExpr` agrees over ≥2 finite synthesized probes at
+ *      rel tol 1e-9 (Adam CRITICAL-2 / EVE-C).
+ * A representable result that DISAGREES dimensionally/numerically THROWS (a
+ * bug to surface); anything we cannot represent / verify / load degrades to a
+ * graceful no-op (return the original, `simplified:false`).
+ *
+ * INTERNAL — surfaced via `upt symbolic --simplify`.
+ *
+ * @module composition/expr-simplify
+ */
+import type { ExprNode } from '../dimensional/validator.js';
+import type { Observable } from './compose-symbolic.js';
+/** A simplification completed but produced a dimensionally/numerically wrong
+ *  result (a real bug — not a graceful no-op). @internal */
+export declare class SimplificationError extends Error {
+    constructor(message: string);
+}
+/** The result of attempting to simplify an expression. */
+export interface SimplifyResult {
+    readonly expr: ExprNode;
+    /** True iff MathTS was present AND produced a guard-passing, distinct form. */
+    readonly simplified: boolean;
+}
+/**
+ * Simplify a scalar `ExprNode` via MathTS, guarded. Returns the original
+ * unchanged (`simplified:false`) when the peer is absent or the result cannot
+ * be represented/verified; THROWS {@link SimplificationError} only when a
+ * representable result disagrees dimensionally/numerically. See module docs.
+ *
+ * @internal
+ */
+export declare function simplifyExpr(expr: ExprNode): Promise<SimplifyResult>;
+/**
+ * Simplify a composed {@link Observable}: returns a freshly-RECONSTRUCTED
+ * Observable (new strict `evaluate` closure over the simplified `expr` +
+ * recomputed `leaves`) when simplification succeeds, else the original
+ * unchanged. See module docs.
+ *
+ * @internal
+ */
+export declare function simplifyObservable(obs: Observable): Promise<Observable>;
+//# sourceMappingURL=expr-simplify.d.ts.map

package/dist/composition/expr-simplify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr-simplify.d.ts","sourceRoot":"","sources":["../../src/composition/expr-simplify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAO5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGxD;4DAC4D;AAC5D,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAoQD,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,CAmD1E;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAI7E"}