universal-physics-tensor 0.45.2 → 0.47.0

package/README.md

@@ -40,57 +40,75 @@ Think of this as:
 
 ## Quick Start
 
+From npm, the CLI is `upt`:
+
+```bash
+npm install universal-physics-tensor
+npx upt help
+npx upt explain hawking-temperature mass=1.989e30
+```
+
+The npm package ships `dist/`, `bin/`, this README and the licence. The documentation, the examples
+and the test fixtures linked below live in the GitHub repository. The steps below work from a clone
+of it:
+
 ```bash
 # Clone the repository
 git clone https://github.com/danielsimonjr/universal-physics-tensor.git
 cd universal-physics-tensor
 
-# Install dependencies
-npm install
+# Install dependencies (Bun is the local/CI package manager; Node ≥ 18 is the runtime)
+bun install
 
 # Build the project
-npm run build
+bun 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 -- discover --source=canonical                 # run the funnel on standard physics ALONE (no bridges)
-npm run upt -- discover --derive                           # surface machine-derived identity consequences (--max-orders / --anchor flags available)
-npm run upt -- probe scan                                  # experimental expression/residual frontier (Product B; not `upt discover`)
-npm run upt -- probe run --problem=tests/fixtures/discovery/pendulum-scaling/public/problem.json
-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)
-npm run upt -- confront                                    # run the catalog's committed real-data confrontations (predicted vs observed)
-npm run upt -- map --source=both --format=mermaid          # VISUAL map of the graph (Mermaid; also --format=dot|svg, --proposed, --out=PATH)
-npm run upt -- map --equation "period = 2*pi*sqrt(length/gravity)"   # drop YOUR OWN equation onto the map: dimensional check + where it lands
+bun run upt -- explain hawking-temperature mass=1.989e30   # explain a built-in quantity
+bun run upt -- priority                                    # triage speculative bridges
+bun run upt -- audit                                       # derive the bridges by dimensions
+bun run upt -- predict                                     # empty regime cells as link hypotheses
+bun run upt -- discover                                    # vet link candidates (merge/unlock/consistency)
+bun run upt -- discover --source=canonical                 # run the funnel on standard physics ALONE (no bridges)
+bun run upt -- discover --derive                           # surface machine-derived identity consequences (--max-orders / --anchor flags available)
+bun run upt -- probe scan                                  # experimental expression/residual frontier (Product B; not `upt discover`)
+bun run upt -- probe run --problem=tests/fixtures/discovery/pendulum-scaling/public/problem.json   # a fixture in the clone
+bun run upt -- connectors                                  # which isolated bridges can connect to the core
+bun run upt -- coverage                                    # audit each bridge's empirical grounding
+bun run upt -- canonical                                   # the standard-physics L-layer registry (answer key)
+bun run upt -- recover                                     # validate bridges against standard physics
+bun run upt -- symbolic --simplify                         # compose + fold bridges' SYMBOLIC forms (MathTS simplify)
+bun run upt -- confront                                    # run the catalog's committed real-data confrontations (predicted vs observed)
+bun run upt -- map --source=both --format=mermaid          # VISUAL map of the graph (Mermaid; also --format=dot|svg, --proposed, --out=PATH)
+bun run upt -- map --equation "period = 2*pi*sqrt(length/gravity)"   # drop YOUR OWN equation onto the map: dimensional check + where it lands
 # ...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)"
+bun 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
+bun 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.)
+bun run upt -- help
+# From an npm install, run the same commands as `npx upt <cmd>`.
+# (`bun run explain` and `bun 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.
-
-See [`cli/README.md`](cli/README.md) for the full CLI reference — every command
+**zero hard dependencies**; the MathTS packages and `@viz-js/viz` are optional peers, which a
+default install does not pull in. Add the ones you want, for example
+`npm install @danielsimonjr/mathts-functions` for the MathTS parser, or `npm install @viz-js/viz`
+for `upt map --format=svg`. The `universal-physics-tensor/numerical/mathts-engine` subpath imports
+`@danielsimonjr/mathts-tensor` directly, so importing it without that peer fails with
+`ERR_MODULE_NOT_FOUND`. That is the opt-in, not a bug: install the peer to use the engine. The main
+entry point never loads that subpath.
+
+See [`cli/README.md`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/cli/README.md) for the full CLI reference — every command
 and alias, the `--source=catalog|canonical|both` flag, input syntax, exit codes,
-and troubleshooting. [`docs/architecture/PHYSICS_MAP.md`](docs/architecture/PHYSICS_MAP.md)
+and troubleshooting. [`docs/architecture/PHYSICS_MAP.md`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/PHYSICS_MAP.md)
 shows the rendered map (`upt map --format=mermaid|dot|svg`).
 
 ## Installation
@@ -157,7 +175,7 @@ Where:
 - **B** (Bridges): Off-diagonal equations connecting regimes
 - **E** (Emergence): Higher-order correlations producing emergent phenomena
 
-> **Note on notation:** the "+" here denotes disjoint union of catalog entries (each tensor slot holds content of exactly one category), not algebraic addition. The type system enforces this disjointness via the `Cell` discriminated union in [`src/core/cell.ts`](src/core/cell.ts); `UniversalTensor.populatedCells()` is the canonical way to enumerate the populated catalog as typed `Cell` values. See also [Part I §1.2](docs/specification/Part-I.md) for the spec-level treatment. Different slots may hold quantities of different physical dimensions (e.g., a Lagrangian density and a decoherence rate) and cannot be summed numerically.
+> **Note on notation:** the "+" here denotes disjoint union of catalog entries (each tensor slot holds content of exactly one category), not algebraic addition. The type system enforces this disjointness via the `Cell` discriminated union in [`src/core/cell.ts`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/src/core/cell.ts); `UniversalTensor.populatedCells()` is the canonical way to enumerate the populated catalog as typed `Cell` values. See also [Part I §1.2](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-I.md) for the spec-level treatment. Different slots may hold quantities of different physical dimensions (e.g., a Lagrangian density and a decoherence rate) and cannot be summed numerically.
 
 ### Bridge Equations
 
@@ -175,7 +193,7 @@ Bridge equations connect different physical regimes:
 - Universal Emergence Equation
 - Complexity-Entropy Production Relation
 
-Parts I–II of the formal specification document the original BE-11…54 corpus; later established additions BE-55…65 are captured in the live code/research record. The **authoritative current catalog** is the versioned, test-pinned JSON artifact at [`data/bridge-catalog.json`](data/bridge-catalog.json), which currently spans BE-11…65. Part III covers algorithmic implementation.
+Parts I–II of the formal specification document the original BE-11…54 corpus; later established additions BE-55…65 are captured in the live code/research record. The **authoritative current catalog** is the versioned, test-pinned JSON artifact at [`data/bridge-catalog.json`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/data/bridge-catalog.json), which currently spans BE-11…65. Part III covers algorithmic implementation.
 
 ### Composing Bridges (v0.8.0)
 
@@ -195,7 +213,7 @@ erasureCost.confidence;                   // 'highly-speculative' (min of the op
 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)
+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** (a bridge's endpoint quantities must differ in regime) now
 adjudicates the catalog — 36 bridges · 5 not-a-bridge · 3 contested —
@@ -213,46 +231,47 @@ can be folded by MathTS `simplify` (optional peer), so CT-1 reduces to
 
 ### 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)**
+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)**
 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-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) · [Part XI: Proposed Equations](docs/specification/Part-XI-Proposed-Equations.md) (non-normative; machine-derived identity consequences, unadjudicated)
+- **[Part I: Foundation & Mathematical Framework](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-I.md)** - Tensor structure, Π = L + B + E decomposition, Bridge Equations 11-20
+- **[Part II: Extended Bridge Equation Catalog](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-II.md)** - Bridge Equations 21-54 across condensed matter, quantum biology, emergent spacetime
+- **[Part III: Computational Implementation](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/specification/Part-III.md)** - Algorithms, information-theoretic bounds, ML integration
+- **[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)
 
 ### Planning & Development
-- **[Development Plan](docs/planning/Development-Plan.md)** - Phased implementation roadmap
-- **[Implementation Plan](docs/planning/Implementation-Plan.md)** - Technical architecture
-- **[System Requirements](docs/planning/System-Requirements.md)** - Functional requirements
+- **[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)
+- **[Development Plan](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/planning/Development-Plan.md)** - Phased implementation roadmap
+- **[Implementation Plan](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/planning/Implementation-Plan.md)** - Technical architecture
+- **[System Requirements](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/planning/System-Requirements.md)** - Functional requirements
 
 ### Architecture
 
 Grounded in a real parse of the code. Every authored document ends with a `## Verification` block,
 and `repo_map.py check` fails when a claim in one stops matching the source.
 
-- **[Overview](docs/architecture/OVERVIEW.md)** - What this is, what it does, how it is laid out
-- **[Architecture](docs/architecture/ARCHITECTURE.md)** - Why it is built this way; principles and key decisions
-- **[Components](docs/architecture/COMPONENTS.md)** - Each module, with real signatures
-- **[Data Flow](docs/architecture/DATAFLOW.md)** - How a request travels end to end
-- **[API Reference](docs/architecture/API.md)** - The public surface, per export
-- **[File Inventory](docs/architecture/FILE_INVENTORY.md)** - Every tracked file, by zone and disposition
-- **[Test Coverage](docs/architecture/TEST_COVERAGE.md)** - What is tested and what is not *(generated)*
-- **[Dependency Graph](docs/architecture/DEPENDENCY_GRAPH.md)** - Who imports whom *(generated)*
-- **[Unused Analysis](docs/architecture/unused-analysis.md)** - Files and exports with no importer *(generated)*
-- **[Duplicate Symbols](docs/architecture/duplicate-symbols.md)** - Names defined in more than one file
-- **[Physics Map](docs/architecture/PHYSICS_MAP.md)** - The bridge catalog as a map
+- **[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
+- **[Components](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/COMPONENTS.md)** - Each module, with real signatures
+- **[Data Flow](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/DATAFLOW.md)** - How a request travels end to end
+- **[API Reference](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/API.md)** - The public surface, per export
+- **[File Inventory](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/FILE_INVENTORY.md)** - Every tracked file, by zone and disposition
+- **[Test Coverage](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/TEST_COVERAGE.md)** - What is tested and what is not *(generated)*
+- **[Dependency Graph](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/DEPENDENCY_GRAPH.md)** - Who imports whom *(generated)*
+- **[Unused Analysis](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/unused-analysis.md)** - Files and exports with no importer *(generated)*
+- **[Duplicate Symbols](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/duplicate-symbols.md)** - Names defined in more than one file
+- **[Physics Map](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/architecture/PHYSICS_MAP.md)** - The bridge catalog as a map
 
 Regenerate the three generated reports with `npm run docs:deps`; do not edit them by hand. The
 `docs-fresh` CI job fails if what is committed differs from a fresh generation.
 
 ### Code Documentation
-- **[Examples](examples/)** - Usage examples and code samples
-- **[Documentation Index](docs/README.md)** - Complete documentation guide
+- **[Examples](https://github.com/danielsimonjr/universal-physics-tensor/tree/master/examples)** - Usage examples and code samples
+- **[Documentation Index](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/README.md)** - Complete documentation guide
 
 ## Benchmarks
 
@@ -263,15 +282,15 @@ npm run bench        # interactive run (median, p99, ops/sec)
 npm run bench:ci     # verbose run for CI log capture
 ```
 
-Baseline results are recorded in [`docs/architecture/benchmarks.md`](docs/architecture/benchmarks.md).
+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
 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](CHANGELOG.md)).
+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](CHANGELOG.md). This README deliberately carries **no
+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`.
 
@@ -282,7 +301,7 @@ The current machine-checked state is:
 | Bridge catalog | **55 entries (BE-11…65)**: 19 established, 33 speculative, 3 highly speculative; the JSON artifact is freshness-tested against the TypeScript registry |
 | Empirical spine | **19 committed confrontations**, exposed through `upt confront` with rigor/caveat metadata |
 | Composition layer | **41 bridge edges** plus the canonical L-layer graph; dimensional, symbolic, discovery, consequence, and visualization tooling |
-| Canonical reference layer | **103 canonical equations** used as the non-speculative answer-key layer for bridge recovery/linkage |
+| Canonical reference layer | **107 canonical equations** used as the non-speculative answer-key layer for bridge recovery/linkage |
 | Architecture | Generated dependency graph reports **0 circular dependencies** and a clean unused-analysis report; `npm run docs:deps` is CI freshness-gated |
 | 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 |
 
@@ -294,16 +313,16 @@ external evidence/domain review before promotion.
 ### Remaining frontier (not code-completion blockers)
 
 - Physics-curation decisions and literature validation are tracked as bounded
-  contributor tasks in [CONTRIBUTING.md](CONTRIBUTING.md).
+  contributor tasks in [CONTRIBUTING.md](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/CONTRIBUTING.md).
 - Longer-horizon production ideas are explicitly non-blocking and live in
-  [`docs/planning/Future-Production-Hardening.md`](docs/planning/Future-Production-Hardening.md).
+  [`docs/planning/Future-Production-Hardening.md`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/docs/planning/Future-Production-Hardening.md).
 - Historical implementation plans are preserved as records; the live code-completion
-  ledger is [`docs/planning/ACTIVE.md`](docs/planning/ACTIVE.md) and is what
+  ledger is [`ACTIVE.md`](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/ACTIVE.md) and is what
   `npm run audit:plans` gates.
 
 ## Contributing
 
-See **[CONTRIBUTING.md](CONTRIBUTING.md)** — it lists bounded,
+See **[CONTRIBUTING.md](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/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.
@@ -334,7 +353,7 @@ This is an **engineer's approach to theoretical physics** — systematic, organi
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+Code: MIT License - see [LICENSE](LICENSE). Exported atlas data (`data/atlas/`): CC BY 4.0 - see [LICENSE-DATA](https://github.com/danielsimonjr/universal-physics-tensor/blob/master/LICENSE-DATA).
 
 ## Author
 

package/bin/upt.mjs

@@ -1,22 +1,22 @@
-#!/usr/bin/env node
-/**
- * upt — thin launcher. All logic lives in src/cli/ (compiled to dist/cli/).
- * This shim only resolves dist/, guards the not-built case, and maps the
- * returned code onto process.exitCode (NOT process.exit — a hard exit can
- * truncate piped stdout).
- */
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { dirname, join } from 'node:path';
-
-const here = dirname(fileURLToPath(import.meta.url));
-const entry = pathToFileURL(join(here, '..', 'dist', 'cli', 'main.js')).href;
-
-let main;
-try {
-  main = await import(entry);
-} catch (err) {
-  console.error('Could not load the built package. Run `npm run build` first.');
-  console.error(String(err && err.message ? err.message : err));
-  process.exit(1);
-}
-process.exitCode = await main.runCli(process.argv.slice(2));
+#!/usr/bin/env node
+/**
+ * upt — thin launcher. All logic lives in src/cli/ (compiled to dist/cli/).
+ * This shim only resolves dist/, guards the not-built case, and maps the
+ * returned code onto process.exitCode (NOT process.exit — a hard exit can
+ * truncate piped stdout).
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const entry = pathToFileURL(join(here, '..', 'dist', 'cli', 'main.js')).href;
+
+let main;
+try {
+  main = await import(entry);
+} catch (err) {
+  console.error('Could not load the built package. Run `npm run build` first.');
+  console.error(String(err && err.message ? err.message : err));
+  process.exit(1);
+}
+process.exitCode = await main.runCli(process.argv.slice(2));

package/dist/atlas/applicability.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Atlas Phase 4, S4.1 — the applicability checker.
+ *
+ * Design note: `docs/planning/Atlas-Phase-4-Design.md` §1.
+ *
+ * **This module answers "what about this bridge is not checked?", and it
+ * returns FINDINGS rather than a boolean.** A boolean would have to choose
+ * between "unchecked" and "wrong", and those are the two states the module
+ * exists to keep apart. Every finding therefore carries a
+ * {@link ApplicabilitySeverity}:
+ *
+ *  - `'blocking'` — the data CONTRADICTS ITSELF. A dimensional failure, two
+ *    records declaring opposite conventions, a literal zero divisor.
+ *  - `'question'` — the data is SILENT. A divisor nobody guarded, a convention
+ *    only one side declares, two premise models whose relationship is
+ *    unrecorded.
+ *
+ * `src/atlas/conventions.ts` already argues this asymmetry at length for the
+ * convention comparison: absence is not disagreement. The same reasoning
+ * governs every rule here. Collapsing the two severities would report "four
+ * findings" for a record whose only defect is that nobody wrote something
+ * down, and would bury a genuine contradiction among them.
+ *
+ * **Nothing here mutates a record and nothing here is a verdict.** The checker
+ * has no authority to promote or reject: it produces the list a reviewer reads.
+ * That is the same firewall the rest of the repo keeps — no machine verdict
+ * mutates a catalog.
+ *
+ * @module atlas/applicability
+ * @internal
+ */
+import type { ExprNode } from '../dimensional/ast-types.js';
+import type { AtlasModel } from './model.js';
+import type { Conventions } from './types.js';
+/** Whether a finding is a contradiction in the data or a silence in it. @internal */
+export type ApplicabilitySeverity = 'blocking' | 'question';
+/**
+ * The rule that produced a finding. A closed union so a caller can filter by
+ * rule without matching on prose.
+ *
+ * @internal
+ */
+export type ApplicabilityFindingKind = 'dimensional-inconsistency' | 'convention-mismatch' | 'convention-undeclared' | 'division-unguarded' | 'division-by-zero' | 'squaring-adds-solutions' | 'model-incompatibility';
+/** One thing a reviewer must resolve before believing the record. @internal */
+export interface ApplicabilityFinding {
+    readonly kind: ApplicabilityFindingKind;
+    readonly severity: ApplicabilitySeverity;
+    /** Human-readable statement of what is unresolved. */
+    readonly detail: string;
+    /**
+     * Where it was found: an AST path (`'args[1]'`), a convention key, or a
+     * model id. Absent when the finding is about the record as a whole.
+     */
+    readonly where?: string;
+}
+/**
+ * What the checker is given. Every field is optional EXCEPT the side
+ * conditions, which are required so that "this record states none" is a
+ * written choice (`[]`) rather than a forgotten argument — the same reasoning
+ * that made `passingWitnessIds` required in `derive-evidence.ts`.
+ *
+ * @internal
+ */
+export interface ApplicabilityInput {
+    /** The transformation's AST, when the record encodes one. */
+    readonly ast?: ExprNode;
+    /** The record's stated side conditions, as free prose. REQUIRED; `[]` is a statement. */
+    readonly sideConditions: readonly string[];
+    /** The premise records' declared conventions. */
+    readonly premiseConventions?: Conventions;
+    /** The conclusion record's declared conventions. */
+    readonly conclusionConventions?: Conventions;
+    /** The premise models (many). */
+    readonly premises?: readonly AtlasModel[];
+    /** The conclusion model (one). */
+    readonly conclusion?: AtlasModel;
+    /**
+     * Family pairs already bridged, so a genuine cross-family step is not
+     * reported as unrecorded. Unordered: `['a','b']` covers `['b','a']`.
+     */
+    readonly declaredBridges?: readonly (readonly [string, string])[];
+}
+/**
+ * Every unresolved question and contradiction the checker can see in a record.
+ *
+ * An EMPTY result means "no rule fired", which is weaker than "this bridge is
+ * valid" and must not be reported as the latter. The rules in hand cover
+ * dimensions, declared conventions, division guards, even-power equating and
+ * model families; a bridge can be wrong in ways none of them reaches.
+ *
+ * @param input - the record's checkable parts. `sideConditions` is required.
+ * @returns findings in rule order (dimensions, conventions, AST, models);
+ * never `null`, never throws on a malformed AST.
+ * @internal
+ */
+export declare function checkApplicability(input: ApplicabilityInput): readonly ApplicabilityFinding[];
+/**
+ * The `'blocking'` subset of {@link checkApplicability}.
+ *
+ * Offered because the two severities are read by different callers — a report
+ * shows both, a gate looks only at contradictions — and filtering on the
+ * severity string at every call site is how one of them eventually filters on
+ * the wrong one.
+ *
+ * @internal
+ */
+export declare function blockingFindings(findings: readonly ApplicabilityFinding[]): readonly ApplicabilityFinding[];
+//# sourceMappingURL=applicability.d.ts.map

package/dist/atlas/applicability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applicability.d.ts","sourceRoot":"","sources":["../../src/atlas/applicability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,qFAAqF;AACrF,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,UAAU,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,uBAAuB,GACvB,oBAAoB,GACpB,kBAAkB,GAClB,yBAAyB,GACzB,uBAAuB,CAAC;AAE5B,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC;IACxB,yFAAyF;IACzF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,iDAAiD;IACjD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,WAAW,CAAC;IAC1C,oDAAoD;IACpD,QAAQ,CAAC,qBAAqB,CAAC,EAAE,WAAW,CAAC;IAC7C,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC1C,kCAAkC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;CACnE;AAoLD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,GACxB,SAAS,oBAAoB,EAAE,CAkFjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,oBAAoB,EAAE,GACxC,SAAS,oBAAoB,EAAE,CAEjC"}