universal-physics-tensor 11.0.0 → 12.0.0

package/dist/diff/bridge-ast-gradient.d.ts

@@ -1,25 +1,24 @@
 /**
- * Exact bridge-gradients via reverse-mode AD over the symbolic RHS AST.
+ * Exact bridge-gradients over the symbolic RHS AST.
  *
  * The catalog's plain-JS evaluators cannot be differentiated by AD (they run
  * raw `Math.*` arithmetic and return a number, which carries no tape; see
  * `bridge-gradient.ts`). But each bridge also carries a faithful symbolic
  * encoding of its RHS (`*_RHS: ExprNode`). This module lowers that scalar AST
- * through `@danielsimonjr/mathts-autograd`'s `TapedTensor` ops — binding the
- * chosen variable to a traced input and every other symbol to a constant tape
- * leaf — so `reverseGrad` returns the EXACT derivative (machine precision), with
- * the plain-JS evaluators left untouched (P8 Decision #1).
+ * with the MathTS scalar builder and differentiates it with MathTS
+ * `compileScalarGradient`: the chosen variable is the one parameter, and every
+ * other symbol is a constant. The result is the EXACT derivative (machine
+ * precision); the plain-JS evaluators stay untouched (P8 Decision #1).
  *
- * Scope: the dimensional scalar grammar is `symbol` + `op(+ − * / ^)` (the
- * transcendentals of a bridge are absorbed into typed-stub *symbols*, so they
- * appear as opaque constants here). A bridge encoded with a typed stub therefore
- * differentiates with respect to the stub, not the physics inside it — faithful,
- * fully-expanded encodings (e.g. BE-42 `ℏc³/(8πGM·k_B)`) differentiate exactly.
- * `^` exponents must be constant (the differentiation variable may not appear in
- * an exponent).
+ * Scope: the scalar grammar is `symbol` + `op(+ − * / ^)` + `transcendental` +
+ * `abs`. A bridge encoded with a typed stub differentiates with respect to the
+ * stub, not the physics inside it; fully-expanded encodings (e.g. BE-42
+ * `ℏc³/(8πGM·k_B)`) differentiate exactly. A `^` exponent must be constant: a
+ * UPT pre-check refuses the differentiation variable in an exponent before
+ * MathTS sees the tree.
  *
- * Loads `@danielsimonjr/mathts-autograd` at the call and throws
- * `EngineCapabilityError` when that import fails.
+ * A point where the value overflows gives `NaN` for the value and the
+ * gradient (MathTS marks the row invalid), not `±Infinity`.
  *
  * @module diff/bridge-ast-gradient
  */
@@ -35,31 +34,36 @@ export interface ASTGradientResult {
     readonly gradient: number;
 }
 /**
- * Differentiate a scalar bridge RHS AST with respect to one symbol via
- * reverse-mode AD. Every symbol other than `varName` is resolved to a constant
- * (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric literal); the
- * `bindings` must contain `varName` (its value sets the point of evaluation).
+ * Differentiate a scalar bridge RHS AST with respect to one symbol through
+ * MathTS `compileScalarGradient`. Every symbol other than `varName` is resolved
+ * to a constant (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric
+ * literal); the `bindings` must contain `varName` (its value sets the point of
+ * evaluation).
  *
+ * @throws TypeError when `varName` is not bound, a symbol cannot be resolved,
+ * `varName` appears in an exponent, or a node kind is outside the scalar grammar.
  * @public
  */
-export declare function bridgeGradientAST(rhs: ExprNode, varName: string, bindings: Record<string, number>): Promise<ASTGradientResult>;
+export declare function bridgeGradientAST(rhs: ExprNode, varName: string, bindings: Record<string, number>): ASTGradientResult;
 /**
  * Convenience wrapper around {@link bridgeGradientAST} that looks the RHS AST up
  * by catalog bridge id. `bridgeId` accepts a number, `'42'`, or `'BE-42'`.
  *
  * Throws if the id has no encoded RHS in {@link BRIDGE_RHS_BY_ID} (e.g. BE-51/52,
  * which are closed-form evaluators without an AST). If the bridge's RHS is not in
- * the differentiable scalar grammar (a tensor/integral/curvature encoding), the
+ * the differentiable scalar grammar (a tensor, integral or curvature encoding), the
  * delegated `bridgeGradientAST` throws the "unsupported node kind" error — use
  * {@link astDifferentiableBridgeIds} to discover which ids are AD-eligible.
  *
  * @public
  */
-export declare function bridgeGradientASTById(bridgeId: number | string, varName: string, bindings: Record<string, number>): Promise<ASTGradientResult>;
+export declare function bridgeGradientASTById(bridgeId: number | string, varName: string, bindings: Record<string, number>): ASTGradientResult;
 /**
  * The catalog bridge ids whose encoded RHS lies entirely in the differentiable
- * scalar grammar — i.e. those `bridgeGradientASTById` can differentiate exactly.
- * Bridges encoded with tensor/integral/curvature nodes (or whose physics is
+ * scalar grammar. `bridgeGradientASTById` differentiates each of them exactly
+ * with respect to any variable that is not in an exponent; a variable in an
+ * exponent is refused (`checkExponents`).
+ * Bridges encoded with tensor, integral or curvature nodes (or whose physics is
  * hidden behind a typed-stub symbol) are excluded from EXACT differentiation
  * (a stub still differentiates w.r.t. the stub symbol, but not the physics
  * inside it). Returned sorted ascending.

package/dist/diff/bridge-ast-gradient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-ast-gradient.d.ts","sourceRoot":"","sources":["../../src/diff/bridge-ast-gradient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAoB,MAAM,6BAA6B,CAAC;AAM9E;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AA2ID;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAgI5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,MAAM,EACzB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAU5B;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,EAAE,CAMrD"}
+{"version":3,"file":"bridge-ast-gradient.d.ts","sourceRoot":"","sources":["../../src/diff/bridge-ast-gradient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAM5D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAgFD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,iBAAiB,CAkCnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,MAAM,EACzB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,iBAAiB,CAUnB;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,EAAE,CAMrD"}

package/dist/diff/bridge-ast-gradient.js

@@ -1,69 +1,45 @@
 /**
- * Exact bridge-gradients via reverse-mode AD over the symbolic RHS AST.
+ * Exact bridge-gradients over the symbolic RHS AST.
  *
  * The catalog's plain-JS evaluators cannot be differentiated by AD (they run
  * raw `Math.*` arithmetic and return a number, which carries no tape; see
  * `bridge-gradient.ts`). But each bridge also carries a faithful symbolic
  * encoding of its RHS (`*_RHS: ExprNode`). This module lowers that scalar AST
- * through `@danielsimonjr/mathts-autograd`'s `TapedTensor` ops — binding the
- * chosen variable to a traced input and every other symbol to a constant tape
- * leaf — so `reverseGrad` returns the EXACT derivative (machine precision), with
- * the plain-JS evaluators left untouched (P8 Decision #1).
+ * with the MathTS scalar builder and differentiates it with MathTS
+ * `compileScalarGradient`: the chosen variable is the one parameter, and every
+ * other symbol is a constant. The result is the EXACT derivative (machine
+ * precision); the plain-JS evaluators stay untouched (P8 Decision #1).
  *
- * Scope: the dimensional scalar grammar is `symbol` + `op(+ − * / ^)` (the
- * transcendentals of a bridge are absorbed into typed-stub *symbols*, so they
- * appear as opaque constants here). A bridge encoded with a typed stub therefore
- * differentiates with respect to the stub, not the physics inside it — faithful,
- * fully-expanded encodings (e.g. BE-42 `ℏc³/(8πGM·k_B)`) differentiate exactly.
- * `^` exponents must be constant (the differentiation variable may not appear in
- * an exponent).
+ * Scope: the scalar grammar is `symbol` + `op(+ − * / ^)` + `transcendental` +
+ * `abs`. A bridge encoded with a typed stub differentiates with respect to the
+ * stub, not the physics inside it; fully-expanded encodings (e.g. BE-42
+ * `ℏc³/(8πGM·k_B)`) differentiate exactly. A `^` exponent must be constant: a
+ * UPT pre-check refuses the differentiation variable in an exponent before
+ * MathTS sees the tree.
  *
- * Loads `@danielsimonjr/mathts-autograd` at the call and throws
- * `EngineCapabilityError` when that import fails.
+ * A point where the value overflows gives `NaN` for the value and the
+ * gradient (MathTS marks the row invalid), not `±Infinity`.
  *
  * @module diff/bridge-ast-gradient
  */
+import { ScalarBuildError } from '@danielsimonjr/mathts-expression';
+import { compileScalarGradient } from '@danielsimonjr/mathts-functions';
+import { forEachScalarLeaf, isDecimalLiteral } from '../dimensional/ast-leaves.js';
 import { constantScope } from '../dimensional/symbolic-constants.js';
-import { EngineCapabilityError } from '../numerical/errors.js';
+import { toScalarNode } from '../dimensional/scalar-lowering.js';
 import { BRIDGE_RHS_BY_ID, parseBridgeId } from '../bridges/rhs-registry.js';
-import { GAUSS_LEGENDRE_16 } from '../numerical/quadrature.js';
-/** Map a transcendental fn name to the TapedTensor method that traces it. */
-function applyTranscendental(fn, t) {
-    switch (fn) {
-        case 'exp':
-            return t.exp();
-        case 'ln':
-            return t.log();
-        case 'log2':
-            return t.log2();
-        case 'log10':
-            return t.log10();
-        case 'sin':
-            return t.sin();
-        case 'cos':
-            return t.cos();
-        case 'tan':
-            return t.tan();
-        case 'sinh':
-            return t.sinh();
-        case 'cosh':
-            return t.cosh();
-        case 'tanh':
-            return t.tanh();
-    }
-}
 /**
  * Named physical constants the bridge encodings reference as bare symbols:
  * every registered spelling, from the constant registry, plus π and its
- * registered multiples, so a traced AST evaluates to the SAME number as the
+ * registered multiples, so the AST evaluates to the SAME number as the
  * numeric evaluator. Callers can override or extend via the `bindings` argument.
  */
 const NAMED_CONSTANTS = constantScope();
 /** Resolve a symbol's numeric value: caller bindings → named constants → numeric literal. */
 function resolveConstant(name, bindings) {
-    if (Object.prototype.hasOwnProperty.call(bindings, name))
+    if (Object.hasOwn(bindings, name))
         return bindings[name];
-    if (Object.prototype.hasOwnProperty.call(NAMED_CONSTANTS, name))
+    if (Object.hasOwn(NAMED_CONSTANTS, name))
         return NAMED_CONSTANTS[name];
     const asNumber = Number(name);
     if (name.trim() !== '' && Number.isFinite(asNumber))
@@ -75,9 +51,8 @@ function resolveConstant(name, bindings) {
  *
  * The exponent may contain scalar arithmetic over constants/bindings (for
  * example `-1/z`) as long as it is independent of the differentiation
- * variable. Variable exponents require a traced `pow(base, exponent)` op,
- * which the current MathTS tape surface does not expose, so they are rejected
- * explicitly rather than being silently detached from AD.
+ * variable. UPT keeps the constant-power contract, so the differentiation
+ * variable in an exponent is refused before MathTS reads the tree.
  */
 function resolveExponent(node, varName, bindings) {
     if (node.kind === 'symbol') {
@@ -103,125 +78,60 @@ function resolveExponent(node, varName, bindings) {
     throw new TypeError(`bridgeGradientAST: '^' exponent must be a constant scalar expression, got node kind '${node.kind}'.`);
 }
 /**
- * Differentiate a scalar bridge RHS AST with respect to one symbol via
- * reverse-mode AD. Every symbol other than `varName` is resolved to a constant
- * (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric literal); the
- * `bindings` must contain `varName` (its value sets the point of evaluation).
+ * Refuse the differentiation variable in any `^` exponent, and check that every
+ * exponent is a constant scalar expression. MathTS would differentiate a
+ * variable exponent; UPT keeps the constant-power contract.
+ */
+function checkExponents(node, varName, bindings) {
+    if (node.kind === 'op') {
+        if (node.op === '^' && node.args.length === 2)
+            resolveExponent(node.args[1], varName, bindings);
+        for (const arg of node.args)
+            checkExponents(arg, varName, bindings);
+    }
+    else if (node.kind === 'transcendental' || node.kind === 'abs') {
+        checkExponents(node.arg, varName, bindings);
+    }
+}
+/**
+ * Differentiate a scalar bridge RHS AST with respect to one symbol through
+ * MathTS `compileScalarGradient`. Every symbol other than `varName` is resolved
+ * to a constant (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric
+ * literal); the `bindings` must contain `varName` (its value sets the point of
+ * evaluation).
  *
+ * @throws TypeError when `varName` is not bound, a symbol cannot be resolved,
+ * `varName` appears in an exponent, or a node kind is outside the scalar grammar.
  * @public
  */
-export async function bridgeGradientAST(rhs, varName, bindings) {
-    if (!Object.prototype.hasOwnProperty.call(bindings, varName)) {
+export function bridgeGradientAST(rhs, varName, bindings) {
+    if (!Object.hasOwn(bindings, varName)) {
         throw new TypeError(`bridgeGradientAST: bindings must contain the differentiation variable '${varName}'.`);
     }
-    let autograd;
-    let tensorMod;
+    checkExponents(rhs, varName, bindings);
+    let lowered;
     try {
-        // The two modules are typed by the structural views above (the members
-        // this lowering calls: reverseGrad, TapedTensor, Tensor.fromNested …).
-        // The casts state that those members exist on the imported modules, which
-        // their own type declarations guarantee; the full MathTS types are not
-        // imported so this file compiles without the autograd types at hand.
-        autograd =
-            (await import('@danielsimonjr/mathts-autograd'));
-        tensorMod =
-            (await import('@danielsimonjr/mathts-tensor'));
+        lowered = toScalarNode(rhs);
     }
-    catch {
-        throw new EngineCapabilityError('mathts-autograd', 'reverseGrad');
+    catch (err) {
+        if (!(err instanceof ScalarBuildError))
+            throw err;
+        throw new TypeError(`bridgeGradientAST: unsupported node kind — ${err.message}. The differentiable grammar is ` +
+            `symbol + op(+ − * / ^) + transcendental + abs. Other encodings (tensor/curvature, integrals, ` +
+            `or physics hidden in a typed-stub symbol) are not exactly differentiable.`);
     }
-    const { reverseGrad, TapedTensor } = autograd;
-    const { Tensor } = tensorMod;
-    // Build the (traced var) → scalar function reverseGrad expects. `x` arrives as
-    // a TapedTensor; constants become extra tape leaves (their gradients are
-    // computed and ignored — only `x`'s gradient is returned).
-    const fn = (x) => {
-        const constLeaf = (v) => TapedTensor.fromTensorAsInput(Tensor.fromNested(v, []), x.tape);
-        // `boundVars` maps an integration variable name to its current (traced)
-        // quadrature point; it is checked BEFORE the diff-var / constants so an
-        // integration variable correctly shadows an outer symbol of the same name.
-        const walk = (node, boundVars) => {
-            if (node.kind === 'symbol') {
-                const bound = boundVars.get(node.name);
-                if (bound !== undefined)
-                    return bound;
-                return node.name === varName
-                    ? x
-                    : constLeaf(resolveConstant(node.name, bindings));
-            }
-            if (node.kind === 'op') {
-                switch (node.op) {
-                    case '+':
-                        return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.add(b));
-                    case '-': {
-                        const terms = node.args.map((a) => walk(a, boundVars));
-                        // Unary minus (0 − t); n-ary subtract folds left.
-                        return terms.length === 1
-                            ? constLeaf(0).sub(terms[0])
-                            : terms.reduce((a, b) => a.sub(b));
-                    }
-                    case '*':
-                        return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.mul(b));
-                    case '/':
-                        return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.divide(b));
-                    case '^':
-                        return walk(node.args[0], boundVars).pow(resolveExponent(node.args[1], varName, bindings));
-                    default:
-                        throw new TypeError(`bridgeGradientAST: unsupported operator '${node.op}'.`);
-                }
-            }
-            if (node.kind === 'transcendental') {
-                return applyTranscendental(node.fn, walk(node.arg, boundVars));
-            }
-            if (node.kind === 'abs') {
-                return walk(node.arg, boundVars).abs();
-            }
-            if (node.kind === 'integral') {
-                // Definite integral via 16-point Gauss–Legendre quadrature, built from
-                // traced ops so reverse-mode AD yields the gradient w.r.t. integrand
-                // parameters (Leibniz: ∫ ∂f/∂θ) and w.r.t. bounds (∂Q/∂b ≈ f(b)).
-                // NOTE: the gradient is EXACT for the quadrature, which APPROXIMATES the
-                // true integral for non-polynomial integrands (exact for constant /
-                // polynomial-degree ≤ 31 integrands).
-                if (!node.lower || !node.upper) {
-                    throw new TypeError(`bridgeGradientAST: an abstract (bound-less) integral is not differentiable; ` +
-                        `supply lower/upper bounds for a definite integral.`);
-                }
-                if (node.over.kind !== 'symbol') {
-                    throw new TypeError(`bridgeGradientAST: integral 'over' must be a symbol.`);
-                }
-                const overName = node.over.name;
-                if (overName === varName) {
-                    throw new TypeError(`bridgeGradientAST: cannot differentiate w.r.t. the integration variable '${overName}'.`);
-                }
-                const lo = walk(node.lower, boundVars);
-                const hi = walk(node.upper, boundVars);
-                const half = hi.sub(lo).scale(0.5); // (b − a)/2
-                const mid = lo.add(hi).scale(0.5); // (a + b)/2
-                let sum = null;
-                for (const gl of GAUSS_LEGENDRE_16) {
-                    const xPoint = mid.add(half.scale(gl.node)); // (b−a)/2·ξ + (a+b)/2
-                    const env = new Map(boundVars);
-                    env.set(overName, xPoint);
-                    const term = walk(node.integrand, env).scale(gl.weight);
-                    sum = sum === null ? term : sum.add(term);
-                }
-                // GAUSS_LEGENDRE_16 is non-empty, so `sum` is set.
-                return half.mul(sum);
-            }
-            throw new TypeError(`bridgeGradientAST: unsupported node kind '${node.kind}' — the differentiable ` +
-                `grammar is symbol + op(+ − * / ^) + transcendental + abs + definite integral. ` +
-                `Other encodings (tensor/curvature, bound-less integrals, or physics hidden in ` +
-                `a typed-stub symbol) are not exactly differentiable.`);
-        };
-        return walk(rhs, new Map());
-    };
-    const xLeaf = Tensor.fromNested(bindings[varName], []);
-    const { value, gradient } = reverseGrad(fn, xLeaf);
-    return {
-        value: value.toNested(),
-        gradient: gradient.toNested(),
-    };
+    const constants = {};
+    forEachScalarLeaf(rhs, (leaf) => {
+        if (leaf.name === varName)
+            return;
+        // A literal spelling stays MathTS's literal unless the caller bound that name.
+        if (isDecimalLiteral(leaf.name) && !Object.hasOwn(bindings, leaf.name))
+            return;
+        constants[leaf.name] = resolveConstant(leaf.name, bindings);
+    }, { transcendental: true, abs: true });
+    const compiled = compileScalarGradient(lowered, { variables: [], parameters: [varName], constants });
+    const { values, grad } = compiled.evaluate([], [bindings[varName]]);
+    return { value: values[0], gradient: grad[0] };
 }
 /**
  * Convenience wrapper around {@link bridgeGradientAST} that looks the RHS AST up
@@ -229,7 +139,7 @@ export async function bridgeGradientAST(rhs, varName, bindings) {
  *
  * Throws if the id has no encoded RHS in {@link BRIDGE_RHS_BY_ID} (e.g. BE-51/52,
  * which are closed-form evaluators without an AST). If the bridge's RHS is not in
- * the differentiable scalar grammar (a tensor/integral/curvature encoding), the
+ * the differentiable scalar grammar (a tensor, integral or curvature encoding), the
  * delegated `bridgeGradientAST` throws the "unsupported node kind" error — use
  * {@link astDifferentiableBridgeIds} to discover which ids are AD-eligible.
  *
@@ -244,7 +154,7 @@ export function bridgeGradientASTById(bridgeId, varName, bindings) {
     }
     return bridgeGradientAST(rhs, varName, bindings);
 }
-/** Whether an AST consists solely of the differentiable scalar grammar (symbol + op(+ − * / ^)). */
+/** Whether an AST consists solely of the differentiable scalar grammar (symbol + op(+ − * / ^) + transcendental + abs). */
 function isDifferentiableScalarAST(node) {
     if (node.kind === 'symbol')
         return true;
@@ -253,24 +163,16 @@ function isDifferentiableScalarAST(node) {
             return false;
         return node.args.every(isDifferentiableScalarAST);
     }
-    if (node.kind === 'transcendental')
+    if (node.kind === 'transcendental' || node.kind === 'abs')
         return isDifferentiableScalarAST(node.arg);
-    if (node.kind === 'abs')
-        return isDifferentiableScalarAST(node.arg);
-    if (node.kind === 'integral') {
-        return (!!node.lower &&
-            !!node.upper &&
-            node.over.kind === 'symbol' &&
-            isDifferentiableScalarAST(node.integrand) &&
-            isDifferentiableScalarAST(node.lower) &&
-            isDifferentiableScalarAST(node.upper));
-    }
     return false;
 }
 /**
  * The catalog bridge ids whose encoded RHS lies entirely in the differentiable
- * scalar grammar — i.e. those `bridgeGradientASTById` can differentiate exactly.
- * Bridges encoded with tensor/integral/curvature nodes (or whose physics is
+ * scalar grammar. `bridgeGradientASTById` differentiates each of them exactly
+ * with respect to any variable that is not in an exponent; a variable in an
+ * exponent is refused (`checkExponents`).
+ * Bridges encoded with tensor, integral or curvature nodes (or whose physics is
  * hidden behind a typed-stub symbol) are excluded from EXACT differentiation
  * (a stub still differentiates w.r.t. the stub symbol, but not the physics
  * inside it). Returned sorted ascending.

package/dist/diff/bridge-ast-gradient.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-ast-gradient.js","sourceRoot":"","sources":["../../src/diff/bridge-ast-gradient.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Exact bridge-gradients via reverse-mode AD over the symbolic RHS AST.\n *\n * The catalog's plain-JS evaluators cannot be differentiated by AD (they run\n * raw `Math.*` arithmetic and return a number, which carries no tape; see\n * `bridge-gradient.ts`). But each bridge also carries a faithful symbolic\n * encoding of its RHS (`*_RHS: ExprNode`). This module lowers that scalar AST\n * through `@danielsimonjr/mathts-autograd`'s `TapedTensor` ops — binding the\n * chosen variable to a traced input and every other symbol to a constant tape\n * leaf — so `reverseGrad` returns the EXACT derivative (machine precision), with\n * the plain-JS evaluators left untouched (P8 Decision #1).\n *\n * Scope: the dimensional scalar grammar is `symbol` + `op(+ − * / ^)` (the\n * transcendentals of a bridge are absorbed into typed-stub *symbols*, so they\n * appear as opaque constants here). A bridge encoded with a typed stub therefore\n * differentiates with respect to the stub, not the physics inside it — faithful,\n * fully-expanded encodings (e.g. BE-42 `ℏc³/(8πGM·k_B)`) differentiate exactly.\n * `^` exponents must be constant (the differentiation variable may not appear in\n * an exponent).\n *\n * Loads `@danielsimonjr/mathts-autograd` at the call and throws\n * `EngineCapabilityError` when that import fails.\n *\n * @module diff/bridge-ast-gradient\n */\n\nimport type { ExprNode, TranscendentalFn } from '../dimensional/validator.js';\nimport { constantScope } from '../dimensional/symbolic-constants.js';\nimport { EngineCapabilityError } from '../numerical/errors.js';\nimport { BRIDGE_RHS_BY_ID, parseBridgeId } from '../bridges/rhs-registry.js';\nimport { GAUSS_LEGENDRE_16 } from '../numerical/quadrature.js';\n\n/**\n * Result of {@link bridgeGradientAST}: the bridge's scalar `value` at the\n * supplied point and the exact `gradient` d(value)/d(varName).\n *\n * @public\n */\nexport interface ASTGradientResult {\n  readonly value: number;\n  readonly gradient: number;\n}\n\n// --- Structural views of the autograd/tensor packages (required dependencies; the\n// dynamic import keeps the AD path off the module's load, and its result is narrowed\n// to the call-site shape). ---\n\ntype TapeHandle = unknown;\n\ninterface TapedScalar {\n  readonly tape: TapeHandle;\n  add(o: TapedScalar): TapedScalar;\n  sub(o: TapedScalar): TapedScalar;\n  mul(o: TapedScalar): TapedScalar;\n  divide(o: TapedScalar): TapedScalar;\n  scale(k: number): TapedScalar;\n  pow(k: number): TapedScalar;\n  exp(): TapedScalar;\n  log(): TapedScalar;\n  log2(): TapedScalar;\n  log10(): TapedScalar;\n  sin(): TapedScalar;\n  cos(): TapedScalar;\n  tan(): TapedScalar;\n  sinh(): TapedScalar;\n  cosh(): TapedScalar;\n  tanh(): TapedScalar;\n  abs(): TapedScalar;\n}\n\n/** Map a transcendental fn name to the TapedTensor method that traces it. */\nfunction applyTranscendental(fn: TranscendentalFn, t: TapedScalar): TapedScalar {\n  switch (fn) {\n    case 'exp':\n      return t.exp();\n    case 'ln':\n      return t.log();\n    case 'log2':\n      return t.log2();\n    case 'log10':\n      return t.log10();\n    case 'sin':\n      return t.sin();\n    case 'cos':\n      return t.cos();\n    case 'tan':\n      return t.tan();\n    case 'sinh':\n      return t.sinh();\n    case 'cosh':\n      return t.cosh();\n    case 'tanh':\n      return t.tanh();\n  }\n}\n\ninterface MathTSTensorLike {\n  toNested(): unknown;\n}\n\ninterface AutogradModuleLike {\n  reverseGrad(\n    fn: (x: TapedScalar) => TapedScalar,\n    x: MathTSTensorLike,\n    cotangent?: MathTSTensorLike,\n  ): { value: MathTSTensorLike; gradient: MathTSTensorLike };\n  TapedTensor: {\n    fromTensorAsInput(t: MathTSTensorLike, tape: TapeHandle): TapedScalar;\n  };\n}\n\ninterface TensorModuleLike {\n  Tensor: { fromNested(data: number, shape: number[]): MathTSTensorLike };\n}\n\n/**\n * Named physical constants the bridge encodings reference as bare symbols:\n * every registered spelling, from the constant registry, plus π and its\n * registered multiples, so a traced AST evaluates to the SAME number as the\n * numeric evaluator. Callers can override or extend via the `bindings` argument.\n */\nconst NAMED_CONSTANTS: Readonly<Record<string, number>> = constantScope();\n\n/** Resolve a symbol's numeric value: caller bindings → named constants → numeric literal. */\nfunction resolveConstant(\n  name: string,\n  bindings: Record<string, number>,\n): number {\n  if (Object.prototype.hasOwnProperty.call(bindings, name))\n    return bindings[name];\n  if (Object.prototype.hasOwnProperty.call(NAMED_CONSTANTS, name))\n    return NAMED_CONSTANTS[name];\n  const asNumber = Number(name);\n  if (name.trim() !== '' && Number.isFinite(asNumber)) return asNumber;\n  throw new TypeError(\n    `bridgeGradientAST: unknown symbol '${name}' — not a binding, a named constant ` +\n      `(${Object.keys(NAMED_CONSTANTS).join(', ')}), or a numeric literal. Supply it in bindings.`,\n  );\n}\n\n/** Resolve a `^` exponent to a numeric constant expression.\n *\n * The exponent may contain scalar arithmetic over constants/bindings (for\n * example `-1/z`) as long as it is independent of the differentiation\n * variable. Variable exponents require a traced `pow(base, exponent)` op,\n * which the current MathTS tape surface does not expose, so they are rejected\n * explicitly rather than being silently detached from AD.\n */\nfunction resolveExponent(\n  node: ExprNode,\n  varName: string,\n  bindings: Record<string, number>,\n): number {\n  if (node.kind === 'symbol') {\n    if (node.name === varName) {\n      throw new TypeError(\n        `bridgeGradientAST: differentiation variable '${varName}' appears as an exponent — ` +\n          `variable exponents are not supported (only constant powers).`,\n      );\n    }\n    return resolveConstant(node.name, bindings);\n  }\n  if (node.kind === 'op') {\n    const values = node.args.map((arg) => resolveExponent(arg, varName, bindings));\n    if (values.length === 0) {\n      throw new TypeError(`bridgeGradientAST: '${node.op}' exponent expression has no operands.`);\n    }\n    switch (node.op) {\n      case '+': return values.reduce((a, b) => a + b);\n      case '-': return values.length === 1 ? -values[0] : values.slice(1).reduce((a, b) => a - b, values[0]);\n      case '*': return values.reduce((a, b) => a * b);\n      case '/': return values.slice(1).reduce((a, b) => a / b, values[0]);\n      case '^': return values.slice(1).reduce((a, b) => a ** b, values[0]);\n    }\n  }\n  throw new TypeError(\n    `bridgeGradientAST: '^' exponent must be a constant scalar expression, got node kind '${node.kind}'.`,\n  );\n}\n\n/**\n * Differentiate a scalar bridge RHS AST with respect to one symbol via\n * reverse-mode AD. Every symbol other than `varName` is resolved to a constant\n * (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric literal); the\n * `bindings` must contain `varName` (its value sets the point of evaluation).\n *\n * @public\n */\nexport async function bridgeGradientAST(\n  rhs: ExprNode,\n  varName: string,\n  bindings: Record<string, number>,\n): Promise<ASTGradientResult> {\n  if (!Object.prototype.hasOwnProperty.call(bindings, varName)) {\n    throw new TypeError(\n      `bridgeGradientAST: bindings must contain the differentiation variable '${varName}'.`,\n    );\n  }\n\n  let autograd: AutogradModuleLike;\n  let tensorMod: TensorModuleLike;\n  try {\n    // The two modules are typed by the structural views above (the members\n    // this lowering calls: reverseGrad, TapedTensor, Tensor.fromNested …).\n    // The casts state that those members exist on the imported modules, which\n    // their own type declarations guarantee; the full MathTS types are not\n    // imported so this file compiles without the autograd types at hand.\n    autograd =\n      (await import('@danielsimonjr/mathts-autograd')) as unknown as AutogradModuleLike;\n    tensorMod =\n      (await import('@danielsimonjr/mathts-tensor')) as unknown as TensorModuleLike;\n  } catch {\n    throw new EngineCapabilityError('mathts-autograd', 'reverseGrad');\n  }\n  const { reverseGrad, TapedTensor } = autograd;\n  const { Tensor } = tensorMod;\n\n  // Build the (traced var) → scalar function reverseGrad expects. `x` arrives as\n  // a TapedTensor; constants become extra tape leaves (their gradients are\n  // computed and ignored — only `x`'s gradient is returned).\n  const fn = (x: TapedScalar): TapedScalar => {\n    const constLeaf = (v: number): TapedScalar =>\n      TapedTensor.fromTensorAsInput(Tensor.fromNested(v, []), x.tape);\n\n    // `boundVars` maps an integration variable name to its current (traced)\n    // quadrature point; it is checked BEFORE the diff-var / constants so an\n    // integration variable correctly shadows an outer symbol of the same name.\n    const walk = (node: ExprNode, boundVars: ReadonlyMap<string, TapedScalar>): TapedScalar => {\n      if (node.kind === 'symbol') {\n        const bound = boundVars.get(node.name);\n        if (bound !== undefined) return bound;\n        return node.name === varName\n          ? x\n          : constLeaf(resolveConstant(node.name, bindings));\n      }\n      if (node.kind === 'op') {\n        switch (node.op) {\n          case '+':\n            return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.add(b));\n          case '-': {\n            const terms = node.args.map((a) => walk(a, boundVars));\n            // Unary minus (0 − t); n-ary subtract folds left.\n            return terms.length === 1\n              ? constLeaf(0).sub(terms[0])\n              : terms.reduce((a, b) => a.sub(b));\n          }\n          case '*':\n            return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.mul(b));\n          case '/':\n            return node.args.map((a) => walk(a, boundVars)).reduce((a, b) => a.divide(b));\n          case '^':\n            return walk(node.args[0], boundVars).pow(\n              resolveExponent(node.args[1], varName, bindings),\n            );\n          default:\n            throw new TypeError(\n              `bridgeGradientAST: unsupported operator '${node.op}'.`,\n            );\n        }\n      }\n      if (node.kind === 'transcendental') {\n        return applyTranscendental(node.fn, walk(node.arg, boundVars));\n      }\n      if (node.kind === 'abs') {\n        return walk(node.arg, boundVars).abs();\n      }\n      if (node.kind === 'integral') {\n        // Definite integral via 16-point Gauss–Legendre quadrature, built from\n        // traced ops so reverse-mode AD yields the gradient w.r.t. integrand\n        // parameters (Leibniz: ∫ ∂f/∂θ) and w.r.t. bounds (∂Q/∂b ≈ f(b)).\n        // NOTE: the gradient is EXACT for the quadrature, which APPROXIMATES the\n        // true integral for non-polynomial integrands (exact for constant /\n        // polynomial-degree ≤ 31 integrands).\n        if (!node.lower || !node.upper) {\n          throw new TypeError(\n            `bridgeGradientAST: an abstract (bound-less) integral is not differentiable; ` +\n              `supply lower/upper bounds for a definite integral.`,\n          );\n        }\n        if (node.over.kind !== 'symbol') {\n          throw new TypeError(`bridgeGradientAST: integral 'over' must be a symbol.`);\n        }\n        const overName = node.over.name;\n        if (overName === varName) {\n          throw new TypeError(\n            `bridgeGradientAST: cannot differentiate w.r.t. the integration variable '${overName}'.`,\n          );\n        }\n        const lo = walk(node.lower, boundVars);\n        const hi = walk(node.upper, boundVars);\n        const half = hi.sub(lo).scale(0.5); // (b − a)/2\n        const mid = lo.add(hi).scale(0.5); // (a + b)/2\n        let sum: TapedScalar | null = null;\n        for (const gl of GAUSS_LEGENDRE_16) {\n          const xPoint = mid.add(half.scale(gl.node)); // (b−a)/2·ξ + (a+b)/2\n          const env = new Map(boundVars);\n          env.set(overName, xPoint);\n          const term = walk(node.integrand, env).scale(gl.weight);\n          sum = sum === null ? term : sum.add(term);\n        }\n        // GAUSS_LEGENDRE_16 is non-empty, so `sum` is set.\n        return half.mul(sum as TapedScalar);\n      }\n      throw new TypeError(\n        `bridgeGradientAST: unsupported node kind '${node.kind}' — the differentiable ` +\n          `grammar is symbol + op(+ − * / ^) + transcendental + abs + definite integral. ` +\n          `Other encodings (tensor/curvature, bound-less integrals, or physics hidden in ` +\n          `a typed-stub symbol) are not exactly differentiable.`,\n      );\n    };\n\n    return walk(rhs, new Map());\n  };\n\n  const xLeaf = Tensor.fromNested(bindings[varName], []);\n  const { value, gradient } = reverseGrad(fn, xLeaf);\n  return {\n    value: value.toNested() as number,\n    gradient: gradient.toNested() as number,\n  };\n}\n\n/**\n * Convenience wrapper around {@link bridgeGradientAST} that looks the RHS AST up\n * by catalog bridge id. `bridgeId` accepts a number, `'42'`, or `'BE-42'`.\n *\n * Throws if the id has no encoded RHS in {@link BRIDGE_RHS_BY_ID} (e.g. BE-51/52,\n * which are closed-form evaluators without an AST). If the bridge's RHS is not in\n * the differentiable scalar grammar (a tensor/integral/curvature encoding), the\n * delegated `bridgeGradientAST` throws the \"unsupported node kind\" error — use\n * {@link astDifferentiableBridgeIds} to discover which ids are AD-eligible.\n *\n * @public\n */\nexport function bridgeGradientASTById(\n  bridgeId: number | string,\n  varName: string,\n  bindings: Record<string, number>\n): Promise<ASTGradientResult> {\n  const id = parseBridgeId(bridgeId);\n  const rhs = BRIDGE_RHS_BY_ID.get(id);\n  if (rhs === undefined) {\n    throw new TypeError(\n      `bridgeGradientASTById: BE-${id} has no encoded RHS AST in the registry ` +\n        `(BE-51/52 are closed-form; ${BRIDGE_RHS_BY_ID.size} bridges have an encoded AST).`\n    );\n  }\n  return bridgeGradientAST(rhs, varName, bindings);\n}\n\n/** Whether an AST consists solely of the differentiable scalar grammar (symbol + op(+ − * / ^)). */\nfunction isDifferentiableScalarAST(node: ExprNode): boolean {\n  if (node.kind === 'symbol') return true;\n  if (node.kind === 'op') {\n    if (!['+', '-', '*', '/', '^'].includes(node.op)) return false;\n    return node.args.every(isDifferentiableScalarAST);\n  }\n  if (node.kind === 'transcendental') return isDifferentiableScalarAST(node.arg);\n  if (node.kind === 'abs') return isDifferentiableScalarAST(node.arg);\n  if (node.kind === 'integral') {\n    return (\n      !!node.lower &&\n      !!node.upper &&\n      node.over.kind === 'symbol' &&\n      isDifferentiableScalarAST(node.integrand) &&\n      isDifferentiableScalarAST(node.lower) &&\n      isDifferentiableScalarAST(node.upper)\n    );\n  }\n  return false;\n}\n\n/**\n * The catalog bridge ids whose encoded RHS lies entirely in the differentiable\n * scalar grammar — i.e. those `bridgeGradientASTById` can differentiate exactly.\n * Bridges encoded with tensor/integral/curvature nodes (or whose physics is\n * hidden behind a typed-stub symbol) are excluded from EXACT differentiation\n * (a stub still differentiates w.r.t. the stub symbol, but not the physics\n * inside it). Returned sorted ascending.\n *\n * @public\n */\nexport function astDifferentiableBridgeIds(): number[] {\n  const ids: number[] = [];\n  for (const [id, rhs] of BRIDGE_RHS_BY_ID) {\n    if (isDifferentiableScalarAST(rhs)) ids.push(id);\n  }\n  return ids.sort((a, b) => a - b);\n}\n"]}
+{"version":3,"file":"bridge-ast-gradient.js","sourceRoot":"","sources":["../../src/diff/bridge-ast-gradient.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Exact bridge-gradients over the symbolic RHS AST.\n *\n * The catalog's plain-JS evaluators cannot be differentiated by AD (they run\n * raw `Math.*` arithmetic and return a number, which carries no tape; see\n * `bridge-gradient.ts`). But each bridge also carries a faithful symbolic\n * encoding of its RHS (`*_RHS: ExprNode`). This module lowers that scalar AST\n * with the MathTS scalar builder and differentiates it with MathTS\n * `compileScalarGradient`: the chosen variable is the one parameter, and every\n * other symbol is a constant. The result is the EXACT derivative (machine\n * precision); the plain-JS evaluators stay untouched (P8 Decision #1).\n *\n * Scope: the scalar grammar is `symbol` + `op(+ − * / ^)` + `transcendental` +\n * `abs`. A bridge encoded with a typed stub differentiates with respect to the\n * stub, not the physics inside it; fully-expanded encodings (e.g. BE-42\n * `ℏc³/(8πGM·k_B)`) differentiate exactly. A `^` exponent must be constant: a\n * UPT pre-check refuses the differentiation variable in an exponent before\n * MathTS sees the tree.\n *\n * A point where the value overflows gives `NaN` for the value and the\n * gradient (MathTS marks the row invalid), not `±Infinity`.\n *\n * @module diff/bridge-ast-gradient\n */\n\nimport { ScalarBuildError } from '@danielsimonjr/mathts-expression';\nimport { compileScalarGradient } from '@danielsimonjr/mathts-functions';\nimport type { ExprNode } from '../dimensional/validator.js';\nimport { forEachScalarLeaf, isDecimalLiteral } from '../dimensional/ast-leaves.js';\nimport { constantScope } from '../dimensional/symbolic-constants.js';\nimport { toScalarNode } from '../dimensional/scalar-lowering.js';\nimport { BRIDGE_RHS_BY_ID, parseBridgeId } from '../bridges/rhs-registry.js';\n\n/**\n * Result of {@link bridgeGradientAST}: the bridge's scalar `value` at the\n * supplied point and the exact `gradient` d(value)/d(varName).\n *\n * @public\n */\nexport interface ASTGradientResult {\n  readonly value: number;\n  readonly gradient: number;\n}\n\n/**\n * Named physical constants the bridge encodings reference as bare symbols:\n * every registered spelling, from the constant registry, plus π and its\n * registered multiples, so the AST evaluates to the SAME number as the\n * numeric evaluator. Callers can override or extend via the `bindings` argument.\n */\nconst NAMED_CONSTANTS: Readonly<Record<string, number>> = constantScope();\n\n/** Resolve a symbol's numeric value: caller bindings → named constants → numeric literal. */\nfunction resolveConstant(\n  name: string,\n  bindings: Record<string, number>,\n): number {\n  if (Object.hasOwn(bindings, name))\n    return bindings[name];\n  if (Object.hasOwn(NAMED_CONSTANTS, name))\n    return NAMED_CONSTANTS[name];\n  const asNumber = Number(name);\n  if (name.trim() !== '' && Number.isFinite(asNumber)) return asNumber;\n  throw new TypeError(\n    `bridgeGradientAST: unknown symbol '${name}' — not a binding, a named constant ` +\n      `(${Object.keys(NAMED_CONSTANTS).join(', ')}), or a numeric literal. Supply it in bindings.`,\n  );\n}\n\n/** Resolve a `^` exponent to a numeric constant expression.\n *\n * The exponent may contain scalar arithmetic over constants/bindings (for\n * example `-1/z`) as long as it is independent of the differentiation\n * variable. UPT keeps the constant-power contract, so the differentiation\n * variable in an exponent is refused before MathTS reads the tree.\n */\nfunction resolveExponent(\n  node: ExprNode,\n  varName: string,\n  bindings: Record<string, number>,\n): number {\n  if (node.kind === 'symbol') {\n    if (node.name === varName) {\n      throw new TypeError(\n        `bridgeGradientAST: differentiation variable '${varName}' appears as an exponent — ` +\n          `variable exponents are not supported (only constant powers).`,\n      );\n    }\n    return resolveConstant(node.name, bindings);\n  }\n  if (node.kind === 'op') {\n    const values = node.args.map((arg) => resolveExponent(arg, varName, bindings));\n    if (values.length === 0) {\n      throw new TypeError(`bridgeGradientAST: '${node.op}' exponent expression has no operands.`);\n    }\n    switch (node.op) {\n      case '+': return values.reduce((a, b) => a + b);\n      case '-': return values.length === 1 ? -values[0] : values.slice(1).reduce((a, b) => a - b, values[0]);\n      case '*': return values.reduce((a, b) => a * b);\n      case '/': return values.slice(1).reduce((a, b) => a / b, values[0]);\n      case '^': return values.slice(1).reduce((a, b) => a ** b, values[0]);\n    }\n  }\n  throw new TypeError(\n    `bridgeGradientAST: '^' exponent must be a constant scalar expression, got node kind '${node.kind}'.`,\n  );\n}\n\n/**\n * Refuse the differentiation variable in any `^` exponent, and check that every\n * exponent is a constant scalar expression. MathTS would differentiate a\n * variable exponent; UPT keeps the constant-power contract.\n */\nfunction checkExponents(node: ExprNode, varName: string, bindings: Record<string, number>): void {\n  if (node.kind === 'op') {\n    if (node.op === '^' && node.args.length === 2) resolveExponent(node.args[1], varName, bindings);\n    for (const arg of node.args) checkExponents(arg, varName, bindings);\n  } else if (node.kind === 'transcendental' || node.kind === 'abs') {\n    checkExponents(node.arg, varName, bindings);\n  }\n}\n\n/**\n * Differentiate a scalar bridge RHS AST with respect to one symbol through\n * MathTS `compileScalarGradient`. Every symbol other than `varName` is resolved\n * to a constant (caller `bindings`, then {@link NAMED_CONSTANTS}, then numeric\n * literal); the `bindings` must contain `varName` (its value sets the point of\n * evaluation).\n *\n * @throws TypeError when `varName` is not bound, a symbol cannot be resolved,\n * `varName` appears in an exponent, or a node kind is outside the scalar grammar.\n * @public\n */\nexport function bridgeGradientAST(\n  rhs: ExprNode,\n  varName: string,\n  bindings: Record<string, number>,\n): ASTGradientResult {\n  if (!Object.hasOwn(bindings, varName)) {\n    throw new TypeError(\n      `bridgeGradientAST: bindings must contain the differentiation variable '${varName}'.`,\n    );\n  }\n  checkExponents(rhs, varName, bindings);\n\n  let lowered: ReturnType<typeof toScalarNode>;\n  try {\n    lowered = toScalarNode(rhs);\n  } catch (err) {\n    if (!(err instanceof ScalarBuildError)) throw err;\n    throw new TypeError(\n      `bridgeGradientAST: unsupported node kind — ${err.message}. The differentiable grammar is ` +\n        `symbol + op(+ − * / ^) + transcendental + abs. Other encodings (tensor/curvature, integrals, ` +\n        `or physics hidden in a typed-stub symbol) are not exactly differentiable.`,\n    );  }\n\n  const constants: Record<string, number> = {};\n  forEachScalarLeaf(\n    rhs,\n    (leaf) => {\n      if (leaf.name === varName) return;\n      // A literal spelling stays MathTS's literal unless the caller bound that name.\n      if (isDecimalLiteral(leaf.name) && !Object.hasOwn(bindings, leaf.name)) return;\n      constants[leaf.name] = resolveConstant(leaf.name, bindings);\n    },\n    { transcendental: true, abs: true },\n  );\n\n  const compiled = compileScalarGradient(lowered, { variables: [], parameters: [varName], constants });\n  const { values, grad } = compiled.evaluate([], [bindings[varName]]);\n  return { value: values[0]!, gradient: grad[0]! };\n}\n\n/**\n * Convenience wrapper around {@link bridgeGradientAST} that looks the RHS AST up\n * by catalog bridge id. `bridgeId` accepts a number, `'42'`, or `'BE-42'`.\n *\n * Throws if the id has no encoded RHS in {@link BRIDGE_RHS_BY_ID} (e.g. BE-51/52,\n * which are closed-form evaluators without an AST). If the bridge's RHS is not in\n * the differentiable scalar grammar (a tensor, integral or curvature encoding), the\n * delegated `bridgeGradientAST` throws the \"unsupported node kind\" error — use\n * {@link astDifferentiableBridgeIds} to discover which ids are AD-eligible.\n *\n * @public\n */\nexport function bridgeGradientASTById(\n  bridgeId: number | string,\n  varName: string,\n  bindings: Record<string, number>\n): ASTGradientResult {\n  const id = parseBridgeId(bridgeId);\n  const rhs = BRIDGE_RHS_BY_ID.get(id);\n  if (rhs === undefined) {\n    throw new TypeError(\n      `bridgeGradientASTById: BE-${id} has no encoded RHS AST in the registry ` +\n        `(BE-51/52 are closed-form; ${BRIDGE_RHS_BY_ID.size} bridges have an encoded AST).`\n    );\n  }\n  return bridgeGradientAST(rhs, varName, bindings);\n}\n\n/** Whether an AST consists solely of the differentiable scalar grammar (symbol + op(+ − * / ^) + transcendental + abs). */\nfunction isDifferentiableScalarAST(node: ExprNode): boolean {\n  if (node.kind === 'symbol') return true;\n  if (node.kind === 'op') {\n    if (!['+', '-', '*', '/', '^'].includes(node.op)) return false;\n    return node.args.every(isDifferentiableScalarAST);\n  }\n  if (node.kind === 'transcendental' || node.kind === 'abs') return isDifferentiableScalarAST(node.arg);\n  return false;\n}\n\n/**\n * The catalog bridge ids whose encoded RHS lies entirely in the differentiable\n * scalar grammar. `bridgeGradientASTById` differentiates each of them exactly\n * with respect to any variable that is not in an exponent; a variable in an\n * exponent is refused (`checkExponents`).\n * Bridges encoded with tensor, integral or curvature nodes (or whose physics is\n * hidden behind a typed-stub symbol) are excluded from EXACT differentiation\n * (a stub still differentiates w.r.t. the stub symbol, but not the physics\n * inside it). Returned sorted ascending.\n *\n * @public\n */\nexport function astDifferentiableBridgeIds(): number[] {\n  const ids: number[] = [];\n  for (const [id, rhs] of BRIDGE_RHS_BY_ID) {\n    if (isDifferentiableScalarAST(rhs)) ids.push(id);\n  }\n  return ids.sort((a, b) => a - b);\n}\n"]}

package/dist/dimensional/ast-types.d.ts

@@ -18,8 +18,11 @@
  */
 import type { Dimension } from './types.js';
 import type { CurvatureCompositeNode } from './curvature-composite.js';
+/** The position of a tensor index: upper (contravariant) or lower (covariant). */
 export type Variance = 'upper' | 'lower';
+/** The semantic class of a tensor symbol: coordinate, field or constant. */
 export type Role = 'coordinate' | 'field' | 'constant';
+/** One index of a tensor: its label and whether it is upper or lower. */
 export interface TensorIndex {
     readonly label: string;
     readonly variance: Variance;
@@ -40,6 +43,7 @@ export interface UpperIndex {
  * are excluded — they produce fractional dimensions.)
  */
 export type TranscendentalFn = 'exp' | 'ln' | 'log2' | 'log10' | 'sin' | 'cos' | 'tan' | 'sinh' | 'cosh' | 'tanh';
+/** A named tensor, with its indices, dimension and optional role. */
 export interface TensorSymbolNode {
     readonly kind: 'tensor-symbol';
     readonly name: string;
@@ -51,10 +55,12 @@ export interface TensorSymbolNode {
      *  operand (default 'symbolic'). */
     readonly numericalForm?: 'symbolic' | 'numerical-fn' | 'grid';
 }
+/** An Einstein-summation product of tensor and scalar operands. */
 export interface TensorProductNode {
     readonly kind: 'tensor-product';
     readonly args: ReadonlyArray<ExprNode>;
 }
+/** A metric tensor, with its name, indices, signature and dimension. */
 export interface MetricTensorNode {
     readonly kind: 'metric-tensor';
     readonly name: string;
@@ -64,11 +70,13 @@ export interface MetricTensorNode {
     /** v0.4.0 numerical-lowering hint for ∂g (default 'computed'). */
     readonly derivativeStrategy?: 'computed' | 'zero' | 'supplied';
 }
+/** The Kronecker delta, with its tensor indices and dimension. */
 export interface KroneckerDeltaNode {
     readonly kind: 'kronecker-delta';
     readonly indices: ReadonlyArray<TensorIndex>;
     readonly dim: Dimension;
 }
+/** The partial derivative of an expression, taken on a covariant index. */
 export interface TensorPartialDerivativeNode {
     readonly kind: 'tensor-partial-derivative';
     readonly of: ExprNode;
@@ -88,6 +96,7 @@ export interface CovariantDerivativeNode {
     readonly gLower: MetricTensorNode;
     readonly gInverse: MetricTensorNode;
 }
+/** The Riemann curvature tensor, with one upper and three lower indices. */
 export type RiemannTensorNode = CurvatureCompositeNode<'riemann-tensor', {
     readonly upperIndex: UpperIndex;
     readonly lowerIndices: readonly [CovariantIndex, CovariantIndex, CovariantIndex];
@@ -126,6 +135,7 @@ export type BianchiResidualNode = CurvatureCompositeNode<'bianchi-residual', {
     /** The Riemann tensor whose cyclic-derivative identity is checked. */
     readonly riemann: RiemannTensorNode;
 }>;
+/** The Weyl curvature tensor, the trace-free part of the Riemann tensor. */
 export type WeylTensorNode = CurvatureCompositeNode<'weyl-tensor', {
     /** Metric g_{μν} (both-lower). Present for numerical lowering consumers. */
     readonly metric: MetricTensorNode;
@@ -147,11 +157,13 @@ export type KretschmannScalarNode = CurvatureCompositeNode<'kretschmann-scalar',
     /** Metric (both-lower preferred). */
     readonly metric: MetricTensorNode;
 }>;
+/** A Killing vector field, with its vector and the metric it preserves. */
 export interface KillingVectorNode {
     readonly kind: 'killing-vector';
     readonly vector: TensorSymbolNode;
     readonly metric: MetricTensorNode;
 }
+/** A conserved charge: a Killing vector contracted with a momentum. */
 export interface ConservedChargeNode {
     readonly kind: 'conserved-charge';
     /** The Killing vector ξ^μ (rank-1, upper variance). */
@@ -160,6 +172,7 @@ export interface ConservedChargeNode {
      *  vector's index label so ξ^μ p_μ is well-formed. */
     readonly momentum: TensorSymbolNode;
 }
+/** The symmetric stress-energy tensor T, with its indices and component dimension. */
 export interface StressEnergyTensorNode {
     readonly kind: 'stress-energy';
     readonly symbol: 'T';
@@ -167,6 +180,7 @@ export interface StressEnergyTensorNode {
     readonly symmetry: 'symmetric';
     readonly componentDim: Dimension;
 }
+/** The cosmological constant Λ, with its dimension and optional numeric value. */
 export interface CosmologicalConstantNode {
     readonly kind: 'cosmological-constant';
     readonly symbol: 'Λ';
@@ -186,6 +200,7 @@ export interface EinsteinFieldEquationNode {
     readonly rhs: StressEnergyTensorNode;
     readonly coupling: 'einstein';
 }
+/** Any node of a dimensional expression: scalar, calculus, tensor, curvature or field-equation. */
 export type ExprNode = {
     kind: 'symbol';
     name: string;