@essrt/physics 4.7.0 → 4.9.0

package/README.md

@@ -34,6 +34,10 @@ const { createEclipseFinders } = require('@essrt/physics/eclipse/finders');
 const { createPredictivePrecession } = require('@essrt/physics/planets/predict');
 ```
 
+**TypeScript**: the package ships declaration files (`types/`, one per
+subpath export) generated from the sources' JSDoc — `import` from
+`@essrt/physics` or any subpath is fully typed; no ambient shim needed.
+
 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,

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@essrt/physics",
-  "version": "4.7.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.",
+  "version": "4.9.0",
+  "description": "ESSRT (Expanding Solar System Resonance Theory) physics core — 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": "v13.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."
+    "_note": "The model identity this package version ships (IP-unified-architecture §10: 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",
+  "types": "types/index.d.ts",
   "files": [
     "src",
+    "types",
     "README.md"
   ],
   "repository": {
@@ -28,41 +30,41 @@
     "geocentric-model"
   ],
   "exports": {
-    ".": "./src/index.js",
-    "./phase": "./src/phase/index.cjs",
-    "./cardinal": "./src/cardinal/index.cjs",
-    "./cardinal/one-source-structure": "./src/cardinal/one-source-structure.cjs",
-    "./moon/ecc-channel": "./src/moon/ecc-channel.cjs",
-    "./moon/deep-ecc-channel": "./src/moon/deep-ecc-channel.cjs",
-    "./moon/deep-modes-artifact": "./src/moon/deep-modes-artifact.cjs",
-    "./earth/deep-orbital-history": "./src/earth/deep-orbital-history.cjs",
-    "./earth/sidereal-year-channel": "./src/earth/sidereal-year-channel.cjs",
-    "./earth/year-lengths": "./src/earth/year-lengths.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/series-extension": "./src/moon/series-extension.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/keplerian-chain": "./src/planets/keplerian-chain.cjs",
-    "./planets/inv-plane-frame": "./src/planets/inv-plane-frame.cjs",
-    "./planets/secular-series": "./src/planets/secular-series.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",
-    "./deltat/recession-history": "./src/deltat/recession-history.cjs",
-    "./climate/l1-orbital": "./src/climate/l1-orbital.cjs",
-    "./eclipse/finders": "./src/eclipse/finders.cjs",
-    "./eclipse/sun-planetary-completion": "./src/eclipse/sun-planetary-completion.cjs",
-    "./sun/longitude-correction": "./src/sun/longitude-correction.cjs"
+    ".": { "types": "./types/index.d.ts", "default": "./src/index.js" },
+    "./phase": { "types": "./types/phase/index.d.cts", "default": "./src/phase/index.cjs" },
+    "./cardinal": { "types": "./types/cardinal/index.d.cts", "default": "./src/cardinal/index.cjs" },
+    "./cardinal/one-source-structure": { "types": "./types/cardinal/one-source-structure.d.cts", "default": "./src/cardinal/one-source-structure.cjs" },
+    "./moon/ecc-channel": { "types": "./types/moon/ecc-channel.d.cts", "default": "./src/moon/ecc-channel.cjs" },
+    "./moon/deep-ecc-channel": { "types": "./types/moon/deep-ecc-channel.d.cts", "default": "./src/moon/deep-ecc-channel.cjs" },
+    "./moon/deep-modes-artifact": { "types": "./types/moon/deep-modes-artifact.d.cts", "default": "./src/moon/deep-modes-artifact.cjs" },
+    "./earth/deep-orbital-history": { "types": "./types/earth/deep-orbital-history.d.cts", "default": "./src/earth/deep-orbital-history.cjs" },
+    "./earth/sidereal-year-channel": { "types": "./types/earth/sidereal-year-channel.d.cts", "default": "./src/earth/sidereal-year-channel.cjs" },
+    "./earth/year-lengths": { "types": "./types/earth/year-lengths.d.cts", "default": "./src/earth/year-lengths.cjs" },
+    "./moon/month-chain": { "types": "./types/moon/month-chain.d.cts", "default": "./src/moon/month-chain.cjs" },
+    "./chain-cycles": { "types": "./types/chain-cycles/index.d.cts", "default": "./src/chain-cycles/index.cjs" },
+    "./moon/arguments": { "types": "./types/moon/arguments.d.cts", "default": "./src/moon/arguments.cjs" },
+    "./moon/series": { "types": "./types/moon/series.d.cts", "default": "./src/moon/series.cjs" },
+    "./moon/series-extension": { "types": "./types/moon/series-extension.d.cts", "default": "./src/moon/series-extension.cjs" },
+    "./moon/apparent": { "types": "./types/moon/apparent.d.cts", "default": "./src/moon/apparent.cjs" },
+    "./planets/geometry": { "types": "./types/planets/geometry.d.cts", "default": "./src/planets/geometry.cjs" },
+    "./planets/fibonacci-laws": { "types": "./types/planets/fibonacci-laws.d.cts", "default": "./src/planets/fibonacci-laws.cjs" },
+    "./planets/ecc-channel": { "types": "./types/planets/ecc-channel.d.cts", "default": "./src/planets/ecc-channel.cjs" },
+    "./planets/orientation": { "types": "./types/planets/orientation.d.cts", "default": "./src/planets/orientation.cjs" },
+    "./planets/asc-node-integrator": { "types": "./types/planets/asc-node-integrator.d.cts", "default": "./src/planets/asc-node-integrator.cjs" },
+    "./planets/orbit-chain": { "types": "./types/planets/orbit-chain.d.cts", "default": "./src/planets/orbit-chain.cjs" },
+    "./planets/keplerian-chain": { "types": "./types/planets/keplerian-chain.d.cts", "default": "./src/planets/keplerian-chain.cjs" },
+    "./planets/inv-plane-frame": { "types": "./types/planets/inv-plane-frame.d.cts", "default": "./src/planets/inv-plane-frame.cjs" },
+    "./planets/secular-series": { "types": "./types/planets/secular-series.d.cts", "default": "./src/planets/secular-series.cjs" },
+    "./planets/predict": { "types": "./types/planets/predict.d.cts", "default": "./src/planets/predict.cjs" },
+    "./planets/model": { "types": "./types/planets/model.d.cts", "default": "./src/planets/model.cjs" },
+    "./deltat/cycles": { "types": "./types/deltat/cycles.d.cts", "default": "./src/deltat/cycles.cjs" },
+    "./deltat/deep-time": { "types": "./types/deltat/deep-time.d.cts", "default": "./src/deltat/deep-time.cjs" },
+    "./deltat/historical": { "types": "./types/deltat/historical.d.cts", "default": "./src/deltat/historical.cjs" },
+    "./deltat/recession-history": { "types": "./types/deltat/recession-history.d.cts", "default": "./src/deltat/recession-history.cjs" },
+    "./climate/l1-orbital": { "types": "./types/climate/l1-orbital.d.cts", "default": "./src/climate/l1-orbital.cjs" },
+    "./eclipse/finders": { "types": "./types/eclipse/finders.d.cts", "default": "./src/eclipse/finders.cjs" },
+    "./eclipse/sun-planetary-completion": { "types": "./types/eclipse/sun-planetary-completion.d.cts", "default": "./src/eclipse/sun-planetary-completion.cjs" },
+    "./sun/longitude-correction": { "types": "./types/sun/longitude-correction.d.cts", "default": "./src/sun/longitude-correction.cjs" }
   },
   "license": "AGPL-3.0-or-later"
 }

package/src/chain-cycles/index.cjs

@@ -73,6 +73,29 @@ function createChainCycleIntegrator({
   /** @type {Map<PeriodSecondsAtAge, Float64Array | null>} */
   const tables = new Map();
 
+  // Exact-argument memo for the year-length integrand of the out-of-range
+  // Simpson fallback. Within one animation frame every integrator node
+  // (the six-plus Moon chains + the seven planets) integrates the SAME
+  // (anchor, currentYear) pair, so the Simpson sample lattice — and with
+  // it every tropicalYearSecondsAtAge(tMa) — repeats across chains, up to
+  // 13× per sample. Exact-key reuse returns the bit-identical value: pure
+  // dedupe, not a resolution change (the sampler-purity trap class is
+  // about grids serving NEARBY arguments; this serves only the same one).
+  // Bounded by wholesale clear — one frame's lattice is ≤ ~1025 entries.
+  /** @type {Map<number, number | null>} */
+  const yearSecondsMemo = new Map();
+  const YEAR_SECONDS_MEMO_CAP = 4096;
+  /** @param {number} tMa @returns {number | null} */
+  function tropicalYearSecondsMemo(tMa) {
+    let v = yearSecondsMemo.get(tMa);
+    if (v === undefined) {
+      v = tropicalYearSecondsAtAge(tMa);
+      if (yearSecondsMemo.size >= YEAR_SECONDS_MEMO_CAP) yearSecondsMemo.clear();
+      yearSecondsMemo.set(tMa, v);
+    }
+    return v;
+  }
+
   /** Lazy cumulative table for one chain; null when the chain is undefined
    *  anywhere in range (→ Simpson fallback).
    *  @param {PeriodSecondsAtAge} periodFnSeconds
@@ -167,7 +190,7 @@ function createChainCycleIntegrator({
       const tMa = (ageAnchorYear - y) / 1e6;
       const tPeriodS = periodFnSeconds(tMa);
       if (tPeriodS === null) return null;
-      const tYrS = tropicalYearSecondsAtAge(tMa);
+      const tYrS = tropicalYearSecondsMemo(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);