universal-physics-tensor 9.0.0 → 11.0.0

package/dist/diff/bridge-gradient.js

@@ -1,97 +1,24 @@
 /**
- * Bridge-parameter differentiation — v0.9 Proposal 8 core layer.
+ * Bridge-parameter differentiation by central finite differences.
  *
- * Wraps catalog bridge evaluators (typed scalar functions with
- * named-field struct inputs like `evaluateShapiroDelay(input:
- * ShapiroInputs): number`) into the shape expected by
- * `TensorEngine.reverseGrad`: `(paramTensor: EngineTensor) →
- * outputScalar`. Returns gradients with respect to a chosen subset
- * of the bridge's input parameters.
+ * A {@link BridgeDiffSpec} wraps one catalog closed form (a plain-JS scalar
+ * function over a named-field struct) and names which fields vary.
+ * {@link bridgeGradientNumerical} perturbs those fields and returns the
+ * gradient keyed by field name.
  *
- * Per P8 Decision #1, this lives in `src/diff/` (NOT in
- * `src/bridges/`), keeping bridge evaluators untouched. The AD
- * dependency `mathts-autograd` is a required dependency. Installing it
- * does not make AD of the plain-JS bridges work: the tape still cannot
- * trace `Math.*` (see the AD limitation below).
+ * There is no engine-AD path over a spec. `evaluate` returns a `number`, and
+ * a number carries no autograd tape, so reverse- or forward-mode AD of a spec
+ * is unreachable by construction; the function that once offered it
+ * (`bridgeGradient`) threw for every shipped spec and was removed. The exact
+ * AD path is {@link bridgeGradientAST} in `bridge-ast-gradient.ts`, which
+ * lowers the bridge's symbolic RHS through `@danielsimonjr/mathts-autograd`.
  *
- * IMPORTANT — AD limitation (verified empirically): `bridgeGradient`
- * does NOT actually differentiate the catalog evaluators. Because P8
- * Decision #1 keeps those evaluators as plain-JS scalar functions
- * (`Math.*` / raw arithmetic on numbers), neither reverse-mode (tape)
- * nor forward-mode (dual) AD can trace them — the tape/dual instrument
- * only sees ops routed through engine-traced tensors. With
- * `MathTSEngine` the autograd `TapedTensor` does not survive
- * `engine.toNested`. `bridgeGradient` therefore only works for
- * functions written in engine ops — not the plain-JS bridges.
- *
- * The SUPPORTED way to differentiate a plain-JS bridge evaluator is
- * {@link bridgeGradientNumerical} (central finite differences, no engine).
+ * This module lives in `src/diff/` (P8 Decision #1), not in `src/bridges/`,
+ * so the catalog closed forms stay untouched.
  *
  * @module diff/bridge-gradient
  */
-import { hasAutogradSupport } from '../numerical/tensor-engine.js';
-import { EngineCapabilityError } from '../numerical/errors.js';
-/**
- * Compute the gradient of a bridge evaluator with respect to its
- * differentiable parameters via reverse-mode AD. The supplied
- * `params` map must contain every key in `spec.paramNames`.
- *
- * Throws `EngineCapabilityError` if the engine doesn't support
- * autograd (the standard graceful-degradation path from v0.4.0;
- * see `MathTSEngine.reverseGrad`).
- *
- * @public
- */
-export async function bridgeGradient(spec, engine, params) {
-    if (!hasAutogradSupport(engine)) {
-        throw new EngineCapabilityError(engine.name, 'reverseGrad');
-    }
-    // Pack params into a 1-D tensor in spec.paramNames order.
-    const packed = spec.paramNames.map((k) => {
-        const v = params[k];
-        if (typeof v !== 'number') {
-            throw new TypeError(`bridgeGradient: ${spec.bridgeId}: missing or non-numeric param '${k}' ` +
-                `(got ${typeof v}). All paramNames must be numbers in the params object.`);
-        }
-        return v;
-    });
-    const paramTensor = engine.fromNested(packed, [packed.length]);
-    // Build the (paramTensor) → scalar function the engine's
-    // reverseGrad expects. The function unpacks the tensor back
-    // into the bridge's Input struct, calls evaluate, and returns
-    // a rank-0 tensor.
-    const fn = (x) => {
-        const unpacked = engine.toNested(x);
-        const input = { ...spec.defaults };
-        spec.paramNames.forEach((k, i) => {
-            input[k] = unpacked[i];
-        });
-        const scalar = spec.evaluate(input);
-        return engine.fromNested(scalar, []);
-    };
-    const { value, gradient } = await engine.reverseGrad(fn, paramTensor);
-    const valueNumber = engine.toNested(value);
-    return { value: valueNumber, gradient };
-}
-/**
- * Convenience: unpack a 1-D gradient tensor into a named-field
- * record matching the spec's `paramNames` order.
- *
- * @public
- */
-export function gradientToNamed(spec, gradient, engine) {
-    const arr = engine.toNested(gradient);
-    if (arr.length !== spec.paramNames.length) {
-        throw new RangeError(`gradientToNamed: ${spec.bridgeId}: gradient length ${arr.length} does not ` +
-            `match paramNames length ${spec.paramNames.length} — a mismatch would ` +
-            `silently leave some params undefined or drop gradient entries.`);
-    }
-    const out = {};
-    spec.paramNames.forEach((k, i) => {
-        out[k] = arr[i];
-    });
-    return out;
-}
+import { centralPartial } from '../numerical/finite-difference.js';
 /**
  * Relative step for central differences: `cbrt(eps)` balances the `O(h²)`
  * truncation error against the `O(eps/h)` round-off error (the central-diff
@@ -101,20 +28,20 @@ export function gradientToNamed(spec, gradient, engine) {
 const CENTRAL_DIFF_REL_STEP = Math.cbrt(Number.EPSILON); // ≈ 6.06e-6
 /**
  * Gradient of a bridge evaluator by **central finite differences** — the
- * supported way to differentiate the catalog's plain-JS evaluators.
+ * way to differentiate the catalog's plain-JS closed forms without
+ * rewriting them. Needs no engine and is synchronous.
  *
- * Reverse-/forward-mode AD ({@link bridgeGradient}) cannot trace these
- * evaluators: per P8 Decision #1 they are plain-JS scalar functions
- * (`Math.*` / raw arithmetic on numbers), so a tape/dual engine observes no
- * traced ops. `bridgeGradientNumerical` perturbs the inputs instead, so it
- * needs no engine and is synchronous.
- *
- * For each differentiable param with value `x` it uses a relative step
- * `h = max(|x|, 1)·cbrt(eps)` and the ACTUAL representable denominator
- * `dx = (x + h) − (x − h)` — so the perturbation survives floating-point
- * rounding even at astrophysical scales (e.g. `M ≈ 2e30 kg`). The supplied
- * `params` must contain every key in `spec.paramNames`; non-differentiable
- * fields come from `spec.defaults`.
+ * For each differentiable param with value `x` it uses the relative step
+ * `h = max(|x|, floor)·cbrt(eps)`, where `floor` is the spec's
+ * {@link BridgeDiffSpec.stepFloors} entry for that param (0 when the spec
+ * states none), and the ACTUAL representable denominator
+ * `dx = (x + h) − (x − h)` (`numerical/finite-difference`) — so the
+ * perturbation survives floating-point rounding at astrophysical scales
+ * (`M ≈ 2e30 kg`) and stays relative at atomic ones (a charge of 1.6e-19
+ * takes a step of 1e-24, not the 6e-6 an absolute floor of 1 gave). A param
+ * at exactly 0 with no stated floor is refused with a `RangeError`: there is
+ * no scale to step by. The supplied `params` must contain every key in
+ * `spec.paramNames`; non-differentiable fields come from `spec.defaults`.
  *
  * @public
  */
@@ -124,9 +51,8 @@ export function bridgeGradientNumerical(spec, params, opts) {
         throw new RangeError(`bridgeGradientNumerical: ${spec.bridgeId}: relStep must be a positive finite number, got ${relStep} ` +
             `(a zero/non-finite step collapses the central-difference denominator to 0 → NaN gradients).`);
     }
-    // Same contract as bridgeGradient: every paramName must be a FINITE number.
-    // (`typeof NaN === 'number'`, so a bare typeof check let NaN/∞ flow into a
-    // silently non-finite gradient.)
+    // Every paramName must be a FINITE number. (`typeof NaN === 'number'`, so a
+    // bare typeof check let NaN/∞ flow into a silently non-finite gradient.)
     for (const k of spec.paramNames) {
         if (!Number.isFinite(params[k])) {
             throw new TypeError(`bridgeGradientNumerical: ${spec.bridgeId}: missing or non-finite param '${k}' ` +
@@ -134,7 +60,10 @@ export function bridgeGradientNumerical(spec, params, opts) {
         }
     }
     // Build the full Input struct (defaults + differentiable params), with an
-    // optional single-param override for the perturbed evaluations.
+    // optional single-param override for the perturbed evaluations. The
+    // `Input` generic has no runtime schema: `spec.paramNames` is declared as
+    // keys of `Input`, and `defaults` is a `Partial<Input>`, so the merged
+    // record is an `Input` by the spec's own contract; the cast states that.
     const buildInput = (override) => {
         const input = { ...spec.defaults };
         for (const k of spec.paramNames)
@@ -147,11 +76,13 @@ export function bridgeGradientNumerical(spec, params, opts) {
     const gradient = {};
     for (const k of spec.paramNames) {
         const x = params[k];
-        const h = Math.max(Math.abs(x), 1) * relStep;
-        const dx = x + h - (x - h); // actual representable step (huge-x safe)
-        const fp = spec.evaluate(buildInput({ key: k, val: x + h }));
-        const fm = spec.evaluate(buildInput({ key: k, val: x - h }));
-        gradient[k] = (fp - fm) / dx;
+        const floor = spec.stepFloors?.[k] ?? 0;
+        const h = Math.max(Math.abs(x), floor) * relStep;
+        if (!(h > 0)) {
+            throw new RangeError(`bridgeGradientNumerical: ${spec.bridgeId}: param '${k}' is ${x} and the spec states no stepFloors['${k}'], ` +
+                `so a relative central-difference step has no scale; state the parameter's scale in the spec's stepFloors.`);
+        }
+        gradient[k] = centralPartial((p) => spec.evaluate(buildInput({ key: k, val: p[k] })), { [k]: x }, k, h);
     }
     return { value, gradient };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"bridge-gradient.js","sourceRoot":"","sources":["../../src/diff/bridge-gradient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bridge-gradient.js","sourceRoot":"","sources":["../../src/diff/bridge-gradient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAoDnE;;;;;GAKG;AACH,MAAM,qBAAqB,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAA2B,EAC3B,MAA8B,EAC9B,IAAoC;IAEpC,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,qBAAqB,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,UAAU,CAClB,4BAA4B,IAAI,CAAC,QAAQ,mDAAmD,OAAO,GAAG;YACtG,6FAA6F,CAC9F,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,SAAS,CACjB,4BAA4B,IAAI,CAAC,QAAQ,kCAAkC,CAAC,IAAI;gBAChF,QAAQ,MAAM,CAAC,CAAC,CAAC,gEAAgE,CAClF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,oEAAoE;IACpE,0EAA0E;IAC1E,uEAAuE;IACvE,yEAAyE;IACzE,MAAM,UAAU,GAAG,CAAC,QAAuC,EAAS,EAAE;QACpE,MAAM,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAA6B,CAAC;QAC9D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU;YAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACtD,IAAI,QAAQ;YAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC;QACjD,OAAO,KAAyB,CAAC;IACnC,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC;QACjD,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACb,MAAM,IAAI,UAAU,CAClB,4BAA4B,IAAI,CAAC,QAAQ,YAAY,CAAC,QAAQ,CAAC,uCAAuC,CAAC,MAAM;gBAC7G,2GAA2G,CAC5G,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3G,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC","sourcesContent":["/**\n * Bridge-parameter differentiation by central finite differences.\n *\n * A {@link BridgeDiffSpec} wraps one catalog closed form (a plain-JS scalar\n * function over a named-field struct) and names which fields vary.\n * {@link bridgeGradientNumerical} perturbs those fields and returns the\n * gradient keyed by field name.\n *\n * There is no engine-AD path over a spec. `evaluate` returns a `number`, and\n * a number carries no autograd tape, so reverse- or forward-mode AD of a spec\n * is unreachable by construction; the function that once offered it\n * (`bridgeGradient`) threw for every shipped spec and was removed. The exact\n * AD path is {@link bridgeGradientAST} in `bridge-ast-gradient.ts`, which\n * lowers the bridge's symbolic RHS through `@danielsimonjr/mathts-autograd`.\n *\n * This module lives in `src/diff/` (P8 Decision #1), not in `src/bridges/`,\n * so the catalog closed forms stay untouched.\n *\n * @module diff/bridge-gradient\n */\n\nimport { centralPartial } from '../numerical/finite-difference.js';\n\n/**\n * Specification of a differentiable bridge: which parameters can vary, in\n * what order the gradient reports them, the fixed inputs, and the bridge's\n * scalar evaluator.\n *\n * `paramNames` is the report order. For a Shapiro-delay spec with\n * `paramNames: ['M_kg', 'R_far_m', 'R_near_m']`, the gradient returned by\n * `bridgeGradientNumerical` has keys in that insertion order.\n *\n * @public\n */\nexport interface BridgeDiffSpec<Input> {\n  /** Catalog id used in error messages (for example the relation that uses the covariant-eikonal method). */\n  readonly bridgeId: string;\n  /** Display name (e.g., 'Shapiro time delay'). */\n  readonly name: string;\n  /**\n   * Which Input keys vary, in report order. All names must be present in the\n   * frozen `Input` struct as `number`-valued keys.\n   */\n  readonly paramNames: ReadonlyArray<keyof Input & string>;\n  /**\n   * The non-differentiable input fields (those NOT in `paramNames`). The\n   * evaluator receives `defaults` merged with the varying params.\n   */\n  readonly defaults: Partial<Input>;\n  /** The bridge's scalar evaluator. */\n  readonly evaluate: (input: Input) => number;\n  /**\n   * The smallest magnitude the relative step is taken against, per parameter:\n   * for `|x| < floor` the step is `floor·relStep`. A parameter that is zero at\n   * a point of interest (an eccentricity on a circular orbit) needs its scale\n   * stated here, because a relative step at zero is no step. A parameter not\n   * named here has no floor: the step is `|x|·relStep`, and `x = 0` is refused.\n   */\n  readonly stepFloors?: Readonly<Partial<Record<keyof Input & string, number>>>;\n}\n\n/**\n * Result of {@link bridgeGradientNumerical}: the bridge's scalar `value`\n * at the supplied point, plus the `gradient` of partial derivatives keyed\n * by `paramName` (insertion follows `spec.paramNames` order).\n *\n * @public\n */\nexport interface BridgeNumericalGradientResult {\n  readonly value: number;\n  readonly gradient: Readonly<Record<string, number>>;\n}\n\n/**\n * Relative step for central differences: `cbrt(eps)` balances the `O(h²)`\n * truncation error against the `O(eps/h)` round-off error (the central-diff\n * optimum). `sqrt(eps)` — the FORWARD-diff optimum — would leave precision on\n * the table for central differences.\n */\nconst CENTRAL_DIFF_REL_STEP = Math.cbrt(Number.EPSILON); // ≈ 6.06e-6\n\n/**\n * Gradient of a bridge evaluator by **central finite differences** — the\n * way to differentiate the catalog's plain-JS closed forms without\n * rewriting them. Needs no engine and is synchronous.\n *\n * For each differentiable param with value `x` it uses the relative step\n * `h = max(|x|, floor)·cbrt(eps)`, where `floor` is the spec's\n * {@link BridgeDiffSpec.stepFloors} entry for that param (0 when the spec\n * states none), and the ACTUAL representable denominator\n * `dx = (x + h) − (x − h)` (`numerical/finite-difference`) — so the\n * perturbation survives floating-point rounding at astrophysical scales\n * (`M ≈ 2e30 kg`) and stays relative at atomic ones (a charge of 1.6e-19\n * takes a step of 1e-24, not the 6e-6 an absolute floor of 1 gave). A param\n * at exactly 0 with no stated floor is refused with a `RangeError`: there is\n * no scale to step by. The supplied `params` must contain every key in\n * `spec.paramNames`; non-differentiable fields come from `spec.defaults`.\n *\n * @public\n */\nexport function bridgeGradientNumerical<Input>(\n  spec: BridgeDiffSpec<Input>,\n  params: Record<string, number>,\n  opts?: { readonly relStep?: number },\n): BridgeNumericalGradientResult {\n  const relStep = opts?.relStep ?? CENTRAL_DIFF_REL_STEP;\n  if (!Number.isFinite(relStep) || relStep <= 0) {\n    throw new RangeError(\n      `bridgeGradientNumerical: ${spec.bridgeId}: relStep must be a positive finite number, got ${relStep} ` +\n      `(a zero/non-finite step collapses the central-difference denominator to 0 → NaN gradients).`,\n    );\n  }\n\n  // Every paramName must be a FINITE number. (`typeof NaN === 'number'`, so a\n  // bare typeof check let NaN/∞ flow into a silently non-finite gradient.)\n  for (const k of spec.paramNames) {\n    if (!Number.isFinite(params[k])) {\n      throw new TypeError(\n        `bridgeGradientNumerical: ${spec.bridgeId}: missing or non-finite param '${k}' ` +\n        `(got ${params[k]}). All paramNames must be finite numbers in the params object.`,\n      );\n    }\n  }\n\n  // Build the full Input struct (defaults + differentiable params), with an\n  // optional single-param override for the perturbed evaluations. The\n  // `Input` generic has no runtime schema: `spec.paramNames` is declared as\n  // keys of `Input`, and `defaults` is a `Partial<Input>`, so the merged\n  // record is an `Input` by the spec's own contract; the cast states that.\n  const buildInput = (override?: { key: string; val: number }): Input => {\n    const input = { ...spec.defaults } as Record<string, unknown>;\n    for (const k of spec.paramNames) input[k] = params[k];\n    if (override) input[override.key] = override.val;\n    return input as unknown as Input;\n  };\n\n  const value = spec.evaluate(buildInput());\n\n  const gradient: Record<string, number> = {};\n  for (const k of spec.paramNames) {\n    const x = params[k];\n    const floor = spec.stepFloors?.[k] ?? 0;\n    const h = Math.max(Math.abs(x), floor) * relStep;\n    if (!(h > 0)) {\n      throw new RangeError(\n        `bridgeGradientNumerical: ${spec.bridgeId}: param '${k}' is ${x} and the spec states no stepFloors['${k}'], ` +\n        `so a relative central-difference step has no scale; state the parameter's scale in the spec's stepFloors.`,\n      );\n    }\n    gradient[k] = centralPartial((p) => spec.evaluate(buildInput({ key: k, val: p[k]! })), { [k]: x }, k, h);\n  }\n\n  return { value, gradient };\n}\n"]}

package/dist/diff/bridge-specs.d.ts

@@ -5,22 +5,34 @@
  * @module diff/bridge-specs
  */
 import type { BridgeDiffSpec } from './bridge-gradient.js';
-interface ShapiroInput {
+import type { CatalogRelation } from '../bridges/catalog-types.js';
+/**
+ * The catalog id a differentiable relation is labelled by. A relation with no
+ * catalog id is not a catalog bridge and gets no `be-<n>` label; it throws
+ * rather than defaulting to `be-0`.
+ * @internal
+ */
+export declare function requireCatalogId(relation: CatalogRelation): number;
+/** Inputs of {@link SHAPIRO_DELAY_DIFF}: the mass and the two radii. @public */
+export interface ShapiroInput {
     readonly M_kg: number;
     readonly R_far_m: number;
     readonly R_near_m: number;
 }
-interface PerihelionInput {
+/** Inputs of {@link PERIHELION_ADVANCE_DIFF}: mass, semi-major axis, eccentricity, optional period. @public */
+export interface PerihelionInput {
     readonly M_kg: number;
     readonly a_m: number;
     /** Orbital eccentricity, 0 ≤ e < 1. A bare `e` is the elementary charge, so it is not this key. */
     readonly eccentricity: number;
     readonly T_yr?: number;
 }
-interface HawkingInput {
+/** Inputs of {@link HAWKING_TEMPERATURE_DIFF}: the mass. @public */
+export interface HawkingInput {
     readonly M_kg: number;
 }
-interface DecoherenceInput {
+/** Inputs of {@link DECOHERENCE_RATE_DIFF}: the rate and the two couplings. @public */
+export interface DecoherenceInput {
     readonly gamma0_per_s: number;
     readonly lambda: number;
     readonly lambda0: number;
@@ -35,5 +47,4 @@ export declare const HAWKING_TEMPERATURE_DIFF: BridgeDiffSpec<HawkingInput>;
 export declare const DECOHERENCE_RATE_DIFF: BridgeDiffSpec<DecoherenceInput>;
 /** Catalog relations this module differentiates. @public */
 export declare const DIFFERENTIABLE_RELATIONS: readonly [BridgeDiffSpec<ShapiroInput>, BridgeDiffSpec<PerihelionInput>, BridgeDiffSpec<HawkingInput>, BridgeDiffSpec<DecoherenceInput>];
-export {};
 //# sourceMappingURL=bridge-specs.d.ts.map

package/dist/diff/bridge-specs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-specs.d.ts","sourceRoot":"","sources":["../../src/diff/bridge-specs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAyB3D,UAAU,YAAY;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,YAAY;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,gBAAgB;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAUD,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,YAAY,CAM3D,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,eAAe,CAMnE,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,EAAE,cAAc,CAAC,YAAY,CAMjE,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,gBAAgB,CAMlE,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB,0IAK3B,CAAC"}
+{"version":3,"file":"bridge-specs.d.ts","sourceRoot":"","sources":["../../src/diff/bridge-specs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAGnE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAKlE;AAsBD,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,+GAA+G;AAC/G,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAUD,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,YAAY,CAM3D,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,eAAe,CASnE,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,EAAE,cAAc,CAAC,YAAY,CAMjE,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,gBAAgB,CAMlE,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB,0IAK3B,CAAC"}

package/dist/diff/bridge-specs.js

@@ -6,6 +6,18 @@
  */
 import { catalogEdgeKey, catalogRelations } from '../bridges/catalog-load.js';
 import { evaluateCatalogRelation } from '../bridges/relation-eval.js';
+/**
+ * The catalog id a differentiable relation is labelled by. A relation with no
+ * catalog id is not a catalog bridge and gets no `be-<n>` label; it throws
+ * rather than defaulting to `be-0`.
+ * @internal
+ */
+export function requireCatalogId(relation) {
+    if (relation.catalogId === null) {
+        throw new Error(`bridge-specs: relation '${relation.id}' has no catalog id and cannot be labelled be-<n>`);
+    }
+    return relation.catalogId;
+}
 function relationWithSource(source) {
     const found = catalogRelations().find((row) => row.sources.includes(source));
     if (found === undefined)
@@ -35,7 +47,7 @@ if (hawking === undefined)
 const decoherence = relationWithSource('system-environment-coupling');
 /** Shapiro delay. Differentiable in mass and the two radii. @public */
 export const SHAPIRO_DELAY_DIFF = {
-    bridgeId: catalogEdgeKey(shapiro.catalogId ?? 0),
+    bridgeId: catalogEdgeKey(requireCatalogId(shapiro)),
     name: 'Shapiro time delay',
     paramNames: ['M_kg', 'R_far_m', 'R_near_m'],
     defaults: {},
@@ -43,15 +55,18 @@ export const SHAPIRO_DELAY_DIFF = {
 };
 /** Perihelion advance in radians per orbit. @public */
 export const PERIHELION_ADVANCE_DIFF = {
-    bridgeId: catalogEdgeKey(perihelion.catalogId ?? 0),
+    bridgeId: catalogEdgeKey(requireCatalogId(perihelion)),
     name: 'Perihelion advance (radian per orbit)',
     paramNames: ['M_kg', 'a_m', 'eccentricity'],
     defaults: {},
     evaluate: (input) => evaluateAliased(perihelion, input),
+    // The eccentricity is a dimensionless number in [0, 1): its scale is 1, so a circular orbit
+    // (eccentricity 0) still takes the step 1·∛ε, the step every orbit took before the floor was stated.
+    stepFloors: { eccentricity: 1 },
 };
 /** Hawking temperature. Differentiable in mass. @public */
 export const HAWKING_TEMPERATURE_DIFF = {
-    bridgeId: catalogEdgeKey(hawking.catalogId ?? 0),
+    bridgeId: catalogEdgeKey(requireCatalogId(hawking)),
     name: 'Hawking temperature',
     paramNames: ['M_kg'],
     defaults: {},
@@ -59,7 +74,7 @@ export const HAWKING_TEMPERATURE_DIFF = {
 };
 /** Decoherence rate. Differentiable in the rate and the two couplings. @public */
 export const DECOHERENCE_RATE_DIFF = {
-    bridgeId: catalogEdgeKey(decoherence.catalogId ?? 0),
+    bridgeId: catalogEdgeKey(requireCatalogId(decoherence)),
     name: 'Decoherence rate',
     paramNames: ['gamma0_per_s', 'lambda', 'lambda0'],
     defaults: {},

package/dist/diff/bridge-specs.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-specs.js","sourceRoot":"","sources":["../../src/diff/bridge-specs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bridge-specs.js","sourceRoot":"","sources":["../../src/diff/bridge-specs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Differentiable relations projected from the catalog. The scalar is the\n * catalog expression. Parameter names are the relation's aliases.\n *\n * @module diff/bridge-specs\n */\n\nimport type { BridgeDiffSpec } from './bridge-gradient.js';\nimport { catalogEdgeKey, catalogRelations } from '../bridges/catalog-load.js';\nimport type { CatalogRelation } from '../bridges/catalog-types.js';\nimport { evaluateCatalogRelation } from '../bridges/relation-eval.js';\n\n/**\n * The catalog id a differentiable relation is labelled by. A relation with no\n * catalog id is not a catalog bridge and gets no `be-<n>` label; it throws\n * rather than defaulting to `be-0`.\n * @internal\n */\nexport function requireCatalogId(relation: CatalogRelation): number {\n  if (relation.catalogId === null) {\n    throw new Error(`bridge-specs: relation '${relation.id}' has no catalog id and cannot be labelled be-<n>`);\n  }\n  return relation.catalogId;\n}\n\nfunction relationWithSource(source: string): CatalogRelation {\n  const found = catalogRelations().find((row) => row.sources.includes(source));\n  if (found === undefined) throw new Error(`bridge-specs: no relation has source '${source}'`);\n  return found;\n}\n\nfunction evaluateAliased(relation: CatalogRelation, input: object): number {\n  const record = input as Record<string, number | undefined>;\n  const bound: Record<string, number> = {};\n  for (const source of relation.sources) {\n    const alias = (relation.aliases[source] ?? []).find((key) => record[key] !== undefined);\n    const key = alias ?? (record[source] !== undefined ? source : undefined);\n    if (key === undefined) throw new Error(`${relation.id}: missing ${source}`);\n    const value = record[key];\n    if (value === undefined) throw new Error(`${relation.id}: missing ${source}`);\n    bound[source] = value;\n  }\n  return evaluateCatalogRelation(relation, bound);\n}\n\n/** Inputs of {@link SHAPIRO_DELAY_DIFF}: the mass and the two radii. @public */\nexport interface ShapiroInput {\n  readonly M_kg: number;\n  readonly R_far_m: number;\n  readonly R_near_m: number;\n}\n\n/** Inputs of {@link PERIHELION_ADVANCE_DIFF}: mass, semi-major axis, eccentricity, optional period. @public */\nexport interface PerihelionInput {\n  readonly M_kg: number;\n  readonly a_m: number;\n  /** Orbital eccentricity, 0 ≤ e < 1. A bare `e` is the elementary charge, so it is not this key. */\n  readonly eccentricity: number;\n  readonly T_yr?: number;\n}\n\n/** Inputs of {@link HAWKING_TEMPERATURE_DIFF}: the mass. @public */\nexport interface HawkingInput {\n  readonly M_kg: number;\n}\n\n/** Inputs of {@link DECOHERENCE_RATE_DIFF}: the rate and the two couplings. @public */\nexport interface DecoherenceInput {\n  readonly gamma0_per_s: number;\n  readonly lambda: number;\n  readonly lambda0: number;\n}\n\nconst shapiro = relationWithSource('far-radius');\nconst perihelion = relationWithSource('semi-major-axis');\nconst hawking = catalogRelations().find(\n  (row) => row.target === 'hawking-temperature' && row.sources.length === 1 && row.sources[0] === 'mass',\n);\nif (hawking === undefined) throw new Error('bridge-specs: no Hawking temperature relation');\nconst decoherence = relationWithSource('system-environment-coupling');\n\n/** Shapiro delay. Differentiable in mass and the two radii. @public */\nexport const SHAPIRO_DELAY_DIFF: BridgeDiffSpec<ShapiroInput> = {\n  bridgeId: catalogEdgeKey(requireCatalogId(shapiro)),\n  name: 'Shapiro time delay',\n  paramNames: ['M_kg', 'R_far_m', 'R_near_m'],\n  defaults: {},\n  evaluate: (input) => evaluateAliased(shapiro, input),\n};\n\n/** Perihelion advance in radians per orbit. @public */\nexport const PERIHELION_ADVANCE_DIFF: BridgeDiffSpec<PerihelionInput> = {\n  bridgeId: catalogEdgeKey(requireCatalogId(perihelion)),\n  name: 'Perihelion advance (radian per orbit)',\n  paramNames: ['M_kg', 'a_m', 'eccentricity'],\n  defaults: {},\n  evaluate: (input) => evaluateAliased(perihelion, input),\n  // The eccentricity is a dimensionless number in [0, 1): its scale is 1, so a circular orbit\n  // (eccentricity 0) still takes the step 1·∛ε, the step every orbit took before the floor was stated.\n  stepFloors: { eccentricity: 1 },\n};\n\n/** Hawking temperature. Differentiable in mass. @public */\nexport const HAWKING_TEMPERATURE_DIFF: BridgeDiffSpec<HawkingInput> = {\n  bridgeId: catalogEdgeKey(requireCatalogId(hawking)),\n  name: 'Hawking temperature',\n  paramNames: ['M_kg'],\n  defaults: {},\n  evaluate: (input) => evaluateAliased(hawking, input),\n};\n\n/** Decoherence rate. Differentiable in the rate and the two couplings. @public */\nexport const DECOHERENCE_RATE_DIFF: BridgeDiffSpec<DecoherenceInput> = {\n  bridgeId: catalogEdgeKey(requireCatalogId(decoherence)),\n  name: 'Decoherence rate',\n  paramNames: ['gamma0_per_s', 'lambda', 'lambda0'],\n  defaults: {},\n  evaluate: (input) => evaluateAliased(decoherence, input),\n};\n\n/** Catalog relations this module differentiates. @public */\nexport const DIFFERENTIABLE_RELATIONS = [\n  SHAPIRO_DELAY_DIFF,\n  PERIHELION_ADVANCE_DIFF,\n  HAWKING_TEMPERATURE_DIFF,\n  DECOHERENCE_RATE_DIFF,\n] as const;\n"]}

package/dist/dimensional/algebra.d.ts

@@ -17,6 +17,17 @@ import { Dimension } from './types.js';
  * @public
  */
 export { DimensionMismatchError } from './errors.js';
+/** The seven SI bases, in the order every exponent list is written. @internal */
+export declare const BASES: readonly ['L', 'M', 'T', 'I', 'Theta', 'N', 'J'];
+/** Exact zero on every base; a base missing from a partial object reads as 0. @internal */
+export declare function isDimensionless(d: Dimension): boolean;
+/**
+ * Exact equality on every base, no tolerance: the predicate for exponents that
+ * were never computed. {@link equals} is the tolerant one for exponents that
+ * were (a fractional power reached by different op chains).
+ * @internal
+ */
+export declare function exactlyEquals(a: Dimension, b: Dimension): boolean;
 /** Product of two dimensions: exponents add per base. */
 export declare function multiply(a: Dimension, b: Dimension): Dimension;
 /** Quotient of two dimensions: exponents subtract per base. */
@@ -57,4 +68,11 @@ export declare function subtract(a: Dimension, b: Dimension): Dimension;
  *      Bases with exponent 0 are omitted; exponent 1 is written without "^1".
  */
 export declare function format(d: Dimension): string;
+/** Each base with its coherent SI unit, kilogram first (the order `siUnitOf` prints). @internal */
+export declare const SI_BASE: readonly (readonly [keyof Dimension, string])[];
+/**
+ * A dimension as SI base units, numerator before one `/` (`m^3/(kg*s^2)`), a bare denominator as
+ * negative powers (`s^-1`), and `1` when dimensionless: the forms `parseUnit` reads back.
+ */
+export declare function siUnitOf(dim: Dimension): string;
 //# sourceMappingURL=algebra.d.ts.map

package/dist/dimensional/algebra.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"algebra.d.ts","sourceRoot":"","sources":["../../src/dimensional/algebra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAC;AAGzD;;;;;GAKG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAKrD,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAM9D;AAED,+DAA+D;AAC/D,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAM5D;AAED,kFAAkF;AAClF,wBAAgB,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAMxD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAU1D;AAED,wFAAwF;AACxF,wBAAgB,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CASzD;AAED,+FAA+F;AAC/F,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAS9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAgB3C"}
+{"version":3,"file":"algebra.d.ts","sourceRoot":"","sources":["../../src/dimensional/algebra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAC;AAGzD;;;;;GAKG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,iFAAiF;AACjF,eAAO,MAAM,KAAK,YAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAGtE,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAEjE;AAED,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAM9D;AAED,+DAA+D;AAC/D,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAM5D;AAED,kFAAkF;AAClF,wBAAgB,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAMxD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAU1D;AAED,wFAAwF;AACxF,wBAAgB,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CASzD;AAED,+FAA+F;AAC/F,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAS9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAgB3C;AAED,mGAAmG;AACnG,eAAO,MAAM,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,SAAS,EAAE,MAAM,CAAC,CAAC,EAQlE,CAAC;AAEF;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAQ/C"}

package/dist/dimensional/algebra.js

@@ -18,7 +18,21 @@ import { DimensionMismatchError } from './errors.js';
  * @public
  */
 export { DimensionMismatchError } from './errors.js';
-const BASES = ['L', 'M', 'T', 'I', 'Theta', 'N', 'J'];
+/** The seven SI bases, in the order every exponent list is written. @internal */
+export const BASES = ['L', 'M', 'T', 'I', 'Theta', 'N', 'J'];
+/** Exact zero on every base; a base missing from a partial object reads as 0. @internal */
+export function isDimensionless(d) {
+    return BASES.every((base) => (d[base] ?? 0) === 0);
+}
+/**
+ * Exact equality on every base, no tolerance: the predicate for exponents that
+ * were never computed. {@link equals} is the tolerant one for exponents that
+ * were (a fractional power reached by different op chains).
+ * @internal
+ */
+export function exactlyEquals(a, b) {
+    return BASES.every((base) => (a[base] ?? 0) === (b[base] ?? 0));
+}
 /** Product of two dimensions: exponents add per base. */
 export function multiply(a, b) {
     const out = {};
@@ -116,4 +130,30 @@ export function format(d) {
         return '[1]';
     return `[${parts.join(' ')}]`;
 }
+/** Each base with its coherent SI unit, kilogram first (the order `siUnitOf` prints). @internal */
+export const SI_BASE = [
+    ['M', 'kg'],
+    ['L', 'm'],
+    ['T', 's'],
+    ['I', 'A'],
+    ['Theta', 'K'],
+    ['N', 'mol'],
+    ['J', 'cd'],
+];
+/**
+ * A dimension as SI base units, numerator before one `/` (`m^3/(kg*s^2)`), a bare denominator as
+ * negative powers (`s^-1`), and `1` when dimensionless: the forms `parseUnit` reads back.
+ */
+export function siUnitOf(dim) {
+    const factor = (u, e) => (e === 1 ? u : `${u}^${e}`);
+    const num = SI_BASE.filter(([k]) => dim[k] > 0).map(([k, u]) => factor(u, dim[k]));
+    const den = SI_BASE.filter(([k]) => dim[k] < 0).map(([k, u]) => factor(u, -dim[k]));
+    if (num.length === 0 && den.length === 0)
+        return '1';
+    if (num.length === 0)
+        return SI_BASE.filter(([k]) => dim[k] < 0).map(([k, u]) => factor(u, dim[k])).join('*');
+    if (den.length === 0)
+        return num.join('*');
+    return `${num.join('*')}/${den.length === 1 ? den[0] : `(${den.join('*')})`}`;
+}
 //# sourceMappingURL=algebra.js.map

package/dist/dimensional/algebra.js.map

@@ -1 +1 @@
-{"version":3,"file":"algebra.js","sourceRoot":"","sources":["../../src/dimensional/algebra.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"algebra.js","sourceRoot":"","sources":["../../src/dimensional/algebra.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Dimensional algebra: per-base-exponent arithmetic.\n *\n * Operations follow standard dimensional analysis (Bridgman, \"Dimensional Analysis\", 1922):\n *   - multiply: add exponents per base\n *   - divide:   subtract exponents per base\n *   - power:    scale exponents by the scalar `n`\n *   - add/sub:  permitted only when both operands have the same dimension\n *\n * @module dimensional/algebra\n */\n\nimport { Dimension, NAMED_DIMENSIONS } from './types.js';\nimport { DimensionMismatchError } from './errors.js';\n\n/**\n * Re-exported for callers that import the error from the algebra module.\n * The definition lives in `errors.ts`.\n *\n * @public\n */\nexport { DimensionMismatchError } from './errors.js';\n\n/** The seven SI bases, in the order every exponent list is written. @internal */\nexport const BASES = ['L', 'M', 'T', 'I', 'Theta', 'N', 'J'] as const;\ntype Base = typeof BASES[number];\n\n/** Exact zero on every base; a base missing from a partial object reads as 0. @internal */\nexport function isDimensionless(d: Dimension): boolean {\n  return BASES.every((base) => (d[base] ?? 0) === 0);\n}\n\n/**\n * Exact equality on every base, no tolerance: the predicate for exponents that\n * were never computed. {@link equals} is the tolerant one for exponents that\n * were (a fractional power reached by different op chains).\n * @internal\n */\nexport function exactlyEquals(a: Dimension, b: Dimension): boolean {\n  return BASES.every((base) => (a[base] ?? 0) === (b[base] ?? 0));\n}\n\n/** Product of two dimensions: exponents add per base. */\nexport function multiply(a: Dimension, b: Dimension): Dimension {\n  const out = {} as Dimension;\n  for (const base of BASES) {\n    out[base as Base] = a[base as Base] + b[base as Base];\n  }\n  return out;\n}\n\n/** Quotient of two dimensions: exponents subtract per base. */\nexport function divide(a: Dimension, b: Dimension): Dimension {\n  const out = {} as Dimension;\n  for (const base of BASES) {\n    out[base as Base] = a[base as Base] - b[base as Base];\n  }\n  return out;\n}\n\n/** Raise a dimension to a (possibly fractional) power: exponents scale by `n`. */\nexport function power(a: Dimension, n: number): Dimension {\n  const out = {} as Dimension;\n  for (const base of BASES) {\n    out[base as Base] = a[base as Base] * n;\n  }\n  return out;\n}\n\n/**\n * Largest exponent difference still treated as equal. Physical dimension\n * exponents are integers or simple rationals (halves, thirds), so any genuine\n * distinction is ≥ ~1/3 — far above this tolerance, which only absorbs\n * floating-point round-off in fractional powers (v0.20 dimensionful `M^0.5`\n * reached by different op chains, e.g. 0.30000000000000004 vs 0.3).\n */\nexport const EXPONENT_TOL = 1e-9;\n\n/**\n * True iff two dimensions have equal exponents on every base, within\n * `EXPONENT_TOL` so floating-point round-off in fractional exponents does not\n * read as unequal.\n *\n * Unrolled over the 7 bases (no iterator / dynamic-key access) and\n * short-circuiting — `equals` is on the hot path (every `add`/`subtract`, and\n * `format`'s named-dimension scan calls it per entry). Stays distinct from\n * `linkage.ts`'s exact `dimEqual`: this one is tolerant by design (the v0.20\n * fractional-power round-off fix), so they are NOT the same predicate.\n */\nexport function equals(a: Dimension, b: Dimension): boolean {\n  return (\n    Math.abs(a.L - b.L) <= EXPONENT_TOL &&\n    Math.abs(a.M - b.M) <= EXPONENT_TOL &&\n    Math.abs(a.T - b.T) <= EXPONENT_TOL &&\n    Math.abs(a.I - b.I) <= EXPONENT_TOL &&\n    Math.abs(a.Theta - b.Theta) <= EXPONENT_TOL &&\n    Math.abs(a.N - b.N) <= EXPONENT_TOL &&\n    Math.abs(a.J - b.J) <= EXPONENT_TOL\n  );\n}\n\n/** Dimensional sum: requires equal dimensions, else throws `DimensionMismatchError`. */\nexport function add(a: Dimension, b: Dimension): Dimension {\n  if (!equals(a, b)) {\n    throw new DimensionMismatchError(\n      `Cannot add unlike dimensions: ${format(a)} + ${format(b)}`,\n      a,\n      b,\n    );\n  }\n  return { ...a };\n}\n\n/** Dimensional difference: requires equal dimensions, else throws `DimensionMismatchError`. */\nexport function subtract(a: Dimension, b: Dimension): Dimension {\n  if (!equals(a, b)) {\n    throw new DimensionMismatchError(\n      `Cannot subtract unlike dimensions: ${format(a)} - ${format(b)}`,\n      a,\n      b,\n    );\n  }\n  return { ...a };\n}\n\n/**\n * Format a `Dimension` for human display.\n *\n * Strategy:\n *   1. If `d` matches a named SI dimension exactly, return e.g. \"[energy]\".\n *      \"dimensionless\" is rendered as \"[1]\" for compactness.\n *   2. Otherwise emit the bracketed product form, e.g. \"[M L^2 T^-2]\".\n *      Bases with exponent 0 are omitted; exponent 1 is written without \"^1\".\n */\nexport function format(d: Dimension): string {\n  for (const [name, ref] of NAMED_DIMENSIONS) {\n    if (equals(d, ref)) {\n      if (name === 'dimensionless') return '[1]';\n      return `[${name}]`;\n    }\n  }\n  const parts: string[] = [];\n  for (const base of BASES) {\n    const exp = d[base as Base];\n    if (exp === 0) continue;\n    if (exp === 1) parts.push(base);\n    else parts.push(`${base}^${exp}`);\n  }\n  if (parts.length === 0) return '[1]';\n  return `[${parts.join(' ')}]`;\n}\n\n/** Each base with its coherent SI unit, kilogram first (the order `siUnitOf` prints). @internal */\nexport const SI_BASE: readonly (readonly [keyof Dimension, string])[] = [\n  ['M', 'kg'],\n  ['L', 'm'],\n  ['T', 's'],\n  ['I', 'A'],\n  ['Theta', 'K'],\n  ['N', 'mol'],\n  ['J', 'cd'],\n];\n\n/**\n * A dimension as SI base units, numerator before one `/` (`m^3/(kg*s^2)`), a bare denominator as\n * negative powers (`s^-1`), and `1` when dimensionless: the forms `parseUnit` reads back.\n */\nexport function siUnitOf(dim: Dimension): string {\n  const factor = (u: string, e: number): string => (e === 1 ? u : `${u}^${e}`);\n  const num = SI_BASE.filter(([k]) => dim[k] > 0).map(([k, u]) => factor(u, dim[k]));\n  const den = SI_BASE.filter(([k]) => dim[k] < 0).map(([k, u]) => factor(u, -dim[k]));\n  if (num.length === 0 && den.length === 0) return '1';\n  if (num.length === 0) return SI_BASE.filter(([k]) => dim[k] < 0).map(([k, u]) => factor(u, dim[k])).join('*');\n  if (den.length === 0) return num.join('*');\n  return `${num.join('*')}/${den.length === 1 ? den[0] : `(${den.join('*')})`}`;\n}\n"]}

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

@@ -17,9 +17,17 @@ import type { Dimension } from './types.js';
 /** A symbol-leaf `ExprNode` carrying its name and SI dimension. */
 export declare function sym(name: string, dim: Dimension): ExprNode;
 /**
- * Build a `Dimension` from its first five base exponents. Arg order is
- * (L, M, T, **I**, **Θ**) — note I precedes Θ; the amount-of-substance (N) and
- * luminous-intensity (J) exponents default to 0.
+ * Build a `Dimension` from its base exponents. Arg order is
+ * (L, M, T, **I**, **Θ**, N, J) — note I precedes Θ; every omitted exponent
+ * is 0, so the amount-of-substance (N) and luminous-intensity (J) exponents
+ * are reachable from the one builder.
  */
-export declare function dim(L?: number, M?: number, T?: number, I?: number, Theta?: number): Dimension;
+export declare function dim(L?: number, M?: number, T?: number, I?: number, Theta?: number, N?: number, J?: number): Dimension;
+/**
+ * `base ^ exponent`, with the exponent a dimensionless literal written `String(exponent)`;
+ * exponent 1 returns `base` itself. The factor both monomial builders share
+ * (`monomialToExpr` in composition/probe/generator.ts, `fromMonomial` in
+ * composition/proposed-bridges.ts), which arrange their factors differently.
+ */
+export declare function symbolPower(base: ExprNode, exponent: number): ExprNode;
 //# sourceMappingURL=ast-builders.d.ts.map

package/dist/dimensional/ast-builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast-builders.d.ts","sourceRoot":"","sources":["../../src/dimensional/ast-builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,mEAAmE;AACnE,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,QAAQ,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,KAAK,SAAI,GAAG,SAAS,CAEpE"}
+{"version":3,"file":"ast-builders.d.ts","sourceRoot":"","sources":["../../src/dimensional/ast-builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,mEAAmE;AACnE,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,QAAQ,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,KAAK,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,SAAS,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAGtE"}

package/dist/dimensional/ast-builders.js

@@ -17,11 +17,23 @@ export function sym(name, dim) {
     return { kind: 'symbol', name, dim };
 }
 /**
- * Build a `Dimension` from its first five base exponents. Arg order is
- * (L, M, T, **I**, **Θ**) — note I precedes Θ; the amount-of-substance (N) and
- * luminous-intensity (J) exponents default to 0.
+ * Build a `Dimension` from its base exponents. Arg order is
+ * (L, M, T, **I**, **Θ**, N, J) — note I precedes Θ; every omitted exponent
+ * is 0, so the amount-of-substance (N) and luminous-intensity (J) exponents
+ * are reachable from the one builder.
  */
-export function dim(L = 0, M = 0, T = 0, I = 0, Theta = 0) {
-    return { L, M, T, I, Theta, N: 0, J: 0 };
+export function dim(L = 0, M = 0, T = 0, I = 0, Theta = 0, N = 0, J = 0) {
+    return { L, M, T, I, Theta, N, J };
+}
+/**
+ * `base ^ exponent`, with the exponent a dimensionless literal written `String(exponent)`;
+ * exponent 1 returns `base` itself. The factor both monomial builders share
+ * (`monomialToExpr` in composition/probe/generator.ts, `fromMonomial` in
+ * composition/proposed-bridges.ts), which arrange their factors differently.
+ */
+export function symbolPower(base, exponent) {
+    if (exponent === 1)
+        return base;
+    return { kind: 'op', op: '^', args: [base, sym(String(exponent), dim())] };
 }
 //# sourceMappingURL=ast-builders.js.map

package/dist/dimensional/ast-builders.js.map

@@ -1 +1 @@
-{"version":3,"file":"ast-builders.js","sourceRoot":"","sources":["../../src/dimensional/ast-builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,mEAAmE;AACnE,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,GAAc;IAC9C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC;IACvD,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"ast-builders.js","sourceRoot":"","sources":["../../src/dimensional/ast-builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,mEAAmE;AACnE,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,GAAc;IAC9C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC;IACrE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAc,EAAE,QAAgB;IAC1D,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;AAC7E,CAAC","sourcesContent":["/**\n * Tiny pure builders for dimensional ASTs — `sym` (a symbol leaf) and `dim`\n * (a `Dimension` from its first five base exponents). These were copy-pasted\n * across the bridge-equation helpers, the canonical L1 builder, the\n * composition layer, and the formula transpiler; this module is their single\n * source of truth.\n *\n * Deliberately depends only on TYPES (`ExprNode`, `Dimension`), so it has no\n * runtime imports and can be imported from any layer without risking a cycle.\n * `_be-helpers` and `_l1-build` re-export `sym`/`dim` for their existing\n * importers, so most call sites are unchanged.\n *\n * @module dimensional/ast-builders\n */\n\nimport type { ExprNode } from './validator.js';\nimport type { Dimension } from './types.js';\n\n/** A symbol-leaf `ExprNode` carrying its name and SI dimension. */\nexport function sym(name: string, dim: Dimension): ExprNode {\n  return { kind: 'symbol', name, dim };\n}\n\n/**\n * Build a `Dimension` from its base exponents. Arg order is\n * (L, M, T, **I**, **Θ**, N, J) — note I precedes Θ; every omitted exponent\n * is 0, so the amount-of-substance (N) and luminous-intensity (J) exponents\n * are reachable from the one builder.\n */\nexport function dim(L = 0, M = 0, T = 0, I = 0, Theta = 0, N = 0, J = 0): Dimension {\n  return { L, M, T, I, Theta, N, J };\n}\n\n/**\n * `base ^ exponent`, with the exponent a dimensionless literal written `String(exponent)`;\n * exponent 1 returns `base` itself. The factor both monomial builders share\n * (`monomialToExpr` in composition/probe/generator.ts, `fromMonomial` in\n * composition/proposed-bridges.ts), which arrange their factors differently.\n */\nexport function symbolPower(base: ExprNode, exponent: number): ExprNode {\n  if (exponent === 1) return base;\n  return { kind: 'op', op: '^', args: [base, sym(String(exponent), dim())] };\n}\n"]}