universal-physics-tensor 0.22.0 → 0.24.0

package/README.md

@@ -60,8 +60,12 @@ npm run upt -- priority                                    # triage speculative
 npm run upt -- audit                                       # derive the bridges by dimensions
 npm run upt -- predict                                     # empty regime cells as link hypotheses
 npm run upt -- discover                                    # vet link candidates (merge/unlock/consistency)
+npm run upt -- discover --source=canonical                 # run the funnel on standard physics ALONE (no bridges)
+npm run upt -- discover --derive                           # surface machine-derived identity consequences (unreleased; --max-orders / --anchor flags available)
 npm run upt -- connectors                                  # which isolated bridges can connect to the core
 npm run upt -- coverage                                    # audit each bridge's empirical grounding
+npm run upt -- canonical                                   # the standard-physics L-layer registry (answer key)
+npm run upt -- recover                                     # validate bridges against standard physics
 npm run upt -- symbolic --simplify                         # compose + fold bridges' SYMBOLIC forms (MathTS simplify)
 # ...and YOUR OWN equations:
 npm run upt -- eval "hbar*c^3/(8*pi*G*M*k_B)" hbar=1.054571817e-34 c=299792458 G=6.6743e-11 M=1.989e30 k_B=1.380649e-23
@@ -79,6 +83,10 @@ and a built-in, dependency-free parser otherwise — transparently, via a
 `FormulaParser` registry (add `--debug` to see which is active). UPT keeps
 **zero hard dependencies**; the MathTS packages are optional.
 
+See [`cli/README.md`](cli/README.md) for the full CLI reference — every command
+and alias, the `--source=catalog|canonical|both` flag, input syntax, exit codes,
+and troubleshooting.
+
 ## Installation
 
 ```bash
@@ -209,7 +217,7 @@ for how the documents evolved.
 - **[Part IV: Validation & Implications](docs/specification/Part-IV.md)** - Experimental pathways, philosophical implications, applications
 - **[Part V: Advanced Mathematics & Protocols](docs/specification/Part-V.md)** - Category theory extensions, validation protocols, algorithmic analysis
 - **[Part VI: Deployment & Governance](docs/specification/Part-VI.md)** - Implementation strategies, applications, governance frameworks
-- **Supplements** - [Part VII: Tensor Algebra](docs/specification/Part-VII-Tensor-Algebra.md) · [Part VIII: Metric Layer](docs/specification/Part-VIII-Metric-Layer.md) · [Part IX: Composition](docs/specification/Part-IX-Composition.md) · [Part X: Curvature & Field Equations](docs/specification/Part-X-Curvature-and-Field-Equations.md)
+- **Supplements** - [Part VII: Tensor Algebra](docs/specification/Part-VII-Tensor-Algebra.md) · [Part VIII: Metric Layer](docs/specification/Part-VIII-Metric-Layer.md) · [Part IX: Composition](docs/specification/Part-IX-Composition.md) · [Part X: Curvature & Field Equations](docs/specification/Part-X-Curvature-and-Field-Equations.md) · [Part XI: Proposed Equations](docs/specification/Part-XI-Proposed-Equations.md) (non-normative; machine-derived identity consequences, unadjudicated)
 
 ### Planning & Development
 - **[Development Plan](docs/planning/Development-Plan.md)** - Phased implementation roadmap
@@ -236,33 +244,40 @@ delivered a measured **5-6× RK4 geodesic-integrator speedup** (see [CHANGELOG](
 
 ## Development Status
 
-**Current version:** v0.7.3 on npm
-([`universal-physics-tensor`](https://www.npmjs.com/package/universal-physics-tensor));
-the branch carries unreleased **v0.8.0 → v0.14** milestones (composition graph +
-GW170817 / BE-23 data confrontations + catalog adjudication, Part-IX Phase C/D,
-the full catalog→graph migration, the bridge-inference + symbolic-composition
-tooling, the G-9 geometrized-units adapters, and the v0.14 work — distributional/
-variational grammar primitives, the `BridgeEquations` facade, G-9 increment 2's
-public adapters, and the `LabeledTensor` axis-order fix + `mergeAxes`/`splitAxis`)
-awaiting a single **rollup tag** — see the [CHANGELOG](CHANGELOG.md) `[Unreleased]`
-block.
+**Current version:** v0.24.0 on npm
+([`universal-physics-tensor`](https://www.npmjs.com/package/universal-physics-tensor),
+published 2026-06-19) — building on the **v0.8.0 → v0.23.0** rollup arc (composition
+graph + GW170817 / BE-23 data confrontations + catalog adjudication, Part-IX
+Phase C/D, the full catalog→graph migration, the bridge-inference +
+symbolic-composition tooling, the G-9 geometrized-units adapters, the
+distributional/variational grammar primitives, the AST bridge-gradient path, and
+the **canonical-equation L-layer** with bridge↔canonical linkage). v0.24.0 adds
+the **identity-consequence surfacer** (`upt discover --derive` → machine-derived
+candidate relations, held out of the catalog pending §XXVII-B review; see
+[Part-XI](docs/specification/Part-XI-Proposed-Equations.md)), **canonical-only
+discovery** (`--source=catalog|canonical|both`), canonical-graph quality fixes
+(magnitude-gate sourcing, variable-name unification, the declared
+compton↔de-Broglie link), and architecture refactors (the `tensor↔cell` runtime
+cycle removed; the `numerical→bridges` upward dependency dropped).
 
 | Metric | Value |
 |---|---|
 | Bridge catalog | **44** (IDs 11-54) — 8 established · 33 speculative · 3 highly-speculative · 0 invalid; membership-adjudicated **36 bridges · 5 not-a-bridge · 3 contested**; **41-edge composition graph** (full migration, 131 centralized quantity nodes) with a bridge-inference suite — **identifiability classifier**, **retrodiction harness**, **Buckingham-π enumerator**, unified by an **`explainQuantity`** entry point, plus (v0.12) the candidate-vetting **discovery loop**, regime-prediction map, empirical-coverage audit, and **symbolic composition** (the Observable contract + MathTS simplification) |
-| Test suite | **2620** passing (5 skipped, 1 todo; incl. property-based algebra tests) — gated by CI |
+| Test suite | **2841** passing (4 skipped, 1 todo; incl. property-based algebra tests) across 277 files — gated by CI |
 | `tsc --noEmit` | clean (src + strict `tsc -p tsconfig.tests.json`) |
 | GR validation anchors | BE-52 Mercury perihelion relErr 1.8×10⁻⁷ · BE-37 Shapiro delay relErr ~2×10⁻⁸ |
 | First derived relation | E_min(M) = ℏc³ln2/(8πGM) from BE-42 ∘ BE-16, relErr ≤ 10⁻¹² (pre-registered CT-1) |
 | First data confrontation | GW170817 → BE-36: recomputed bounds +6.5×10⁻¹⁶ / −3.1×10⁻¹⁵ vs published +7×10⁻¹⁶ / −3×10⁻¹⁵ |
-| Core capability | Dimensional AST validator (23 node kinds; valence-homogeneity + symbolic-exponent grammar, v0.13; distributional/variational primitives, v0.14) · curvature + Einstein-field-equation layers · GL4 symplectic geodesic integrator · composition graph (`composeEdges` + symbolic `composeSymbolic`) · geometrized-units adapters (G-9 increment 1, v0.13) |
+| Core capability | Dimensional AST validator (23 node kinds; valence-homogeneity + symbolic-exponent grammar, v0.13; distributional/variational primitives, v0.14) · curvature + Einstein-field-equation layers · GL4 symplectic geodesic integrator · composition graph (`composeEdges` + symbolic `composeSymbolic`) · geometrized-units adapters (G-9 increment 1, v0.13) · canonical-equation **L-layer** + bridge↔canonical linkage / F4 guard (v0.22) · **identity-consequence surfacer** (`upt discover --derive`, unreleased) |
 
 Release history lives in the **[CHANGELOG](CHANGELOG.md)** — from the v0.1.0
 catalog-closure milestone (40/40 AST encodings via the Wave A→Z encoding arc,
 with cross-LLM validation of the highest-stakes reformulations) through the
 GR-foundations releases (v0.4.x–v0.6.0), the v0.7.x intelligent-index / gradient
-series, the v0.8–v0.11 composition + catalog→graph arc, and the v0.12–v0.13
-inference / symbolic-composition / units work. The formal
+series, the v0.8–v0.11 composition + catalog→graph arc, the v0.12–v0.13
+inference / symbolic-composition / units work, and the v0.14–v0.23
+distributional/variational grammar, AST bridge-gradient path, canonical-equation
+L-layer, bridge↔canonical linkage, and identity-consequence surfacer arc. The formal
 spec's own revision ledger is at
 [docs/specification/CHANGELOG.md](docs/specification/CHANGELOG.md).
 

package/bin/upt.mjs

@@ -20,7 +20,7 @@ const here = dirname(fileURLToPath(import.meta.url));
 const dist = (...p) => pathToFileURL(join(here, '..', 'dist', ...p)).href;
 
 let api, analysis, formulaReg, dimSpecMod, prediction, discovery, coverage, simplifyMod;
-let canonicalReg, linkageMod;
+let canonicalReg, linkageMod, proposedMod;
 try {
   api = await import(dist('index.js'));
   analysis = await import(dist('composition', 'bridge-analysis.js'));
@@ -32,13 +32,14 @@ try {
   simplifyMod = await import(dist('composition', 'expr-simplify.js'));
   canonicalReg = await import(dist('canonical', 'registry.js'));
   linkageMod = await import(dist('canonical', 'linkage.js'));
+  proposedMod = await import(dist('composition', 'proposed-bridges.js'));
 } catch (err) {
   console.error('Could not load the built package. Run `npm run build` first.');
   console.error(String(err.message || err));
   process.exit(1);
 }
 
-const { explainQuantity, CATALOG_GRAPH, M_SUN_KG, composeSymbolic,
+const { explainQuantity, CATALOG_GRAPH, CANONICAL_GRAPH, M_SUN_KG, composeSymbolic,
   be42Edge, be16Edge, lawSchwarzschildRadius, be42ViaRsEdge, format } = api;
 const { bridgePriority, attemptDerivation, dimensionalFreedom, dimensionallyDetermines, buckinghamPi, linkageMap, proposeLinkCandidates, proposeOrphanConnectors } = { ...analysis, ...api };
 const { getFormulaParser, getFormulaParserKind, getFormulaDimensionChecker } = formulaReg;
@@ -49,9 +50,31 @@ const { auditCoverage } = coverage;
 const { simplifyObservable } = simplifyMod;
 const { CANONICAL_EQUATIONS, bridgesWithoutCanonicalPartner } = canonicalReg;
 const { scanLinkages } = linkageMod;
+const { deriveProposedBridges } = proposedMod;
 
 const GRAPH = CATALOG_GRAPH;
 
+// `--source=catalog|canonical|both` selects which graph the analysis commands
+// (`discover` / `candidates` / `map`) run over. `catalog` (default) is the
+// 44-bridge catalog; `canonical` is the standard-physics L-layer ALONE, with
+// the speculative bridges excluded; `both` is the bridges plus the canonical
+// established-physics backbone.
+function resolveGraph(args) {
+  const flag = (args || []).find((a) => a.startsWith('--source='));
+  const src = flag ? flag.slice('--source='.length) : 'catalog';
+  switch (src) {
+    case 'catalog':
+      return { graph: CATALOG_GRAPH, label: 'catalog (44-bridge)' };
+    case 'canonical':
+      return { graph: CANONICAL_GRAPH, label: 'canonical (standard-physics L-layer, bridges excluded)' };
+    case 'both':
+      return { graph: [...CATALOG_GRAPH, ...CANONICAL_GRAPH], label: 'catalog + canonical' };
+    default:
+      console.error(`upt: unknown --source='${src}' (expected: catalog | canonical | both)`);
+      process.exit(1);
+  }
+}
+
 // ── help ────────────────────────────────────────────────────────────────
 function help() {
   console.log(`upt — Universal Physics Tensor bridge-inference CLI
@@ -72,12 +95,12 @@ Usage:
         re-derive as a recognized monomial (with the prefactor recovered),
         which are decoys, which are dimensionally open.
 
-  upt map
+  upt map [--source=catalog|canonical|both]
         Map how the equations LINK: connected components (clusters) of the
-        catalog graph by shared quantities, the anchored core, the link
-        hubs, and the isolated tail.
+        graph by shared quantities, the anchored core, the link hubs, and
+        the isolated tail.
 
-  upt candidates
+  upt candidates [--source=catalog|canonical|both]
         Propose candidate cross-cluster links (quantities of the same
         dimension in different clusters) for PHYSICIST REVIEW — a
         coincidence-heavy surface, not discovered bridges.
@@ -88,11 +111,22 @@ Usage:
         (triadic closure). Makes the namesake tensor operational. Review
         surface, not discovered bridges.
 
-  upt discover
+  upt discover [--source=catalog|canonical|both]
         VET the link candidates through the inference suite: hypothesise
         each identification a≡b and test whether it merges disconnected
         physics, unlocks quantities, and stays numerically consistent.
         Ranks promising / inert / contradictory.
+        --source=canonical runs the funnel on the standard-physics L-layer
+        ALONE (bridges excluded) — new candidates from established physics,
+        and a self-consistency check (expect 0 contradictory).
+        --derive emits, for each 'promising' identification, the ONE algebraic
+        relation it implies (monomial elimination) as an UNADJUDICATED, math-only
+        proposal — NOT a bridge (Part-VI §XXVII-B). Pairs with --source=canonical.
+        --max-orders=N tunes the magnitude-clash threshold (default 3); looser N
+        keeps more candidates 'promising', tighter N falsifies more as clashes.
+        --anchor=k=v[,k2=v2] overrides the numeric anchor (default mass=M_sun)
+        for the consistency/closure check. Both reshape the candidate pool that
+        --derive consumes.
 
   upt connectors
         Of the 20 ISOLATED bridges, which could connect to the anchored
@@ -327,11 +361,12 @@ async function derive(args) {
 }
 
 // ── map (how the equations link) ──────────────────────────────────────────
-function mapCmd() {
-  const m = linkageMap(GRAPH);
+function mapCmd(args) {
+  const { graph, label } = resolveGraph(args);
+  const m = linkageMap(graph);
   const mix = (s) => Object.entries(s).map(([k, v]) => `${v} ${k}`).join(', ');
-  console.log('\nCatalog linkage map — how the equations connect via shared quantities');
-  console.log(`(${m.componentCount} components over ${GRAPH.length} edges; ${m.compositions} compose into chains)\n`);
+  console.log(`\nLinkage map — how the equations connect via shared quantities  [source: ${label}]`);
+  console.log(`(${m.componentCount} components over ${graph.length} edges; ${m.compositions} compose into chains)\n`);
   for (const c of m.clusters.filter((x) => x.size > 1)) {
     console.log(`  ● cluster of ${c.size}${c.anchored ? '  [ANCHORED to known physics]' : ''}`);
     console.log(`     edges:  ${c.edges.join(', ')}`);
@@ -344,11 +379,12 @@ function mapCmd() {
 }
 
 // ── candidates (map-proposed links for review) ────────────────────────────
-function candidatesCmd() {
-  const cands = proposeLinkCandidates(GRAPH);
+function candidatesCmd(args) {
+  const { graph, label } = resolveGraph(args);
+  const cands = proposeLinkCandidates(graph);
   const core = cands.filter((c) => c.touchesCore);
   const ck = cands.filter((c) => c.touchesCore && c.sameKind);
-  console.log('\nLink candidates — cross-cluster quantities sharing a dimension');
+  console.log(`\nLink candidates — cross-cluster quantities sharing a dimension  [source: ${label}]`);
   console.log('⚠ a coincidence-heavy REVIEW SURFACE, NOT discovered bridges. Same dimension is a');
   console.log('  weak signal; each needs a physicist to accept or (far more often) reject.\n');
   console.log(`  funnel:  ${cands.length} total  →  ${core.length} touch the anchored core  →  ${ck.length} also same-kind\n`);
@@ -387,12 +423,45 @@ function predictCmd() {
 }
 
 // ── discover (vet link candidates through the inference suite) ─────────────
-function discoverCmd() {
-  const ranked = rankDiscoveries(GRAPH);
+// Parse the discovery knobs (DiscoveryOptions) from CLI flags:
+//   --max-orders=N        magnitude-clash threshold (default 3)
+//   --anchor=k=v[,k2=v2]  numeric anchor for the consistency/closure check
+//                         (default mass=M_sun); repeatable
+function parseDiscoveryOpts(args) {
+  const a = args || [];
+  const opts = {};
+  const mo = a.find((x) => x.startsWith('--max-orders='));
+  if (mo) {
+    const n = Number(mo.slice('--max-orders='.length));
+    if (Number.isFinite(n)) opts.maxOrdersOfMagnitude = n;
+  }
+  const gt = {};
+  for (const x of a.filter((x) => x.startsWith('--anchor='))) {
+    for (const pair of x.slice('--anchor='.length).split(',')) {
+      const [k, v] = pair.split('=');
+      const val = Number(v);
+      if (k && Number.isFinite(val)) gt[k] = val;
+    }
+  }
+  if (Object.keys(gt).length) opts.groundTruth = gt;
+  return opts;
+}
+
+function discoverCmd(args) {
+  const { graph, label } = resolveGraph(args);
+  const opts = parseDiscoveryOpts(args);
+  const ranked = rankDiscoveries(graph, opts);
+  if (Object.keys(opts).length) {
+    const bits = [];
+    if (opts.maxOrdersOfMagnitude !== undefined) bits.push(`max-orders=${opts.maxOrdersOfMagnitude}`);
+    if (opts.groundTruth) bits.push(`anchor={${Object.entries(opts.groundTruth).map(([k, v]) => `${k}=${v}`).join(', ')}}`);
+    console.log(`  [discovery options: ${bits.join('; ')}]`);
+  }
+  if ((args || []).includes('--derive')) return deriveCmd(ranked, label);
   const by = (v) => ranked.filter((r) => r.verdict === v);
   const promising = by('promising'), inert = by('inert'), contra = by('contradictory');
   const clash = by('magnitude-clash');
-  console.log('\nDiscovery — link candidates VETTED through the inference suite');
+  console.log(`\nDiscovery — link candidates VETTED through the inference suite  [source: ${label}]`);
   console.log('⚠ a REVIEW SURFACE: `promising` means "worth a physicist\'s minute", not "true".');
   console.log('  Each candidate hypothesises an identification a≡b and tests its consequences.\n');
   console.log(`  funnel:  ${ranked.length} candidates  →  ${promising.length} promising  ` +
@@ -410,7 +479,15 @@ function discoverCmd() {
   if (clash.length) {
     console.log(`\n  MAGNITUDE-CLASH (representative values differ by > N orders — a falsifier):`);
     for (const r of clash) {
-      console.log(`    ${(r.a + ' ≟ ' + r.b).padEnd(52)} ~${r.ordersApart.toFixed(1)} orders apart`);
+      const basis = r.magnitudeUsedAnchor ? '  (anchor-derived)' : '';
+      console.log(`    ${(r.a + ' ≟ ' + r.b).padEnd(52)} ~${r.ordersApart.toFixed(1)} orders apart${basis}`);
+    }
+  }
+  const subsumed = inert.filter((r) => r.subsuming);
+  if (subsumed.length) {
+    console.log(`\n  SUBSUMING (generic ≟ specialization — tautological, barred from promising):`);
+    for (const r of subsumed) {
+      console.log(`    ${(r.a + ' ≟ ' + r.b).padEnd(52)} [${r.dim}]`);
     }
   }
   if (contra.length) {
@@ -422,6 +499,35 @@ function discoverCmd() {
   console.log('\n  (magnitude gate abstains where a representative value is unknown; weak priors on dimension.)');
 }
 
+// ── discover --derive (identity-consequence proposals) ────────────────────
+function deriveCmd(ranked, label) {
+  const proposals = deriveProposedBridges(ranked);
+  console.log(`\nDerived identity-consequence PROPOSALS — UNADJUDICATED, math-only  [source: ${label}]`);
+  console.log('⚠ Each is the ALGEBRAIC CONSEQUENCE of an unadjudicated identification — NOT a new');
+  console.log('  relation and NOT a bridge. No mechanism asserted. Promotion to the catalog needs');
+  console.log('  adversarial + literature review (Part-VI §XXVII-B). The enumerator proposes; humans dispose.\n');
+  if (!proposals.length) {
+    console.log('  no admissible proposal (need two fully-quantitative, monomial canonical targets).');
+    return;
+  }
+  for (const p of proposals) {
+    let approx = '';
+    try {
+      const vals = Object.fromEntries((p.governing || []).map((g) => [g.name, 300]));
+      const at = (p.governing || []).map((g) => `${g.name}=300`).join(', ');
+      approx = `  ≈ ${p.evaluate(vals).toExponential(2)}${at ? ` (${at})` : ''}`;
+    } catch { approx = ''; }
+    console.log(`  ${p.id}`);
+    console.log(`      ${p.formulaLatex}      ${p.dimensionalSignature}${approx}`);
+    console.log(`      from: ${p.derivedFrom.identification.a} ≟ ${p.derivedFrom.identification.b}` +
+      `  (${p.derivedFrom.sourceEquationIds[0]} = ${p.derivedFrom.sourceEquationIds[1]}); solved for ${p.derivedFrom.solvedFor}`);
+    if (p.alsoDerivableFrom && p.alsoDerivableFrom.length) {
+      console.log(`      also derivable from: ${p.alsoDerivableFrom.join('; ')}`);
+    }
+  }
+  console.log('');
+}
+
 // ── coverage (empirical-spine audit) ──────────────────────────────────────
 function coverageCmd() {
   const r = auditCoverage();
@@ -556,10 +662,10 @@ switch (cmd) {
   case 'explain': explain(rest[0], rest.slice(1)); break;
   case 'priority': case 'prioritize': case 'triage': priority(); break;
   case 'audit': audit(); break;
-  case 'map': case 'linkage': mapCmd(); break;
-  case 'candidates': case 'propose': candidatesCmd(); break;
+  case 'map': case 'linkage': mapCmd(rest); break;
+  case 'candidates': case 'propose': candidatesCmd(rest); break;
   case 'predict': case 'predictions': predictCmd(); break;
-  case 'discover': case 'discovery': discoverCmd(); break;
+  case 'discover': case 'discovery': discoverCmd(rest); break;
   case 'connectors': case 'orphans': connectorsCmd(); break;
   case 'coverage': case 'grounding': coverageCmd(); break;
   case 'canonical': case 'laws': canonicalCmd(); break;

package/dist/bridges/equations/_be-helpers.d.ts

@@ -26,71 +26,7 @@
  */
 import type { ExprNode, DimensionValidationReport } from '../../dimensional/validator.js';
 import type { Dimension } from '../../dimensional/types.js';
-/**
- * Declarative spec for a single field of an evaluator's `input` record.
- *
- * The default behaviour (no `min`/`max`) only verifies finiteness
- * (`Number.isFinite`). The bound predicates compose with `Number.isFinite`
- * so the resulting error always reads "finite ⟨adj⟩ number" — drop-in
- * compatible with the existing BE-NN per-evaluator message format
- * `"<evaluator>: <field> must be a finite <adjective> number, got <v>"`.
- *
- * The intentional simplicity: no closed-form domain constraints (e.g.,
- * `R_near ≤ R_far`). Anything beyond per-field range checks stays inline
- * in the evaluator (honesty policy — see commit message).
- *
- * @internal
- */
-interface FieldSpec {
-    /** Field name on the `input` record (e.g., `'M_kg'`). */
-    readonly name: string;
-    /** Inclusive lower bound (default `-Infinity`). */
-    readonly min?: number;
-    /** Inclusive upper bound (default `Infinity`). */
-    readonly max?: number;
-    /** Strict `>` instead of `≥` at the lower bound. */
-    readonly excludeMin?: boolean;
-    /** Strict `<` instead of `≤` at the upper bound. */
-    readonly excludeMax?: boolean;
-    /** Explicit override — when `min === 0` and you want to permit zero. */
-    readonly allowZero?: boolean;
-    /**
-     * Optional domain-specific noun phrase (e.g., 'probability', 'angle').
-     * When set, replaces the auto-generated "in range [a, b]" prose:
-     *   "<evaluator>: <field> must be a finite <description> number, got <v>"
-     *
-     * v0.7.1 Phase 4 Task 4.4 — Eve E4 fix. Restores the pre-extraction
-     * BE-25-iit-phi "probability" domain noun without reverting the
-     * helper-based migration.
-     *
-     * @internal
-     */
-    readonly description?: string;
-}
-/**
- * Validate every field of `input` named by `fieldSpecs`. Throws a
- * `RangeError` on the first violation with a message that contains
- * the keywords (`"finite"`, plus `"positive"` / `"non-negative"` /
- * `"in range"`) the existing per-BE-NN tests pattern-match against.
- *
- * The error message format matches the pre-extraction convention:
- *
- *   `<evaluatorName>: <fieldName> must be a finite <range> number, got <value>`
- *
- * Sample existing prose this preserves:
- *
- *   `evaluateShapiroDelay: M_kg must be a finite positive number, got -1`
- *   `evaluateLandauerEnergy: temperature_K must be a finite non-negative number, got -1`
- *   `evaluateQuantumBounce: Lambda_Tinv2 must be finite, got NaN`
- *
- * @param input - The evaluator's input record.
- * @param fieldSpecs - The per-field range specs to enforce.
- * @param evaluatorName - The calling function's name (e.g.,
- *   `'evaluateShapiroDelay'`), used as the error-message prefix.
- *
- * @internal
- */
-export declare function validateFiniteInputs<T extends object>(input: T, fieldSpecs: ReadonlyArray<FieldSpec>, evaluatorName: string): void;
+export { validateFiniteInputs, type FieldSpec } from '../../numerical/input-validation.js';
 /**
  * Run `validateEquation(lhs, rhs)` + `validate(lhs)` + `validate(rhs)`
  * and pack the result into the canonical `DimensionValidationReport`
@@ -142,5 +78,4 @@ export declare function validateBEDimensions(lhs: ExprNode, rhs: ExprNode, _equa
  * @internal
  */
 export declare function sym(name: string, dim: Dimension): ExprNode;
-export {};
 //# sourceMappingURL=_be-helpers.d.ts.map

package/dist/bridges/equations/_be-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_be-helpers.d.ts","sourceRoot":"","sources":["../../../src/bridges/equations/_be-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE1F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAM5D;;;;;;;;;;;;;;GAcG;AACH,UAAU,SAAS;IACjB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAwCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EACnD,KAAK,EAAE,CAAC,EACR,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,EACpC,aAAa,EAAE,MAAM,GACpB,IAAI,CAgCN;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,QAAQ,EACb,GAAG,EAAE,QAAQ,EACb,cAAc,EAAE,MAAM,GACrB,yBAAyB,CAS3B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,QAAQ,CAE1D"}
+{"version":3,"file":"_be-helpers.d.ts","sourceRoot":"","sources":["../../../src/bridges/equations/_be-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE1F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAQ5D,OAAO,EAAE,oBAAoB,EAAE,KAAK,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAM3F;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,QAAQ,EACb,GAAG,EAAE,QAAQ,EACb,cAAc,EAAE,MAAM,GACrB,yBAAyB,CAS3B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,QAAQ,CAE1D"}

package/dist/bridges/equations/_be-helpers.js

@@ -25,89 +25,13 @@
  * @module bridges/equations/_be-helpers
  */
 import { validate, validateEquation } from '../../dimensional/validator.js';
-/**
- * Compose the adjective phrase that appears in the error message,
- * picked to match the existing per-BE-NN prose conventions:
- *
- *   - `min=0, excludeMin=true`  → "positive"        (i.e., `> 0`)
- *   - `min=0`                   → "non-negative"    (i.e., `≥ 0`)
- *   - bounded but not a 0-pin   → "in range [a, b]" (closed/open as set)
- *   - unbounded                 → ""                (just "finite")
- */
-function describeRange(spec) {
-    // Caller-supplied domain noun (e.g., 'probability') takes priority
-    // over the auto-generated range prose. Yields:
-    //   "<evaluator>: <field> must be a finite <description> number, got <v>"
-    // E.g., for BE-25 IIT p_cond / p_marg:
-    //   "evaluateIntrinsicInformation: p_cond must be a finite probability number, got -0.1"
-    if (spec.description !== undefined)
-        return `${spec.description} `;
-    const hasMin = spec.min !== undefined;
-    const hasMax = spec.max !== undefined;
-    const lowOpen = !!spec.excludeMin;
-    const highOpen = !!spec.excludeMax;
-    // The two ubiquitous zero-pinned shapes — keep these phrasings exactly
-    // as the existing 42 BE-NN evaluators emit them.
-    if (hasMin && !hasMax && spec.min === 0 && !spec.allowZero) {
-        if (lowOpen)
-            return 'positive '; // "finite positive number"
-        return 'non-negative '; // "finite non-negative number"
-    }
-    if (!hasMin && !hasMax)
-        return ''; // "finite number"
-    const lo = hasMin ? spec.min : -Infinity;
-    const hi = hasMax ? spec.max : Infinity;
-    const lb = lowOpen ? '(' : '[';
-    const rb = highOpen ? ')' : ']';
-    return `in range ${lb}${lo}, ${hi}${rb} `;
-}
-/**
- * Validate every field of `input` named by `fieldSpecs`. Throws a
- * `RangeError` on the first violation with a message that contains
- * the keywords (`"finite"`, plus `"positive"` / `"non-negative"` /
- * `"in range"`) the existing per-BE-NN tests pattern-match against.
- *
- * The error message format matches the pre-extraction convention:
- *
- *   `<evaluatorName>: <fieldName> must be a finite <range> number, got <value>`
- *
- * Sample existing prose this preserves:
- *
- *   `evaluateShapiroDelay: M_kg must be a finite positive number, got -1`
- *   `evaluateLandauerEnergy: temperature_K must be a finite non-negative number, got -1`
- *   `evaluateQuantumBounce: Lambda_Tinv2 must be finite, got NaN`
- *
- * @param input - The evaluator's input record.
- * @param fieldSpecs - The per-field range specs to enforce.
- * @param evaluatorName - The calling function's name (e.g.,
- *   `'evaluateShapiroDelay'`), used as the error-message prefix.
- *
- * @internal
- */
-export function validateFiniteInputs(input, fieldSpecs, evaluatorName) {
-    for (const spec of fieldSpecs) {
-        const raw = input[spec.name];
-        const value = raw;
-        if (typeof value !== 'number' || !Number.isFinite(value)) {
-            const range = describeRange(spec);
-            throw new RangeError(`${evaluatorName}: ${spec.name} must be a finite ${range}number, got ${String(value)}`);
-        }
-        if (spec.min !== undefined) {
-            const violatesMin = spec.excludeMin ? value <= spec.min : value < spec.min;
-            if (violatesMin) {
-                const range = describeRange(spec);
-                throw new RangeError(`${evaluatorName}: ${spec.name} must be a finite ${range}number, got ${value}`);
-            }
-        }
-        if (spec.max !== undefined) {
-            const violatesMax = spec.excludeMax ? value >= spec.max : value > spec.max;
-            if (violatesMax) {
-                const range = describeRange(spec);
-                throw new RangeError(`${evaluatorName}: ${spec.name} must be a finite ${range}number, got ${value}`);
-            }
-        }
-    }
-}
+// ---------------------------------------------------------------------------
+// Helper 1 — Runtime input validation (S-1)
+// ---------------------------------------------------------------------------
+// `validateFiniteInputs` (+ `FieldSpec`) moved to the dependency-free leaf
+// `numerical/input-validation.ts` so the numerical layer no longer imports
+// upward from `bridges`. Re-exported here so every BE-NN evaluator is unchanged.
+export { validateFiniteInputs } from '../../numerical/input-validation.js';
 // ---------------------------------------------------------------------------
 // Helper 2 — Per-bridge dimensional self-check (S-2)
 // ---------------------------------------------------------------------------

package/dist/bridges/equations/_be-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"_be-helpers.js","sourceRoot":"","sources":["../../../src/bridges/equations/_be-helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"_be-helpers.js","sourceRoot":"","sources":["../../../src/bridges/equations/_be-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAG5E,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAC9E,2EAA2E;AAC3E,2EAA2E;AAC3E,iFAAiF;AACjF,OAAO,EAAE,oBAAoB,EAAkB,MAAM,qCAAqC,CAAC;AAE3F,8EAA8E;AAC9E,qDAAqD;AACrD,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAa,EACb,GAAa,EACb,cAAsB;IAEtB,MAAM,EAAE,GAAG,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC3B,OAAO;QACL,EAAE,EAAE,EAAE,CAAC,EAAE;QACT,MAAM,EAAE,IAAI,CAAC,iBAAiB;QAC9B,MAAM,EAAE,IAAI,CAAC,iBAAiB;KAC/B,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,uDAAuD;AACvD,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,GAAc;IAC9C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AACvC,CAAC"}

package/dist/canonical/entries/l1-gravity-thermo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"l1-gravity-thermo.d.ts","sourceRoot":"","sources":["../../../src/canonical/entries/l1-gravity-thermo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AA+DlE,eAAO,MAAM,iBAAiB,EAAE,SAAS,iBAAiB,EAkFzD,CAAC"}
+{"version":3,"file":"l1-gravity-thermo.d.ts","sourceRoot":"","sources":["../../../src/canonical/entries/l1-gravity-thermo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAyElE,eAAO,MAAM,iBAAiB,EAAE,SAAS,iBAAiB,EA8GzD,CAAC"}

package/dist/canonical/entries/l1-gravity-thermo.js

@@ -19,27 +19,36 @@ const BH_GOV = [
 const LANDAUER_TARGET = { name: 'erasure-energy', dim: ENERGY };
 const LANDAUER_GOV = [
     { name: 'k_B', dim: ENTROPY },
-    { name: 'T', dim: TEMPERATURE },
+    { name: 'temperature', dim: TEMPERATURE },
+];
+// ── Jarzynski equality  ΔF = −k_B T ln⟨exp(−W/k_B T)⟩  (the dimensionless ──
+// log of the work-ensemble average is the leading factor; dimensionally
+// ΔF = k_B·T, the same monomial as Landauer). The canonical L-layer partner
+// for BE-29 — see docs/research/BE-29-Landauer-Recovery.md.
+const JARZYNSKI_TARGET = { name: 'free-energy-difference', dim: ENERGY };
+const JARZYNSKI_GOV = [
+    { name: 'k_B', dim: ENTROPY },
+    { name: 'temperature', dim: TEMPERATURE },
 ];
 // ── Newton's law of gravitation  F = G m₁ m₂ / r²  (free mass-ratio group) ──
 const NEWTON_TARGET = { name: 'gravitational-force', dim: FORCE };
 const NEWTON_GOV = [
     { name: 'G', dim: GRAV },
-    { name: 'm_1', dim: MASS },
-    { name: 'm_2', dim: MASS },
+    { name: 'mass', dim: MASS },
+    { name: 'secondary-mass', dim: MASS },
     { name: 'r', dim: LENGTH },
 ];
 // ── Stefan–Boltzmann law  j = σ T⁴  (radiative FLUX) ────────────────────────
 const SB_TARGET = { name: 'radiative-flux', dim: SB_FLUX };
 const SB_GOV = [
     { name: 'sigma_sb', dim: SIGMA_SB },
-    { name: 'T', dim: TEMPERATURE },
+    { name: 'temperature', dim: TEMPERATURE },
 ];
 // ── Ideal gas law  P = N k_B T / V  (N is a dimensionless count) ────────────
 const GAS_TARGET = { name: 'pressure', dim: PRESSURE };
 const GAS_GOV = [
     { name: 'k_B', dim: ENTROPY },
-    { name: 'T', dim: TEMPERATURE },
+    { name: 'temperature', dim: TEMPERATURE },
     { name: 'V', dim: VOLUME },
 ];
 export const L1_GRAVITY_THERMO = [
@@ -81,6 +90,34 @@ export const L1_GRAVITY_THERMO = [
         partnerBridges: ['16'],
         restatesBridge: '16',
     }),
+    l1(JARZYNSKI_TARGET, JARZYNSKI_GOV, {
+        id: 'CE-jarzynski',
+        name: 'Jarzynski free-energy equality',
+        domain: 'statistical',
+        formula_latex: '\\Delta F = -k_B T \\ln \\langle \\exp(-W/(k_B T)) \\rangle',
+        // The leading dimensionless factor is the ensemble functional
+        // ln⟨exp(−βW)⟩, not a universal constant, so the strongest honest claim
+        // is the algebraic form up to that factor.
+        epistemicStatus: 'scalar-up-to-constant',
+        // Mirrors BE29_JARZYNSKI_RHS: −1 · k_B · T · ln⟨exp(−βW)⟩, the log encoded
+        // as a dimensionless stub (the AST has no ln primitive). Structurally this
+        // is the k_B·T·(dimensionless) thermodynamic form — the same one Landauer
+        // shares, which is exactly why BE-29 "recovers" CE-landauer.
+        scalarAst: op('*', [
+            sym('-1', DIMENSIONLESS),
+            sym('k_B', ENTROPY),
+            sym('T', TEMPERATURE),
+            sym('ln_avg_exp_minus_betaW', DIMENSIONLESS),
+        ]),
+        regime: { scale: 'mesoscopic' },
+        assumptions: ['isothermal', 'arbitrary work protocol between two equilibria'],
+        references: ['Jarzynski 1997 PRL 78:2690'],
+        // 29 = BE-29 (Jarzynski equality) — this canonical entry IS that bridge's
+        // own relation, so it is a declared restatement (NOT a discovery). Its
+        // structural match to CE-landauer stays a `recovers` form-coincidence.
+        partnerBridges: ['29'],
+        restatesBridge: '29',
+    }),
     l1(NEWTON_TARGET, NEWTON_GOV, {
         id: 'CE-newton-gravitation',
         name: "Newton's law of gravitation",