Opposite pulses and two energy ledgers

/**
 * Kernel function: evaluates the moving-frame pulse energies and their angle-invariant sum (Paper 4, §1 & Paper 3, §8).
 * Pulse 1: (L/2) * gamma * (1 - beta * cos(phi))
 * Pulse 2: (L/2) * gamma * (1 + beta * cos(phi))
 * Sum: gamma * L
 */
export function evaluatePulseEnergies(
  emittedEnergyRestFrame: number,
  frameSpeed: number,
  emissionAngleRad: number,
): Readonly<{
  lorentzFactor: number;
  pulse1Moving: number;
  pulse2Moving: number;
  pulseSumMoving: number;
  pulseEnergyRatio: number;
  dopplerFrequencyRatio: number;
}> {
  const g = 1 / Math.sqrt(1 - frameSpeed * frameSpeed);
  const halfL = emittedEnergyRestFrame / 2;
  const cosPhi = Math.cos(emissionAngleRad);
  const factor1 = 1 - frameSpeed * cosPhi;
  const factor2 = 1 + frameSpeed * cosPhi;
  const p1 = halfL * g * factor1;
  const p2 = halfL * g * factor2;
  const sum = g * emittedEnergyRestFrame;
  const ratio = factor1 / factor2;
  return Object.freeze({
    lorentzFactor: g,
    pulse1Moving: p1,
    pulse2Moving: p2,
    pulseSumMoving: sum,
    pulseEnergyRatio: ratio,
    dopplerFrequencyRatio: ratio,
  });
}

/**
 * Kernel function: evaluates the rest-frame and moving-frame energy balances (Paper 4, §1).
 * Rest frame balance: E0 - E1 = L
 * Moving frame balance: H0 - H1 = gamma * L
 */
export function evaluateLedgers(
  emittedEnergyRestFrame: number,
  frameSpeed: number,
  _emissionAngleRad: number,
  initialBodyEnergy?: MassEnergyLedgerSeed,
): Readonly<{
  restBalanceLight: number;
  movingBalanceLight: number;
  lorentzFactor: number;
}> {
  if (initialBodyEnergy !== undefined) {
    initializeMassEnergyLedger({ restEnergyBefore: initialBodyEnergy });
  }
  const g = 1 / Math.sqrt(1 - frameSpeed * frameSpeed);
  return Object.freeze({
    restBalanceLight: emittedEnergyRestFrame,
    movingBalanceLight: g * emittedEnergyRestFrame,
    lorentzFactor: g,
  });
}

/**
 * Kernel function: evaluates the subtraction move (H0 - E0) - (H1 - E1) and the resulting kinetic energy difference (Paper 4, §1).
 * Subtraction: (H0 - E0) - (H1 - E1) = L * (gamma - 1)
 * If premise === "unchanged": K0 - K1 = L * (gamma - 1)
 */
export function evaluateSubtraction(
  emittedEnergyRestFrame: number,
  frameSpeed: number,
  _emissionAngleRad: number,
  premise: Me01Premise = "unchanged",
): Readonly<{
  subtractionValue: number;
  lorentzFactor: number;
  kineticDifference: number | null;
  premise: Me01Premise;
}> {
  const g = 1 / Math.sqrt(1 - frameSpeed * frameSpeed);
  // Reuse the cancellation-free owner: gamma - 1 rounds to zero at walking speeds.
  const difference = gammaMinusOne(frameSpeed);
  if (difference.status !== "value") {
    throw new RangeError("Subtraction requires a finite subluminal observer speed.");
  }
  const sub = emittedEnergyRestFrame * difference.value;
  return Object.freeze({
    subtractionValue: sub,
    lorentzFactor: g,
    kineticDifference: premise === "unchanged" ? sub : null,
    premise,
  });
}

/**
 * Validates and initializes the mass-energy ledger.
 *
 * Enforces the non-circularity doctrine (Paper 4 / AGENTS.md):
 * The mass-energy ledger must NEVER initialise a body's energy with Mc^2 or gamma Mc^2.
 * Rest energy and moving body energy on the historical route must remain symbolic (E₀, H₀).
 * Any attempt to seed the ledger with Mc^2 or gamma Mc^2 is rejected with an Error.
 */
export function initializeMassEnergyLedger(
  seed?: MassEnergyLedgerInit,
): InitializedMassEnergyLedger {
  const isNumericValue = (val: unknown): boolean => {
    if (val === undefined || val === null) return false;
    if (typeof val === "number" && Number.isFinite(val)) return true;
    if (typeof val === "string") {
      const trimmed = val.trim();
      if (trimmed !== "" && !Number.isNaN(Number(trimmed))) return true;
    }
    if (typeof val === "object") {
      const rec = val as Record<string, unknown>;
      if (typeof rec.value === "number" && Number.isFinite(rec.value)) return true;
      if (rec.kind === "numeric" || rec.kind === "value") return true;
      if (typeof rec.numericFrom === "string") return true;
    }
    return false;
  };

  const isCircular = (val: unknown): boolean => {
    if (val === undefined || val === null) return false;
    if (typeof val === "string") {
      const lower = val.toLowerCase().replace(/[\s_*^·×-]/g, "");
      if (
        lower.includes("mc2") ||
        lower.includes("mc²") ||
        lower.includes("gammamc") ||
        lower.includes("γmc") ||
        lower.includes("mc^2")
      ) {
        return true;
      }
    }
    if (typeof val === "object") {
      const rec = val as Record<string, unknown>;
      if (rec.numericFrom === "mc2" || rec.numericFrom === "gamma-mc2") return true;
      if (typeof rec.formula === "string" && isCircular(rec.formula)) return true;
      if (typeof rec.id === "string" && isCircular(rec.id)) return true;
      if (typeof rec.kind === "string" && isCircular(rec.kind)) return true;
      if (typeof rec.expr === "string" && isCircular(rec.expr)) return true;
    }
    return false;
  };

  if (isCircular(seed?.restEnergyBefore) || isCircular(seed?.movingEnergyBefore)) {
    throw new MassEnergyError(
      "absolute-energy-not-admitted",
      "Circularity violation: the mass-energy ledger must NEVER initialise a body's energy with Mc^2 or gamma Mc^2.",
    );
  }

  if (seed?.historicalMode !== false) {
    if (isNumericValue(seed?.restEnergyBefore) || isNumericValue(seed?.movingEnergyBefore)) {
      throw new MassEnergyError(
        "absolute-energy-not-admitted",
        "Supplying a numeric absolute rest energy in the historical model is rejected. Rest and moving energies must remain symbolic.",
      );
    }
  }

  return Object.freeze({
    restBodyBefore: asSymbolic(
      "bodyEnergyRestBefore",
      "J",
      "rest-body-energy-before",
      "massEnergy.restBodyBefore",
      "E₀",
    ),
    restBodyAfter: asSymbolic(
      "bodyEnergyRestAfter",
      "J",
      "rest-body-energy-after",
      "massEnergy.restBodyAfter",
      "E₁",
    ),
    movingBodyBefore: asSymbolic(
      "bodyEnergyMovingBefore",
      "J",
      "moving-body-energy-before",
      "massEnergy.movingBodyBefore",
      "H₀",
    ),
    movingBodyAfter: asSymbolic(
      "bodyEnergyMovingAfter",
      "J",
      "moving-body-energy-after",
      "massEnergy.movingBodyAfter",
      "H₁",
    ),
  });
}