opensci-engine 0.1.0__tar.gz

opensci_engine-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+.pyodide_final/
+.pyodide_report_out/
+dist/
+build/
+*.egg-info/
+tests/pyodide/node_modules/

opensci_engine-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: opensci-engine
+Version: 0.1.0
+Summary: Deterministic, stateless, offline 3D optical / layout / control engineering engine for OpenSci (CPython + Pyodide).
+Author: OpenSci
+License: Proprietary
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: numpy<3,>=2.3
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: scipy<2,>=1.16
+Requires-Dist: shapely<3,>=2.1
+Provides-Extra: test
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# opensci-engine
+
+Deterministic, stateless, **offline** engineering computation core for OpenSci: 3D geometric optics, Gaussian beams
+(x/y-independent q-parameter), Jones polarization with a transported 3D transverse basis, analytic two-beam interference,
+2.5D layout, and control / recoverability analysis. One pure-Python package, one algorithm core for native CPython,
+Pyodide/WASM (Web Worker), CI and controlled server verification.
+
+* Python **3.14**, `numpy`, `scipy`, `pydantic>=2`, `shapely` (layout only). No compiler, CMake, CUDA or system library.
+* Same input + same engine version + same numerical settings = same result within the declared tolerance.
+* Everything out of scope returns `OUT_OF_MODEL_SCOPE` / `UNKNOWN` — never `PASS`.
+
+```bash
+pip install opensci-engine
+opensci-engine validate request.json --pretty
+```
+
+## Quick example (405 nm / 500 nm two-beam interference)
+
+Every example in this repository is an executable fixture (`tests/fixtures/requests/*.json`, built by
+`tests/fixture_scenes.py`). The 405 nm / 500 nm case:
+
+```python
+import json
+from opensci_engine import ValidationRequest, validate
+
+request = ValidationRequest.model_validate_json(open("tests/fixtures/requests/interference_405_500.json").read())
+result = validate(request)
+
+print(result.status)                                   # PASS
+pair = result.interference[0]
+print(f"{pair.fringe_period_nm:.6f} nm, {pair.half_angle_deg:.4f} deg")   # 500.000000 nm, 23.8911 deg (traced 3D wave vectors)
+print(f"{pair.fringe_visibility:.6f} {pair.coherence_margin:.6f}")           # 1.000000 1.000000
+print(result.manifest.input_hash, result.manifest.result_hash)
+```
+
+Build a scene programmatically with the factories in `opensci_engine.builders`:
+
+```python
+import math
+from opensci_engine import builders as B
+from opensci_engine.contracts import ProjectSnapshot, Target
+from opensci_engine import ValidationRequest, validate
+
+project = ProjectSnapshot(
+    components=(
+        B.laser("L", wavelength_nm=532.0, waist_radius_mm=1.0, position=(0, 0, 20), direction=(1, 0, 0)),
+        B.thin_lens("Lens", focal_length_mm=100.0, clear_radius_mm=12.7, position=(10, 0, 20), axis=(1, 0, 0)),
+    ),
+    observations=(B.observation_plane("focus", position=(110, 0, 20), normal=(1, 0, 0), radius_mm=5.0),),
+    targets=(Target(target_id="w", metric="beam_radius_mm", observation_id="focus", maximum=0.05),),
+)
+result = validate(ValidationRequest(project=project))
+```
+
+## Public API
+
+| Object | Purpose |
+|---|---|
+| `validate(request)` / `validate_json(text)` | pure function: request -> `ValidationResult` (never raises for physical / contract validation outcomes represented by the result model) |
+| `ValidationRequest`, `ProjectSnapshot`, `EngineConfiguration`, `NumericalConfig` | inputs (Pydantic v2, JSON friendly) |
+| `ValidationResult`, `ValidationIssue`, `ValidationManifest` | outputs (finite numbers only, structured issues, hashes) |
+| `opensci_engine.builders` | element factories producing contract objects |
+| `opensci_engine.compare.compare_results` | cross-runtime comparison within `cross_runtime_rel_tol/abs_tol` |
+| `opensci-engine validate|schema|compare` | command line |
+
+Status vocabulary: `PASS`, `WARNING`, `FAIL`, `UNKNOWN`, `NOT_APPLICABLE`, `OUT_OF_MODEL_SCOPE`.
+CLI exit codes: 0 PASS/WARNING/NOT_APPLICABLE, 1 FAIL, 2 UNKNOWN, 3 OUT_OF_MODEL_SCOPE, 64 usage error.
+
+The "never raises" guarantee above applies to the `validate()` / `validate_json()` entry points: physical and
+contract-validation outcomes are always represented by the `ValidationResult` model, never raised as exceptions.
+Direct construction of the frozen Pydantic contract models (e.g. `builders.laser(wavelength_nm=float("nan"))` or
+`SourceSpec(...)`) can still raise a Pydantic `ValidationError` *before* those entry points are called, because the
+contract models deliberately set `allow_inf_nan=False`. Pass such input through `validate_json` (the CLI / Pyodide
+bridge) to receive it as a structured `FAIL` / `INVALID_INPUT` result instead.
+
+## Conventions (short; details in `docs/NUMERICAL_CONVENTIONS.md`)
+
+Right-handed 3D, lengths mm, wavelengths nm (vacuum), angles degrees at the API, power W, `w` = 1/e² intensity **radius**.
+Element local `+z` = optical axis; surface normals are explicit; Jones vectors live in a transported transverse basis
+`(e1, e2)`, `e1 × e2 = d`. `E ∝ exp[i(k·r − ωt)]`.
+
+## Documentation
+
+* `docs/ENGINE_ARCHITECTURE.md` — layers, contracts (frozen vs provisional), dependency decisions
+* `docs/PHYSICS_SCOPE.md` — equations, assumptions, applicability, failure modes, independent references per module
+* `docs/NUMERICAL_CONVENTIONS.md` — units, frames, every tolerance and its reason, determinism, hashing
+* `docs/PYODIDE_COMPATIBILITY.md` — Pyodide policy and the automated tests
+* `KNOWN_LIMITATIONS.md`, `GOLDEN_CASE_REPORT.md`, `NUMERICAL_ACCURACY_REPORT.md`, `PYODIDE_COMPATIBILITY_REPORT.md`,
+  `DEPENDENCY_REPORT.md`, `ENGINE_IMPLEMENTATION_REPORT.md`
+
+## Development
+
+```bash
+uv venv --python 3.14 .venv
+uv pip install -e ".[test]"
+pytest                                   # native tests (golden physics, robustness, layout, control, determinism, hygiene)
+python tests/generate_fixtures.py        # regenerate fixtures / snapshots
+python benchmarks/bench_validation.py    # standard local-validation benchmark
+cd tests/pyodide && npm ci && cd ../..
+pytest -m pyodide                        # real Pyodide install + native/Pyodide parity (needs node + network on a cold cache)
+pytest -m install                        # build the wheel, install into a clean venv, run a Golden Case
+```

opensci_engine-0.1.0/README.md

@@ -0,0 +1,102 @@
+# opensci-engine
+
+Deterministic, stateless, **offline** engineering computation core for OpenSci: 3D geometric optics, Gaussian beams
+(x/y-independent q-parameter), Jones polarization with a transported 3D transverse basis, analytic two-beam interference,
+2.5D layout, and control / recoverability analysis. One pure-Python package, one algorithm core for native CPython,
+Pyodide/WASM (Web Worker), CI and controlled server verification.
+
+* Python **3.14**, `numpy`, `scipy`, `pydantic>=2`, `shapely` (layout only). No compiler, CMake, CUDA or system library.
+* Same input + same engine version + same numerical settings = same result within the declared tolerance.
+* Everything out of scope returns `OUT_OF_MODEL_SCOPE` / `UNKNOWN` — never `PASS`.
+
+```bash
+pip install opensci-engine
+opensci-engine validate request.json --pretty
+```
+
+## Quick example (405 nm / 500 nm two-beam interference)
+
+Every example in this repository is an executable fixture (`tests/fixtures/requests/*.json`, built by
+`tests/fixture_scenes.py`). The 405 nm / 500 nm case:
+
+```python
+import json
+from opensci_engine import ValidationRequest, validate
+
+request = ValidationRequest.model_validate_json(open("tests/fixtures/requests/interference_405_500.json").read())
+result = validate(request)
+
+print(result.status)                                   # PASS
+pair = result.interference[0]
+print(f"{pair.fringe_period_nm:.6f} nm, {pair.half_angle_deg:.4f} deg")   # 500.000000 nm, 23.8911 deg (traced 3D wave vectors)
+print(f"{pair.fringe_visibility:.6f} {pair.coherence_margin:.6f}")           # 1.000000 1.000000
+print(result.manifest.input_hash, result.manifest.result_hash)
+```
+
+Build a scene programmatically with the factories in `opensci_engine.builders`:
+
+```python
+import math
+from opensci_engine import builders as B
+from opensci_engine.contracts import ProjectSnapshot, Target
+from opensci_engine import ValidationRequest, validate
+
+project = ProjectSnapshot(
+    components=(
+        B.laser("L", wavelength_nm=532.0, waist_radius_mm=1.0, position=(0, 0, 20), direction=(1, 0, 0)),
+        B.thin_lens("Lens", focal_length_mm=100.0, clear_radius_mm=12.7, position=(10, 0, 20), axis=(1, 0, 0)),
+    ),
+    observations=(B.observation_plane("focus", position=(110, 0, 20), normal=(1, 0, 0), radius_mm=5.0),),
+    targets=(Target(target_id="w", metric="beam_radius_mm", observation_id="focus", maximum=0.05),),
+)
+result = validate(ValidationRequest(project=project))
+```
+
+## Public API
+
+| Object | Purpose |
+|---|---|
+| `validate(request)` / `validate_json(text)` | pure function: request -> `ValidationResult` (never raises for physical / contract validation outcomes represented by the result model) |
+| `ValidationRequest`, `ProjectSnapshot`, `EngineConfiguration`, `NumericalConfig` | inputs (Pydantic v2, JSON friendly) |
+| `ValidationResult`, `ValidationIssue`, `ValidationManifest` | outputs (finite numbers only, structured issues, hashes) |
+| `opensci_engine.builders` | element factories producing contract objects |
+| `opensci_engine.compare.compare_results` | cross-runtime comparison within `cross_runtime_rel_tol/abs_tol` |
+| `opensci-engine validate|schema|compare` | command line |
+
+Status vocabulary: `PASS`, `WARNING`, `FAIL`, `UNKNOWN`, `NOT_APPLICABLE`, `OUT_OF_MODEL_SCOPE`.
+CLI exit codes: 0 PASS/WARNING/NOT_APPLICABLE, 1 FAIL, 2 UNKNOWN, 3 OUT_OF_MODEL_SCOPE, 64 usage error.
+
+The "never raises" guarantee above applies to the `validate()` / `validate_json()` entry points: physical and
+contract-validation outcomes are always represented by the `ValidationResult` model, never raised as exceptions.
+Direct construction of the frozen Pydantic contract models (e.g. `builders.laser(wavelength_nm=float("nan"))` or
+`SourceSpec(...)`) can still raise a Pydantic `ValidationError` *before* those entry points are called, because the
+contract models deliberately set `allow_inf_nan=False`. Pass such input through `validate_json` (the CLI / Pyodide
+bridge) to receive it as a structured `FAIL` / `INVALID_INPUT` result instead.
+
+## Conventions (short; details in `docs/NUMERICAL_CONVENTIONS.md`)
+
+Right-handed 3D, lengths mm, wavelengths nm (vacuum), angles degrees at the API, power W, `w` = 1/e² intensity **radius**.
+Element local `+z` = optical axis; surface normals are explicit; Jones vectors live in a transported transverse basis
+`(e1, e2)`, `e1 × e2 = d`. `E ∝ exp[i(k·r − ωt)]`.
+
+## Documentation
+
+* `docs/ENGINE_ARCHITECTURE.md` — layers, contracts (frozen vs provisional), dependency decisions
+* `docs/PHYSICS_SCOPE.md` — equations, assumptions, applicability, failure modes, independent references per module
+* `docs/NUMERICAL_CONVENTIONS.md` — units, frames, every tolerance and its reason, determinism, hashing
+* `docs/PYODIDE_COMPATIBILITY.md` — Pyodide policy and the automated tests
+* `KNOWN_LIMITATIONS.md`, `GOLDEN_CASE_REPORT.md`, `NUMERICAL_ACCURACY_REPORT.md`, `PYODIDE_COMPATIBILITY_REPORT.md`,
+  `DEPENDENCY_REPORT.md`, `ENGINE_IMPLEMENTATION_REPORT.md`
+
+## Development
+
+```bash
+uv venv --python 3.14 .venv
+uv pip install -e ".[test]"
+pytest                                   # native tests (golden physics, robustness, layout, control, determinism, hygiene)
+python tests/generate_fixtures.py        # regenerate fixtures / snapshots
+python benchmarks/bench_validation.py    # standard local-validation benchmark
+cd tests/pyodide && npm ci && cd ../..
+pytest -m pyodide                        # real Pyodide install + native/Pyodide parity (needs node + network on a cold cache)
+pytest -m install                        # build the wheel, install into a clean venv, run a Golden Case
+```

opensci_engine-0.1.0/docs/ENGINE_ARCHITECTURE.md

@@ -0,0 +1,149 @@
+# opensci-engine — Architecture
+
+Status: Phase 1 baseline (engine v0.1.0). This document is normative for module
+boundaries, public contracts and dependency choices. Physics scope is in
+`PHYSICS_SCOPE.md`; numeric conventions in `NUMERICAL_CONVENTIONS.md`; Pyodide
+constraints in `PYODIDE_COMPATIBILITY.md`.
+
+## 1. What the engine is
+
+`opensci-engine` is a **deterministic, stateless, offline engineering
+computation library**. One import, one call:
+
+```
+ValidationRequest (Pydantic, JSON)  ->  validate()  ->  ValidationResult (Pydantic, JSON)
+```
+
+It is not a database, web API, cloud service, supplier resolver, catalog or
+file store. It performs no I/O of any kind while computing (no network, no
+filesystem reads of user data, no environment probing other than the
+Python/NumPy versions recorded in the manifest, no clocks, no global
+mutable caches, no multiprocessing).
+
+Invariant: same canonical input + same engine version + same
+`NumericalConfig` = same result within the declared numerical tolerance.
+
+## 2. Layering
+
+```
+ JSON / Python objects
+        |
+        v
+ contracts/   Pydantic v2, frozen, extra="forbid", JSON friendly   <-- public boundary
+        |  (validated, then lowered once)
+        v
+ scene/       lowering: contracts -> numpy-backed internal structures (dataclasses)
+        |
+        v
+ math/ optics/ layout/ control/   pure numerical code, NumPy arrays / dataclasses, no Pydantic in loops
+        |
+        v
+ validation/  targets, aggregation, issue synthesis   -> Pydantic results
+        |
+        v
+ manifest/    canonical serialization, hashing
+```
+
+Rules:
+
+* Pydantic objects are created only at the boundary (input validation and
+  result assembly), never inside ray/beam/optimizer inner loops.
+* `math/` depends on NumPy only. `optics/`, `layout/`, `control/` depend on
+  `math/`, `config` and `errors/`, never on `contracts/` request/result types
+  except through `scene/` lowering.
+* `contracts/` never import `optics/` etc. (one-way dependency), so contracts
+  can be frozen independently of algorithms.
+* No module reads a module-level mutable. All tolerances travel in an explicit
+  `NumericalConfig` object (frozen, hashed into the manifest).
+
+## 3. Package layout
+
+```
+src/opensci_engine/
+  __init__.py          public API: validate, validate_json, __version__, contracts re-exports
+  _version.py          ENGINE_VERSION, SCHEMA_VERSION, NUMERICAL_CONFIG_VERSION, MODEL_VERSIONS
+  config.py            NumericalConfig (all epsilons/tolerances, each documented)
+  errors/              Status, ErrorCode, ValidationIssue, EngineInputError
+  math/                vectors, rotation (quaternion), pose, rng (PCG64 -> uniform/normal)
+  contracts/           frozen public models (see 4)
+  scene/               contracts -> internal lowering
+  optics/
+    materials/         constant / Sellmeier / tabulated n(lambda), coatings, range checks
+    surfaces/          plane & sphere intersection, aperture, Snell/reflect/TIR, thin lens
+    polarization/      Jones calculus, transverse-basis transport, Fresnel, elements
+    gaussian/          q-parameter / ABCD (x,y independent), truncation, applicability
+    rays/              vectorized ray bundles, sequential-agnostic (non-sequential) tracer, pupil sampling
+    interference/      two-beam analytic model
+  layout/              footprint, keepout, beam envelope, moving envelope (Shapely, 2D/2.5D only)
+  control/             actuators, sensors, Jacobian, Levenberg-Marquardt, recoverability, Monte Carlo
+  validation/          target metric registry, out-of-scope registry, pipeline
+  manifest/            canonical JSON, hashing, ValidationManifest assembly
+  cli.py               `opensci-engine validate request.json`
+```
+
+## 4. Public contracts
+
+### 4.1 Frozen (physics/math layer; independent of the database team)
+
+`Vector3`, `Quaternion`, `Pose3D`, `Ray`, `RaySegment`, `OpticalSurface`
+(plane, sphere; apertures; interactions), `OpticalPort`, `OpticalPath`,
+`BeamState`, `GaussianBeamState`, `JonesVector`, `PolarizationBasis`,
+`MaterialOpticalModel` (+ `CoatingModel`), `Target`, `Observation`,
+`ValidationResult`, `ValidationIssue`, `ValidationManifest`, `NumericalConfig`.
+
+"Frozen" means: field names and semantics may only change via a
+`SCHEMA_VERSION` bump plus migration. This is enforced: `tests/fixtures/contract_freeze.json` stores the JSON-Schema hash of
+each frozen model and `tests/test_fixtures_cli_freeze.py::test_frozen_contracts_are_unchanged_since_the_recorded_baseline`
+fails on any change without a version bump (`python tests/generate_fixtures.py --freeze` rewrites the baseline).
+
+### 4.2 Provisional (awaiting the database / Product & Supply team)
+
+`EngineeringComponentSnapshot`, `EngineeringEnvelopeSnapshot`,
+`ActuatorSpec`, `ControlSpec`, `SourceSpec` (wrapper fields other than the
+physical beam parameters), `ProjectSnapshot` (container fields such as ids,
+names, revision metadata), `ValidationRequest.project` envelope.
+
+The envelope's plan-parallel frame (`EngineeringEnvelopeSnapshot.frame_pose`) and the element `mount_margin_mm` semantics
+were introduced during implementation because the first draft (footprints in the optical local frame; an infinite blocking plane)
+was physically wrong (documented in `ENGINE_IMPLEMENTATION_REPORT.md`).
+
+These are *engine-side input snapshots*. The engine never imports an ORM or
+`DesignPart`/`SupplierPart`/`AssemblyImplementation`. The future adapter
+direction is `Database model -> adapter -> Engineering*Snapshot -> engine`.
+
+## 5. Dependency decisions
+
+| Package | Decision | Reason |
+|---|---|---|
+| numpy | required, `>=2.3,<3` | vector math; shipped by Pyodide 314 (2.4.6) |
+| scipy | required, `>=1.16,<2` | interpolation (`PchipInterpolator`, `RegularGridInterpolator`); shipped by Pyodide (1.18.0) |
+| pydantic | required, `>=2.11,<3` | public contracts; Pyodide ships 2.12.5 + pydantic-core wasm |
+| shapely | required, `>=2.1,<3` | *only* `layout/` footprint / keepout polygon operations; Pyodide ships 2.1.2 |
+| networkx | not adopted | Pyodide's build depends on matplotlib; graph needs here are trees |
+| trimesh | not adopted | not in Pyodide lock; M1 needs only analytic plane/sphere geometry, so no Rtree/Embree question arises |
+
+Shapely does 2D/2.5D footprint booleans, distances and buffering. It does
+not replace 3D physics: beam/ray propagation, apertures and surface
+intersection are NumPy.
+
+## 6. Runtime targets
+
+Native CPython 3.14, Pyodide 314.0.x in a Web Worker, CI, controlled server
+verification. The package is pure Python (`py3-none-any` wheel); all binary
+dependencies come from the target's own distribution (PyPI wheels / Pyodide
+lock). No compiler, CMake, CUDA or system shared library.
+
+## 7. Statefulness
+
+None. `validate()` is a pure function of `(request)`. Caches (e.g., material
+index lookups inside one trace) live for one call. There are no module-level
+caches or mutable globals. `engine_build_id` is recomputed per call from the
+installed package's `.py` source bytes (read-only, ~ms) and is used only for
+the manifest; it cannot influence physics.
+
+## 8. Extension points
+
+* New element type: add a discriminated-union member in `contracts/optics.py`
+  and an interaction handler in `optics/surfaces/interaction.py`.
+* New metric: register in `validation/metrics.py`; unsupported physics goes
+  into the explicit out-of-scope registry (returns `OUT_OF_MODEL_SCOPE`).

opensci_engine-0.1.0/docs/NUMERICAL_CONVENTIONS.md

@@ -0,0 +1,181 @@
+# opensci-engine — Numerical Conventions
+
+## 1. Units (fixed by schema, not by field-level choice)
+
+| Quantity | Unit | Notes |
+|---|---|---|
+| length | mm | every `*_mm` field; radius vs diameter is explicit in the field name (`*_radius_mm`) — never both |
+| wavelength | nm (vacuum) | `wavelength_nm`; fringe periods in nm |
+| angle (API) | degree | `*_deg`; internal computation in radian |
+| power | W | `power_W` |
+| irradiance | W/mm² | conversion to mW/cm² only in exposure metrics |
+| time | s | |
+| dose | mJ/cm² | |
+| phase | rad | |
+| Gaussian radius | mm | `w` is the **1/e² intensity radius** (not FWHM, not diameter) |
+| divergence | rad | half-angle, `θ = M²λ/(π n w₀)` |
+
+## 2. Coordinates
+
+* Global frame: right-handed, `x` right, `y` forward, `z` up (board normal).
+  The baseplate top plane is `z = 0` unless the project says otherwise; the
+  optical axis height is an absolute `z` of the ray.
+* Element local frame: right-handed, origin at the element reference point.
+  For transmissive elements local `+z` is the nominal optical axis (light
+  travels along `+z`); surface normals are given explicitly per surface, so no
+  hidden convention is required.
+* `Pose3D = (position_mm, quaternion (w,x,y,z))`; *active* transform
+  `x_g = R(q) x_l + p`. Composition `T_parent ∘ T_child`: `R = R_p R_c`,
+  `p = R_p p_c + p_p`. Quaternions are Hamilton, unit norm within
+  `quaternion_norm_tol`, renormalized on lowering (the deviation is not
+  hidden: outside tolerance is a validation error).
+* `Pose3D.from_axis_direction(position, axis, up)` (the `compute_pose` helper):
+  local `z := axis`, local `y := up` orthogonalized against `axis`, local
+  `x := y × z`.
+* Angle sign: positive rotation is right-handed about the stated axis.
+* Surface normal `n̂`: "positive side" is the side `n̂` points toward.
+  `medium_positive` / `medium_negative` name the media on the two sides. A ray
+  with `d̂·n̂ < 0` arrives from the positive side.
+* Mirror: `reflective_side ∈ {positive, negative, both}`. Sphere normal is the
+  outward radial vector.
+* Signed radius for ABCD: `R>0` if the centre of curvature lies ahead of the
+  surface along the propagation direction (refraction) / on the incident
+  side (mirror, concave).
+* Transverse basis of a ray: `(e₁, e₂)`, `e₁ × e₂ = d̂`.
+* Polarization phase convention: `E ∝ exp[i(k·r − ωt)]`; a retarder's slow axis
+  gets `+δ/2`. Ideal metal mirror: `(r_s, r_p) = (−1, +1)` in the `(ŝ, d̂×ŝ)` triad, equivalently
+  `E_out = −(I − 2 n̂ n̂ᵀ) E_in` (tested against exact vector reflection through non-coplanar folds).
+* Mount margin: a surface with a clear aperture may declare `mount_margin_mm` — the width of the
+  opaque ring around the aperture. A ray hitting the ring is blocked (`CLIPPED`); a ray beyond it
+  (or beyond the aperture when the margin is 0, e.g. a mirror edge) *misses* the element and passes by.
+  An infinite plane never blocks anything by itself.
+* Observation planes are virtual and unbounded. Without an active `aperture` every crossing is an
+  arrival. With one, a beam counts as an arrival only if its chief ray is inside the area or at least
+  `capture_min_power_fraction` of its Gaussian power falls inside it; otherwise the crossing is
+  reported as `OBSERVATION_NOT_REACHED` with `nearest_miss_mm`. Two observation planes must not be
+  coincident (the second would be hidden by the ray-advance guard).
+* Envelope frame: `EngineeringEnvelopeSnapshot.frame_pose` places the envelope frame relative to the
+  component frame. The footprint / z range / keepout / tool / cable regions live in that frame and
+  must be plan-parallel. For elements built with local `z` = beam axis use
+  `Pose3D.plan_frame_for_optical_axis()` (envelope x = beam axis, y = transverse horizontal, z = up).
+* Two-beam phase difference: `phase_difference_rad = wrap[k₀ (OPL_a − OPL_b) − arg⟨E_a, E_b⟩]`
+  with `⟨E_a, E_b⟩ = conj(E_a)·E_b` (3D fields, interface phases included, spatial fringe term
+  excluded).
+
+## 3. Tolerances (all in `NumericalConfig`, each with a stated reason)
+
+No numeric literal used as a tolerance appears outside `config.py`, named module constants
+or `units.py` (enforced by `tests/test_hygiene.py`, which AST-scans the physics packages for
+unnamed floats and large integers). The table below is generated from `NumericalConfig`
+(`python docs/generate_docs.py`); `tests/test_docs_in_sync.py` fails if it drifts.
+
+<!-- BEGIN TOLERANCES (generated by docs/generate_docs.py; do not edit) -->
+
+| Field | Default | Meaning / reason |
+|---|---|---|
+| `ray_min_advance_mm` | `1e-07` | Minimum ray parameter t for a valid hit; prevents re-intersecting the surface just left. |
+| `parallel_dot_tol` | `1e-12` | |n.d| below this is 'parallel': no intersection is reported. |
+| `grazing_warn_aoi_deg` | `85.0` | AOI above which GRAZING_INCIDENCE warns. |
+| `grazing_fail_aoi_deg` | `89.9` | AOI above which the interaction is rejected. |
+| `antiparallel_tol` | `1e-12` | 1+cos(angle) below which two directions are treated as antiparallel (basis transport). |
+| `unit_vector_tol` | `1e-09` | Allowed |1-|v|| for user-supplied unit vectors. |
+| `zero_vector_tol` | `1e-12` | Vectors with norm below this are zero-length. |
+| `quaternion_norm_tol` | `1e-06` | Allowed |1-|q|| for user-supplied quaternions. |
+| `aperture_edge_tol_mm` | `1e-09` | Inclusive aperture boundary tolerance (floating-point edge). |
+| `tir_warn_margin` | `0.001` | Relative distance to the critical angle that triggers TIR_BOUNDARY. |
+| `power_epsilon_W` | `1e-15` | Power at or below this terminates a path (ZERO_POWER). |
+| `energy_conservation_tol` | `1e-09` | Tolerance for R+T<=1 and unit-norm Jones checks. |
+| `basis_orthonormality_tol` | `1e-09` | Allowed deviation of a transported transverse basis before a warning. |
+| `max_interactions_per_path` | `64` | Guard against infinite cavity loops. |
+| `max_paths` | `4096` | Guard against unbounded branching. |
+| `retarder_warn_aoi_deg` | `20.0` | Retarder/polarizer AOI above which RETARDER_OBLIQUE_INCIDENCE warns. |
+| `sellmeier_pole_rel_tol` | `1e-09` | Relative |l^2 - C_i| / l^2 below which a Sellmeier pole is considered hit. |
+| `tabulated_range_tol_nm` | `1e-09` | Slack (nm) on the inclusive wavelength validity bounds of materials and coatings. |
+| `tabulated_aoi_tol_deg` | `1e-09` | Slack (deg) on the AOI bounds of tabulated coatings. |
+| `gaussian_warn_divergence_rad` | `0.1` | Half-angle divergence (NA~0.1) warning threshold. |
+| `gaussian_scope_divergence_rad` | `0.3` | Half-angle divergence above which the paraxial Gaussian model is out of scope. |
+| `gaussian_max_w_over_radius` | `0.2` | Beam radius / |surface radius of curvature| limit for ABCD validity. |
+| `gaussian_max_aoi_deg` | `60.0` | Tilted-surface ABCD validity limit on AOI. |
+| `gaussian_clip_warn_fraction` | `0.001` | Truncation power loss that warns. |
+| `gaussian_clip_scope_fraction` | `0.1` | Truncation power loss above which the Gaussian state is invalidated. |
+| `gaussian_astig_align_tol` | `1e-09` | |sin(phi)cos(phi)| below which beam axes are aligned with (t,s). |
+| `gaussian_round_tol` | `1e-09` | Relative difference below which the two transverse axes are 'round'. |
+| `gaussian_plane_axial_spread_fraction` | `0.1` | Axial spread across a tilted plane footprint vs z_R that triggers a warning. |
+| `aperture_quad_angular` | `256` | Angular trapezoid nodes for circular-aperture Gaussian truncation (periodic, spectral). |
+| `aperture_quad_sector_nodes` | `48` | Gauss-Legendre nodes per panel/sector for off-axis circular and rectangular truncation. |
+| `aperture_quad_extent_sigmas` | `6.0` | Gaussian integrals are truncated at this many beam radii from the beam centre (exp(-72) ~ 0). |
+| `pupil_ring_count` | `8` | Equal-power rings in the default pupil sampling. |
+| `pupil_points_per_ring` | `12` | Points on each ring of the default pupil sampling. |
+| `interference_min_crossing_deg` | `1e-06` | Crossing angle below which the fringe period is undefined. |
+| `interference_wavelength_tol_nm` | `1e-09` | Two arrivals must agree in wavelength within this to interfere. |
+| `interference_min_overlap` | `0.001` | Spatial overlap ratio below which beams are considered not overlapping (visibility < 0.1 %). |
+| `interference_collinear_period_ratio` | `10.0` | Fringe period / beam diameter above which two beams are treated as collinear (single-fringe detector). |
+| `max_interference_pairs` | `256` | Cap on automatically analysed beam pairs per observation. |
+| `interference_det_tol` | `1e-30` | Determinant floor for the summed envelope matrix. |
+| `fd_step_translation_mm` | `0.001` | Central-difference step for translation DOFs. |
+| `fd_step_rotation_rad` | `1e-05` | Central-difference step for rotation DOFs. |
+| `lm_initial_damping` | `0.001` | Initial Levenberg-Marquardt damping. |
+| `lm_damping_up` | `10.0` | Damping multiplier after a rejected step. |
+| `lm_damping_down` | `0.1` | Damping multiplier after an accepted step. |
+| `lm_max_damping` | `1000000000000.0` | Damping above which LM gives up. |
+| `lm_max_iterations` | `100` | Iteration cap for LM. |
+| `lm_cost_tol` | `1e-18` | Converged when the cost falls below this. |
+| `lm_step_tol` | `1e-12` | Converged when the scaled step norm falls below this. |
+| `lm_residual_tol` | `1e-06` | Default weighted-residual norm regarded as converged when the spec gives none (sensor units, e.g. mm). |
+| `lm_scaling_floor` | `1e-12` | Floor on diag(J^T J) in Marquardt scaling so unobserved DOFs stay bounded. |
+| `lm_gain_accept` | `0.0` | Minimum actual/predicted reduction ratio to accept a step. |
+| `jacobian_rcond` | `1e-10` | Singular values below rcond*sigma_max are rank-deficient. |
+| `observability_participation_min` | `0.25` | An actuator is reported unobservable when at least this fraction of its unit motion lies in the null space of the sensor Jacobian (0.5 would sit exactly on the symmetric two-DOF case). |
+| `jacobian_condition_warn` | `1000000.0` | Jacobian condition number that warns. |
+| `capture_min_power_fraction` | `0.001` | Detected/available power below this means the beam is lost. |
+| `capture_scan_max_points` | `4096` | Maximum points of the coarse-capture raster scan. |
+| `layout_geometry_tol_mm` | `1e-06` | Overlaps/clearance deficits below this are ignored. |
+| `layout_arc_resolution` | `32` | Shapely buffer segments per quarter circle. |
+| `beam_envelope_k` | `2.0` | Beam envelope radius = k*w (k=2 -> 1-exp(-8)=99.97% power). |
+| `moving_envelope_rotation_samples` | `9` | Angles sampled for rotational sweeps. |
+| `layout_height_tol_mm` | `1e-06` | Height intervals overlapping by less than this are disjoint. |
+| `hash_float_sig_digits` | `9` | Significant digits kept when hashing results. |
+| `hash_float_abs_floor` | `1e-12` | Result values below this magnitude hash as 0. |
+| `cross_runtime_rel_tol` | `1e-09` | Relative tolerance for cross-runtime comparison. |
+| `cross_runtime_abs_tol` | `1e-12` | Absolute tolerance for cross-runtime comparison. |
+
+<!-- END TOLERANCES -->
+
+Changing a default increments `NUMERICAL_CONFIG_VERSION`.
+
+## 4. Determinism
+
+* No wall-clock, no `id()`, no dict-order dependence in results (all
+  collections are sorted by stable ids before output).
+* Random numbers only in Monte Carlo, from `numpy.random.PCG64(seed)` raw
+  64-bit words; uniform `u = (w >> 11) · 2⁻⁵³`; normal via Box–Muller using
+  `math.log`/`math.cos`. The PRNG identifier `PCG64+BoxMuller-v1` and the seed
+  go into the manifest.
+* NumPy `BitGenerator` raw streams are stable across versions and platforms;
+  `Generator` distribution methods are deliberately not used.
+* Floating-point differences between runtimes come from libm/BLAS; results are
+  compared with `cross_runtime_rel_tol` / `_abs_tol`, never bitwise.
+
+## 5. Error reporting, never NaN
+
+All public numeric outputs are finite. If a computation cannot produce a
+finite meaningful number it returns a structured `ValidationIssue`
+(`code`, `message`, `location`, `affected_targets`, `numerical_context`,
+`suggested_action`) and the dependent metric has status `UNKNOWN`,
+`FAIL` or `OUT_OF_MODEL_SCOPE` with `value = null`. Result models forbid
+`NaN`/`Inf` (`allow_inf_nan=False`).
+
+## 6. Canonical serialization and hashing
+
+* JSON, UTF-8, keys sorted, no whitespace (`separators=(",",":")`).
+* Inputs hashed from the validated model dump (`mode="json"`, so defaults are
+  materialized and aliases normalized).
+* Floats in **results** are quantized before hashing: value `v` with
+  `|v| < hash_float_abs_floor` → `0.0`; else round to `hash_float_sig_digits`
+  significant digits and print with `repr`. This makes `result_hash` stable
+  against last-bit libm differences; cross-runtime comparison still uses
+  explicit tolerances (`compare_results`), because rounding can straddle a
+  boundary.
+* Hash = SHA-256 hex. No secret keys: hashes are integrity/reproducibility
+  aids, not authenticity proofs.
+* `trace_hash` covers the ordered ray-event list of the chief rays.