universal-physics-tensor 10.0.0 → 12.0.0

package/README.md

@@ -7,6 +7,7 @@
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
 <!-- readme-status:badge -->
 [![TypeScript](https://img.shields.io/badge/TypeScript-7.0+-blue)](https://www.typescriptlang.org/)
+[![Lean-proved bridges: 119 full · 22 weak · 19 pending](https://img.shields.io/badge/Lean--proved%20bridges-119%20full%20%C2%B7%2022%20weak%20%C2%B7%2019%20pending-blue)](https://github.com/danielsimonjr/universal-physics-tensor/tree/master/lean)
 <!-- /readme-status:badge -->
 
 ## Vision
@@ -87,7 +88,7 @@ npx upt search pendulum
 
 `upt explain hawking-temperature mass=1Msun` prints `Recovered value: 6.16842971641034e-8`, reached
 by the two routes of BE-42 (`be-42` and `be-42-via-rs`). `upt evaluate be-63 mu_e=2` prints
-`mass [kg] = 2.895722239784147e+30`, the Chandrasekhar mass of an ideal degenerate gas, about
+`mass [kg] = 2.895722231692708e+30`, the Chandrasekhar mass of an ideal degenerate gas, about
 1.456 solar masses at M_sun = 1.989e30 kg. `upt search pendulum` names `CE-pendulum-period`,
 `model-pendulum`, and `ab-pendulum-linear`, each with the command that opens its record. Every flag of every command is in [`docs/CLI.md`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/CLI.md).
 
@@ -127,7 +128,7 @@ by the two routes of BE-42 (`be-42` and `be-42-via-rs`). `upt evaluate be-63 mu_
 | `axes` (`axis-audit`) | Report which tensor classification axes gate the discovery funnel. |
 | `candidates` (`propose`) | Propose same-dimension links between clusters for physicist review. |
 | `connectors` (`orphans`) | Find same-dimension identifications that would pull an isolated bridge into the core. |
-| `discover` (`discovery`) | Vet quantity identifications and rank them promising, inert, or contradictory. |
+| `discover` (`discovery`) | Vet quantity identifications and rank them promising (two tiers: magnitude checked or unchecked), inert, or contradictory. |
 | `frontier` | Print null results and missing connections as two lists, neither of them a score. |
 | `ground` | Show which falsifiers ran on one discovery candidate, and which abstained. |
 | `predict` (`predictions`) | Rank empty regime cells as undiscovered-connection hypotheses. |
@@ -253,13 +254,13 @@ Bridge equations connect different physical regimes:
 - Universal Emergence Equation
 - Complexity-Entropy Production Relation
 
-Parts I–II of the formal specification write up the cross-domain bridges; a standard bridge is a catalog record and has no specification heading. The **authoritative current catalog** is the versioned, schema-checked JSON file [`data/bridge-catalog.json`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/data/bridge-catalog.json); its id range and counts are the generated Bridge catalog row of the Development Status table below. Part III covers algorithmic implementation.
+Parts I–II of the formal specification write up the cross-domain bridges; a standard bridge is a catalog record and has no specification heading. The **authoritative current catalog** is the versioned, schema-checked JSON file [`data/bridge-catalog.json`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/data/bridge-catalog.json). Its id range and counts are in the generated Bridge catalog row of the Development Status table below. Part III covers algorithmic implementation.
 
 ### Composing Bridges
 
-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:
+Bridges are edges in a typed quantity graph. Compatible edges
+**compose**. The junction gets an exact dimensional check, validity
+domains carry through, and confidence drops to the weakest link:
 
 ```typescript
 import { CATALOG_GRAPH, composeEdges, M_SUN_KG } from 'universal-physics-tensor';
@@ -272,7 +273,7 @@ erasureCost.evaluate({ mass: M_SUN_KG }); // ≈ 5.9e-31 J — E_min(M) = ℏc³
 erasureCost.confidence;                   // 'highly-speculative' (min of the operands)
 ```
 
-`GM_SUN_SI` is the IAU 2015 nominal solar gravitational parameter, `1.3271244e20` m³/s². It is not `G_SI * M_SUN_SI`. `parseUnit`, `convertValue`, and `UnitError` read a number with a unit:
+`GM_SUN_SI` is the IAU 2015 nominal solar gravitational parameter, `1.3271244e20` m³/s², and is not `G_SI * M_SUN_SI`. `parseUnit`, `convertValue`, and `UnitError` read a number with a unit:
 
 ```typescript
 import { GM_SUN_SI, convertValue } from 'universal-physics-tensor';
@@ -283,27 +284,26 @@ convertValue('25degC', 'K'); // { value: 298.15, given: 'degC', affine: 'celsius
 
 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
+literature-anchored result. The result was pre-registered before implementation and
 pinned to relErr ≤ 10⁻¹² (see [Part IX](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-IX-Composition.md)
 and `docs/planning/v0.8.0-Design.md`). A computable **membership
-criterion** (the catalog's `bridges` label tuple: two different regime labels; a
-rejected id is not a bridge) adjudicates the catalog — <!-- readme-status:membership -->152 bridges · 5 not-a-bridge · 3 unadjudicated (by the catalog's `bridges` label tuple, not the endpoint-regime criterion)<!-- /readme-status:membership --> —
-with rejections recorded in a reviewable negative catalog
-(`src/bridges/rejected.ts`).
-
-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
+criterion** adjudicates the catalog. The criterion is the catalog's `bridges` label tuple: two different regime labels, and a
+rejected id is not a bridge. The adjudicated catalog has <!-- readme-status:membership -->152 bridges · 5 not-a-bridge · 3 unadjudicated (by the catalog's `bridges` label tuple, not the endpoint-regime criterion)<!-- /readme-status:membership -->.
+A reviewable negative catalog (`src/bridges/rejected.ts`) records the rejections.
+
+Composition is also **symbolic** (`composeSymbolic`). A bridge may
+carry an optional `symbolic` `ExprNode` form. Composing two of them
+substitutes one AST into the other's junction. The result is dimensionally validated and
+numerically evaluable, not just a chained numeric closure. The composed form
 can be folded by MathTS `simplify`, so CT-1 reduces to
 `ℏc³ln2/(8πGM)` with `k_B` cancelled. See `upt symbolic --simplify`.
 
 ## Documentation
 
 ### Formal Specification
-Complete theoretical foundation of the Universal Physics Tensor Framework —
-see the **[specification index](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/README.md)** for the full
-reader's map and the **[spec revision history](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/CHANGELOG.md)**
+Complete theoretical foundation of the Universal Physics Tensor Framework.
+See the **[specification index](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/README.md)** for the full
+reader's map. See the **[spec revision history](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/CHANGELOG.md)**
 for how the documents evolved.
 
 - **[Part I: Foundation & Mathematical Framework](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-I.md)** - Theoretical foundation: the rank-6 catalog `Π`, framing commitment, consistency invariants, and the cross-domain bridges in categories A–E
@@ -312,7 +312,8 @@ for how the documents evolved.
 - **[Part IV: Validation & Implications](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-IV.md)** - Experimental pathways, philosophical implications, applications
 - **[Part V: Advanced Mathematics & Protocols](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-V.md)** - Category theory extensions, validation protocols, algorithmic analysis
 - **[Part VI: Deployment & Governance](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-VI.md)** - Implementation strategies, applications, governance frameworks
-- **Supplements** - [Part VII: Tensor Algebra](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-VII-Tensor-Algebra.md) · [Part VIII: Metric Layer](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-VIII-Metric-Layer.md) · [Part IX: Composition](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-IX-Composition.md) · [Part X: Curvature & Field Equations](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-X-Curvature-and-Field-Equations.md) · [Part XI: Proposed Equations](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-XI-Proposed-Equations.md) (non-normative; machine-derived identity consequences, unadjudicated)
+- **Supplements** - [Part VII: Tensor Algebra](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-VII-Tensor-Algebra.md) · [Part VIII: Metric Layer](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-VIII-Metric-Layer.md) · [Part IX: Composition](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-IX-Composition.md)
+- **More supplements** - [Part X: Curvature & Field Equations](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-X-Curvature-and-Field-Equations.md) · [Part XI: Proposed Equations](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-XI-Proposed-Equations.md) (non-normative; machine-derived identity consequences, unadjudicated)
 
 ### Planning & Development
 - **[ROADMAP.md](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/ROADMAP.md)** - Strategic direction: from bridge catalog to a verified, regime-aware physics atlas (phased, with exit criteria)
@@ -322,10 +323,11 @@ for how the documents evolved.
 
 ### Architecture
 
-Hand-written. Each document ends with a `## Verification` block that says what was re-measured
-for it and what was not. No checker runs over these documents in CI (the `repo_map.py` tool that
-once did is private and is not in this repository), so a claim in them is current only as far as
-its Verification block says.
+Hand-written. Each document ends with a `## Verification` block. The block lists the counts that
+`repo-tools check . --docs=docs/architecture` compares with the code. The pre-push hook runs that
+check when `repo-tools` is installed. The non-required `architecture-docs claims` CI job runs it on every pull request
+and every push to `master`. The generated files in the same
+directory come from `bun run docs:deps`, and the `docs-fresh` CI job checks them.
 
 - **[Overview](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/OVERVIEW.md)** - What this is, what it does, how it is laid out
 - **[Architecture](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/ARCHITECTURE.md)** - Why it is built this way; principles and key decisions
@@ -356,16 +358,17 @@ npm run bench:ci     # verbose run for CI log capture
 ```
 
 Baseline results are recorded in [`docs/architecture/benchmarks.md`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/benchmarks.md).
-These are **correctness-first baselines, not optimization targets**. Comparative
+The baselines are **correctness-first, not optimization targets**. Comparative
 analysis has since landed: v0.6.0's BR-2 `christoffelFn` flat-array refactor
 delivered a measured **5-6× RK4 geodesic-integrator speedup** (see [CHANGELOG](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/CHANGELOG.md)).
 
 ## Development Status
 
 The current version is recorded in `package.json` and on npm; release chronology
-lives in the [CHANGELOG](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/CHANGELOG.md). This README deliberately carries **no
-version number and no release-by-release counts** — both drift, and nothing gates
-this file. It said `v0.44.1` while the package was at `0.44.3`.
+lives in the [CHANGELOG](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/CHANGELOG.md). This README carries **no
+version number and no release-by-release counts**, because both drift. The marked
+status spans hold generated text. `bun scripts/readme-status.ts --check` verifies
+them in CI and in the pre-push hook.
 
 The current machine-checked state is:
 
@@ -376,13 +379,13 @@ The current machine-checked state is:
 | Empirical spine | **19 committed confrontations**, exposed through `upt confront` with rigor/caveat metadata |
 | Composition layer | **158 bridge edges** plus the canonical L-layer graph; dimensional, symbolic, discovery, consequence, and visualization tooling |
 | Canonical reference layer | **109 canonical equations** used as the non-speculative answer-key layer for bridge recovery/linkage |
-| Architecture | Generated dependency graph reports **0 circular dependencies**. The unused-analysis report lists **0** files and **66** exports with no importer. Both reports are regenerated by `bun run docs:deps`, and the `docs-fresh` job fails when they are stale |
+| Architecture | Generated dependency graph reports **0 circular dependencies**. The unused-analysis report lists **0** files and **21** exports with no importer. Both reports are regenerated by `bun run docs:deps`, and the `docs-fresh` job fails when they are stale |
 | Quality gates | Build, strict source+test TypeScript checks, full Vitest suite, active-plan audit, package-content smoke test, and nightly long-horizon GL4/Shapiro accuracy tests |
-| Formal references | **10** atlas bridges derive `formally-proved` from a reviewed `lean4-physjs` reference. **16** catalog equations carry a counted reference and do not light that tag. **119** state the catalogued equation, kind `bridge`; the catalog path passes that reference, so catalog evidence and edge evidence include `formally-proved`, except an unadjudicated row, which stays `proposed`. **3** carry a cross-check and **3** carry a property. Each kind is the PhysJS manifest entry's own field. Nested statements are not second references. The pin and the split are [`NOTES.md`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/NOTES.md) |
+| Formal references | **10** atlas bridges derive `formally-proved` from a reviewed `lean4-physjs` reference. **16** catalog equations carry a counted reference and do not light that tag. **119** state the catalogued equation, kind `bridge`; the catalog path passes that reference, so catalog evidence and edge evidence include `formally-proved`, except an unadjudicated row, which stays `proposed`. **3** carry a cross-check and **3** carry a property. Each kind is the Lean manifest entry's own field (`formal/lean/manifest.json`; the theorems are this repository's `lean/`). Nested statements are not second references. The split is in [`NOTES.md`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/NOTES.md) |
 <!-- /readme-status:table -->
 
-The project is **engineering-complete for its stated goal**: it is a computational
-laboratory and falsification/review instrument, not a claim that physics itself is
+The project is **engineering-complete for its stated goal**. The project is a computational
+laboratory and falsification/review instrument. The project does not claim that physics itself is
 complete or unified. New physics claims remain reviewable hypotheses and require
 external evidence/domain review before promotion.
 
@@ -398,10 +401,10 @@ external evidence/domain review before promotion.
 
 ## Contributing
 
-See **[CONTRIBUTING.md](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/CONTRIBUTING.md)** — it lists bounded,
+See **[CONTRIBUTING.md](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/CONTRIBUTING.md)**. The file 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.
+the dev quick-start. The file also explains the JSON catalog review surface.
 
 Contributions are welcome, especially from:
 - **Physicists** - Validate equations, suggest corrections, add physics insights
@@ -425,7 +428,7 @@ The same systems thinking applies to physics:
 - Emergence = higher-order system behaviors (correlations)
 - Validation = experimental data matching (consistency checks)
 
-This is an **engineer's approach to theoretical physics** — systematic, organized, and open to collaboration with domain experts.
+The project is an **engineer's approach to theoretical physics** — systematic, organized, and open to collaboration with domain experts.
 
 ## License
 

package/bin/upt.mjs

@@ -5,6 +5,11 @@
  * returned code onto process.exitCode (NOT process.exit — a hard exit can
  * truncate piped stdout). The one exception is a reader that closed the pipe
  * (`upt map | head -1`): nothing more can be delivered, so the run ends quietly.
+ *
+ * A defect (an error that is neither UsageError nor CliError, which `runCli`
+ * rethrows) goes to `reportInternalError` (dist/cli/main.js): `upt: internal
+ * error: <message>` with exit 70 (EX_SOFTWARE), not Node's stack and an
+ * unhandled rejection.
  */
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -25,4 +30,11 @@ try {
   console.error(String(err && err.message ? err.message : err));
   process.exit(1);
 }
-process.exitCode = await main.runCli(process.argv.slice(2));
+try {
+  process.exitCode = await main.runCli(process.argv.slice(2));
+} catch (err) {
+  // Last resort: a defect, since every usage error and value refusal was mapped to an exit
+  // code inside runCli. reportInternalError prints the message, not the stack, and returns
+  // EX_SOFTWARE (70); it is unit-tested in tests/cli/internal-error-exit.test.ts.
+  process.exitCode = main.reportInternalError(err);
+}