@essrt/physics 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# @essrt/physics
+
+The physics core of **ESSRT** — the Expanding Solar System Resonance Theory —
+as implemented by the [Holistic Universe Model](https://3d.holisticuniverse.com)
+([source, AGPL-3.0](https://github.com/dvansonsbeek/3d)). Pure computation:
+no I/O, no globals, no DOM, constants injected. The package ships the
+**complete model**, including the fitted coefficients, so an installed copy
+reproduces the hosted simulator bit-for-bit on the shared golden masters.
+
+## Versioning — two axes, deliberately
+
+- **Package semver** (this package's `version`) tracks the **API axis** —
+  what `import` gives you.
+- **Model identity** rides *inside* every published version: the
+  `essrt.modelVersion` field in `package.json` plus `CONSTANTS_HASH` and
+  `COEFFICIENTS_HASH` in `src/constants/`. A refit or structural model
+  change always lands as a new package version — npm's immutability then
+  guarantees a pinned version's results never change.
+
+Cite results as *model vX.Y (package A.B.C)*.
+
+## Usage
+
+```js
+import { DEFAULT_CONSTANTS, FITTED_COEFFICIENTS, createEpochPrimitives } from '@essrt/physics';
+```
+
+Domain modules are CJS subpath exports, each a `create*` factory taking its
+dependencies explicitly (the injectable-constants design — counterfactual
+runs are first-class):
+
+```js
+const { createEclipseFinders } = require('@essrt/physics/eclipse/finders');
+const { createPredictivePrecession } = require('@essrt/physics/planets/predict');
+```
+
+See the `exports` map in `package.json` for the full surface: moon
+(arguments/series/apparent/ecc-channel/month-chain), planets (geometry,
+corrections, predict, model, fibonacci-laws, …), deltat (cycles, deep-time,
+historical), cardinal points, phase, chain-cycles, sun, climate, eclipse
+finders, and the published reference curves.
+
+## Provenance
+
+Every value derives from the model parameters and fitted coefficients in
+this package; the fitting pipeline, verification gates, dataset manifest and
+documentation live in the [public repository](https://github.com/dvansonsbeek/3d).
+Preprint: <https://doi.org/10.21203/rs.3.rs-8758810/v4>.
+
+## Licence
+
+AGPL-3.0-or-later. Commercial licensing: dennis@holisticuniverse.com.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@essrt/physics",
+  "version": "1.0.0",
+  "description": "ESSRT (Expanding Solar System Resonance Theory) physics core \u2014 pure, injectable-constants, no I/O, no globals, no DOM. The complete model incl. fitted coefficients; every published version immutably ships one recorded model identity.",
+  "essrt": {
+    "modelVersion": "v10.0",
+    "_note": "The model identity this package version ships (IP-unified-architecture \u00a710: package semver tracks the API axis; the model version + CONSTANTS_HASH/COEFFICIENTS_HASH in src/constants/ carry the scientific identity). The version-pinning gate enforces this pairing against public/input/model-version.json."
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dvansonsbeek/3d.git",
+    "directory": "packages/physics"
+  },
+  "homepage": "https://3d.holisticuniverse.com",
+  "keywords": [
+    "essrt",
+    "astronomy",
+    "solar-system",
+    "deep-time",
+    "eclipse",
+    "precession",
+    "geocentric-model"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./phase": "./src/phase/index.cjs",
+    "./cardinal": "./src/cardinal/index.cjs",
+    "./moon/ecc-channel": "./src/moon/ecc-channel.cjs",
+    "./moon/month-chain": "./src/moon/month-chain.cjs",
+    "./chain-cycles": "./src/chain-cycles/index.cjs",
+    "./moon/arguments": "./src/moon/arguments.cjs",
+    "./moon/series": "./src/moon/series.cjs",
+    "./moon/apparent": "./src/moon/apparent.cjs",
+    "./planets/geometry": "./src/planets/geometry.cjs",
+    "./planets/fibonacci-laws": "./src/planets/fibonacci-laws.cjs",
+    "./planets/ecc-channel": "./src/planets/ecc-channel.cjs",
+    "./planets/orientation": "./src/planets/orientation.cjs",
+    "./planets/asc-node-integrator": "./src/planets/asc-node-integrator.cjs",
+    "./planets/orbit-chain": "./src/planets/orbit-chain.cjs",
+    "./planets/corrections": "./src/planets/corrections.cjs",
+    "./planets/predict": "./src/planets/predict.cjs",
+    "./planets/model": "./src/planets/model.cjs",
+    "./deltat/cycles": "./src/deltat/cycles.cjs",
+    "./deltat/deep-time": "./src/deltat/deep-time.cjs",
+    "./deltat/historical": "./src/deltat/historical.cjs",
+    "./climate/l1-orbital": "./src/climate/l1-orbital.cjs",
+    "./eclipse/finders": "./src/eclipse/finders.cjs",
+    "./reference/published-curves": "./src/reference/published-curves.cjs",
+    "./sun/longitude-correction": "./src/sun/longitude-correction.cjs"
+  },
+  "license": "AGPL-3.0-or-later"
+}

package/src/cardinal/index.cjs

@@ -0,0 +1,323 @@
+/**
+ * Cardinal-point model — THE shared implementation (Phase 7.2).
+ *
+ * The §10 derived form and everything on it, extracted verbatim from
+ * tools/lib/orbital-engine.js (which the browser mirrored function-for-
+ * function — this file replaces both copies):
+ *
+ *   JD_X(Y)  = anchor_X + ΣT_trop(Y) + δ_X(Y) − δ_X(2000)
+ *   ΣT_trop  = lincoef·(Y−2000) + driftTerm(Y) + Ih(Y)
+ *   δ_X      = sinusoids + equation-of-centre orders (e(t)ⁿ·sin(nM), e(t)
+ *              the LAW OF COSINES) + §10g quadrature-locked joint sidebands
+ *   T_X(Y)   = the EXACT term-by-term derivative of JD_X
+ *
+ * LOAD-BEARING, do not "improve":
+ *  - lincoef/h0/h1 come from the fit and are used VERBATIM — recomputing
+ *    lincoef from the 1-year anchor injects a −12,276 s ramp; holding H
+ *    constant inside Ih costs up to 5.2 s (§10c/§10e-quinquies).
+ *  - The drift term is Simpson on 2000-yr NODE SPACING (not a fixed node
+ *    count: that was exact in-window and −33,758 s at −380 Ma) plus the
+ *    Euler–Maclaurin endpoint term (omitting it costs 6–13 s).
+ *  - The equation-of-centre terms are {order,sin,cos}, NOT sinusoids — read
+ *    as H/16+H/32 harmonics they are wrong by the whole ~1.78 d braid.
+ *  - §10g joint sidebands are SHARED across the four points with phase
+ *    order·λ_X − 2π·div·c — COUNTER-rotating. The minus sign is load-bearing:
+ *    the co-rotating sense captures NOTHING (measured — the sign experiment,
+ *    doc 99 "the braid law").
+ *  - The year-length derivative keeps ONE deliberate divergence from the
+ *    exact derivative: its drift part uses the real-LOD convention
+ *    (`meanYearRealLodDays`) — the tweakpane's epoch-local days ("~400 days
+ *    at the Devonian") — where the JD form integrates the SI form. Equal at
+ *    J2000 up to the known 118 ms fit-basis gap.
+ *
+ * The `cyclesBetween` the caller injects is the ENGINE'S OWN function, so
+ * each engine's deep-time/snapshot toggle semantics are preserved exactly;
+ * under deep time both engines now route it through @essrt/physics/phase.
+ */
+
+'use strict';
+
+/** @type {Record<string, number>} */
+const JOINT_LAMBDA = { SS: 0, AE: Math.PI / 2, WS: Math.PI, VE: 1.5 * Math.PI };
+
+const DRIFT_NODE_SPACING_YEARS = 2000;
+const DRIFT_SIMPSON_N_MIN = 64;
+
+/** @typedef {{ lincoef: number, h0: number, h1: number }} DerivedCoefs */
+/** @typedef {{ order: number, sin: number, cos: number }} EccTerm */
+/** @typedef {{ order: number, div: number, sin: number, cos: number }} JointTerm */
+
+/**
+ * @param {{
+ *   isDeepTime: () => boolean,
+ *   constants: {
+ *     anchors: Record<string, number>,
+ *     harmonics: Record<string, Array<[number, number, number]>>,
+ *     eccTerms: (Record<string, EccTerm[]> | null),
+ *     jointTerms: ({ terms: JointTerm[] } | null),
+ *     derived: (DerivedCoefs | null),
+ *     tropicalHarmonics: Array<[number, number, number]>,
+ *     balancedYear: number,
+ *     meanSolarYearDays: number,
+ *     hJ2000: number,
+ *     eccentricityBase: number,
+ *     eccentricityAmplitude: number,
+ *     tiltMeanDeg: number,
+ *     raAngleDeg: number,
+ *     inclAmplitudeDeg: number,
+ *   },
+ *   fns: {
+ *     cyclesBetween: (yearA: number, yearB: number, divisorN: number) => (number | null),
+ *     analyticTropicalDays: (year: number) => (number | null),
+ *     meanHAtAgeMa: (tMa: number) => (number | null),
+ *     meanYearRealLodDays: (tMa: number) => (number | null),
+ *     eccentricityAt: (year: number) => number,
+ *   },
+ * }} deps
+ */
+function createCardinalModel({ isDeepTime, constants, fns }) {
+  const {
+    anchors,               // { SS, WS, VE, AE } — J2000 event JDs
+    harmonics,             // { type: [[div, sin, cos], …] } — δ sinusoids
+    eccTerms,              // { type: [{order, sin, cos}, …] } | null
+    jointTerms,            // { terms: [{order, div, sin, cos}, …] } | null
+    derived,               // { lincoef, h0, h1 } — fit-calibrated, VERBATIM
+    tropicalHarmonics,     // TROPICAL_YEAR_HARMONICS [[div, sin, cos], …]
+    balancedYear,
+    meanSolarYearDays,
+    hJ2000,
+    eccentricityBase,
+    eccentricityAmplitude,
+    tiltMeanDeg,           // for RA
+    raAngleDeg,
+    inclAmplitudeDeg,
+  } = constants;
+  const {
+    cyclesBetween,         // (yearA, yearB, divisorN) => cycles | null
+    analyticTropicalDays,  // (year) => SI days | null — the drift integrand base
+    meanHAtAgeMa,          // (t_Ma) => H | null — the derivative's dc/dY
+    meanYearRealLodDays,   // (t_Ma) => days | null — real-LOD drift convention
+    eccentricityAt,        // (year) => e(t), law of cosines on the H/16 phase
+  } = fns;
+
+  /** @param {number} year */
+  const cycleOf = (year) => {
+    const c = cyclesBetween(balancedYear, year, 1);
+    return c === null ? 0 : c;
+  };
+
+  /** @param {number} year */
+  const driftIntegrand = (year) => {
+    const a = analyticTropicalDays(year);
+    return a === null ? 0 : (a - meanSolarYearDays);
+  };
+
+  /** @param {number} year */
+  function driftTerm(year) {
+    const span = year - 2000;
+    if (span === 0) return 0;
+    let n = Math.ceil(Math.abs(span) / DRIFT_NODE_SPACING_YEARS);
+    if (n % 2) n++;
+    if (n < DRIFT_SIMPSON_N_MIN) n = DRIFT_SIMPSON_N_MIN;
+    const h = span / n;
+    const f0 = driftIntegrand(2000), fN = driftIntegrand(year);
+    let acc = f0 + fN;
+    for (let i = 1; i < n; i++) acc += driftIntegrand(2000 + i * h) * ((i % 2) ? 4 : 2);
+    return acc * h / 3 - (fN - f0) / 2;
+  }
+
+  /** Step 6d's self-corrected tropical harmonic series, as a length deviation.
+   *  @param {number} year */
+  function tropHarmonicsAt(year) {
+    const c = cycleOf(year), c0 = cycleOf(2000);
+    let s = 0;
+    for (const [div, sinC, cosC] of tropicalHarmonics) {
+      const th = 2 * Math.PI * div * c, th0 = 2 * Math.PI * div * c0;
+      s += sinC * (Math.sin(th) - Math.sin(th0)) + cosC * (Math.cos(th) - Math.cos(th0));
+    }
+    return s;
+  }
+
+  // Ih(Y) = Σ_{2000→Y} of the tropical harmonics, closed form. H stays INSIDE
+  // the integral (h0 + h1·c) — it moves 27.5 yr across the window and
+  // multiplies the amplitude. Deep-time only, so `derived` is present here.
+  /** @param {number} year */
+  function integratedTropHarmonics(year) {
+    const D = /** @type {DerivedCoefs} */ (derived);
+    const cY = cycleOf(year), c0 = cycleOf(2000);
+    let tot = 0, k0 = 0;
+    for (const [div, sinC, cosC] of tropicalHarmonics) {
+      const k = 2 * Math.PI * div;
+      /** @param {number} c */
+      const F = (c) => {
+        const sn = Math.sin(k * c), cs = Math.cos(k * c), Hc = D.h0 + D.h1 * c;
+        return [-Hc * cs / k + D.h1 * sn / (k * k), Hc * sn / k + D.h1 * cs / (k * k)];
+      };
+      const a = F(c0), b = F(cY);
+      tot += sinC * (b[0] - a[0]) + cosC * (b[1] - a[1]);
+      k0 += sinC * Math.sin(k * c0) + cosC * Math.cos(k * c0);
+    }
+    return tot - k0 * (year - 2000)
+         - (tropHarmonicsAt(year) - tropHarmonicsAt(2000)) / 2;
+  }
+
+  /** @param {number} year */
+  function sigmaTropical(year) {
+    const D = /** @type {DerivedCoefs} */ (derived);
+    return D.lincoef * (year - 2000) + driftTerm(year) + integratedTropHarmonics(year);
+  }
+
+  // δ_X(2000) — the self-correction that pins JD(2000) to the anchor exactly
+  // (sinusoids + ecc orders; the §10g joint terms self-correct inline).
+  // Computed lazily so the phase table builds on the caller's schedule.
+  /** @type {Record<string, number> | null} */
+  let _selfCorr = null;
+  function selfCorr() {
+    if (_selfCorr !== null) return _selfCorr;
+    _selfCorr = {};
+    const c2000 = cycleOf(2000);
+    for (const type of ['SS', 'WS', 'VE', 'AE']) {
+      let h2000 = 0;
+      for (const [div, sinC, cosC] of harmonics[type]) {
+        const th0 = 2 * Math.PI * div * c2000;
+        h2000 += sinC * Math.sin(th0) + cosC * Math.cos(th0);
+      }
+      const ecc = eccTerms && eccTerms[type];
+      if (ecc) {
+        const e0 = eccentricityAt(2000);
+        const th0 = 2 * Math.PI * 16 * c2000;
+        for (const t of ecc) {
+          const eN0 = Math.pow(e0, t.order);
+          h2000 += t.sin * eN0 * Math.sin(t.order * th0) + t.cos * eN0 * Math.cos(t.order * th0);
+        }
+      }
+      _selfCorr[type] = h2000;
+    }
+    return _selfCorr;
+  }
+
+  /** @param {number} year @param {string} [type] */
+  function computeSolsticeJD(year, type) {
+    const cp = type || 'SS';
+    const anchor = anchors[cp];
+    const deep = isDeepTime();
+
+    let jd = deep
+      ? anchor + sigmaTropical(year)
+      : anchor + meanSolarYearDays * (year - 2000);
+
+    const cY = cycleOf(year);
+    for (const [div, sinC, cosC] of harmonics[cp]) {
+      jd += sinC * Math.sin(2 * Math.PI * div * cY) + cosC * Math.cos(2 * Math.PI * div * cY);
+    }
+    const ecc = eccTerms && eccTerms[cp];
+    if (ecc) {
+      const e = eccentricityAt(year);
+      const th = 2 * Math.PI * 16 * cY;
+      for (const t of ecc) {
+        const eN = Math.pow(e, t.order);
+        jd += t.sin * eN * Math.sin(t.order * th) + t.cos * eN * Math.cos(t.order * th);
+      }
+    }
+    if (jointTerms) {
+      const lam = JOINT_LAMBDA[cp];
+      const c2000 = cycleOf(2000);
+      for (const t of jointTerms.terms) {
+        const th  = t.order * lam - 2 * Math.PI * t.div * cY;
+        const th0 = t.order * lam - 2 * Math.PI * t.div * c2000;
+        jd += t.sin * (Math.sin(th) - Math.sin(th0)) + t.cos * (Math.cos(th) - Math.cos(th0));
+      }
+    }
+    jd -= selfCorr()[cp];
+    return jd;
+  }
+
+  /** The EXACT term-by-term derivative of computeSolsticeJD — except the
+   *  drift part, which deliberately stays in the real-LOD convention (see
+   *  the file header). Neglected: the drift Euler–Maclaurin half-sample
+   *  term's own derivative (f′/2, sub-µs).
+   *  @param {number} year @param {string} [type] */
+  function computeSolsticeYearLength(year, type) {
+    const cp = type || 'SS';
+    const deep = isDeepTime();
+    const t_Ma = (2000 - year) / 1e6;
+
+    const H_at = deep ? (meanHAtAgeMa(t_Ma) ?? hJ2000) : hJ2000;
+    const dcdY = 1 / H_at;
+    const cY = cycleOf(year);
+
+    let length;
+    if (deep && derived) {
+      length = derived.lincoef;
+      const mSY_at = meanYearRealLodDays(t_Ma);
+      if (mSY_at !== null) length += (mSY_at - meanSolarYearDays);
+      length += tropHarmonicsAt(year);
+      let dTrop = 0;
+      for (const [div, sinC, cosC] of tropicalHarmonics) {
+        const k = 2 * Math.PI * div, th = k * cY;
+        dTrop += k * dcdY * (sinC * Math.cos(th) - cosC * Math.sin(th));
+      }
+      length -= dTrop / 2;
+    } else {
+      length = meanSolarYearDays;
+    }
+
+    for (const [div, sinC, cosC] of harmonics[cp]) {
+      const k = 2 * Math.PI * div, th = k * cY;
+      length += k * dcdY * (sinC * Math.cos(th) - cosC * Math.sin(th));
+    }
+
+    const ecc = eccTerms && eccTerms[cp];
+    if (ecc) {
+      const th16 = 2 * Math.PI * 16 * cY;
+      const thp = 2 * Math.PI * 16 * dcdY;
+      const e = eccentricityAt(year);
+      const de = eccentricityBase * eccentricityAmplitude * Math.sin(th16) * thp / e;
+      for (const t of ecc) {
+        const n = t.order, nth = n * th16;
+        const eN = Math.pow(e, n), eN1 = Math.pow(e, n - 1);
+        length += t.sin * (n * eN1 * de * Math.sin(nth) + eN * n * thp * Math.cos(nth))
+                + t.cos * (n * eN1 * de * Math.cos(nth) - eN * n * thp * Math.sin(nth));
+      }
+    }
+
+    if (jointTerms) {
+      const lam = JOINT_LAMBDA[cp];
+      for (const t of jointTerms.terms) {
+        const k = 2 * Math.PI * t.div;
+        const th = t.order * lam - k * cY;
+        length += k * dcdY * (-t.sin * Math.cos(th) + t.cos * Math.sin(th));
+      }
+    }
+    return length;
+  }
+
+  /** RA where a cardinal point occurs — fully derived, zero fitted constants.
+   *  INTEGRATED phase: the formula describes where the SCENE puts the point,
+   *  and the scene's H/3 and H/8 objects rotate on integrated phase.
+   *  @param {number} year @param {string} [type] */
+  function computeSolsticeRA(year, type) {
+    const sinE = Math.sin(tiltMeanDeg * Math.PI / 180);
+    const baseRA = /** @type {Record<string, number>} */ ({ SS: 90, WS: 270, VE: 0, AE: 180 })[type || 'SS'];
+    const raMean = baseRA - raAngleDeg / sinE;
+    const amp = inclAmplitudeDeg / sinE;
+    const cY = cycleOf(year);
+    const phase3 = 2 * Math.PI * 3 * cY;
+    const phase8 = 2 * Math.PI * 8 * cY;
+    return raMean + amp * (-Math.sin(phase3) + Math.sin(phase8));
+  }
+
+  /** Tropical year as the mean of the four cardinal intervals — the
+   *  physically correct definition (Σδ_X ≡ 0 makes the braid cancel).
+   *  @param {number} year */
+  function computeTropicalYearLength(year) {
+    return (computeSolsticeYearLength(year, 'SS') +
+            computeSolsticeYearLength(year, 'WS') +
+            computeSolsticeYearLength(year, 'VE') +
+            computeSolsticeYearLength(year, 'AE')) / 4;
+  }
+
+  return { computeSolsticeJD, computeSolsticeYearLength, computeSolsticeRA, computeTropicalYearLength };
+}
+
+module.exports = { createCardinalModel, JOINT_LAMBDA };

package/src/chain-cycles/index.cjs

@@ -0,0 +1,189 @@
+/**
+ * Generic chain-cycle integrator — THE shared implementation (Phase 8.2-4).
+ *
+ * Counts cycles of any evolving period T(t) between two calendar years:
+ * ∫ (T_yr_SI / T_period_SI)(y) dy. Serves every Moon scene-graph chain
+ * (tropical month, perigee/node precession, the beat cycles) AND the seven
+ * planet OrbitalCyclesBetween functions — it is chain-generic, keyed by the
+ * period function's identity.
+ *
+ * Extracted VERBATIM from src/script.js _moonCycleTable/_moonCycleTableAt/
+ * _moonChainCycles, which tools/lib/scene-graph.js mirrored. Three mirror
+ * gaps closed by this move (each measured against the lunar golden masters):
+ *
+ *  - S5: the snapshot branch (deep-time OFF → linear at the J2000 rate),
+ *    the memoized periodFn(0), and the bounded FIFO cache existed only in
+ *    the browser. They are the implementation now; the Node engine gains
+ *    them (its snapshot semantics thereby ALIGN with the browser's).
+ *  - S12: the browser maps year → age with ageAnchorYear = startmodelYear
+ *    (2000.5, the scene's t_Ma convention) while the tools mirror used a
+ *    literal 2000 — a half-year skew in the integrand argument. The anchor
+ *    is INJECTED; both engines pass startmodelYear (the certified browser
+ *    convention).
+ *  - The cumulative table stays anchored C(gridAnchorYear) = 0 at calendar
+ *    2000 (NOT 2000.5) in both engines — grid anchor and age anchor are two
+ *    different constants, deliberately (cf. the phase machinery's
+ *    tableAnchorYear vs driftRefYear pair).
+ *
+ * NUMERICS ARE LOAD-BEARING: fixed 10-yr grid over ±250 kyr, per-cell
+ * 3-point Simpson at build, LINEAR interpolation on read; adaptive Simpson
+ * (~1 sample/kyr, n ∈ [32, 1024], even) as the out-of-range fallback. The
+ * table replaced the per-call Simpson for in-range spans (the L-4
+ * 92 s/century full-canon regression); an "analytically better" integrator
+ * here would detach the runtime from the certified numbers.
+ */
+
+'use strict';
+
+/**
+ * @typedef {(tMa: number) => (number | null)} PeriodSecondsAtAge
+ */
+
+/**
+ * @param {{
+ *   ageAnchorYear: number,
+ *   tropicalYearSecondsAtAge: (tMa: number) => (number | null),
+ *   tropicalYearJ2000Seconds: number,
+ *   isDeepTime: () => boolean,
+ *   gridMinYear?: number,
+ *   gridMaxYear?: number,
+ *   gridStepYears?: number,
+ *   gridAnchorYear?: number,
+ *   maxCacheEntries?: number,
+ * }} deps — ageAnchorYear is the year whose age is 0 in the period
+ *   functions' t_Ma coordinate (startmodelYear = 2000.5, the certified
+ *   convention); tropicalYearJ2000Seconds feeds the snapshot branch;
+ *   isDeepTime is read PER CALL so the engine's runtime toggle works.
+ */
+function createChainCycleIntegrator({
+  ageAnchorYear,
+  tropicalYearSecondsAtAge,
+  tropicalYearJ2000Seconds,
+  isDeepTime,
+  gridMinYear = 2000 - 250000,
+  gridMaxYear = 2000 + 250000,
+  gridStepYears = 10,
+  gridAnchorYear = 2000,
+  maxCacheEntries = 512,
+}) {
+  /** @type {WeakMap<PeriodSecondsAtAge, Map<string, number>>} */
+  const caches = new WeakMap();
+  /** @type {WeakMap<PeriodSecondsAtAge, number>} */
+  const j2000Periods = new WeakMap();       // memoized periodFn(0)
+  /** @type {Map<PeriodSecondsAtAge, Float64Array | null>} */
+  const tables = new Map();
+
+  /** Lazy cumulative table for one chain; null when the chain is undefined
+   *  anywhere in range (→ Simpson fallback).
+   *  @param {PeriodSecondsAtAge} periodFnSeconds
+   *  @returns {Float64Array | null} */
+  function table(periodFnSeconds) {
+    let tab = tables.get(periodFnSeconds);
+    if (tab !== undefined) return tab;
+    const N = Math.round((gridMaxYear - gridMinYear) / gridStepYears);
+    const cum = new Float64Array(N + 1);
+    const anchorIdx = Math.round((gridAnchorYear - gridMinYear) / gridStepYears);
+    /** @param {number} y @returns {number | null} */
+    const f = (y) => {
+      const tMa = (ageAnchorYear - y) / 1e6;
+      const tPeriodS = periodFnSeconds(tMa);
+      if (tPeriodS === null) return null;
+      const tYrS = tropicalYearSecondsAtAge(tMa);
+      return tYrS === null ? null : tYrS / tPeriodS;
+    };
+    let ok = true;
+    let fPrev = f(gridMinYear);
+    for (let i = 1; i <= N; i++) {
+      const fMid = f(gridMinYear + (i - 0.5) * gridStepYears);
+      const fCur = f(gridMinYear + i * gridStepYears);
+      if (fPrev === null || fMid === null || fCur === null) { ok = false; break; }
+      cum[i] = cum[i - 1] + (fPrev + 4 * fMid + fCur) * (gridStepYears / 6);
+      fPrev = fCur;
+    }
+    if (ok) {
+      const c0 = cum[anchorIdx];
+      for (let i = 0; i <= N; i++) cum[i] -= c0;   // anchor C(gridAnchorYear) = 0
+      tab = cum;
+    } else {
+      tab = null;
+    }
+    tables.set(periodFnSeconds, tab);
+    return tab;
+  }
+
+  /** @param {Float64Array} tab @param {number} y @returns {number} */
+  function tableAt(tab, y) {
+    const idxF = (y - gridMinYear) / gridStepYears;
+    const i = Math.floor(idxF);
+    return tab[i] + (idxF - i) * (tab[i + 1] - tab[i]);
+  }
+
+  /** Cycles of the chain between two calendar years. Snapshot mode: linear
+   *  at the J2000 rate. Deep time: table lookup in ±range, adaptive Simpson
+   *  beyond. null past the tidal-lock asymptote.
+   *  @param {PeriodSecondsAtAge} periodFnSeconds
+   *  @param {number} yearA @param {number} yearB
+   *  @returns {number | null} */
+  function cyclesBetween(periodFnSeconds, yearA, yearB) {
+    const dy = yearB - yearA;
+    if (dy === 0) return 0;
+
+    let tJ2000 = j2000Periods.get(periodFnSeconds);
+    if (tJ2000 === undefined) {
+      const t0 = periodFnSeconds(0);
+      if (t0 === null) return null;
+      tJ2000 = t0;
+      j2000Periods.set(periodFnSeconds, tJ2000);
+    }
+
+    if (!isDeepTime()) {
+      return dy * tropicalYearJ2000Seconds / tJ2000;
+    }
+
+    // Cumulative-table fast path (deterministic, call-order independent)
+    if (yearA > gridMinYear && yearA < gridMaxYear && yearB > gridMinYear && yearB < gridMaxYear) {
+      const tab = table(periodFnSeconds);
+      if (tab !== null) return tableAt(tab, yearB) - tableAt(tab, yearA);
+    }
+
+    let cache = caches.get(periodFnSeconds);
+    if (!cache) {
+      cache = new Map();
+      caches.set(periodFnSeconds, cache);
+    }
+    const cacheKey = yearA + '|' + yearB;
+    const hit = cache.get(cacheKey);
+    if (hit !== undefined) return hit;
+
+    // Adaptive Simpson: ~1 sample per 1 kyr, capped at 1024 to bound per-call cost.
+    let n = Math.max(32, Math.ceil(Math.abs(dy) / 1000));
+    if (n > 1024) n = 1024;
+    if (n % 2 === 1) n++;
+    const h = dy / n;
+
+    let sum = 0;
+    for (let i = 0; i <= n; i++) {
+      const y = yearA + i * h;
+      const tMa = (ageAnchorYear - y) / 1e6;
+      const tPeriodS = periodFnSeconds(tMa);
+      if (tPeriodS === null) return null;
+      const tYrS = tropicalYearSecondsAtAge(tMa);
+      if (tYrS === null) return null;
+      const integrand = tYrS / tPeriodS;  // cycles per SI year
+      const w = (i === 0 || i === n) ? 1 : (i % 2 === 1 ? 4 : 2);
+      sum += w * integrand;
+    }
+    const result = (sum * h) / 3;
+
+    if (cache.size >= maxCacheEntries) {
+      const firstKey = cache.keys().next().value;
+      cache.delete(/** @type {string} */ (firstKey));
+    }
+    cache.set(cacheKey, result);
+    return result;
+  }
+
+  return { cyclesBetween };
+}
+
+module.exports = { createChainCycleIntegrator };

package/src/climate/l1-orbital.cjs

@@ -0,0 +1,46 @@
+/**
+ * Climate Formula L1 orbital layer — THE shared evaluator (Phase 8.4,
+ * slice 4). The δ¹⁸O contribution from the L1 (orbital/Milankovitch)
+ * harmonic layer only, in ‰ — excludes the intercept, L2 (405-kyr
+ * carbon), L3 (regime steps), y_mean, and trend_slope: consumers want
+ * the orbital FLUCTUATION around J2000, not the secular baseline.
+ *
+ * Primary consumer: the GIA α(t) chain — one physical mechanism, two
+ * observables: the same L1 signal that fits δ¹⁸O also drives α via
+ * Milankovitch forcing → ice sheets → GIA J₂/α → LOD (doc 99
+ * §prediction-7). Both engines hand-mirrored this loop; it lives once
+ * now.
+ *
+ * ENGINE-SIDE, by design: the regime selection (CLIMATE_FORMULA_COEFFS
+ * lookup, the ALPHA_CLIMATE_REGIME_KEY choice), the α formula itself
+ * (one subtraction around engine state), and the lattice-α pin machinery
+ * (_withLatticeAlpha — mutable engine state with try/finally semantics
+ * and, in the browser, a TDZ-history guard).
+ */
+
+'use strict';
+
+/**
+ * @typedef {Object} ClimateL1Regime
+ * @property {Array<{n: number, a: number, b: number}>} l1Terms - 8H-lattice
+ *   harmonics (n = cycles per 8H)
+ * @property {number} yStdDenormalization - the fit's y_std scale-back
+ * @property {number} eightHKyr - 8H in kyr (the fit's period base)
+ */
+
+/**
+ * @param {number} year - calendar year
+ * @param {ClimateL1Regime} regime
+ * @returns {number} L1 orbital δ¹⁸O contribution, ‰
+ */
+function evalClimateL1OrbitalPermil(year, regime) {
+  const t_kyr_BP = (2000 - year) / 1000;
+  let L1_sum = 0;
+  for (const c of regime.l1Terms) {
+    const omega = 2 * Math.PI * c.n / regime.eightHKyr;
+    L1_sum += c.a * Math.cos(omega * t_kyr_BP) + c.b * Math.sin(omega * t_kyr_BP);
+  }
+  return L1_sum * regime.yStdDenormalization;
+}
+
+module.exports = { evalClimateL1OrbitalPermil };