universal-physics-tensor 0.5.0 → 0.7.0

package/dist/numerical/lowering.js

@@ -10,13 +10,23 @@
  *
  * @module numerical/lowering
  */
-import { validate } from '../dimensional/validator.js';
 import { computeContraction, validateTensorSymbol } from '../dimensional/tensor.js';
-import { pderivGrid, pderivNumericalFn, pderivSymbolic } from './pderiv.js';
 import { validateMetricTensor, validateKroneckerDelta, validatePartialDerivative, } from '../dimensional/metric-validators.js';
 import { NumericalBackendError } from './errors.js';
-import { zeroTensor, zeroTensorLike, flatToNested, flattenNA, tensorAdd, tensorAddScaled, computeChristoffelTensor, contractChristoffelWithOperand, getMetricDerivFlat, } from './connection-lowering-helpers.js';
-import { christoffelAt, dGammaAt, buildRiemann, bianchiResidualAt, } from './curvature-lowering-helpers.js';
+import { christoffelAt, dGammaAt, buildRiemann, contractRiemannJS, 
+// v0.6.1 Phase 2: the bianchi-residual + weyl-tensor arms moved into
+// these two helpers (full FD pipeline + result-wrap).
+lowerBianchiResidual, lowerWeylTensor, } from './curvature-lowering-helpers.js';
+// v0.7 follow-up to v0.6.1's LOC-target miss: the four private helpers
+// (isMetricTensorNode, dimensionOf, requireValue, flattenNestedArray)
+// live in lowering-utils.ts so the new derivative-lowering.ts can
+// share them without a forward-import cycle.
+import { dimensionOf, requireValue, flattenNestedArray, } from './lowering-utils.js';
+// v0.7 follow-up: tensor-partial-derivative + covariant-derivative
+// case arms extracted (was lines 523-820, ~298 LOC). The recursive
+// lowerNode call is threaded as a thunk to keep the module graph
+// acyclic.
+import { lowerTensorPartialDerivative, lowerCovariantDerivative, } from './derivative-lowering.js';
 function isContractable(node) {
     return node.kind === 'tensor-symbol'
         || node.kind === 'metric-tensor'
@@ -39,26 +49,6 @@ function operandIndices(node) {
     }
     return node.indices;
 }
-function dimensionOf(inputs) {
-    return inputs.dimension ?? 4;
-}
-/** Look up a named tensor's concrete value, or throw. */
-function requireValue(name, inputs) {
-    const v = inputs.tensors.get(name);
-    if (v === undefined) {
-        throw new NumericalBackendError(`lowering: no value supplied for "${name}" in inputs.tensors`);
-    }
-    return v;
-}
-/** Flatten a NestedArray to a plain number[] and check expected size.
- *  Delegates to the canonical flattenNA() from connection-lowering-helpers. */
-function flattenNestedArray(data, expectedSize) {
-    const out = flattenNA(data);
-    if (out.length !== expectedSize) {
-        throw new NumericalBackendError(`lowering: flattenNestedArray: got ${out.length} elements, expected ${expectedSize}`);
-    }
-    return out;
-}
 /**
  * Build the EinsumSpec for a flat tensor-product.
  *
@@ -69,9 +59,10 @@ function flattenNestedArray(data, expectedSize) {
  * labels to their (operand, axis) sites. There is exactly one
  * contraction-decision implementation in the codebase.
  *
- * @internal — cross-module/test use only; not part of the consumer surface.
+ * v0.6.1: dropped export — was @internal-tagged with no external consumer.
+ * `lowerTensorProduct` (this file) is the only call site.
  */
-export function buildEinsumSpec(operands, contractionPairs, freeIndices) {
+function buildEinsumSpec(operands, contractionPairs, freeIndices) {
     // Map every label to its (operand, axis) sites — via operandIndices() so a
     // tensor-partial-derivative operand contributes its [...of.indices, wrtIndex]
     // effective axes.
@@ -120,344 +111,19 @@ function lowerContractable(node, inputs, engine) {
     const shape = node.indices.map(() => N);
     return engine.fromNested(requireValue(node.name, inputs), shape);
 }
-/** Lower a validated ExprNode to an EngineTensor.
- *  @internal — cross-module/test use only; not part of the consumer surface. */
-export function lowerNode(node, inputs, engine) {
+/**
+ * Dispatcher for the six curvature-composite AST kinds.
+ *
+ * v0.6.0 Task 3.10e: extracted from `lowerNode`'s switch so all curvature
+ * lowering logic lives in one named helper. `CURVATURE_KIND_REGISTRY[node.kind]`
+ * supplies the per-kind shape/dim spec; the actual numerical paths are
+ * preserved verbatim from the prior per-kind arms — no logic changes.
+ *
+ * Called from `lowerNode` for all `CurvatureKind` discriminants.
+ * @internal
+ */
+function lowerCurvature(node, inputs, engine) {
     switch (node.kind) {
-        case 'symbol':
-            return engine.fromNested(requireValue(node.name, inputs), []);
-        case 'tensor-symbol':
-        case 'metric-tensor':
-        case 'kronecker-delta':
-            return lowerContractable(node, inputs, engine);
-        case 'op': {
-            if (node.op === '+' || node.op === '-') {
-                if (node.args.length === 0)
-                    return engine.fromNested(0, []);
-                let acc = lowerNode(node.args[0], inputs, engine);
-                for (let i = 1; i < node.args.length; i++) {
-                    const next = lowerNode(node.args[i], inputs, engine);
-                    acc = node.op === '+' ? engine.add(acc, next) : engine.sub(acc, next);
-                }
-                return acc;
-            }
-            // '*' / '/' / '^' are scalar-only. Guard arity so an unvalidated AST
-            // surfaces a clean NumericalBackendError instead of a raw TypeError
-            // (zero-operand '/') or a silent NaN (wrong-arity '^'). The '*' case
-            // with zero args is already fine — reduce(..., 1) returns 1.
-            if (node.op === '/' && node.args.length === 0) {
-                throw new NumericalBackendError("lowering: op '/' requires at least one operand");
-            }
-            if (node.op === '^' && node.args.length !== 2) {
-                throw new NumericalBackendError(`lowering: op '^' requires exactly 2 operands (base, exponent), got ${node.args.length}`);
-            }
-            // '*' / '/' / '^' are scalar-only (the validator rejects tensor
-            // operands). Lower each to rank-0, do the arithmetic in JS, lift back.
-            const scalars = node.args.map((a) => {
-                const t = lowerNode(a, inputs, engine);
-                if (t.shape.length !== 0) {
-                    throw new NumericalBackendError(`lowering: op '${node.op}' got a rank-${t.shape.length} operand — scalar ops require rank-0`);
-                }
-                return engine.toNested(t);
-            });
-            let value;
-            if (node.op === '*')
-                value = scalars.reduce((a, b) => a * b, 1);
-            else if (node.op === '/')
-                value = scalars.reduce((a, b) => a / b);
-            else
-                value = Math.pow(scalars[0], scalars[1]); // '^'
-            return engine.fromNested(value, []);
-        }
-        case 'tensor-product': {
-            for (const arg of node.args) {
-                if (arg.kind === 'tensor-product') {
-                    throw new NumericalBackendError('lowering: nested tensor-product numerical evaluation is not supported in v0.3.5 — '
-                        + 'flatten the contraction into a single product');
-                }
-            }
-            // Contractable operands (tensor-symbol / metric-tensor / kronecker-delta
-            // / tensor-partial-derivative) participate in the einsum; everything
-            // else must be a rank-0 scalar factor.
-            const operands = node.args.filter(isContractable);
-            const scalarArgs = node.args.filter((a) => !isContractable(a));
-            // computeContraction is the single authority on WHICH indices contract
-            // (variance-aware, implicit-metric rule). See buildEinsumSpec JSDoc.
-            // The recursive validateContractionChild resolves tensor-partial-derivative
-            // operands via validatePartialDerivative.
-            function validateContractionChild(child) {
-                if (child.kind === 'tensor-symbol')
-                    return validateTensorSymbol(child);
-                if (child.kind === 'metric-tensor')
-                    return validateMetricTensor(child);
-                if (child.kind === 'kronecker-delta')
-                    return validateKroneckerDelta(child);
-                if (child.kind === 'tensor-partial-derivative') {
-                    const r = validatePartialDerivative(child, (g) => validateContractionChild(g));
-                    return { dim: r.dim, freeIndices: r.freeIndices };
-                }
-                throw new NumericalBackendError(`lowering: unexpected operand '${child.kind}' in tensor-product einsum`);
-            }
-            const { contractionPairs, freeIndices } = computeContraction(operands, validateContractionChild);
-            const spec = buildEinsumSpec(operands, contractionPairs, freeIndices);
-            const operandTensors = operands.map((n) => lowerContractable(n, inputs, engine));
-            let result = engine.einsum(spec, ...operandTensors);
-            // Scalar operands multiply the whole contraction.
-            for (const s of scalarArgs) {
-                const st = lowerNode(s, inputs, engine);
-                if (st.shape.length !== 0) {
-                    throw new NumericalBackendError('lowering: non-scalar non-contractable operand in tensor-product');
-                }
-                result = engine.scale(result, engine.toNested(st));
-            }
-            return result;
-        }
-        case 'tensor-partial-derivative': {
-            // v0.3.5/v0.4.0 scope: `of` is a tensor-symbol or metric-tensor.
-            // ∂_μ(of) adds the wrtIndex as a trailing axis — the result shape is
-            // [...ofShape, N], NOT ofShape. (For BE-37, `of` = the scalar S is
-            // rank-0, so ∂_μ S is the rank-1 wave covector k_μ, shape [N].)
-            const of = node.of;
-            // v0.4.0 extension: metric-tensor pderiv dispatch.
-            if (of.kind === 'metric-tensor') {
-                const mNode = of;
-                const strategy = mNode.derivativeStrategy ?? 'computed';
-                const N = dimensionOf(inputs);
-                const coordLabel = node.wrtIndex.label;
-                const ofShape = mNode.indices.map(() => N);
-                const resultShape = [...ofShape, N];
-                if (strategy === 'zero') {
-                    // ∂g = 0 everywhere (constant/flat metric).
-                    return zeroTensor(resultShape, engine);
-                }
-                if (strategy === 'supplied') {
-                    // Look up the N slices ∂_mu g for mu=0..N-1 and stack them as the
-                    // trailing axis. Key format: `${metricName}/${coordLabel}_${mu}`.
-                    // Result shape: [...ofShape, N] = [N, N, N] for a rank-2 metric.
-                    // Build as a flat array then convert to nested for engine.fromNested().
-                    const size = resultShape.reduce((a, b) => a * b, 1);
-                    const flat = new Array(size).fill(0);
-                    // ofShape = [N, N], resultShape = [N, N, N]
-                    // flat[i*N*N + j*N + mu] = (∂_mu g)[i][j]
-                    for (let mu = 0; mu < N; mu++) {
-                        const key = `${mNode.name}/${coordLabel}_${mu}`;
-                        const slice = inputs.metricDerivatives?.get(key);
-                        if (slice === undefined) {
-                            throw new NumericalBackendError(`lowering: metric-tensor pderiv with strategy='supplied': ` +
-                                `no metricDerivatives entry for "${key}"`);
-                        }
-                        // Flatten the slice (shape [N,N]) and write into flat at stride N (last axis)
-                        const flatSlice = flattenNestedArray(slice, N * N);
-                        for (let ij = 0; ij < N * N; ij++) {
-                            flat[ij * N + mu] = flatSlice[ij];
-                        }
-                    }
-                    return engine.fromNested(flatToNested(flat, resultShape), resultShape);
-                }
-                // strategy === 'computed': treat as zero for constant-tensor metrics
-                // (the raw metric supplied via inputs.tensors has no coordinate dependence).
-                return zeroTensor(resultShape, engine);
-            }
-            if (of.kind !== 'tensor-symbol') {
-                throw new NumericalBackendError(`lowering: tensor-partial-derivative numerical eval requires a tensor-symbol `
-                    + `or metric-tensor 'of' operand in v0.3.5/v0.4.0 — got '${of.kind}'`);
-            }
-            const sym = of;
-            const form = sym.numericalForm ?? 'symbolic';
-            const coordLabel = node.wrtIndex.label;
-            const N = dimensionOf(inputs);
-            const ofShape = sym.indices.map(() => N);
-            const resultShape = [...ofShape, N];
-            if (form === 'symbolic') {
-                // pderivSymbolic returns the caller-supplied full ∂_μ(of) tensor,
-                // which must already be of shape [...ofShape, N].
-                const d = pderivSymbolic(sym.name, coordLabel, inputs.derivatives ?? new Map());
-                return engine.fromNested(d, resultShape);
-            }
-            if (form === 'numerical-fn') {
-                // v0.3.5: 'numerical-fn' lowering is scoped to a rank-0 `of` (scalar
-                // field). ∂_μ ranges over all N coordinate axes — stack the N
-                // single-axis derivatives into the rank-1 result. Higher-rank fields
-                // under 'numerical-fn' are a v0.4.0 concern.
-                if (ofShape.length !== 0) {
-                    throw new NumericalBackendError(`lowering: 'numerical-fn' pderiv lowering supports a rank-0 'of' in v0.3.5; `
-                        + `"${sym.name}" is rank ${ofShape.length}`);
-                }
-                const fn = inputs.fields?.get(sym.name);
-                if (!fn) {
-                    throw new NumericalBackendError(`lowering: 'numerical-fn' tensor-symbol "${sym.name}" has no field fn in inputs.fields`);
-                }
-                const coordValues = inputs.coords ? [...inputs.coords.values()] : [];
-                const components = [];
-                for (let axis = 0; axis < N; axis++) {
-                    components.push(pderivNumericalFn(fn, coordValues, axis));
-                }
-                return engine.fromNested(components, [N]);
-            }
-            // form === 'grid': the GridField is the field sampled over space, and
-            // pderivGrid returns the derivative field sampled on that same grid —
-            // result shape is grid.shape. This is a distinct semantic from
-            // symbolic/numerical-fn (a sampled derivative field, not a single
-            // tensor), kept as the v0.5.0 BSSN forward-compat path. v0.3.5 has no
-            // release test driving 'grid' through lowering; pderivGrid itself is
-            // unit-tested in Task 10's pderiv.test.ts.
-            const grid = inputs.grids?.get(sym.name);
-            if (!grid) {
-                throw new NumericalBackendError(`lowering: 'grid' tensor-symbol "${sym.name}" has no GridField in inputs.grids`);
-            }
-            const gridAxis = inputs.coords ? [...inputs.coords.keys()].indexOf(coordLabel) : 0;
-            const flat = pderivGrid(grid, gridAxis < 0 ? 0 : gridAxis);
-            return engine.fromNested(flat.length === 1 ? flat[0] : flat, grid.shape);
-        }
-        case 'covariant-derivative': {
-            // S2(a) fix: `of.freeIndices` does NOT exist on the raw ExprNode.
-            // Re-validate the `of` subtree to obtain its free-index structure.
-            const covNode = node;
-            const ofExpr = covNode.of;
-            // TS-2 runtime guard: `covNode.of` is typed as `unknown` (module-cycle
-            // prevents ExprNode import in connection-validators.ts). The cast above
-            // is unchecked — a malformed AST bypassing validate() would produce a
-            // cryptic TypeError at `ofExpr.kind` below. Throw a clear message now.
-            if (typeof ofExpr.kind !== 'string') {
-                throw new NumericalBackendError(`lowering: CovariantDerivativeNode.of must have a string 'kind' field ` +
-                    `(got ${JSON.stringify(ofExpr.kind)}). ` +
-                    `Always call validate() before evaluateNumericalRaw().`);
-            }
-            const ofValidation = validate(ofExpr);
-            // Build ordered list of free indices: [{label, variance}].
-            // Iterate of.indices (NOT validation.freeIndices Map) — declaration order IS
-            // the axis layout. For tensor-symbol and metric-tensor, of.indices is the
-            // canonical axis order; the freeIndices Map insertion order is also
-            // of.indices order (validateTensorSymbol iterates node.indices), but relying
-            // on that is an undocumented invariant. Iterating of.indices directly makes
-            // the axis ordering guarantee explicit and safe for future of-kinds.
-            const ofFreeIndices = [];
-            const ofIndices = ofExpr.indices;
-            if (ofIndices) {
-                // tensor-symbol / metric-tensor: iterate the declared indices in order.
-                // Each index is either free (present in ofValidation.freeIndices) or
-                // contracted (absent — skip). In practice, of.indices for a simple
-                // tensor-symbol or metric-tensor has no contracted indices, but we
-                // guard with the Map lookup for safety.
-                for (const idx of ofIndices) {
-                    const counts = ofValidation.freeIndices.get(idx.label);
-                    if (counts === undefined)
-                        continue; // contracted — not a free axis
-                    ofFreeIndices.push({
-                        label: idx.label,
-                        variance: idx.variance,
-                        pos: ofFreeIndices.length,
-                    });
-                }
-            }
-            else {
-                // Fallback for future of-kinds without .indices (e.g. tensor-product).
-                // Map iteration order is insertion order — a best-effort axis ordering.
-                let axisPos = 0;
-                for (const [label, counts] of ofValidation.freeIndices) {
-                    for (let i = 0; i < counts.upper; i++) {
-                        ofFreeIndices.push({ label, variance: 'upper', pos: axisPos++ });
-                    }
-                    for (let i = 0; i < counts.lower; i++) {
-                        ofFreeIndices.push({ label, variance: 'lower', pos: axisPos++ });
-                    }
-                }
-            }
-            // Lower the operand tensor.
-            const ofTensor = lowerNode(ofExpr, inputs, engine);
-            const N = dimensionOf(inputs);
-            // TS-2 runtime guard: gLower must be a metric-tensor node (validated
-            // upstream). A malformed AST bypassing validate() could reach here with
-            // a wrong kind, causing a silent wrong-path execution.
-            if (covNode.gLower.kind !== 'metric-tensor') {
-                throw new NumericalBackendError(`lowering: CovariantDerivativeNode.gLower must be a metric-tensor node ` +
-                    `(got kind='${covNode.gLower.kind}')`);
-            }
-            const strategy = covNode.gLower.derivativeStrategy ?? 'computed';
-            // S2(b): strategy='zero' → flat space, Γ=0, ∇_μ T = ∂_μ T.
-            // For constant tensors (like a flat metric), ∂_μ T = 0, so result is all zeros.
-            // We return a zero tensor of shape [...ofShape, N] (wrt axis appended last).
-            if (strategy === 'zero') {
-                const outShape = [...ofTensor.shape, N];
-                return zeroTensor(outShape, engine);
-            }
-            // v0.4.0 CRITICAL FIX (Finding #1): 'computed' on a raw-tensor metric means
-            // constant metric → Γ = 0 → covariant-derivative = partial derivative only.
-            // v0.5.0 will replace this with coordinate-grid finite-difference.
-            // This early return MUST come before the Christoffel construction below,
-            // because getMetricDerivFlat only accepts 'zero' | 'supplied'; if 'computed'
-            // fell through, the type cast was silently wrong at runtime and the function
-            // threw NumericalBackendError for every coordinate.
-            //
-            // Compute partial first so we can return it directly.
-            // (partial is also needed by the 'supplied' path below, so we compute it
-            //  unconditionally and use the early return only for 'computed'.)
-            //
-            // UC-2 (v0.4.6): `of` is always tensor-symbol or metric-tensor at this
-            // point. validateCovariantDerivative (connection-validators.ts) only
-            // accepts those kinds for the 'of' field; any other kind fails dimensional
-            // validation before evaluateNumerical reaches lowerNode. A covariant-
-            // derivative with a scalar 'of' (ofFreeIndices.length === 0) already
-            // returned at the early-return below. The old else-branch ("Scalar or
-            // other: partial is zero") was therefore unreachable and is removed here;
-            // replaced with an explicit throw to make the invariant visible if a
-            // bypass-validate AST construction ever violates it.
-            if (ofExpr.kind !== 'tensor-symbol' && ofExpr.kind !== 'metric-tensor') {
-                throw new NumericalBackendError(`lowering: covariant-derivative 'of' must be tensor-symbol or metric-tensor ` +
-                    `(got '${ofExpr.kind}') — validated nodes cannot reach this point`);
-            }
-            const pdNode = {
-                kind: 'tensor-partial-derivative',
-                of: ofExpr,
-                wrt: covNode.wrt,
-                wrtIndex: covNode.wrtIndex,
-            };
-            const partial = lowerNode(pdNode, inputs, engine);
-            // v0.4.0 spec: 'computed' on a raw-tensor metric = constant metric → Γ = 0.
-            // The covariant-derivative reduces to the ordinary partial derivative.
-            // v0.5.0 will add coordinate-grid finite-difference here.
-            if (strategy === 'computed') {
-                return partial;
-            }
-            // S2(c) + S2(d): Build Christoffel Γ^α_{μν} from metric data and apply
-            // the sign rule to all free indices of `of`:
-            //   ∇_μ T^α_β = ∂_μ T^α_β + Γ^α_{μλ} T^λ_β − Γ^λ_{μβ} T^α_λ
-            //
-            // If `of` has no free indices (scalar), no correction needed.
-            if (ofFreeIndices.length === 0) {
-                return partial;
-            }
-            // Get metric and inverse metric data.
-            const gLowerNode = covNode.gLower;
-            const gInverseNode = covNode.gInverse;
-            const gInverseData = flattenNestedArray(requireValue(gInverseNode.name, inputs), N * N);
-            // coordLabel for metricDerivatives keys (wrtIndex.label of the covariant derivative)
-            const coordLabel = covNode.wrtIndex.label;
-            // getMetricDeriv(mu): returns flat [N*N] of ∂_{mu} g
-            const getMetricDeriv = (mu) => getMetricDerivFlat(gLowerNode.name, coordLabel, mu, 'supplied', 
-            // ^ strategy can only be 'supplied' here: 'zero' returned at line 457-459,
-            //   'computed' returned at line 491-493, scalar 'of' returned at line 500-502.
-            // Safe per audit UC-1: 'zero' strategy is short-circuited in earlier guard.
-            N, inputs.metricDerivatives);
-            // Compute Γ^α_{μν} from metric data.
-            const GammaTensor = computeChristoffelTensor(gInverseData, getMetricDeriv, N, engine);
-            const GammaFlat = flattenNestedArray(engine.toNested(GammaTensor), N * N * N);
-            // Apply the Christoffel correction for each free index of `of`.
-            // S2(d) sign rule: upper → +Γ, lower → −Γ.
-            const ofFlat = flattenNestedArray(engine.toNested(ofTensor), ofTensor.shape.reduce((a, b) => a * b, 1));
-            const ofShapeArr = [...ofTensor.shape];
-            let correction = zeroTensorLike(partial, engine);
-            for (const freeIdx of ofFreeIndices) {
-                const term = contractChristoffelWithOperand(GammaFlat, ofFlat, ofShapeArr, freeIdx.pos, freeIdx.variance, N, engine);
-                const sign = freeIdx.variance === 'upper' ? 1 : -1;
-                correction = tensorAddScaled(correction, term, sign, engine);
-            }
-            return tensorAdd(partial, correction, engine);
-        }
-        case 'integral':
-        case 'derivative':
-            throw new NumericalBackendError(`lowering: '${node.kind}' is not numerically evaluated in v0.3.5 — `
-                + 'use tensor-partial-derivative for differentiation');
         case 'ricci-tensor': {
             // v0.5.0 Task 7 — Ricci R_μν = R^λ_{μλν} (Carroll Eq. 3.91). Lowers
             // the embedded Riemann tensor via the 'riemann-tensor' case (so all
@@ -487,24 +153,16 @@ export function lowerNode(node, inputs, engine) {
             // composite node directly, no rewrite into a tensor-product.)
             const ricciNode = node;
             const N = dimensionOf(inputs);
-            const innerR = lowerNode(ricciNode.riemann, inputs, engine);
+            // RiemannTensorNode is a member of ExprNode and CurvatureKind — cast is safe.
+            const innerR = lowerCurvature(ricciNode.riemann, inputs, engine);
             const flatR = flattenNestedArray(engine.toNested(innerR), N * N * N * N);
-            // Contract R[λ][μ_out][λ][ν_out] → Ricci[μ_out][ν_out].
-            // Flat index of R[a][b][c][d] (row-major, all axes size N):
-            //   a*N^3 + b*N^2 + c*N + d.
-            const ricci2d = Array.from({ length: N }, () => new Array(N).fill(0));
-            const N2 = N * N;
-            const N3 = N * N * N;
-            for (let muOut = 0; muOut < N; muOut++) {
-                for (let nuOut = 0; nuOut < N; nuOut++) {
-                    let sum = 0;
-                    for (let lam = 0; lam < N; lam++) {
-                        // R[lam][muOut][lam][nuOut]
-                        sum += flatR[lam * N3 + muOut * N2 + lam * N + nuOut];
-                    }
-                    ricci2d[muOut][nuOut] = sum;
-                }
-            }
+            // Contract R[λ][μ_out][λ][ν_out] → Ricci[μ_out][ν_out] via the shared
+            // `contractRiemannJS` helper (AS-1, v0.5.1). On R^ρ_{σμν} stored as
+            // R[ρ][σ][μ][ν], the Carroll Eq. 3.91 contraction is upperAxis=0 (ρ)
+            // against lowerAxis=2 (μ); free outputs are axes [1, 3] = (σ, ν).
+            const ricci2d = contractRiemannJS(flatR, N, {
+                upperAxis: 0, lowerAxis: 2, outAxes: [1, 3],
+            });
             return engine.fromNested(ricci2d, [N, N]);
         }
         case 'einstein-tensor': {
@@ -533,7 +191,7 @@ export function lowerNode(node, inputs, engine) {
             const ricciNodeInner = {
                 kind: 'ricci-tensor', riemann: eNode.riemann,
             };
-            const innerR = lowerNode(ricciNodeInner, inputs, engine);
+            const innerR = lowerCurvature(ricciNodeInner, inputs, engine);
             const Ric = engine.toNested(innerR);
             // Step 2: g_μν and g^μν from inputs.tensors (raw constant matrices at
             // the test coordinate point). Mirrors how ricci-tensor's de-Sitter
@@ -559,40 +217,9 @@ export function lowerNode(node, inputs, engine) {
         }
         case 'bianchi-residual': {
             // v0.5.0 Task 9 — Bianchi-identity residual B_{λμνρσ}.
-            //
-            // Approach 1 (full ∇, not raw ∂): cyclic sum
-            //   B_{λμνρσ} = ∇_λ R_{μνρσ} + ∇_μ R_{νλρσ} + ∇_ν R_{λμρσ}
-            // where each ∇_λ R_{μνρσ} is computed with the four Christoffel-
-            // correction terms (one per lower index of R). All FD/contraction
-            // arithmetic happens in the helper module — this case just wires
-            // x / metric closures from `inputs` to `bianchiResidualAt`.
-            //
-            // The result is a 5-deep nested array [N][N][N][N][N] with index order
-            // B[λ][μ][ν][ρ][σ]. Returned as an EngineTensor of shape [N,N,N,N,N];
-            // callers (typically bianchiResidual().evaluate) materialise via
-            // engine.toNested.
-            //
-            // Walks the node directly — no AST rewrite into an op('+') of pderiv
-            // products. Matches Task 6/7/8 walk-directly philosophy.
-            const bNode = node;
-            const rNode = bNode.riemann;
-            const N = dimensionOf(inputs);
-            // Coordinate value: same convention as the riemann-tensor case.
-            const xCoordName = rNode.xCoord.name;
-            const xRaw = requireValue(xCoordName, inputs);
-            const x = flattenNestedArray(xRaw, N);
-            // Coordinate-dependent metric closures.
-            const gName = rNode.gLower.name;
-            const gInvName = rNode.gInverse.name;
-            const gFn = inputs.fields?.get(gName);
-            const gInverseFn = inputs.fields?.get(gInvName);
-            if (!gFn || !gInverseFn) {
-                throw new NumericalBackendError(`lowering: bianchi-residual numerical evaluation requires coordinate-` +
-                    `dependent metric closures in inputs.fields for "${gName}" and "${gInvName}". ` +
-                    `Got fields=[${[...(inputs.fields?.keys() ?? [])].join(',')}].`);
-            }
-            const B = bianchiResidualAt(x, gFn, gInverseFn, N, engine);
-            return engine.fromNested(B, [N, N, N, N, N]);
+            // Extracted into `lowerBianchiResidual` in v0.6.1 Phase 2; the body
+            // here is just the type-narrowed dispatch.
+            return lowerBianchiResidual(node, inputs, engine);
         }
         case 'riemann-tensor': {
             // v0.5.0 Task 6 (Phase 1c-ii). Walks the node directly (no AST rewrite
@@ -627,6 +254,190 @@ export function lowerNode(node, inputs, engine) {
             // Materialise back into an EngineTensor in [N,N,N,N] shape.
             return engine.fromNested(R, [N, N, N, N]);
         }
+        case 'weyl-tensor': {
+            // v0.6.0 Task 3.2 — Weyl C^ρ_{σμν}.
+            // Extracted into `lowerWeylTensor` in v0.6.1 Phase 2; the body here
+            // is just the type-narrowed dispatch.
+            return lowerWeylTensor(node, inputs, engine);
+        }
+        case 'kretschmann-scalar': {
+            // v0.6.0 Task 3.5/3.6 — KretschmannScalarNode: K = R_{ρσμν} R^{ρσμν}.
+            //
+            // The full lowering arm (Riemann→lower + computeKretschmann) is deferred
+            // to Task 3.7 where the Schwarzschild closed-form test pins it. Callers
+            // can invoke `computeKretschmann` directly with a sampled riemannLower
+            // array (see tests/numerical/kretschmann-schwarzschild.test.ts).
+            //
+            // Raises a descriptive error so callers get a clear signal instead of
+            // the generic 'unknown kind' exhaustiveness message.
+            void node;
+            throw new NumericalBackendError(`lowering: 'kretschmann-scalar' end-to-end lowering is not yet implemented ` +
+                `(Task 3.7). Use computeKretschmann() from src/numerical/kretschmann.ts ` +
+                `with a pre-computed riemannLower array and invertMetric().`);
+        }
+        default: {
+            const _exhaustive = node;
+            void _exhaustive;
+            throw new NumericalBackendError(`lowerCurvature: unhandled curvature kind ${JSON.stringify(node.kind)}`);
+        }
+    }
+}
+/** Lower a validated ExprNode to an EngineTensor.
+ *  @internal — cross-module/test use only; not part of the consumer surface. */
+export function lowerNode(node, inputs, engine) {
+    switch (node.kind) {
+        case 'symbol':
+            return engine.fromNested(requireValue(node.name, inputs), []);
+        case 'tensor-symbol':
+        case 'metric-tensor':
+        case 'kronecker-delta':
+            return lowerContractable(node, inputs, engine);
+        case 'op': {
+            if (node.op === '+' || node.op === '-') {
+                if (node.args.length === 0)
+                    return engine.fromNested(0, []);
+                let acc = lowerNode(node.args[0], inputs, engine);
+                for (let i = 1; i < node.args.length; i++) {
+                    const next = lowerNode(node.args[i], inputs, engine);
+                    acc = node.op === '+' ? engine.add(acc, next) : engine.sub(acc, next);
+                }
+                return acc;
+            }
+            // '*' / '/' / '^' are scalar-only. Guard arity so an unvalidated AST
+            // surfaces a clean NumericalBackendError instead of a raw TypeError
+            // (zero-operand '/') or a silent NaN (wrong-arity '^'). The '*' case
+            // with zero args is already fine — reduce(..., 1) returns 1.
+            if (node.op === '/' && node.args.length === 0) {
+                throw new NumericalBackendError("lowering: op '/' requires at least one operand");
+            }
+            if (node.op === '^' && node.args.length !== 2) {
+                throw new NumericalBackendError(`lowering: op '^' requires exactly 2 operands (base, exponent), got ${node.args.length}`);
+            }
+            // '*' / '/' / '^' are scalar-only (the validator rejects tensor
+            // operands). Lower each to rank-0, do the arithmetic in JS, lift back.
+            const scalars = node.args.map((a) => {
+                const t = lowerNode(a, inputs, engine);
+                if (t.shape.length !== 0) {
+                    throw new NumericalBackendError(`lowering: op '${node.op}' got a rank-${t.shape.length} operand — scalar ops require rank-0`);
+                }
+                return engine.toNested(t);
+            });
+            let value;
+            if (node.op === '*')
+                value = scalars.reduce((a, b) => a * b, 1);
+            else if (node.op === '/')
+                value = scalars.reduce((a, b) => a / b);
+            else
+                value = Math.pow(scalars[0], scalars[1]); // '^'
+            return engine.fromNested(value, []);
+        }
+        case 'tensor-product': {
+            for (const arg of node.args) {
+                if (arg.kind === 'tensor-product') {
+                    throw new NumericalBackendError('lowering: nested tensor-product numerical evaluation is not supported in v0.3.5 — '
+                        + 'flatten the contraction into a single product');
+                }
+            }
+            // Contractable operands (tensor-symbol / metric-tensor / kronecker-delta
+            // / tensor-partial-derivative) participate in the einsum; everything
+            // else must be a rank-0 scalar factor.
+            const operands = node.args.filter(isContractable);
+            const scalarArgs = node.args.filter((a) => !isContractable(a));
+            // computeContraction is the single authority on WHICH indices contract
+            // (variance-aware, implicit-metric rule). See buildEinsumSpec JSDoc.
+            // The recursive validateContractionChild resolves tensor-partial-derivative
+            // operands via validatePartialDerivative.
+            function validateContractionChild(child) {
+                if (child.kind === 'tensor-symbol')
+                    return validateTensorSymbol(child);
+                if (child.kind === 'metric-tensor')
+                    return validateMetricTensor(child);
+                if (child.kind === 'kronecker-delta')
+                    return validateKroneckerDelta(child);
+                if (child.kind === 'tensor-partial-derivative') {
+                    const r = validatePartialDerivative(child, (g) => validateContractionChild(g));
+                    return { dim: r.dim, freeIndices: r.freeIndices };
+                }
+                throw new NumericalBackendError(`lowering: unexpected operand '${child.kind}' in tensor-product einsum`);
+            }
+            const { contractionPairs, freeIndices } = computeContraction(operands, validateContractionChild);
+            const spec = buildEinsumSpec(operands, contractionPairs, freeIndices);
+            const operandTensors = operands.map((n) => lowerContractable(n, inputs, engine));
+            let result = engine.einsum(spec, ...operandTensors);
+            // Scalar operands multiply the whole contraction.
+            for (const s of scalarArgs) {
+                const st = lowerNode(s, inputs, engine);
+                if (st.shape.length !== 0) {
+                    throw new NumericalBackendError('lowering: non-scalar non-contractable operand in tensor-product');
+                }
+                result = engine.scale(result, engine.toNested(st));
+            }
+            return result;
+        }
+        case 'tensor-partial-derivative':
+            // v0.7 follow-up to v0.6.1 LOC miss: body extracted to
+            // derivative-lowering.ts. No recursive lowerNode call from
+            // this arm, so the thunk parameter is not needed.
+            return lowerTensorPartialDerivative(node, inputs, engine);
+        case 'covariant-derivative':
+            // v0.7 follow-up to v0.6.1 LOC miss: body extracted to
+            // derivative-lowering.ts. Recursive lowerNode call threaded
+            // via thunk to keep the module graph acyclic.
+            return lowerCovariantDerivative(node, inputs, engine, lowerNode);
+        case 'integral':
+        case 'derivative':
+            throw new NumericalBackendError(`lowering: '${node.kind}' is not numerically evaluated in v0.3.5 — `
+                + 'use tensor-partial-derivative for differentiation');
+        // v0.6.0 Task 3.10e: ricci-tensor, einstein-tensor, bianchi-residual,
+        // riemann-tensor, weyl-tensor, kretschmann-scalar all delegate to
+        // lowerCurvature — the extracted curvature-composite dispatcher.
+        case 'ricci-tensor':
+        case 'einstein-tensor':
+        case 'bianchi-residual':
+        case 'riemann-tensor':
+        case 'weyl-tensor':
+        case 'kretschmann-scalar':
+            return lowerCurvature(node, inputs, engine);
+        case 'killing-vector': {
+            // v0.6.0 Task 1.1: KillingVectorNode symbolic AST added. Numerical
+            // evaluation (verifyKillingEquation / evaluateConservedCharge) is
+            // deferred to Task 1.3 (src/numerical/killing.ts). Until then, the
+            // lowering layer raises a descriptive error so callers get a clear
+            // signal instead of the generic 'unknown kind' message.
+            throw new NumericalBackendError(`lowering: 'killing-vector' numerical evaluation is not yet implemented ` +
+                `(Task 1.3). Use verifyKillingEquation() from src/numerical/killing.ts.`);
+        }
+        case 'conserved-charge': {
+            // v0.6.0 Task 1.2: ConservedChargeNode symbolic AST added. Numerical
+            // evaluation (evaluateConservedCharge) is deferred to Task 1.3
+            // (src/numerical/killing.ts). Raises a descriptive error so callers
+            // get a clear signal instead of the generic 'unknown kind' message.
+            throw new NumericalBackendError(`lowering: 'conserved-charge' numerical evaluation is not yet implemented ` +
+                `(Task 1.3). Use evaluateConservedCharge() from src/numerical/killing.ts.`);
+        }
+        case 'stress-energy': {
+            // v0.6.0 Task 2.1: StressEnergyTensorNode symbolic AST added. Full
+            // numerical evaluation (T_μν from a perfect-fluid or explicit component
+            // map) is deferred to Task 2.4 (src/numerical/einstein-equation.ts).
+            // Raises a descriptive error so callers get a clear signal instead of
+            // the generic 'unknown kind' message from the exhaustiveness guard.
+            throw new NumericalBackendError(`lowering: 'stress-energy' numerical evaluation is not yet implemented ` +
+                `(Task 2.4). Use the Einstein-equation evaluator in src/numerical/einstein-equation.ts.`);
+        }
+        case 'cosmological-constant': {
+            // v0.6.0 Task 2.1: CosmologicalConstantNode symbolic AST added. Numerical
+            // evaluation (inject Λ as a scalar into the Einstein equation) is deferred
+            // to Task 2.4 (src/numerical/einstein-equation.ts).
+            throw new NumericalBackendError(`lowering: 'cosmological-constant' numerical evaluation is not yet implemented ` +
+                `(Task 2.4). Use the Einstein-equation evaluator in src/numerical/einstein-equation.ts.`);
+        }
+        case 'einstein-equation': {
+            // v0.6.0 Task 2.3: EinsteinFieldEquationNode predicate AST added. Numerical
+            // evaluation (G_μν + Λ g_μν = κ T_μν residual tensor) is deferred to
+            // Task 2.4 (src/numerical/einstein-equation.ts).
+            throw new NumericalBackendError(`lowering: 'einstein-equation' numerical evaluation is not yet implemented ` +
+                `(Task 2.4). Use the Einstein-equation evaluator in src/numerical/einstein-equation.ts.`);
+        }
         default: {
             const _exhaustive = node;
             void _exhaustive;