@essrt/physics 4.8.0 → 5.0.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.8.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": "5.0.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."
+    "modelVersion": "v14.0",
+    "_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,42 @@
     "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" },
+    "./earth/precession-composed": { "types": "./types/earth/precession-composed.d.cts", "default": "./src/earth/precession-composed.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/climate/l1-orbital.cjs

@@ -22,10 +22,11 @@
 
 /**
  * @typedef {Object} ClimateL1Regime
- * @property {Array<{n: number, a: number, b: number}>} l1Terms - 8H-lattice
- *   harmonics (n = cycles per 8H)
+ * @property {Array<{period_kyr: number, a: number, b: number}>} l1Terms - the
+ *   L1 lines: periods in kyr (the engine's own orbital lines + the 405-kyr
+ *   family — data/l1-physical-lines.json, ONE home) with fitted cos/sin
+ *   coefficients
  * @property {number} yStdDenormalization - the fit's y_std scale-back
- * @property {number} eightHKyr - 8H in kyr (the fit's period base)
  */
 
 /**
@@ -37,10 +38,80 @@ 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;
+    const omega = (2 * Math.PI) / c.period_kyr;
     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 };
+/**
+ * The GIA channel — the polar moment's LAGGED response to the ice history the
+ * L1 layer proxies (holisticuniverse plan 06, D7). The solid Earth responds to
+ * an ice load through the mantle's viscoelastic relaxation, so
+ *
+ *   α(t) = α₀ − k · [ L1(t) − ⟨L1⟩_τ(t) ]
+ *
+ * with ⟨L1⟩_τ the causal exponential average over the PAST (time constant τ).
+ * Every L1 line passes that filter as a line, Ĉ' = Ĉ · iωτ/(1 + iωτ) with
+ * Ĉ = a + ib in physical time, so the evaluator stays a sinusoid sum and each
+ * runtime's lattice-α pin and memo are untouched. k > 0 is the direct-load
+ * sign (an uncompensated ice load lowers α); after a rapid deglaciation
+ * L1 − ⟨L1⟩ < 0, α sits above equilibrium and relaxes for ~τ — today's
+ * −0.35 ms/cy non-tidal drift is that tail. k is DERIVED at construction so
+ * that dα/dt(J2000) equals the satellite-gravimetry rate (Cox & Chao 2002
+ * dJ₂/dt ÷ the Peltier J₂→α factor): no stored scale. τ was MEASURED against
+ * the historical ΔT record through the joint fitter (optimum 5–6 kyr,
+ * the degree-2 Maxwell estimate; plan 06 D7 record). Replaces the
+ * instantaneous α ∝ L1 law, which had the deglacial transient's sign and
+ * timing backwards and depended on fitted comb lines the T1 test retired.
+ *
+ * @param {Array<{period_kyr: number, a: number, b: number}>} l1Terms
+ * @param {number} relaxationKyr - τ in kyr
+ * @returns {Array<{period_kyr: number, a: number, b: number}>}
+ */
+function laggedL1Terms(l1Terms, relaxationKyr) {
+  return l1Terms.map((c) => {
+    const wt = ((2 * Math.PI) / c.period_kyr) * relaxationKyr;   // ωτ, dimensionless
+    const d = 1 + wt * wt;
+    const Hre = (wt * wt) / d, Him = wt / d;                     // H(ω) = iωτ / (1 + iωτ)
+    return { period_kyr: c.period_kyr, a: c.a * Hre - c.b * Him, b: c.a * Him + c.b * Hre };
+  });
+}
+
+/**
+ * @param {{
+ *   l1Terms: Array<{period_kyr: number, a: number, b: number}>,
+ *   yStdDenormalization: number,
+ *   relaxationKyr: number,
+ *   alphaGiaRateJ2000PerYr: number,
+ *   alphaJ2000: number,
+ * }} cfg - relaxationKyr and alphaGiaRateJ2000PerYr are model-parameters
+ *   deepTime constants; alphaJ2000 the IERS moment-of-inertia factor
+ * @returns {{
+ *   alphaAt: (year: number) => number,
+ *   laggedL1PermilAt: (year: number) => number,
+ *   kPerPermille: number,
+ *   relaxationKyr: number,
+ *   laggedL1Terms: Array<{period_kyr: number, a: number, b: number}>,
+ * }}
+ */
+function createAlphaGiaChannel({ l1Terms, yStdDenormalization, relaxationKyr, alphaGiaRateJ2000PerYr, alphaJ2000 }) {
+  const lagged = laggedL1Terms(l1Terms, relaxationKyr);
+  const regime = { l1Terms: lagged, yStdDenormalization };
+  // dL'/dyear at J2000 in closed form: with t = (2000 − year)/1000,
+  // d/dyear Σ[a cos ωt + b sin ωt] = −(1/1000)·Σ ω(−a sin ωt + b cos ωt) → at t = 0: −(1/1000)·Σ ω b
+  let sum = 0;
+  for (const c of lagged) sum += ((2 * Math.PI) / c.period_kyr) * c.b;
+  const slopeJ2000PermillePerYr = (-sum / 1000) * yStdDenormalization;
+  const kPerPermille = -alphaGiaRateJ2000PerYr / slopeJ2000PermillePerYr;   // dα/dt = −k · dL'/dt
+  const laggedJ2000 = evalClimateL1OrbitalPermil(2000, regime);
+  return {
+    alphaAt: (year) => alphaJ2000 - kPerPermille * (evalClimateL1OrbitalPermil(year, regime) - laggedJ2000),
+    laggedL1PermilAt: (year) => evalClimateL1OrbitalPermil(year, regime),
+    kPerPermille,
+    relaxationKyr,
+    laggedL1Terms: lagged,
+  };
+}
+
+module.exports = { evalClimateL1OrbitalPermil, laggedL1Terms, createAlphaGiaChannel };