@essrt/physics 1.0.0

package/src/eclipse/finders.cjs

@@ -0,0 +1,311 @@
+/**
+ * Eclipse geometry — sun longitude + the predictive finders (Phase 8.5).
+ *
+ * Single-copy extraction from the browser (there was never a Node twin;
+ * the moon series beneath is shared since 8.2 — the engines inject their
+ * own truncated-series evaluators and ΔT convention).
+ *
+ * sunLonDegAt — Meeus Ch. 25 low-precision Sun geocentric ecliptic
+ * longitude. Accepts JD_UT; converts internally to JD_TT via the injected
+ * ΔT. Returns MEAN GEOMETRIC longitude, NOT apparent — LOAD-BEARING: the
+ * framework's SUN_HARMONICS was fitted against observed eclipses that
+ * already include aberration/nutation, so adding raw aberration here
+ * double-counted the correction (measured 2026-07: 2024 Dallas 12→24 km
+ * worse). Upgrading to apparent longitude requires refitting
+ * SUN_HARMONICS with the correction active.
+ *
+ * findLunarEclipsesInRange — per-opposition shadow geometry (the Danjon
+ * ~2% atmospheric enlargement, as used by the NASA Lunar Canon and Meeus
+ * Ch. 54 — the pure geometric shadow under-classifies borderline events,
+ * e.g. 2021-05-26), zero-crossing + 40-step bisection to ~1 s.
+ *
+ * findSolarEclipsesInRange — per-conjunction geometry (topocentric Moon
+ * disk distinguishes total from annular), then refinement from
+ * longitude-conjunction to MINIMUM γ — NASA's "greatest eclipse"
+ * convention, typically 5–15 min apart.
+ *
+ * Sun distance and the synodic month arrive as GETTERS (both are
+ * epoch-mutable engine globals). Sun-distance variation over the orbit
+ * (~0.5%) is currently neglected — refinement recorded (Phase L-4).
+ *
+ * The scene-umbra conventions (piercing point / NASA radial projection)
+ * are NOT here: they navigate the THREE scene through the Tychosium-
+ * derived scaffold, which never enters this package (§2h).
+ */
+
+'use strict';
+
+/**
+ * @typedef {Object} EclipseFinderDeps
+ * @property {(jd: number) => number} moonLonDegAt - truncated-series ecliptic longitude
+ * @property {(jd: number) => number} moonBetaDegAt - truncated-series ecliptic latitude
+ * @property {(jd: number) => number} moonDistanceKmAt - truncated-series distance
+ * @property {(jd: number) => number} deltaTSecondsAt - the engine's ΔT convention
+ * @property {() => number} getSynodicMonthDays - live (epoch-mutable)
+ * @property {() => number} getSunDistanceKm - live (epoch-mutable)
+ * @property {{ rEarthMetres: number, moonDiameterKm: number,
+ *   sunDiameterKm: number, j2000JD: number, julianCenturyDays: number }} constants
+ */
+
+/** @param {EclipseFinderDeps} deps */
+function createEclipseFinders(deps) {
+  const K = deps.constants;
+
+  /** Sun's geocentric ecliptic longitude in degrees (0–360) at given JD_UT.
+   * MEAN GEOMETRIC — see the module header. @param {number} jd @returns {number} */
+  function sunLonDegAt(jd) {
+    const _d2r = Math.PI / 180;
+    const T = (jd + deps.deltaTSecondsAt(jd) / 86400 - K.j2000JD) / K.julianCenturyDays;
+    const L0 = 280.46646 + 36000.76983 * T + 0.0003032 * T * T;
+    const M = (357.52911 + 35999.05029 * T - 0.0001537 * T * T) * _d2r;
+    const C = (1.914602 - 0.004817 * T - 0.000014 * T * T) * Math.sin(M)
+            + (0.019993 - 0.000101 * T) * Math.sin(2 * M)
+            + 0.000289 * Math.sin(3 * M);
+    return ((L0 + C) % 360 + 360) % 360;
+  }
+
+  /**
+   * Find all lunar-eclipse-class oppositions in [jdStart, jdEnd].
+   * @param {number} jdStart @param {number} jdEnd
+   * @returns {Array<{jd: number, beta: number, moonDistance_km: number,
+   *   type: string, magnitudeUmbral: number, magnitudePenumbral: number}>}
+   */
+  function findLunarEclipsesInRange(jdStart, jdEnd) {
+    // Step size: small fraction of synodic month for reliable zero-crossing
+    // detection (~6° diff change per step, well clear of the 30° wrap filter).
+    const STEP_DAYS = deps.getSynodicMonthDays() / 60;
+
+    // Per-event-distance geometry — the shadow angular radii are computed
+    // PER OPPOSITION using each event's Moon distance (perigee vs apogee
+    // varies the threshold by ~5.5%, which dominates type-classification
+    // at boundary cases).
+    const _rad2deg = 180 / Math.PI;
+    const R_EARTH_KM = K.rEarthMetres / 1000;
+    const R_MOON_KM = K.moonDiameterKm / 2;
+    const R_SUN_KM = K.sunDiameterKm / 2;
+    const D_SUN_KM = deps.getSunDistanceKm();
+    const umbraApex_rad = Math.atan((R_SUN_KM - R_EARTH_KM) / D_SUN_KM);
+    const penumbraApex_rad = Math.atan((R_SUN_KM + R_EARTH_KM) / D_SUN_KM);
+
+    // Shadow radii carry the standard ~2% atmospheric enlargement (Danjon
+    // rule / Chauvenet's 1/50, as used by the NASA Lunar Canon and Meeus
+    // Ch. 54).
+    const SHADOW_ENLARGEMENT = 1.02;
+    /** @param {number} D_MOON_KM */
+    const _shadowGeometry = (D_MOON_KM) => {
+      const moonR = Math.atan(R_MOON_KM / D_MOON_KM) * _rad2deg;
+      const umbraR = Math.atan((R_EARTH_KM - D_MOON_KM * Math.tan(umbraApex_rad)) / D_MOON_KM) * _rad2deg * SHADOW_ENLARGEMENT;
+      const penumR = Math.atan((R_EARTH_KM + D_MOON_KM * Math.tan(penumbraApex_rad)) / D_MOON_KM) * _rad2deg * SHADOW_ENLARGEMENT;
+      return {
+        moonR, umbraR, penumR,
+        totalMax: umbraR - moonR,
+        partialMax: umbraR + moonR,
+        penumMax: penumR + moonR,
+      };
+    };
+
+    // Wrapped opposition diff: 0 means Moon at opposition (Sun + 180°)
+    /** @param {number} jd */
+    const oppDiff = (jd) => {
+      let d = deps.moonLonDegAt(jd) - sunLonDegAt(jd) - 180;
+      while (d > 180) d -= 360;
+      while (d <= -180) d += 360;
+      return d;
+    };
+
+    const results = [];
+    let prevJD = jdStart;
+    let prevDiff = oppDiff(prevJD);
+
+    for (let jd = jdStart + STEP_DAYS; jd <= jdEnd; jd += STEP_DAYS) {
+      const d = oppDiff(jd);
+      // Zero-crossing: sign change from − to + with no wrap discontinuity
+      if (prevDiff < 0 && d >= 0 && (d - prevDiff) < 30) {
+        // Bisect to refine opposition to ~1-second precision
+        let lo = prevJD, hi = jd;
+        for (let i = 0; i < 40; i++) {
+          const mid = (lo + hi) / 2;
+          if (oppDiff(mid) < 0) lo = mid; else hi = mid;
+          if (hi - lo < 1 / 86400) break;
+        }
+        const jdOpp = (lo + hi) / 2;
+        const beta = deps.moonBetaDegAt(jdOpp);
+        const absB = Math.abs(beta);
+
+        // Per-event shadow geometry using the actual Moon distance at this
+        // opposition — closes the ~5.5% perigee/apogee threshold variation.
+        const D_moon_jd = deps.moonDistanceKmAt(jdOpp);
+        const G = _shadowGeometry(D_moon_jd);
+
+        let type = null;
+        if (absB <= G.totalMax) type = 'Total';
+        else if (absB <= G.partialMax) type = 'Partial';
+        else if (absB <= G.penumMax) type = 'Penumbral';
+
+        if (type) {
+          const magUmbral = Math.max(0, (G.partialMax - absB) / (2 * G.moonR));
+          const magPenumbral = Math.max(0, (G.penumMax - absB) / (2 * G.moonR));
+          results.push({
+            jd: jdOpp,
+            beta: beta,
+            moonDistance_km: D_moon_jd,
+            type: type,
+            magnitudeUmbral: magUmbral,    // 0 for Penumbral-only; (0,1) Partial; ≥1 Total
+            magnitudePenumbral: magPenumbral,
+          });
+        }
+      }
+      prevDiff = d;
+      prevJD = jd;
+    }
+
+    return results;
+  }
+
+  /**
+   * Find all solar-eclipse-class conjunctions in [jdStart, jdEnd].
+   * Events are timed at MINIMUM γ (NASA "greatest eclipse" convention).
+   * @param {number} jdStart @param {number} jdEnd
+   * @returns {Array<{jd: number, beta: number, moonDistance_km: number,
+   *   type: string, moonAppR_topo: number, sunAppR: number, moonSunRatio: number}>}
+   */
+  function findSolarEclipsesInRange(jdStart, jdEnd) {
+    const STEP_DAYS = deps.getSynodicMonthDays() / 60;
+    const _rad2deg = 180 / Math.PI;
+    const R_EARTH_KM = K.rEarthMetres / 1000;
+    const R_MOON_KM = K.moonDiameterKm / 2;
+    const R_SUN_KM = K.sunDiameterKm / 2;
+    const D_SUN_KM = deps.getSunDistanceKm();
+    const sunAppR = Math.atan(R_SUN_KM / D_SUN_KM) * _rad2deg;  // ~0.266°
+
+    // Per-event geometry at conjunction (Meeus Ch. 54 simplified geocentric
+    // form). "Topocentric" Moon size: at the sub-Moon point an observer is
+    // 1 Earth-radius closer than the geocenter (ratio ≈ 1.017) — this is
+    // what distinguishes total from annular when geocentric Moon ≈ Sun.
+    /** @param {number} D_MOON_KM */
+    const _solarGeometry = (D_MOON_KM) => {
+      const moonAppR_geo = Math.atan(R_MOON_KM / D_MOON_KM) * _rad2deg;
+      const moonAppR_topo = Math.atan(R_MOON_KM / (D_MOON_KM - R_EARTH_KM)) * _rad2deg;
+      const parallax = Math.atan(R_EARTH_KM / D_MOON_KM) * _rad2deg;  // ~0.95°
+      return {
+        moonAppR_geo, moonAppR_topo, parallax, sunAppR,
+        partialLim: sunAppR + moonAppR_geo + parallax,
+        centralLim: parallax - Math.abs(moonAppR_topo - sunAppR),
+        isTotal: moonAppR_topo > sunAppR,
+      };
+    };
+
+    // Wrapped conjunction diff: 0 means Moon at conjunction with the Sun
+    /** @param {number} jd */
+    const conjDiff = (jd) => {
+      let d = deps.moonLonDegAt(jd) - sunLonDegAt(jd);
+      while (d > 180) d -= 360;
+      while (d <= -180) d += 360;
+      return d;
+    };
+
+    // Geocentric γ (Earth-radii): perpendicular distance from Earth's center
+    // to the Sun–Moon line. NASA's "greatest eclipse" TD is the moment of
+    // MINIMUM γ — typically 5–15 min from longitude conjunction, because at
+    // conjunction the Moon may still be approaching in the β direction.
+    const _d2r = Math.PI / 180;
+    /** @param {number} jd */
+    const gammaAtJd = (jd) => {
+      const sunLonR = sunLonDegAt(jd) * _d2r;
+      const moonLonR = deps.moonLonDegAt(jd) * _d2r;
+      const moonBetR = deps.moonBetaDegAt(jd) * _d2r;
+      const D_moon = deps.moonDistanceKmAt(jd);
+      const D_sun = D_SUN_KM;
+      const sX = D_sun * Math.cos(sunLonR), sY = D_sun * Math.sin(sunLonR);
+      const cb = Math.cos(moonBetR);
+      const mX = D_moon * cb * Math.cos(moonLonR);
+      const mY = D_moon * cb * Math.sin(moonLonR);
+      const mZ = D_moon * Math.sin(moonBetR);
+      const dX = mX - sX, dY = mY - sY, dZ = mZ;
+      const dLen = Math.sqrt(dX*dX + dY*dY + dZ*dZ);
+      const ux = dX/dLen, uy = dY/dLen, uz = dZ/dLen;
+      // Perpendicular distance from origin to the line through Moon along u
+      const proj = mX*ux + mY*uy + mZ*uz;
+      const perpX = mX - proj*ux, perpY = mY - proj*uy, perpZ = mZ - proj*uz;
+      return Math.sqrt(perpX*perpX + perpY*perpY + perpZ*perpZ) / R_EARTH_KM;
+    };
+
+    // Refine conjunction-JD to true min-γ JD: coarse 1-min scan over ±20 min,
+    // then parabolic interpolation on the 3 points around the minimum.
+    /** @param {number} jdConj */
+    const refineMinGamma = (jdConj) => {
+      const stepMin = 1 / (24 * 60);
+      let bestJD = jdConj, bestG = gammaAtJd(jdConj);
+      for (let dt = -20; dt <= 20; dt++) {
+        if (dt === 0) continue;
+        const jd = jdConj + dt * stepMin;
+        const g = gammaAtJd(jd);
+        if (g < bestG) { bestG = g; bestJD = jd; }
+      }
+      const yL = gammaAtJd(bestJD - stepMin);
+      const y0 = bestG;
+      const yR = gammaAtJd(bestJD + stepMin);
+      const denom = yL - 2*y0 + yR;
+      if (Math.abs(denom) > 1e-15) {
+        const delta = 0.5 * (yL - yR) / denom;  // fractional offset in [-1, +1]
+        if (Math.abs(delta) < 1) {
+          const refinedJD = bestJD + delta * stepMin;
+          const refinedG = gammaAtJd(refinedJD);
+          if (refinedG < bestG) return refinedJD;
+        }
+      }
+      return bestJD;
+    };
+
+    const results = [];
+    let prevJD = jdStart;
+    let prevDiff = conjDiff(prevJD);
+
+    for (let jd = jdStart + STEP_DAYS; jd <= jdEnd; jd += STEP_DAYS) {
+      const d = conjDiff(jd);
+      if (prevDiff < 0 && d >= 0 && (d - prevDiff) < 30) {
+        // Bisect to ~1-second precision on conjunction
+        let lo = prevJD, hi = jd;
+        for (let i = 0; i < 40; i++) {
+          const mid = (lo + hi) / 2;
+          if (conjDiff(mid) < 0) lo = mid; else hi = mid;
+          if (hi - lo < 1 / 86400) break;
+        }
+        const jdConj = (lo + hi) / 2;
+        // Refine to NASA's "greatest eclipse" convention (minimum γ).
+        const jdGreatest = refineMinGamma(jdConj);
+        const beta = deps.moonBetaDegAt(jdGreatest);
+        const absB = Math.abs(beta);
+        const D_moon = deps.moonDistanceKmAt(jdGreatest);
+        const G = _solarGeometry(D_moon);
+
+        let type = null;
+        if (absB <= G.centralLim) {
+          type = G.isTotal ? 'Total' : 'Annular';
+        } else if (absB <= G.partialLim) {
+          type = 'Partial';
+        }
+
+        if (type) {
+          results.push({
+            jd: jdGreatest,
+            beta: beta,
+            moonDistance_km: D_moon,
+            type: type,
+            moonAppR_topo: G.moonAppR_topo,
+            sunAppR: G.sunAppR,
+            moonSunRatio: G.moonAppR_topo / G.sunAppR,
+          });
+        }
+      }
+      prevDiff = d;
+      prevJD = jd;
+    }
+
+    return results;
+  }
+
+  return { sunLonDegAt, findLunarEclipsesInRange, findSolarEclipsesInRange };
+}
+
+module.exports = { createEclipseFinders };

package/src/index.js

@@ -0,0 +1,252 @@
+/**
+ * @essrt/physics — the pure physics core.
+ *
+ * PHASE 2 SKELETON. No physics has moved yet; `script.js` remains the
+ * implementation. This file exists so the architecture rules have something to
+ * enforce before code arrives — that ordering is the whole point of Phase 2.
+ *
+ * Three rules this package must never break (IP-unified-architecture.md §2b, §2h):
+ *
+ *   1. It imports NOTHING external. Not `three`, not `fs`, not `next`, not
+ *      `document`, not `process`. Language built-ins only.
+ *   2. Constants are INJECTED, never imported. A `import { H } from './constants'`
+ *      inside a layer is a design defect, not a shortcut — it makes
+ *      counterfactuals impossible, which is the one capability DE440 and Laskar
+ *      cannot offer.
+ *   3. No scene-graph scaffold. `containerObj`, `pivotObj`, `planetObj`,
+ *      `orbitCentera/b/c`, `orbitTilta/b`, `startPos` are Tychosium-derived (GPL)
+ *      and belong to `simulator`. Nothing GPL-derived may be reachable from here,
+ *      because this package is the one that can be licensed commercially.
+ *
+ * All three are enforced: `npm run lint` and `npm run check:boundaries`.
+ */
+
+import { DEFAULT_CONSTANTS as GENERATED, CONSTANTS_HASH, REFERENCE_DATA } from './constants/index.js';
+
+/**
+ * Keys `createModel` refuses. Derived from REFERENCE_DATA rather than listed by
+ * hand, so classifying a new block in the generator automatically protects it —
+ * a hand-written list would drift the moment someone added a bound.
+ * @type {string[]}
+ */
+const NEVER_INJECTABLE = Object.keys(REFERENCE_DATA);
+
+/**
+ * @typedef {Record<string, unknown> & { hash?: string }} Constants
+ */
+
+/**
+ * @typedef {Object} Model
+ * @property {Constants} constants   the resolved context, frozen
+ * @property {string} hash           identifies this context; differs for a counterfactual
+ * @property {() => {axialPrecessionPeriodYears: number, inclinationPrecessionPeriodYears: number, perihelionPrecessionPeriodYears: number}} computeLatticePeriodsYears
+ * @property {(year: number) => number} eccentricity
+ */
+
+/**
+ * Generated at build time from `public/input/{model-parameters,astro-reference}.json`
+ * (§2g) by `tools/constants/generate.mjs`. 324 values across 15 blocks.
+ *
+ * Free parameters and measured anchors only. Validation targets are excluded by
+ * the generator's CLASSIFICATION map, so a counterfactual cannot move the
+ * goalposts it is judged by (§2d).
+ * @type {Constants}
+ */
+export { GENERATED as DEFAULT_CONSTANTS, CONSTANTS_HASH };
+
+/**
+ * Validation targets and presentation data. Single-sourced so nothing keeps a
+ * duplicate copy, but NOT part of the model context — `createModel` refuses
+ * these keys (§2d).
+ */
+export { REFERENCE_DATA };
+
+/**
+ * Fitting-pipeline output at full precision, with its own hash (§2j).
+ * Not part of the injectable context: a counterfactual perturbs the parameters
+ * we chose, not the 2,400-term output of a fit.
+ */
+export { FITTED_COEFFICIENTS, COEFFICIENTS_HASH } from './constants/index.js';
+
+/**
+ * Phase 6 surface — the epoch layer. `createEpochPrimitives` + `deriveEpochParams`
+ * are what `src/script.js` and `tools/lib/deep-time.js` converge on: one
+ * derivation of the parameter bundle, one implementation of the chain. The
+ * browser imports these; the Node engine is held bit-identical by the layer0
+ * identity gate until Phase C rewrites it as an adapter.
+ */
+export { createEpochPrimitives } from './layer0/index.js';
+export { deriveEpochParams } from './layer0/derive-params.js';
+export { createDerivedViews } from './layer1/index.js';
+// Phase 7 — the shared integrated-phase and cardinal-point machinery (CJS on
+// purpose: tools/lib requires the same files via the exports-map subpaths;
+// re-exported here so bundled ESM consumers need only the package root).
+export { createPhaseMachinery } from './phase/index.cjs';
+export { createCardinalModel } from './cardinal/index.cjs';
+// Phase 8.2 — the lunar machinery, extracted layer by layer (survey order:
+// eccentricity channel → month chain → cycle tables → arguments → series →
+// apparent). Same CJS + root re-export convention.
+export { createMoonEccChannel } from './moon/ecc-channel.cjs';
+export { createMoonMonthChain } from './moon/month-chain.cjs';
+export { createChainCycleIntegrator } from './chain-cycles/index.cjs';
+export { createMoonArguments } from './moon/arguments.cjs';
+export { createMoonSeries } from './moon/series.cjs';
+export { createMoonApparent } from './moon/apparent.cjs';
+// Phase 8.3 — the planet machinery, extracted by LAW over body records
+// (survey order: geometry → Fibonacci laws → channels → chains → corrections).
+export { derivePlanetGeometry } from './planets/geometry.cjs';
+export * as planetFibonacciLaws from './planets/fibonacci-laws.cjs';
+export { eccentricityFromCycles, computeEccentricityIntegrated } from './planets/ecc-channel.cjs';
+export * as planetOrientation from './planets/orientation.cjs';
+export { integrateAscendingNode } from './planets/asc-node-integrator.cjs';
+export * as planetOrbitChain from './planets/orbit-chain.cjs';
+export { evaluateParallaxBasis, gravitationTermDeltasDeg, evaluateElongationBasis } from './planets/corrections.cjs';
+export { createPredictivePrecession, calcPlanetPerihelionLongDeg } from './planets/predict.cjs';
+// L10 — the composition front door: one law set, N body records. Thin by
+// design; engines keep their direct call sites (see planets/model.cjs).
+export { createPlanetModel } from './planets/model.cjs';
+// Phase 8.4 — the climate/ΔT machinery, extracted layer by layer.
+export { createDeltaTCycles } from './deltat/cycles.cjs';
+export { createDeepTimeLod } from './deltat/deep-time.cjs';
+export { deltaTEspenakMeeusCanonSeconds } from './deltat/historical.cjs';
+export { evalClimateL1OrbitalPermil } from './climate/l1-orbital.cjs';
+// Phase 8.5 — eclipse geometry (single-copy: the browser had no Node twin).
+export { createEclipseFinders } from './eclipse/finders.cjs';
+// Phase 8.6 — the published reference curves (external comparison formulas
+// and datasets, exactly as published; comparison references, never inputs).
+export * as publishedCurves from './reference/published-curves.cjs';
+// Phase 9 — S-P8: the fitted sun-longitude harmonic stack (three copies → one).
+export { createSunLongitudeCorrection } from './sun/longitude-correction.cjs';
+
+/**
+ * Build a model bound to a set of constants.
+ *
+ * Dependency injection rather than import is the key decision (§2d): it is what
+ * makes `createModel({ ...DEFAULT_CONSTANTS, neptuneMassRatio: x })` express a
+ * counterfactual. Retrofitting it later is prohibitive, so the shape lands now
+ * even though the body is empty.
+ *
+ * @param {Constants} [constants]
+ * @returns {Model}
+ */
+export const createModel = (constants = GENERATED) => {
+  // Validation targets are not merely absent from DEFAULT_CONSTANTS — they are
+  // REFUSED here. Absence alone only stops the spread form
+  // `{...DEFAULT_CONSTANTS, x}`; nothing stopped a caller passing a bound
+  // explicitly. Saturn fails its Laplace-Lagrange bound in verify-laws (44/45),
+  // and a counterfactual that could widen that bound would be measuring itself.
+  for (const key of NEVER_INJECTABLE) {
+    if (constants && Object.prototype.hasOwnProperty.call(constants, key)) {
+      throw new Error(
+        `physics: "${key}" is a validation target and cannot be injected (§2d). `
+        + 'It is exported as REFERENCE_DATA, which createModel does not accept — '
+        + 'a counterfactual must not be able to move the goalposts it is judged by.',
+      );
+    }
+  }
+
+  // Test the ARGUMENT, not the copy. `ctx` below is a fresh frozen object, so
+  // `ctx === GENERATED` is never true and the fast path never fired — every
+  // call fell through to isDefault(), which serialises the whole context twice.
+  // Harmless at 10 KB (~0.4 ms); ruinous once the fitted coefficients arrive,
+  // which are ~400 KB.
+  const isGeneratedDefault = constants === GENERATED;
+
+  const ctx = Object.freeze({ ...constants });
+
+  // The hash identifies THIS context, not the default one. A counterfactual
+  // that reported the default hash would be unreproducible — you could not tell
+  // from a stored result which constants produced it, which is the whole point
+  // of carrying a hash (§2d). Recomputed rather than copied for that reason.
+  //
+  // isDefault() still runs for a caller who passes a value-identical COPY
+  // (`{...DEFAULT_CONSTANTS}`); only the identity case is short-circuited.
+  const hash = isGeneratedDefault || isDefault(ctx) ? CONSTANTS_HASH : hashOf(ctx);
+
+  return {
+    constants: ctx,
+    hash,
+
+    /**
+     * H-lattice periods — the structural identities, in years.
+     *
+     * PURE ALGEBRA OVER THE CONTEXT. No epoch, no formula, no fit. These are
+     * the divisor relationships H/13, H/3, H/16 that define the lattice, and
+     * they exist here in Phase 5 for one reason: a hash-only counterfactual
+     * test would still pass if `createModel` ignored its argument entirely.
+     * Something has to READ the context and return a number for injection to be
+     * demonstrated end to end.
+     *
+     * The motion model is Phase 6. This is not it.
+     *
+     * `divisor` and `period` are never interchangeable (CLAUDE.md): 13 is the
+     * divisor, H/13 years is the period. The names say which.
+     *
+     * @returns {{axialPrecessionPeriodYears: number, inclinationPrecessionPeriodYears: number, perihelionPrecessionPeriodYears: number}}
+     */
+    computeLatticePeriodsYears: () => {
+      const H = /** @type {{holisticyearLength: number}} */ (
+        /** @type {Record<string, unknown>} */ (ctx).foundational
+      ).holisticyearLength;
+      return {
+        axialPrecessionPeriodYears: H / 13,
+        inclinationPrecessionPeriodYears: H / 3,
+        perihelionPrecessionPeriodYears: H / 16,
+      };
+    },
+
+    /**
+     * @param {number} year
+     * @returns {number}
+     */
+    eccentricity: (year) => {
+      void year; void ctx;
+      throw new Error('physics: not implemented until Phase 6 — see IP-technical-design.md §6');
+    },
+  };
+};
+
+/**
+ * Key-sorted canonical form, so the digest depends on values and not on
+ * property insertion order — `{...DEFAULT, x}` and `{x, ...DEFAULT}` describe
+ * the same counterfactual and must hash alike.
+ *
+ * @param {unknown} v
+ * @returns {unknown}
+ */
+const canonical = (v) => {
+  if (Array.isArray(v)) return v.map(canonical);
+  if (v && typeof v === 'object') {
+    const o = /** @type {Record<string, unknown>} */ (v);
+    return Object.fromEntries(Object.keys(o).sort().filter((k) => k !== 'hash').map((k) => [k, canonical(o[k])]));
+  }
+  return v;
+};
+
+/**
+ * @param {Constants} ctx
+ * @returns {boolean} true when ctx is value-identical to the generated set
+ */
+const isDefault = (ctx) =>
+  JSON.stringify(canonical(ctx)) === JSON.stringify(canonical(GENERATED));
+
+/**
+ * FNV-1a over the canonical form. Not cryptographic and does not need to be —
+ * it distinguishes constant sets, it does not authenticate them. `node:crypto`
+ * is unavailable here by design: physics imports no Node builtins (§2b),
+ * because it runs in a browser too.
+ *
+ * @param {Constants} ctx
+ * @returns {string} 16 hex chars, prefixed to mark it as a derived context
+ */
+const hashOf = (ctx) => {
+  const s = JSON.stringify(canonical(ctx));
+  let h1 = 0x811c9dc5;
+  let h2 = 0x01000193;
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0;
+    h2 = Math.imul(h2 ^ c, 0x85ebca6b) >>> 0;
+  }
+  return `cf-${h1.toString(16).padStart(8, '0')}${h2.toString(16).padStart(8, '0')}`;
+};

package/src/layer0/derive-params.js

@@ -0,0 +1,85 @@
+/**
+ * Derive the Layer 0 parameter bundle from raw catalogue constants.
+ *
+ * Mirrors `tools/lib/deep-time.js` lines ~60–101 OPERATION FOR OPERATION —
+ * grouping, order, the speed-of-light fallback ternary, all of it. Floating
+ * point is not associative, so "algebraically the same" is not the standard
+ * here; bit-identical is, and the layer0 identity test compares every field of
+ * this function's output against the values deep-time.js derives internally.
+ * If the two ever disagree, one of them changed and the other did not — which
+ * is the exact drift mode that produced five diverging implementations.
+ *
+ * Pure function, imports nothing. Lives in physics so the browser and the Node
+ * engine can both build Layer 0 from ONE derivation (deep-time.js keeps its
+ * own inline copy only until Phase C rewrites it; until then the test is the
+ * enforcement).
+ */
+
+/**
+ * @typedef {Object} RawEpochConstants
+ * @property {number} solarLuminosityW          IAU 2015 nominal (W)
+ * @property {number} solarWindKgPerS           Ulysses/ACE/Wind
+ * @property {number} speedOfLightKmPerS        km/s (fallback 299792458 m/s if falsy)
+ * @property {number} alpha1PerMa
+ * @property {number} alpha3PerMa3
+ * @property {number} alpha4PerMa4
+ * @property {number} holisticYearJ2000         H
+ * @property {number} meanSiderealYearSeconds
+ * @property {number} meanSiderealYearDaysKinematic
+ * @property {number} sunMassKg                 M_SUN
+ * @property {number} gmEarthAloneKm3S2
+ * @property {number} gmMoonAloneKm3S2
+ * @property {number} gravitationalConstantKm3KgS2
+ * @property {number} earthMoiFactorJ2000
+ * @property {number} earthDiameterKm
+ * @property {number} moonDistanceKm
+ * @property {number} moonOrbitalEccentricity
+ * @property {number} gmEarthMoonSystemKm3S2
+ */
+
+/**
+ * @param {RawEpochConstants} raw
+ * @returns {import('./index.js').EpochParams}
+ */
+export const deriveEpochParams = (raw) => {
+  // Solar physics — Driver 2 mass loss
+  const cSiMPerS = raw.speedOfLightKmPerS ? raw.speedOfLightKmPerS * 1000 : 299792458;
+  const dmDtTotalKgS = raw.solarLuminosityW / (cSiMPerS * cSiMPerS) + raw.solarWindKgPerS;
+
+  // J2000 anchors derived from framework constants
+  const lodNowH13Seconds = raw.meanSiderealYearSeconds / raw.meanSiderealYearDaysKinematic;
+  const solarMassLossFracPerYear = dmDtTotalKgS * raw.meanSiderealYearSeconds / raw.sunMassKg;
+
+  // Earth mass, moments
+  const earthMassKg = raw.gmEarthAloneKm3S2 / raw.gravitationalConstantKm3KgS2;
+  const moonMassKg = raw.gmMoonAloneKm3S2 / raw.gravitationalConstantKm3KgS2;
+  const earthRadiusM = (raw.earthDiameterKm / 2) * 1000;
+  const iEarthJ2000 = raw.earthMoiFactorJ2000 * earthMassKg * earthRadiusM * earthRadiusM;
+
+  // Moon constants
+  const moonDistanceNowM = raw.moonDistanceKm * 1000;
+  const moonEccentricityFactor = Math.sqrt(1 - raw.moonOrbitalEccentricity * raw.moonOrbitalEccentricity);
+  const gmEarthMoonM3S2 = raw.gmEarthMoonSystemKm3S2 * 1e9;
+  const totalAngularMomentumKgM2S = (iEarthJ2000 * 2 * Math.PI / lodNowH13Seconds)
+    + (moonMassKg * Math.sqrt(gmEarthMoonM3S2 * moonDistanceNowM) * moonEccentricityFactor);
+  const moonLockDistanceM = (totalAngularMomentumKgM2S / (moonMassKg * Math.sqrt(gmEarthMoonM3S2) * moonEccentricityFactor)) ** 2;
+
+  return Object.freeze({
+    epochYear: 2000,
+    alpha1PerMa: raw.alpha1PerMa,
+    alpha3PerMa3: raw.alpha3PerMa3,
+    alpha4PerMa4: raw.alpha4PerMa4,
+    moonDistanceNowM,
+    moonLockDistanceM,
+    totalAngularMomentumKgM2S,
+    moonMassKg,
+    gmEarthMoonM3S2,
+    moonEccentricityFactor,
+    earthMassKg,
+    earthRadiusM,
+    holisticYearJ2000: raw.holisticYearJ2000,
+    lodNowH13Seconds,
+    siderealYearJ2000Seconds: raw.meanSiderealYearSeconds,
+    solarMassLossFracPerYear,
+  });
+};