universal-physics-tensor 0.7.2 → 0.14.0

package/README.md

@@ -3,8 +3,9 @@
 **Computational framework for exploring unified physics through tensor formalism**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/danielsimonjr/universal-physics-tensor/actions/workflows/ci.yml/badge.svg)](https://github.com/danielsimonjr/universal-physics-tensor/actions/workflows/ci.yml)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0+-blue)](https://www.typescriptlang.org/)
 
 ## Vision
 
@@ -52,8 +53,32 @@ npm run build
 
 # Run the smoke test
 node test-example.js
+
+# Bridge-inference CLI (no TypeScript needed) — `upt` subcommands:
+npm run upt -- explain hawking-temperature mass=1.989e30   # explain a built-in quantity
+npm run upt -- priority                                    # triage speculative bridges
+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 -- connectors                                  # which isolated bridges can connect to the core
+npm run upt -- coverage                                    # audit each bridge's empirical grounding
+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
+npm run upt -- derive period:time length:length gravity:acceleration --formula "2*pi*sqrt(length/gravity)"
+#   → period ∝ length^0.5·gravity^-0.5 ; formula dimension: [time] ✓ matches target ;
+#     formula MATCHES, recovered prefactor ≈ 6.2832 (2π)
+npm run upt -- help
+# Once published, the same commands run via `npx universal-physics-tensor <cmd>`.
+# (`npm run explain` and `npm run bridge-priority` remain as aliases.)
 ```
 
+`eval`/`derive --formula` use the MathTS expression engine
+(`@danielsimonjr/mathts-functions`) when the optional peers are installed,
+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.
+
 ## Installation
 
 ```bash
@@ -98,7 +123,12 @@ const quantumLaws = tensor.queryLaws({ scale: 'quantum' });
 console.log(quantumLaws.map(l => l.name));
 ```
 
-> **Note:** This example uses only the APIs currently implemented. Computable bridge equation solvers (e.g., a `BridgeEquations` class with `decoherence(...)` methods) are specified in Parts I–III but not yet implemented — see [Development Status](#development-status).
+> **Note:** Each catalogued bridge ships a computable `evaluate*()` function, and
+> the `BridgeEquations` facade (v0.14) gathers them under readable method names —
+> e.g. `BridgeEquations.decoherenceRate({ gamma0_per_s, lambda, lambda0 })` (BE-11)
+> or `BridgeEquations.hawkingTemperature({ M_kg })` (BE-42). The formal spec
+> (Parts I–III) defines the underlying physics and AST encodings; the facade is
+> the convenience layer over those evaluators.
 
 ## Core Concepts
 
@@ -131,19 +161,55 @@ Bridge equations connect different physical regimes:
 - Universal Emergence Equation
 - Complexity-Entropy Production Relation
 
-See [Part I](docs/specification/Part-I.md) and [Part II](docs/specification/Part-II.md) of the formal specification for the complete bridge equation catalog (Bridge Equations 11–52). Part III covers algorithmic implementation.
+See [Part I](docs/specification/Part-I.md) and [Part II](docs/specification/Part-II.md) of the formal specification for the complete bridge equation catalog (Bridge Equations 11–54). Part III covers algorithmic implementation. The catalog is also published as a reviewable JSON artifact at [`data/bridge-catalog.json`](data/bridge-catalog.json).
+
+### Composing Bridges (v0.8.0)
+
+Bridges are edges in a typed quantity graph, and compatible edges
+**compose** — with an exact dimensional check at the junction, validity
+domains carried through, and confidence demoted to the weakest link:
+
+```typescript
+import { composeEdges, be42Edge, be16Edge, M_SUN_KG } from 'universal-physics-tensor';
+
+// Hawking temperature (M → T_H) ∘ Landauer bound (T → E_min)
+const erasureCost = composeEdges(be42Edge, be16Edge);
+erasureCost.evaluate({ mass: M_SUN_KG }); // ≈ 5.9e-31 J — E_min(M) = ℏc³ln2/(8πGM)
+erasureCost.confidence;                   // 'highly-speculative' (min of the operands)
+```
+
+That derived relation — the minimum erasure cost at a black-hole
+horizon — is the framework's first **derived** (rather than encoded)
+literature-anchored result, pre-registered before implementation and
+pinned to relErr ≤ 10⁻¹² (see [Part IX](docs/specification/Part-IX-Composition.md)
+and `docs/planning/v0.8.0-Design.md`). A computable **membership
+criterion** (a bridge's endpoint quantities must differ in regime) now
+adjudicates the catalog — 36 bridges · 5 not-a-bridge · 3 contested —
+with rejections recorded in a reviewable negative catalog
+(`src/bridges/rejected.ts`).
+
+Since v0.12, composition is also **symbolic** (`composeSymbolic`): bridges may
+carry an optional `symbolic` `ExprNode` form, and composing two of them
+substitutes one AST into the other's junction, dimensionally validated and
+numerically evaluable — not just a chained numeric closure. The composed form
+can be folded by MathTS `simplify` (optional peer), so CT-1 reduces to
+`ℏc³ln2/(8πGM)` with `k_B` cancelled. See `upt symbolic --simplify`.
 
 ## Documentation
 
-### Formal Specification (6-Part Series)
-Complete theoretical foundation of the Universal Physics Tensor Framework:
+### Formal Specification
+Complete theoretical foundation of the Universal Physics Tensor Framework —
+see the **[specification index](docs/specification/README.md)** for the full
+reader's map and the **[spec revision history](docs/specification/CHANGELOG.md)**
+for how the documents evolved.
 
 - **[Part I: Foundation & Mathematical Framework](docs/specification/Part-I.md)** - Tensor structure, Π = L + B + E decomposition, Bridge Equations 11-20
-- **[Part II: Extended Bridge Equation Catalog](docs/specification/Part-II.md)** - Bridge Equations 21-52 across condensed matter, quantum biology, emergent spacetime
+- **[Part II: Extended Bridge Equation Catalog](docs/specification/Part-II.md)** - Bridge Equations 21-54 across condensed matter, quantum biology, emergent spacetime
 - **[Part III: Computational Implementation](docs/specification/Part-III.md)** - Algorithms, information-theoretic bounds, ML integration
 - **[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)
 
 ### Planning & Development
 - **[Development Plan](docs/planning/Development-Plan.md)** - Phased implementation roadmap
@@ -170,118 +236,90 @@ delivered a measured **5-6× RK4 geodesic-integrator speedup** (see [CHANGELOG](
 
 ## Development Status
 
-**Current Version:** v0.6.0 (released 2026-05-20). Einstein field equation
-closure + curvature classification + Shapiro investigation. See
-[CHANGELOG](CHANGELOG.md) for full details.
-
-### v0.6.0 — Einstein field equation closure + curvature classification (2026-05-20)
+**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.
 
 | Metric | Value |
 |---|---|
-| Bridge catalog | **42 / 42** (IDs 11-52, unchanged from v0.4.0) |
-| Test suite | **1693** passing (179 files, 1 skip + 1 todo) |
-| `tsc --noEmit` | clean |
-| Breaking changes | `christoffelFn` / `schwarzschildChristoffelFn` now return `Float64Array(64)` (λ-major) instead of nested `number[4][4][4]`; `pderivNumericalFn` default `order` flipped `2 → 4` |
-
-36 tasks across 4 phases:
-
-- **Killing-vector machinery** — `KillingVectorNode` + `ConservedChargeNode`
-  AST kinds; `verifyKillingEquation` and `evaluateConservedCharge` — the first
-  structural encoding of a continuous symmetry and its Noether charge.
-- **Einstein field equation closure** — `StressEnergyTensorNode`,
-  `CosmologicalConstantNode`, `EinsteinFieldEquationNode`, plus
-  `validateEinsteinFieldEquation` / `evaluateEinsteinEquationResidual`. Closes
-  the gap BE-17's docstring had documented as impossible: matter-coupled
-  `G_μν = κ T_μν` is now structurally encodable alongside the vacuum case.
-- **Curvature classification** — `WeylTensorNode`, `KretschmannScalarNode`,
-  `computeKretschmann`, and the `CurvatureCompositeNode<K,S>` factory extracted
-  from the now-five-instance curvature pattern (`CURVATURE_KIND_REGISTRY`
-  provides introspection across curvature node kinds).
-- **Release-prep** — BR-2 `christoffelFn` flat-array refactor (BREAKING; **5-6×
-  RK4 speedup**), `pderivNumericalFn` 4th-order default, and the PC-1.5 Shapiro
-  residual-floor investigation (`docs/architecture/pc-1.5-shapiro-residual-floor.md`).
-
-**Honest framing:** Per Decision #9, no bridge status pins were promoted from
-`speculative` → `established` — structural encoding is necessary but not
-sufficient; observational grounding must be established independently.
-
-### Release history
-
-Earlier milestones (full detail in [CHANGELOG](CHANGELOG.md)):
-
-- **v0.5.1** (2026-05-19) — stability/hygiene patch; constants canonicalization,
-  diagnostic-warning propagation through the curvature pipeline.
-- **v0.5.0** (2026-05-18) — GR foundations: GL4 symplectic integrator, bisection
-  perihelion finder, `RiemannTensorNode`, `ricci`/`einstein`/`bianchiResidual`
-  helpers, BE-52 Mercury and BE-37 Shapiro activations.
-- **v0.4.5/v0.4.6** (2026-05-17/18) — refactor + benchmark scaffold;
-  `bench/` infrastructure with correctness-first baselines.
-- **v0.4.0** (2026-05-15) — connection layer (Christoffel),
-  automatic differentiation (`Float64ReferenceEngine` + `MathTSEngine`),
-  bridges BE-51/BE-52 added (catalog 40 → 42).
-- **v0.3.5** (2026-05-14) — numerical-contraction backend: `TensorEngine`
-  interface, AST→engine lowering, BE-37 Shapiro-delay eikonal end-to-end.
-
-### ✅ Milestone — catalog closed at 40/40 (v0.1.0, 2026-05-12)
-
-> Historical snapshot of the v0.1.0 catalog-closure event. Counts below are
-> v0.1.0-era figures, not current state — see the v0.6.0 table above for
-> current numbers (42 bridges, 1693 tests).
-
-First tagged release; the Tier-5 AST encoding rollout reached **full coverage**
-with the Wave Z arc (commits `9cb299f` through `b358257`). Every bridge in
-`src/bridges/index.ts` had a non-null `dimensional_signature`, an AST module in
-`src/bridges/equations/`, a numerical evaluator with input-validation guards,
-and per-bridge encoding tests. SemVer applies from this release onward.
-
-| Metric (v0.1.0) | Value |
-|---|---|
-| AST encodings | **40 / 40** |
-| `dimensional_signature === null` count | 0 |
-| `status === 'invalid'` count | 0 |
-| Test suite | **1161 / 1161** passing across 68 files |
-| Status distribution | 6 established · 31 speculative · 3 highly-speculative · 0 invalid |
-
-**Encoding patterns established during the rollout:** typed-stubs for
-transcendentals and operator-valued interiors (log/exp/tensor
-contractions absorbed into single dimensioned symbols);
-squared-form to avoid fractional exponents (S², L²=Γt, Q_soft²);
-ensemble-average stubs (Jarzynski ⟨exp(-βW)⟩); observational-bound
-dimensionless ratios (GW170817 |c_GW-c|/c); integral primitive for
-boundary integrals (BE-26 WKB, BE-44 soft-hair L²-norm); and **bridge
-reformulation** — replacing broken or contested formulations with
-canonical literature forms while preserving the bridge label
-(precedent: BE-25 Penrose-Hameroff → IIT Φ_max; Wave Z applied this
-to BE-16 → Landauer, BE-37 → Shapiro delay, BE-28 → Onsager σ).
-
-**Cross-LLM validation:** the three highest-stakes Wave-Z reformulations
-(BE-16 Landauer, BE-37 Shapiro, BE-28 Onsager — all promoted from
-`status='invalid'`) were independently cross-validated by both OpenAI
-o3 and Gemini Pro.
-
-### Planned (post-closure)
-
-- **v0.1.0 release** — trigger condition met; cut is a discretionary
-  release decision documented in `v0.1.0-Release-Procedure.md`.
-- **Grammar extensions for genuinely-deferred primitives:** Dirac-δ
-  correlators (would enable a fuller BE-15 Hohenberg-Halperin Model A
-  Langevin encoding), variational-δ operator (would enable a faithful
-  MEPP encoding for BE-28 that captures the maximization claim).
-  Neither is currently planned — both are scope expansions beyond the
-  scalar-AST design.
-- **Wider rank-6 tensor with numerical operations** — the
-  catalog-encoding work has been the priority; tensor operators are the
-  next conceptual layer.
+| 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 |
+| `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) |
+
+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
+spec's own revision ledger is at
+[docs/specification/CHANGELOG.md](docs/specification/CHANGELOG.md).
+
+### Roadmap
+
+- **Units-normalization (G-9)** — increment 1 (the geometrized-units boundary
+  adapters, dimension-functor-driven) shipped in v0.13; **increment 2 (v0.14)**
+  promoted the adapters (`toGeometrized`/`fromGeometrized`/`geometrizedFactor`/
+  `NonGeometrizableDimensionError`) to the public API, added a geometrized-native
+  Schwarzschild fixture (x⁰=ct chart) + an SI↔geometrized Kretschmann equivalence
+  test (the adapter exercised on the mass input, `M_geom = GM/c²`); the FD
+  order-2 claw-back was cut as a provable unit-invariant no-op. **Increment 3**
+  (deferred, own plan+vet): subsuming the `unitless*` fixture family + routing
+  the DEFAULT GR pipeline onto the geometrized fast path.
+- **Bridge-inference + symbolic-composition tooling** — **DONE (v0.12–v0.13)**:
+  the discovery loop, regime-prediction, coverage audit, orphan-connector
+  analysis, `composeSymbolic` (the Observable contract) + optional MathTS
+  simplification — all REVIEW SURFACES for physicist judgment, not automated
+  discovery.
+- **Grammar extensions for genuinely-deferred primitives** — **GRAMMAR DONE
+  (v0.14)**: the `dirac-delta` correlator (`[δ(x)]=[x]⁻¹`) and the
+  `variational-derivative` operator (`[δF/δφ]=[F]/([φ]·[μ])`) are now scalar
+  `ExprNode` arms (Adam+Eve-vetted;
+  `docs/planning/v0.14-Distributional-Grammar-Design.md`). The full Model-A
+  Langevin / fluctuation-dissipation relation BE-15 documented as un-encodable
+  now validates dimensionally homogeneous. The CATALOG re-encoding that USES the
+  new grammar — BE-15's faithful Langevin form, and a faithful BE-28 MEPP
+  variational maximization (BE-28's σ=ΣJX carries a CRITICAL WARNING that it is
+  the *definiendum*, not the maximization principle) — is a physics-curation
+  decision deferred to a physicist (CONTRIBUTING.md); barrier 3 (functional
+  integration over field configurations) remains out of scope. (A separate
+  bounded grammar extension — symbolic exponents on a dimensionless base —
+  landed in v0.13, letting BE-33 carry its faithful `(T/T₀)^(−1/z)` form.)
+- ~~Catalog → quantity-graph migration~~ — **DONE (v0.11, 2026-06-11)**:
+  the full 41-edge graph is live, gated by the name-collision
+  namespacing rule (`CompositionAliasError` + reviewable
+  `SOURCE_ALIAS_DISPOSITIONS`); the ~90 new quantity-naming judgments
+  are the standing physicist-review surface.
+- **More data confrontations** — GW170817 → BE-36 and the BE-23
+  Planckian-dissipation check (Legros et al. 2019, honest
+  aggregate-level encoding) have shipped; upgrading BE-23 to the
+  per-material α table is the next bounded step.
 - **Three.js / game-engine class visualization** in a separate repo
   (out of UPT scope per project decision; see
   `docs/planning/Future-Production-Hardening.md`).
-- **Experimental data validation pipelines** — applicable now that
-  catalog encoding is complete.
-- **Collaboration with physics researchers** — the open question is
-  recruiting them (see Contributing section).
+- **Collaboration with physics researchers** — eight bounded review tasks
+  are waiting in [CONTRIBUTING.md](CONTRIBUTING.md), including the three
+  contested membership adjudications (BE-44/46/50) and the CI-1/CI-2
+  dynamic-scaling call surfaced by the orphan-connector analysis.
 
 ## Contributing
 
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** — it lists bounded,
+no-code-required physics-review tasks (catalog adjudications, encoding
+checks against the literature, quantity-identification reviews) plus
+the dev quick-start, and explains the JSON catalog review surface.
+
 Contributions are welcome, especially from:
 - **Physicists** - Validate equations, suggest corrections, add physics insights
 - **Mathematicians** - Verify formalism, improve rigor, suggest optimizations