@essrt/physics 2.5.0 → 3.0.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@essrt/physics",
-  "version": "2.5.0",
+  "version": "3.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": "v12.0",
+    "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."
   },
   "type": "module",

package/src/constants/generated.js

@@ -35,7 +35,7 @@
 export const CONSTANTS_HASH = "ffbce6e075ca2f25";
 
 /** Model version label — single source: public/input/model-version.json (§10 two-axis scheme). */
-export const MODEL_VERSION = "v12.0";
+export const MODEL_VERSION = "v13.0";
 
 /** Canonical preprint DOI — single source: public/input/model-version.json. */
 export const PREPRINT_DOI = "10.21203/rs.3.rs-8758810/v4";

package/src/index.js

@@ -145,9 +145,11 @@ export { createSunLongitudeCorrection } from './sun/longitude-correction.cjs';
  * even though the body is empty.
  *
  * @param {Constants} [constants]
+ * @param {{ laws?: { eccentricityAt?: (year: number) => number, eccentricityRateAt?: (year: number) => number, perihelionLongitudeDegAt?: (year: number) => number } }} [opts]
+ *   `laws` — research overrides for Earth's orbit laws (doc 109 §7); absent = the shipped laws, bit-identical. Not part of the hash.
  * @returns {Model}
  */
-export const createModel = (constants = GENERATED) => {
+export const createModel = (constants = GENERATED, opts = {}) => {
   // 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
@@ -183,7 +185,9 @@ export const createModel = (constants = GENERATED) => {
 
   // The §7a assembly: every factory wired from THIS context, so counterfactual
   // constants flow through the entire motion model.
-  const surfaces = assembleModel(ctx, FITTED);
+  // opts.laws — research overrides for Earth's orbit laws (see assembleModel);
+  // absent = the shipped laws, bit-identical. Never part of the hash.
+  const surfaces = assembleModel(ctx, FITTED, opts.laws ?? {});
 
   return {
     constants: ctx,

package/src/model.js

@@ -65,9 +65,16 @@ const MOON_ECC_SENSITIVITY_NODE = 1.018;
  *
  * @param {Readonly<Record<string, any>>} C  the frozen constants context
  * @param {Readonly<Record<string, any>>} F  the fitted coefficients
+ * @param {{ eccentricityAt?: (year: number) => number, eccentricityRateAt?: (year: number) => number, perihelionLongitudeDegAt?: (year: number) => number }} [laws]
+ *   RESEARCH OVERRIDES for Earth's orbit laws (doc 109 §7): an alternative e(t),
+ *   de/dt(t) and ϖ_of-date(t) flow through every consumer (the eclipse Sun, the
+ *   Moon's E-factor, the cardinal points) exactly as the shipped laws do. Default
+ *   {} = the shipped laws, bit-identical to before this parameter existed. Not a
+ *   counterfactual in the §2d sense (no hash change) — callers must say when
+ *   they used it; the generators refuse to --write under an override.
  * @returns the assembled surfaces (epoch, earth, lengths, cardinal, moon) — type inferred so ReturnType stays precise
  */
-export function assembleModel(C, F) {
+export function assembleModel(C, F, laws = {}) {
   // ── Derived constants (constants.js §9 order) ─────────────────────────────
   const H = C.foundational.holisticyearLength;
   const meanSolarYearDays = Math.round(C.foundational.inputmeanlengthsolaryearindays * (H / 8)) / (H / 8);
@@ -290,14 +297,14 @@ export function assembleModel(C, F) {
 
   // ── Earth scalars (integrated-phase display semantics) ────────────────────
   /** @param {number} year @returns {number} */
-  const earthPerihelionDeg = (year) => {
+  const earthPerihelionDeg = laws.perihelionLongitudeDegAt ?? ((year) => {
     let longitude = 270.0 + 360.0 * cyclesBetween(balancedYear, year, 16);
     for (const [div, sinC, cosC] of F.PERI_HARMONICS_RAW) {
       const ph = phaseRadians(balancedYear, year, div);
       longitude += sinC * Math.sin(ph) + cosC * Math.cos(ph);
     }
     return (((longitude + F.PERI_OFFSET) % 360) + 360) % 360;
-  };
+  });
   /** @param {number} year @returns {number} */
   const obliquityDeg = (year) => {
     let obliq = solsticeObliquityMean;
@@ -343,10 +350,10 @@ export function assembleModel(C, F) {
     eccentricityJ2000: C.earthOrbital.earthEccentricityJ2000,
   });
   /** @param {number} year @returns {number} */
-  const eccentricityAt = (year) => moonEcc.eccAt(year - 2000);
+  const eccentricityAt = laws.eccentricityAt ?? ((year) => moonEcc.eccAt(year - 2000));
   /** de/dyear of the one law — the cardinal braid's equation-of-centre
    *  derivative rides it. @param {number} year @returns {number} */
-  const eccentricityRateAt = (year) => moonEcc.eccRateAt(year - 2000);
+  const eccentricityRateAt = laws.eccentricityRateAt ?? ((year) => moonEcc.eccRateAt(year - 2000));
   /** @param {number} year @returns {number} */
   const inclinationDeg = (year) => earthInclMean
     - earthInclAmplitude * Math.cos(phaseRadians(balancedYear, year, 3));