universal-physics-tensor 0.7.2 → 0.14.0

package/dist/composition/expr-simplify.js

@@ -0,0 +1,330 @@
+/**
+ * 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 { validate } from '../dimensional/validator.js';
+import { equals } from '../dimensional/algebra.js';
+import { DIMENSIONLESS } from '../dimensional/types.js';
+import { evalExpr } from './expr-eval.js';
+import { CONSTANTS } from './symbolic-constants.js';
+import { makeObservable } from './compose-symbolic.js';
+/** A simplification completed but produced a dimensionally/numerically wrong
+ *  result (a real bug — not a graceful no-op). @internal */
+export class SimplificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SimplificationError';
+    }
+}
+/** Thrown internally when a node cannot be rendered/walked — caught and turned
+ *  into a graceful no-op (never escapes the module). */
+class Unsupported extends Error {
+}
+// ---------------------------------------------------------------------------
+// Optional-peer load — cache + quietly + simplify-smoke (mirrors
+// formula-registry.ts).
+// ---------------------------------------------------------------------------
+let cached;
+/** Run `fn` with MathTS's import-time WASM-fallback chatter suppressed. */
+async function quietly(fn) {
+    const origWarn = console.warn;
+    const origError = console.error;
+    const origWrite = process.stderr.write.bind(process.stderr);
+    console.warn = () => { };
+    console.error = () => { };
+    process.stderr.write = () => true;
+    try {
+        return await fn();
+    }
+    finally {
+        console.warn = origWarn;
+        console.error = origError;
+        process.stderr.write = origWrite;
+    }
+}
+/** Load + smoke-test the peer. A peer with `parse` but a missing/broken
+ *  `simplify` (it must actually CANCEL) is rejected → null (graceful no-op). */
+async function detect() {
+    try {
+        // Import AND smoke-test inside one suppression window (the WASM-fallback
+        // chatter fires lazily on first parse/simplify, not only at import).
+        return await quietly(async () => {
+            const mod = (await import('@danielsimonjr/mathts-functions'));
+            if (typeof mod.parse !== 'function' || typeof mod.simplify !== 'function') {
+                return null;
+            }
+            // Smoke: g0 must cancel out of (g0)*((g1)/(g0)) → only g1 remains.
+            const s = mod.simplify(mod.parse('(g0)*((g1)/(g0))'));
+            const names = new Set();
+            collectMathSymbols(s, names);
+            return names.size === 1 && names.has('g1') ? mod : null;
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function loadSimplifier() {
+    cached ??= detect();
+    return cached;
+}
+/** Synchronous variant of {@link quietly} for the parse+simplify calls (MathTS
+ *  emits WASM-fallback chatter lazily on first use, not only at import). */
+function quietlySync(fn) {
+    const origWarn = console.warn;
+    const origError = console.error;
+    const origWrite = process.stderr.write.bind(process.stderr);
+    console.warn = () => { };
+    console.error = () => { };
+    process.stderr.write = () => true;
+    try {
+        return fn();
+    }
+    finally {
+        console.warn = origWarn;
+        console.error = origError;
+        process.stderr.write = origWrite;
+    }
+}
+function collectMathSymbols(n, out) {
+    if (n.type === 'SymbolNode' && n.name)
+        out.add(n.name);
+    if (n.content)
+        collectMathSymbols(n.content, out);
+    for (const a of n.args ?? [])
+        collectMathSymbols(a, out);
+}
+const isLiteral = (name) => Number.isFinite(Number(name));
+/** Render a scalar ExprNode to a mathjs-safe, fully-parenthesized string,
+ *  gensym'ing each non-literal leaf by NAME (so repeats share an identifier
+ *  and can cancel). Throws `Unsupported` on non-scalar arms. */
+function renderGensym(expr, gensymOf, meta) {
+    switch (expr.kind) {
+        case 'symbol': {
+            if (isLiteral(expr.name))
+                return String(Number(expr.name));
+            let g = gensymOf.get(expr.name);
+            if (g === undefined) {
+                g = `g${gensymOf.size}`;
+                gensymOf.set(expr.name, g);
+                meta.set(g, { name: expr.name, dim: expr.dim });
+            }
+            return g;
+        }
+        case 'op': {
+            if (expr.op === '^') {
+                const exp = expr.args[1];
+                if (!exp || exp.kind !== 'symbol' || !isLiteral(exp.name)) {
+                    throw new Unsupported();
+                }
+                return `(${renderGensym(expr.args[0], gensymOf, meta)})^${Number(exp.name)}`;
+            }
+            if (expr.args.length === 0)
+                throw new Unsupported();
+            const parts = expr.args.map((a) => `(${renderGensym(a, gensymOf, meta)})`);
+            return `(${parts.join(expr.op)})`;
+        }
+        default:
+            throw new Unsupported(); // integral / derivative / tensor arms
+    }
+}
+const lit = (v) => ({ kind: 'symbol', name: String(v), dim: DIMENSIONLESS });
+/** Walk a simplified MathTS node back to an ExprNode, un-gensym'ing leaves and
+ *  rejecting anything outside UPT's integer-exponent scalar model (→ throws
+ *  `Unsupported`, a graceful no-op). */
+function walkBack(node, meta) {
+    switch (node.type) {
+        case 'ConstantNode': {
+            if (typeof node.value !== 'number' || !Number.isFinite(node.value)) {
+                throw new Unsupported();
+            }
+            return lit(node.value);
+        }
+        case 'SymbolNode': {
+            const m = node.name !== undefined ? meta.get(node.name) : undefined;
+            if (!m)
+                throw new Unsupported(); // a symbol we did not issue
+            return { kind: 'symbol', name: m.name, dim: m.dim };
+        }
+        case 'ParenthesisNode':
+            if (!node.content)
+                throw new Unsupported();
+            return walkBack(node.content, meta);
+        case 'OperatorNode': {
+            const op = node.op;
+            const args = node.args ?? [];
+            if (op === '^') {
+                if (args.length !== 2)
+                    throw new Unsupported();
+                const exp = args[1];
+                if (exp.type !== 'ConstantNode' ||
+                    typeof exp.value !== 'number' ||
+                    !Number.isInteger(exp.value)) {
+                    throw new Unsupported(); // non-integer exponent — not in ℤ⁷ model
+                }
+                return {
+                    kind: 'op',
+                    op: '^',
+                    args: [walkBack(args[0], meta), lit(exp.value)],
+                };
+            }
+            if ((op === '+' || op === '-') && args.length === 1) {
+                // unary minus → (-1) * arg
+                return { kind: 'op', op: '*', args: [lit(-1), walkBack(args[0], meta)] };
+            }
+            if (op === '+' || op === '-' || op === '*' || op === '/') {
+                if (args.length < 2)
+                    throw new Unsupported();
+                return { kind: 'op', op, args: args.map((a) => walkBack(a, meta)) };
+            }
+            throw new Unsupported();
+        }
+        default:
+            throw new Unsupported(); // FunctionNode (sqrt/cbrt/…) etc.
+    }
+}
+// ---------------------------------------------------------------------------
+// Guards.
+// ---------------------------------------------------------------------------
+function symbolNames(expr, out = []) {
+    if (expr.kind === 'symbol')
+        out.push(expr.name);
+    else if (expr.kind === 'op')
+        for (const a of expr.args)
+            symbolNames(a, out);
+    else if (expr.kind === 'integral') {
+        symbolNames(expr.over, out);
+        symbolNames(expr.integrand, out);
+    }
+    else if (expr.kind === 'derivative') {
+        symbolNames(expr.of, out);
+        symbolNames(expr.wrt, out);
+    }
+    return out;
+}
+const nonNumericSymbols = (expr) => symbolNames(expr).filter((n) => !isLiteral(n));
+const PROBE_VALUES = [2.3, 3.7, 5.1, 7.9, 11.3, 13.1, 17.9, 19.3];
+const PROBE_MULTIPLIERS = [1, 1.7, 0.41, 2.9];
+/** Numeric agreement of `original` and `candidate` over synthesized probes.
+ *  Free (non-constant) leaves get distinct, mutually-incommensurate values to
+ *  avoid accidental cancellation. <2 finite probes ⇒ 'insufficient' (cannot
+ *  verify — EVE-C). */
+function numericAgreement(original, candidate) {
+    const leaves = [...new Set(nonNumericSymbols(original))].filter((n) => !(n in CONSTANTS));
+    let finiteProbes = 0;
+    for (const mult of PROBE_MULTIPLIERS) {
+        const values = {};
+        leaves.forEach((leaf, i) => {
+            values[leaf] = PROBE_VALUES[i % PROBE_VALUES.length] * mult;
+        });
+        let a;
+        let b;
+        try {
+            a = evalExpr(original, values);
+            b = evalExpr(candidate, values);
+        }
+        catch {
+            continue; // a probe drove evalExpr non-finite — skip it
+        }
+        if (!Number.isFinite(a) || !Number.isFinite(b))
+            continue;
+        finiteProbes++;
+        if (Math.abs(a - b) / Math.abs(b || 1) > 1e-9)
+            return 'disagree';
+    }
+    return finiteProbes >= 2 ? 'agree' : 'insufficient';
+}
+/**
+ * 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 async function simplifyExpr(expr) {
+    const mod = await loadSimplifier();
+    if (!mod)
+        return { expr, simplified: false };
+    const gensymOf = new Map();
+    const meta = new Map();
+    let candidate;
+    try {
+        const str = renderGensym(expr, gensymOf, meta);
+        // The peer can THROW on some forms (e.g. a known mathts `simplify` BigInt
+        // bug on nested `a/(b/c²)`); that, like an unsupported node, is a graceful
+        // no-op, not an error. WASM chatter is suppressed (the call is lazy).
+        const simplifiedNode = quietlySync(() => mod.simplify(mod.parse(str)));
+        candidate = walkBack(simplifiedNode, meta);
+    }
+    catch {
+        return { expr, simplified: false }; // unsupported / unrepresentable / peer threw
+    }
+    // Guard 1 — dimensional. Inability to validate ⇒ no-op; a CHANGED dimension
+    // is a representable disagreement ⇒ throw.
+    const origDim = validate(expr).inferredDimension;
+    const newResult = validate(candidate);
+    if (origDim === null || !newResult.ok || newResult.inferredDimension === null) {
+        return { expr, simplified: false };
+    }
+    if (!equals(origDim, newResult.inferredDimension)) {
+        throw new SimplificationError(`simplifyExpr: the simplified form changed dimension — a CAS or ` +
+            `walk-back error.`);
+    }
+    // Guard 2 — structural subset (no non-numeric leaf invented).
+    const origSyms = new Set(nonNumericSymbols(expr));
+    for (const s of nonNumericSymbols(candidate)) {
+        if (!origSyms.has(s))
+            return { expr, simplified: false }; // suspicious ⇒ no-op
+    }
+    // Guard 3 — numeric agreement.
+    const verdict = numericAgreement(expr, candidate);
+    if (verdict === 'disagree') {
+        throw new SimplificationError(`simplifyExpr: the simplified form disagrees numerically with the ` +
+            `original — a CAS or walk-back error.`);
+    }
+    if (verdict === 'insufficient')
+        return { expr, simplified: false };
+    // Identical-structure ⇒ nothing gained; report not simplified.
+    const changed = symbolNames(candidate).length !== symbolNames(expr).length;
+    return { expr: candidate, simplified: changed };
+}
+/**
+ * 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 async function simplifyObservable(obs) {
+    const { expr, simplified } = await simplifyExpr(obs.expr);
+    if (!simplified)
+        return obs;
+    return makeObservable(obs.name, obs.symbol, obs.dim, expr);
+}
+//# sourceMappingURL=expr-simplify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expr-simplify.js","sourceRoot":"","sources":["../../src/composition/expr-simplify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;4DAC4D;AAC5D,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAkBD;wDACwD;AACxD,MAAM,WAAY,SAAQ,KAAK;CAAG;AAElC,8EAA8E;AAC9E,iEAAiE;AACjE,wBAAwB;AACxB,8EAA8E;AAE9E,IAAI,MAAwD,CAAC;AAE7D,2EAA2E;AAC3E,KAAK,UAAU,OAAO,CAAI,EAAoB;IAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAC9B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC;IAChC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5D,OAAO,CAAC,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;IACxB,OAAO,CAAC,KAAK,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;IACxB,OAAO,CAAC,MAA6B,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC;IAC1D,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC;QACxB,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC;QACzB,OAAO,CAAC,MAA6B,CAAC,KAAK,GAAG,SAAS,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;gFACgF;AAChF,KAAK,UAAU,MAAM;IACnB,IAAI,CAAC;QACH,yEAAyE;QACzE,qEAAqE;QACrE,OAAO,MAAM,OAAO,CAAC,KAAK,IAAI,EAAE;YAC9B,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CACvB,iCAAiC,CAClC,CAAoC,CAAC;YACtC,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;gBAC1E,OAAO,IAAI,CAAC;YACd,CAAC;YACD,mEAAmE;YACnE,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;YACtD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;YAChC,kBAAkB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAC7B,OAAO,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1D,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,cAAc;IACrB,MAAM,KAAK,MAAM,EAAE,CAAC;IACpB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;4EAC4E;AAC5E,SAAS,WAAW,CAAI,EAAW;IACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAC9B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC;IAChC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5D,OAAO,CAAC,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;IACxB,OAAO,CAAC,KAAK,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;IACxB,OAAO,CAAC,MAA6B,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC;IAC1D,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC;QACxB,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC;QACzB,OAAO,CAAC,MAA6B,CAAC,KAAK,GAAG,SAAS,CAAC;IAC3D,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,CAAW,EAAE,GAAgB;IACvD,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,CAAC,IAAI;QAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC,CAAC,OAAO;QAAE,kBAAkB,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAClD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE;QAAE,kBAAkB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC3D,CAAC;AAWD,MAAM,SAAS,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AAE3E;;gEAEgE;AAChE,SAAS,YAAY,CACnB,IAAc,EACd,QAA6B,EAC7B,IAA2B;IAE3B,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YAC3D,IAAI,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;gBACpB,CAAC,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACxB,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBAC3B,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,IAAI,CAAC,CAAC,CAAC;YACV,IAAI,IAAI,CAAC,EAAE,KAAK,GAAG,EAAE,CAAC;gBACpB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACzB,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC1D,MAAM,IAAI,WAAW,EAAE,CAAC;gBAC1B,CAAC;gBACD,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/E,CAAC;YACD,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,WAAW,EAAE,CAAC;YACpD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3E,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC;QACpC,CAAC;QACD;YACE,MAAM,IAAI,WAAW,EAAE,CAAC,CAAC,sCAAsC;IACnE,CAAC;AACH,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,CAAS,EAAY,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC;AAE/F;;wCAEwC;AACxC,SAAS,QAAQ,CAAC,IAAc,EAAE,IAA2B;IAC3D,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnE,MAAM,IAAI,WAAW,EAAE,CAAC;YAC1B,CAAC;YACD,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;QACD,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACpE,IAAI,CAAC,CAAC;gBAAE,MAAM,IAAI,WAAW,EAAE,CAAC,CAAC,4BAA4B;YAC7D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;QACtD,CAAC;QACD,KAAK,iBAAiB;YACpB,IAAI,CAAC,IAAI,CAAC,OAAO;gBAAE,MAAM,IAAI,WAAW,EAAE,CAAC;YAC3C,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACtC,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;YAC7B,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACf,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;oBAAE,MAAM,IAAI,WAAW,EAAE,CAAC;gBAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;gBACpB,IACE,GAAG,CAAC,IAAI,KAAK,cAAc;oBAC3B,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;oBAC7B,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAC5B,CAAC;oBACD,MAAM,IAAI,WAAW,EAAE,CAAC,CAAC,yCAAyC;gBACpE,CAAC;gBACD,OAAO;oBACL,IAAI,EAAE,IAAI;oBACV,EAAE,EAAE,GAAG;oBACP,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;iBAChD,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACpD,2BAA2B;gBAC3B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;YAC3E,CAAC;YACD,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACzD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;oBAAE,MAAM,IAAI,WAAW,EAAE,CAAC;gBAC7C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;YACtE,CAAC;YACD,MAAM,IAAI,WAAW,EAAE,CAAC;QAC1B,CAAC;QACD;YACE,MAAM,IAAI,WAAW,EAAE,CAAC,CAAC,kCAAkC;IAC/D,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,WAAW,CAAC,IAAc,EAAE,MAAgB,EAAE;IACrD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI;YAAE,WAAW,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SACvE,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAClC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC5B,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACnC,CAAC;SAAM,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QACtC,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAC1B,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,iBAAiB,GAAG,CAAC,IAAc,EAAY,EAAE,CACrD,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjD,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAClE,MAAM,iBAAiB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;AAE9C;;;uBAGuB;AACvB,SAAS,gBAAgB,CACvB,QAAkB,EAClB,SAAmB;IAEnB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAC7D,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,CACzB,CAAC;IACF,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,IAAI,IAAI,iBAAiB,EAAE,CAAC;QACrC,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YACzB,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;QAC9D,CAAC,CAAC,CAAC;QACH,IAAI,CAAS,CAAC;QACd,IAAI,CAAS,CAAC;QACd,IAAI,CAAC;YACH,CAAC,GAAG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/B,CAAC,GAAG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,8CAA8C;QAC1D,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAS;QACzD,YAAY,EAAE,CAAC;QACf,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI;YAAE,OAAO,UAAU,CAAC;IACnE,CAAC;IACD,OAAO,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC;AACtD,CAAC;AAaD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAc;IAC/C,MAAM,GAAG,GAAG,MAAM,cAAc,EAAE,CAAC;IACnC,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAE7C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzC,IAAI,SAAmB,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC/C,0EAA0E;QAC1E,2EAA2E;QAC3E,sEAAsE;QACtE,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvE,SAAS,GAAG,QAAQ,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,6CAA6C;IACnF,CAAC;IAED,4EAA4E;IAC5E,2CAA2C;IAC3C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,iBAAiB,CAAC;IACjD,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IACtC,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,SAAS,CAAC,iBAAiB,KAAK,IAAI,EAAE,CAAC;QAC9E,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,mBAAmB,CAC3B,iEAAiE;YAC/D,kBAAkB,CACrB,CAAC;IACJ,CAAC;IAED,8DAA8D;IAC9D,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;IAClD,KAAK,MAAM,CAAC,IAAI,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,qBAAqB;IACjF,CAAC;IAED,+BAA+B;IAC/B,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAClD,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3B,MAAM,IAAI,mBAAmB,CAC3B,mEAAmE;YACjE,sCAAsC,CACzC,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,KAAK,cAAc;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAEnE,+DAA+D;IAC/D,MAAM,OAAO,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IAC3E,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAe;IACtD,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,UAAU;QAAE,OAAO,GAAG,CAAC;IAC5B,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC7D,CAAC"}

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

@@ -0,0 +1,29 @@
+/**
+ * Scalar `ExprNode` substitution (v0.12 symbolic composition).
+ *
+ * `substitute(expr, name, replacement)` replaces every `{kind:'symbol', name}`
+ * leaf with `replacement`, recursing the scalar arms (`op` / `integral` /
+ * `derivative`). It returns the new tree AND the occurrence count — the count
+ * is load-bearing: `composeSymbolic` rejects a ZERO-occurrence substitution
+ * (a silent no-op that would yield a dimensionally-valid but physics-wrong
+ * composition ignoring the first operand — Adam A-3). Tensor arms are out of
+ * scope and throw (symbolic composition targets scalar closed forms).
+ *
+ * INTERNAL — not on the public surface.
+ *
+ * @module composition/expr-subst
+ */
+import type { ExprNode } from '../dimensional/validator.js';
+/** The substituted tree and how many leaves were replaced. */
+export interface SubstitutionResult {
+    readonly expr: ExprNode;
+    readonly count: number;
+}
+/**
+ * Replace every leaf `symbol` named `name` with `replacement`. See module
+ * docs. Returns `{ expr, count }`.
+ *
+ * @internal
+ */
+export declare function substitute(expr: ExprNode, name: string, replacement: ExprNode): SubstitutionResult;
+//# sourceMappingURL=expr-subst.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expr-subst.d.ts","sourceRoot":"","sources":["../../src/composition/expr-subst.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAG5D,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,QAAQ,GACpB,kBAAkB,CA0CpB"}

package/dist/composition/expr-subst.js

@@ -0,0 +1,60 @@
+/**
+ * Scalar `ExprNode` substitution (v0.12 symbolic composition).
+ *
+ * `substitute(expr, name, replacement)` replaces every `{kind:'symbol', name}`
+ * leaf with `replacement`, recursing the scalar arms (`op` / `integral` /
+ * `derivative`). It returns the new tree AND the occurrence count — the count
+ * is load-bearing: `composeSymbolic` rejects a ZERO-occurrence substitution
+ * (a silent no-op that would yield a dimensionally-valid but physics-wrong
+ * composition ignoring the first operand — Adam A-3). Tensor arms are out of
+ * scope and throw (symbolic composition targets scalar closed forms).
+ *
+ * INTERNAL — not on the public surface.
+ *
+ * @module composition/expr-subst
+ */
+import { SymbolicEvalError } from './expr-eval.js';
+/**
+ * Replace every leaf `symbol` named `name` with `replacement`. See module
+ * docs. Returns `{ expr, count }`.
+ *
+ * @internal
+ */
+export function substitute(expr, name, replacement) {
+    switch (expr.kind) {
+        case 'symbol':
+            return expr.name === name
+                ? { expr: replacement, count: 1 }
+                : { expr, count: 0 };
+        case 'op': {
+            let count = 0;
+            const args = expr.args.map((a) => {
+                const r = substitute(a, name, replacement);
+                count += r.count;
+                return r.expr;
+            });
+            return { expr: { ...expr, args }, count };
+        }
+        case 'integral': {
+            const over = substitute(expr.over, name, replacement);
+            const integrand = substitute(expr.integrand, name, replacement);
+            return {
+                expr: { ...expr, over: over.expr, integrand: integrand.expr },
+                count: over.count + integrand.count,
+            };
+        }
+        case 'derivative': {
+            const of = substitute(expr.of, name, replacement);
+            const wrt = substitute(expr.wrt, name, replacement);
+            return {
+                expr: { ...expr, of: of.expr, wrt: wrt.expr },
+                count: of.count + wrt.count,
+            };
+        }
+        default:
+            throw new SymbolicEvalError(`substitute: node kind '${expr.kind}' is out of scope (scalar ` +
+                `symbol/op/integral/derivative only; tensor nodes are not ` +
+                `substitutable here).`);
+    }
+}
+//# sourceMappingURL=expr-subst.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expr-subst.js","sourceRoot":"","sources":["../../src/composition/expr-subst.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAQnD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,IAAc,EACd,IAAY,EACZ,WAAqB;IAErB,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI;gBACvB,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE;gBACjC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAEzB,KAAK,IAAI,CAAC,CAAC,CAAC;YACV,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC/B,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;gBAC3C,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC;gBACjB,OAAO,CAAC,CAAC,IAAI,CAAC;YAChB,CAAC,CAAC,CAAC;YACH,OAAO,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC;QAC5C,CAAC;QAED,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;YACtD,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;YAChE,OAAO;gBACL,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,CAAC,IAAI,EAAE;gBAC7D,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK;aACpC,CAAC;QACJ,CAAC;QAED,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,MAAM,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;YAClD,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;YACpD,OAAO;gBACL,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE;gBAC7C,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK;aAC5B,CAAC;QACJ,CAAC;QAED;YACE,MAAM,IAAI,iBAAiB,CACzB,0BAA0B,IAAI,CAAC,IAAI,4BAA4B;gBAC7D,2DAA2D;gBAC3D,sBAAsB,CACzB,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/composition/identifiability.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Identifiability classifier (Consequence 1 of
+ * docs/planning/Bridge-Inference-Epistemics-Note.md, designed in
+ * docs/planning/Identifiability-Classifier-Design-Note.md).
+ *
+ * Answers a STRUCTURAL question over the directed hypergraph of
+ * `BridgeEdge`s: given a set of known quantities and a target quantity,
+ * how many INDEPENDENT ways can the graph compute the target from the
+ * knowns? The count drives the epistemics-note trichotomy:
+ *
+ *   - under-determined — unreachable; needs more inputs or more physics.
+ *   - exactly-determined — one derivation; solvable (up to the
+ *     dimensionless constant dimensional analysis cannot supply).
+ *   - over-determined — ≥2 derivations; the surplus are FALSIFIABLE
+ *     consistency constraints (each predicts the target; they must
+ *     agree). The headline regime.
+ *   - given — the target is itself a known (degenerate); derivations
+ *     become cross-checks on the supplied value.
+ *
+ * This is STRUCTURAL, not parametric: it does not decide whether the
+ * resulting nonlinear system has a unique numeric solution (undecidable
+ * in general for closed-form evaluators). "Independent derivation" means
+ * a structurally distinct edge, NOT a provably-independent formula — two
+ * edges encoding the same relation are counted as two (an honest
+ * over-count). The classifier PROPOSES; humans filter (Part-VI §XXVII-B),
+ * exactly as `enumerateCompositions` does.
+ *
+ * @module composition/identifiability
+ */
+import type { BridgeEdge } from './edge.js';
+import type { QuantityIdentification } from './compose.js';
+/** The four-way structural-identifiability verdict. @public */
+export type IdentifiabilityVerdict = 'given' | 'under-determined' | 'exactly-determined' | 'over-determined';
+/** Options for the classifier. @public */
+export interface IdentifiabilityOptions {
+    /**
+     * Quantity identifications honored when expanding determinability
+     * (directed name-equivalences: `from` determinable ⟹ `to` determinable).
+     * Defaults to the registered {@link QUANTITY_IDENTIFICATIONS}, mirroring
+     * how `composeEdges` connects the graph. Pass `[]` for the pure
+     * physical-edge graph.
+     */
+    readonly identifications?: readonly QuantityIdentification[];
+}
+/** The result of classifying one target against one known set. @public */
+export interface IdentifiabilityResult {
+    /** The target quantity name that was classified. */
+    readonly target: string;
+    /** The known-quantity names (deduplicated). */
+    readonly known: readonly string[];
+    readonly verdict: IdentifiabilityVerdict;
+    /**
+     * Ids of the distinct edges that independently derive the target from
+     * the known set — sources determinable WITHOUT using any edge into the
+     * target (so circular self-support is excluded). Empty ⟺ no physical
+     * derivation (under-determined, or determined only by identity).
+     */
+    readonly derivations: readonly string[];
+    /**
+     * Redundant derivations = falsifiable consistency constraints. For a
+     * non-given target the first derivation pins the value and the rest are
+     * checks (`max(0, |derivations| − 1)`); for a given (measured) target
+     * every derivation is a check (`|derivations|`).
+     */
+    readonly surplusConstraints: number;
+    /**
+     * For under-determined targets: the upstream quantities that block
+     * determinability — on some path toward the target, not determinable
+     * from the known set, not themselves known. Knowing a sufficient subset
+     * moves the target toward determined. Empty when determinable.
+     */
+    readonly blockingFrontier: readonly string[];
+    /** Every quantity determinable from the known set (the forward closure). */
+    readonly determinable: readonly string[];
+}
+/**
+ * The monotone forward closure: the least set ⊇ `knownNames` closed under
+ * "all of an edge's sources determinable ⟹ its target determinable",
+ * with identifications expanding it as directed name-equivalences.
+ *
+ * A parameter-free edge (empty `sources`) fires unconditionally — its
+ * target is in every closure (a constant is always determinable).
+ *
+ * @public
+ */
+export declare function forwardClosure(edges: readonly BridgeEdge[], knownNames: readonly string[], identifications?: readonly QuantityIdentification[]): Set<string>;
+/**
+ * Classify the structural identifiability of `targetName` given
+ * `knownNames` over `edges`. See the module docs and
+ * docs/planning/Identifiability-Classifier-Design-Note.md.
+ *
+ * @public
+ */
+export declare function classifyIdentifiability(edges: readonly BridgeEdge[], knownNames: readonly string[], targetName: string, opts?: IdentifiabilityOptions): IdentifiabilityResult;
+/**
+ * Classify every quantity that is some edge's target, against one known
+ * set. The natural feeder for a retrodiction harness (mask a node, ask
+ * whether the graph recovers it). Sorted by target name.
+ *
+ * @public
+ */
+export declare function classifyAll(edges: readonly BridgeEdge[], knownNames: readonly string[], opts?: IdentifiabilityOptions): IdentifiabilityResult[];
+//# sourceMappingURL=identifiability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"identifiability.d.ts","sourceRoot":"","sources":["../../src/composition/identifiability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAG3D,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAC9B,OAAO,GACP,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,CAAC;AAEtB,0CAA0C;AAC1C,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAC9D;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,eAAe,GAAE,SAAS,sBAAsB,EAA6B,GAC5E,GAAG,CAAC,MAAM,CAAC,CAoBb;AAyBD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,sBAA2B,GAChC,qBAAqB,CAyDvB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,IAAI,GAAE,sBAA2B,GAChC,qBAAqB,EAAE,CAKzB"}