@actuarial-ts/core 0.2.0 → 0.4.0

package/src/odpBootstrap.ts

@@ -0,0 +1,337 @@
+import type { Triangle } from "./types.js";
+import { ReservingError } from "./types.js";
+import { isNum, lastObservedIndex } from "./util.js";
+import { cumulativeToIncremental } from "./triangleAlgebra.js";
+import {
+  createRng,
+  summarizeSample,
+  type StochasticResult,
+} from "./stochastic.js";
+
+/**
+ * Over-dispersed Poisson (ODP) bootstrap of the chain ladder.
+ *
+ * Ground truth (England & Verrall 1999/2002; Shapland, CAS Monograph No. 4):
+ * - The cross-classified ODP GLM's fitted values reproduce the all-year
+ *   volume-weighted chain ladder EXACTLY. In practice the fitted past
+ *   incrementals come from the backwards recursion: anchor each row's
+ *   latest observed cumulative, divide back through the volume-weighted
+ *   factors, and difference.
+ * - Unscaled Pearson residuals r = (q - m) / sqrt(m) on incrementals; the
+ *   scale parameter is phi = sum(r^2) / (n - p) with p = 2I - 1 parameters for
+ *   an I-origin triangle and n = the incrementals that CONTRIBUTE a residual.
+ *   On a well-behaved triangle that is every observed incremental, but a
+ *   non-positive fitted mean leaves the residual undefined: such a cell is
+ *   absent from the numerator, so counting it in the denominator would divide
+ *   the sum of squares by degrees of freedom it never earned.
+ * - Resampling: draw residuals with replacement onto the fitted past
+ *   (q* = m + r sqrt(m)), cumulate, refit volume-weighted factors, project
+ *   each future incremental, and add process variance by sampling
+ *   Gamma(mean m_f, variance phi m_f). Residuals are inflated by
+ *   sqrt(n / (n - p)) first (the standard small-sample bias adjustment) —
+ *   controllable via options.
+ * - Structural zero residuals (cells the fit reproduces exactly by
+ *   construction, e.g. the corners) are excluded from the resampling pool.
+ *
+ * The GLM-mean == chain-ladder identity is the method's own validation
+ * hook: `odpFit(tri).reserveByOrigin` must tie to the volume-weighted
+ * chain ladder to floating-point precision, and the test suite pins it.
+ */
+
+export interface OdpFit {
+  /** Volume-weighted all-year factors, one per development interval. */
+  factors: number[];
+  /** Fitted past incrementals m_ij (null where unobserved). */
+  fittedIncrementals: (number | null)[][];
+  /** Unscaled Pearson residuals (null where unobserved or structurally zero). */
+  residuals: (number | null)[][];
+  /** Future incremental means per cell (null where already observed). */
+  futureMeans: (number | null)[][];
+  /** Expected unpaid per origin (== volume-weighted chain ladder reserve). */
+  reserveByOrigin: { origin: string; reserve: number }[];
+  phi: number;
+  /** Incrementals contributing a residual — the dispersion's numerator count. */
+  n: number;
+  /** Fitted parameters, 2I - 1 for an I-origin triangle. */
+  p: number;
+  /** Residuals actually in the resampling pool (structural zeros excluded). */
+  poolSize: number;
+  warnings: string[];
+}
+
+/** Volume-weighted all-year factors (the ODP GLM's implied development). */
+function volumeWeightedFactors(tri: Triangle): number[] {
+  const K = tri.ages.length;
+  const out: number[] = [];
+  for (let j = 0; j < K - 1; j++) {
+    let num = 0;
+    let den = 0;
+    for (let i = 0; i < tri.origins.length; i++) {
+      const c0 = tri.values[i]![j] ?? null;
+      const c1 = tri.values[i]![j + 1] ?? null;
+      if (isNum(c0) && isNum(c1) && c0 > 0) {
+        num += c1;
+        den += c0;
+      }
+    }
+    if (den <= 0) {
+      throw new ReservingError(
+        "NO_FACTOR",
+        `Development column ${tri.ages[j]}-${tri.ages[j + 1]} has no usable factors for the ODP fit`,
+      );
+    }
+    out.push(num / den);
+  }
+  return out;
+}
+
+/** Fits the ODP cross-classified model via the chain-ladder equivalence. */
+export function odpFit(tri: Triangle): OdpFit {
+  const warnings: string[] = [];
+  const I = tri.origins.length;
+  const K = tri.ages.length;
+  if (I < 3 || K < 3) {
+    throw new ReservingError("TOO_SMALL", "The ODP bootstrap needs at least a 3x3 triangle");
+  }
+  const factors = volumeWeightedFactors(tri);
+  const incr = cumulativeToIncremental(tri);
+
+  // Backwards recursion for fitted past cumulatives, anchored at each row's
+  // latest observed diagonal.
+  const fittedCum: (number | null)[][] = tri.origins.map(() => new Array(K).fill(null));
+  const latestIdx: number[] = [];
+  for (let i = 0; i < I; i++) {
+    const d = lastObservedIndex(tri.values[i]!);
+    latestIdx.push(d);
+    if (d < 0) {
+      warnings.push(`Origin ${tri.origins[i]} has no observed cells; excluded from the fit`);
+      continue;
+    }
+    const anchor = tri.values[i]![d]!;
+    fittedCum[i]![d] = anchor;
+    for (let j = d - 1; j >= 0; j--) {
+      fittedCum[i]![j] = fittedCum[i]![j + 1]! / factors[j]!;
+    }
+  }
+
+  // Fitted past incrementals.
+  const fittedIncrementals: (number | null)[][] = fittedCum.map((row, i) => {
+    const d = latestIdx[i]!;
+    return row.map((v, j) => {
+      if (j > d || !isNum(v)) return null;
+      if (j === 0) return v;
+      return v - row[j - 1]!;
+    });
+  });
+
+  // Pearson residuals; structural zeros (|q - m| ~ 0 at machine precision
+  // where the fit reproduces the cell by construction) leave the pool.
+  const residuals: (number | null)[][] = tri.origins.map(() => new Array(K).fill(null));
+  let n = 0;
+  let sumSq = 0;
+  let pool = 0;
+  let negativeFitted = 0;
+  for (let i = 0; i < I; i++) {
+    for (let j = 0; j <= latestIdx[i]!; j++) {
+      const q = incr.values[i]![j] ?? null;
+      const m = fittedIncrementals[i]![j] ?? null;
+      if (!isNum(q) || !isNum(m)) continue;
+      if (m <= 0) {
+        // The Pearson residual (q - m)/sqrt(m) is undefined for a non-positive
+        // fitted mean, so this cell contributes nothing to `sumSq` — and must
+        // therefore not count toward the degrees of freedom that divide it.
+        // Counting it would inflate `n - p`, understating phi and with it the
+        // process variance, which is the wrong direction for a reserve range.
+        negativeFitted++;
+        continue;
+      }
+      n++;
+      const r = (q - m) / Math.sqrt(m);
+      sumSq += r * r;
+      if (Math.abs(r) > 1e-10) {
+        residuals[i]![j] = r;
+        pool++;
+      } else {
+        residuals[i]![j] = 0; // structural zero: reported, not resampled
+      }
+    }
+  }
+  if (negativeFitted > 0) {
+    warnings.push(
+      `${negativeFitted} fitted incremental(s) are non-positive; their residuals are undefined and excluded (see Shapland on negative incrementals)`,
+    );
+  }
+  const p = 2 * I - 1;
+  if (n <= p) {
+    throw new ReservingError(
+      "TOO_SMALL",
+      `The ODP fit has ${n} usable residual(s) for ${p} parameters; no degrees of ` +
+        `freedom remain to estimate dispersion` +
+        (negativeFitted > 0
+          ? ` (${negativeFitted} cell(s) were excluded for a non-positive fitted mean)`
+          : ""),
+    );
+  }
+  const phi = sumSq / (n - p);
+
+  // Future incremental means from the fitted projection.
+  const futureMeans: (number | null)[][] = tri.origins.map(() => new Array(K).fill(null));
+  const reserveByOrigin: { origin: string; reserve: number }[] = [];
+  for (let i = 0; i < I; i++) {
+    const d = latestIdx[i]!;
+    if (d < 0) continue;
+    let cum = tri.values[i]![d]!;
+    let reserve = 0;
+    for (let j = d + 1; j < K; j++) {
+      const next = cum * factors[j - 1]!;
+      const m = next - cum;
+      futureMeans[i]![j] = m;
+      reserve += m;
+      cum = next;
+    }
+    reserveByOrigin.push({ origin: tri.origins[i]!, reserve });
+  }
+
+  return {
+    factors,
+    fittedIncrementals,
+    residuals,
+    futureMeans,
+    reserveByOrigin,
+    phi,
+    n,
+    p,
+    poolSize: pool,
+    warnings,
+  };
+}
+
+export interface OdpBootstrapOptions {
+  nSims: number;
+  seed: number;
+  /** Inflate residuals by sqrt(n/(n-p)) before resampling (default true). */
+  biasAdjust?: boolean;
+  /** Add ODP process variance via gamma sampling (default true). */
+  processVariance?: boolean;
+}
+
+export interface OdpBootstrapResult extends StochasticResult {
+  method: "odpBootstrap";
+  fit: OdpFit;
+}
+
+/** The ODP bootstrap. Same seed + same triangle = same result, bit for bit. */
+export function runOdpBootstrap(tri: Triangle, options: OdpBootstrapOptions): OdpBootstrapResult {
+  const { nSims, seed } = options;
+  if (!Number.isInteger(nSims) || nSims < 100) {
+    throw new ReservingError("TOO_SMALL", "The bootstrap needs an integer nSims >= 100");
+  }
+  const biasAdjust = options.biasAdjust ?? true;
+  const processVariance = options.processVariance ?? true;
+
+  const fit = odpFit(tri);
+  const warnings = [...fit.warnings];
+  const I = tri.origins.length;
+  const K = tri.ages.length;
+  const rng = createRng(seed);
+
+  // Residual pool (bias-adjusted), flattened.
+  const inflate = biasAdjust ? Math.sqrt(fit.n / (fit.n - fit.p)) : 1;
+  const pool: number[] = [];
+  for (const row of fit.residuals) {
+    for (const r of row) {
+      if (isNum(r) && Math.abs(r) > 1e-10) pool.push(r * inflate);
+    }
+  }
+  if (pool.length < 10) {
+    throw new ReservingError("TOO_SMALL", "Fewer than 10 usable residuals; bootstrap unreliable");
+  }
+
+  const latestIdx = tri.values.map((row) => lastObservedIndex(row));
+  let negativeFutureMeans = 0;
+
+  const totals: number[] = new Array(nSims).fill(0);
+  const perOrigin: number[][] = tri.origins.map(() => new Array(nSims).fill(0));
+
+  for (let b = 0; b < nSims; b++) {
+    // 1. Pseudo past incrementals -> pseudo cumulative triangle.
+    const pseudoCum: (number | null)[][] = tri.origins.map(() => new Array(K).fill(null));
+    for (let i = 0; i < I; i++) {
+      let running = 0;
+      for (let j = 0; j <= latestIdx[i]!; j++) {
+        const m = fit.fittedIncrementals[i]![j];
+        if (!isNum(m) || m <= 0) {
+          // Cells without a usable fitted value keep their mean contribution.
+          running += isNum(m) ? m : 0;
+        } else {
+          const r = pool[Math.floor(rng.next() * pool.length)]!;
+          running += m + r * Math.sqrt(m);
+        }
+        pseudoCum[i]![j] = running;
+      }
+    }
+    const pseudo: Triangle = {
+      kind: tri.kind,
+      origins: tri.origins,
+      ages: tri.ages,
+      values: pseudoCum,
+    };
+
+    // 2. Refit and project; 3. process variance on each future incremental.
+    let factors: number[];
+    try {
+      factors = volumeWeightedFactors(pseudo);
+    } catch {
+      // A pathological resample (non-positive column volume) is discarded by
+      // reusing the fitted factors; counted and warned once at the end.
+      factors = fit.factors;
+      negativeFutureMeans++;
+    }
+    for (let i = 0; i < I; i++) {
+      const d = latestIdx[i]!;
+      if (d < 0) continue;
+      let cum = pseudoCum[i]![d]!;
+      let reserve = 0;
+      for (let j = d + 1; j < K; j++) {
+        const next = cum * factors[j - 1]!;
+        let m = next - cum;
+        if (processVariance) {
+          if (m > 0) {
+            // Gamma with mean m, variance phi m.
+            m = rng.gamma(m / fit.phi) * fit.phi;
+          } else if (m < 0) {
+            negativeFutureMeans++;
+          }
+        }
+        reserve += m;
+        // The projection chain advances on the mean path; process noise is
+        // per-cell around the mean (England & Verrall 2002, Appendix 3).
+        cum = next;
+      }
+      perOrigin[i]![b] = reserve;
+      totals[b]! += reserve;
+    }
+  }
+  if (negativeFutureMeans > 0) {
+    warnings.push(
+      `${negativeFutureMeans} simulated future incremental(s)/resample(s) had non-positive means; added deterministically without process variance (documented simplification for downward development)`,
+    );
+  }
+
+  const byOrigin = tri.origins
+    .map((origin, i) => ({ origin, samples: perOrigin[i]! }))
+    .filter((e) => latestIdx[tri.origins.indexOf(e.origin)]! >= 0 && e.samples.some((v) => v !== 0))
+    .map((e) => ({ origin: e.origin, summary: summarizeSample(e.samples) }));
+
+  return {
+    method: "odpBootstrap",
+    quantity: "unpaid",
+    seed,
+    nSims,
+    total: summarizeSample(totals),
+    byOrigin,
+    totalSamples: [...totals].sort((a, b) => a - b),
+    fit,
+    warnings,
+  };
+}

package/src/onlevel.ts

@@ -0,0 +1,155 @@
+import { ReservingError } from "./types.js";
+import { isNum } from "./util.js";
+
+/**
+ * Parallelogram-method premium on-leveling (Werner & Modlin ch. 5).
+ *
+ * Assumptions, stated plainly: policies carry an ANNUAL term, are written
+ * uniformly through time, and premium earns evenly over the policy term. A
+ * rate change applies to policies WRITTEN on or after its effective date.
+ * Under those assumptions the share of a calendar period's EARNED premium
+ * sitting at each historical rate level is a piece of parallelogram
+ * geometry, computed here exactly (piecewise-linear integration, no grids).
+ *
+ * The on-level factor for a period = current cumulative rate level divided
+ * by the average rate level earned in that period.
+ */
+
+export interface RateChange {
+  /** ISO date the change takes effect (applies to policies written on/after it). */
+  effectiveDate: string;
+  /** Rate change, e.g. 0.05 = +5%. */
+  change: number;
+}
+
+export interface OnLevelRow {
+  origin: string;
+  /** Average relative rate level earned in the period (1 = initial level). */
+  averageRateLevel: number;
+  /** currentLevel / averageRateLevel. */
+  onLevelFactor: number;
+}
+
+export interface OnLevelResult {
+  rows: OnLevelRow[];
+  /** Cumulative rate level after all changes (1 = initial level). */
+  currentLevel: number;
+  warnings: string[];
+}
+
+/** ISO date -> fractional year (2021-07-01 -> ~2021.5). */
+function dateToYearFraction(iso: string): number {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(iso);
+  if (!m) {
+    throw new ReservingError("BAD_DATE", `Not an ISO date: ${iso}`);
+  }
+  const year = Number(m[1]);
+  const start = Date.UTC(year, 0, 1);
+  const next = Date.UTC(year + 1, 0, 1);
+  const t = Date.UTC(year, Number(m[2]) - 1, Number(m[3]));
+  return year + (t - start) / (next - start);
+}
+
+/** Origin label -> [start, end) in fractional years ("2021" or "2021Q3"). */
+function originInterval(origin: string): [number, number] {
+  const year = Number(origin.slice(0, 4));
+  if (!Number.isInteger(year)) {
+    throw new ReservingError("BAD_ORIGIN", `Cannot parse an origin period from "${origin}"`);
+  }
+  const qMatch = /Q([1-4])$/.exec(origin);
+  if (qMatch) {
+    const q = Number(qMatch[1]);
+    return [year + (q - 1) / 4, year + q / 4];
+  }
+  return [year, year + 1];
+}
+
+/**
+ * Earned-premium density of the period [p0, p1) by policy WRITTEN time w:
+ * overlap of the earning interval [w, w+1] with [p0, p1). Integrated exactly
+ * over [a, b] (the density is piecewise linear with breakpoints at p0-1,
+ * p1-1, p0, p1).
+ */
+function earnedArea(p0: number, p1: number, a: number, b: number): number {
+  const lo = Math.max(a, p0 - 1);
+  const hi = Math.min(b, p1);
+  if (hi <= lo) return 0;
+  const density = (w: number): number =>
+    Math.max(0, Math.min(p1, w + 1) - Math.max(p0, w));
+  // Integrate exactly across the linear segments.
+  const breaks = [p0 - 1, p1 - 1, p0, p1]
+    .filter((x) => x > lo && x < hi)
+    .sort((x, y) => x - y);
+  const knots = [lo, ...breaks, hi];
+  let area = 0;
+  for (let i = 0; i + 1 < knots.length; i++) {
+    const x0 = knots[i]!;
+    const x1 = knots[i + 1]!;
+    area += ((density(x0) + density(x1)) / 2) * (x1 - x0); // exact: linear segment
+  }
+  return area;
+}
+
+/**
+ * On-level factors per origin period from a rate-change history. Changes
+ * effective before all data simply set the base level; an empty history
+ * yields factors of exactly 1.
+ */
+export function parallelogramOnLevel(
+  origins: string[],
+  history: RateChange[],
+): OnLevelResult {
+  const warnings: string[] = [];
+  for (const rc of history) {
+    if (!isNum(rc.change) || rc.change <= -1) {
+      throw new ReservingError(
+        "BAD_RATE_CHANGE",
+        "A rate change must be a number greater than -100%",
+      );
+    }
+  }
+  const changes = [...history]
+    .map((rc) => ({ at: dateToYearFraction(rc.effectiveDate), change: rc.change }))
+    .sort((a, b) => a.at - b.at);
+
+  // Rate-level eras: [eraStart_i, eraStart_{i+1}) at cumulative level_i.
+  const eras: { from: number; level: number }[] = [{ from: -Infinity, level: 1 }];
+  let level = 1;
+  for (const c of changes) {
+    level *= 1 + c.change;
+    eras.push({ from: c.at, level });
+  }
+  const currentLevel = level;
+
+  const rows: OnLevelRow[] = origins.map((origin) => {
+    const [p0, p1] = originInterval(origin);
+    const total = earnedArea(p0, p1, -Infinity, p1);
+    if (!(total > 0)) {
+      throw new ReservingError("BAD_ORIGIN", `Origin "${origin}" has no earnable area`);
+    }
+    let weighted = 0;
+    for (let i = 0; i < eras.length; i++) {
+      const from = eras[i]!.from;
+      const to = i + 1 < eras.length ? eras[i + 1]!.from : Infinity;
+      const share = earnedArea(p0, p1, from, to) / total;
+      weighted += share * eras[i]!.level;
+    }
+    return {
+      origin,
+      averageRateLevel: weighted,
+      onLevelFactor: currentLevel / weighted,
+    };
+  });
+
+  if (changes.length > 0) {
+    const lastOriginEnd = Math.max(...origins.map((o) => originInterval(o)[1]));
+    const beyond = changes.filter((c) => c.at >= lastOriginEnd);
+    if (beyond.length > 0) {
+      warnings.push(
+        `${beyond.length} rate change(s) effective after the last origin period only move the current level (nothing historical to restate)`,
+      );
+    }
+  }
+
+  return { rows, currentLevel, warnings };
+}

package/src/periods.ts

@@ -0,0 +1,177 @@
+import { ReservingError } from "./types.js";
+
+export type QuarterNumber = 1 | 2 | 3 | 4;
+
+export interface QuarterPeriod {
+  year: number;
+  quarter: QuarterNumber;
+}
+
+export type QuarterFormat = "compact" | "hyphenated" | "quarter-first";
+export type DevelopmentAgeConvention = "quarter-end-first-observation" | "elapsed";
+
+const QUARTER_PATTERNS = [
+  /^(\d{4})Q([1-4])$/i,
+  /^(\d{4})-Q([1-4])$/i,
+  /^Q([1-4])\s+(\d{4})$/i,
+] as const;
+
+/** Parses `2024Q3`, `2024-Q3`, or `Q3 2024`; no lexical date guessing. */
+export function parseQuarterPeriod(value: string): QuarterPeriod {
+  const text = value.trim();
+  for (let i = 0; i < QUARTER_PATTERNS.length; i++) {
+    const match = QUARTER_PATTERNS[i]!.exec(text);
+    if (!match) continue;
+    const quarterFirst = i === 2;
+    const year = Number(match[quarterFirst ? 2 : 1]);
+    const quarter = Number(match[quarterFirst ? 1 : 2]) as QuarterNumber;
+    if (Number.isSafeInteger(year) && year >= 1 && year <= 9999) return { year, quarter };
+  }
+  throw new ReservingError(
+    "BAD_ORIGIN",
+    `Quarter period must be YYYYQn, YYYY-Qn, or Qn YYYY with n from 1 to 4; got ${JSON.stringify(value)}`,
+  );
+}
+
+export function formatQuarterPeriod(
+  period: QuarterPeriod,
+  format: QuarterFormat = "compact",
+): string {
+  assertQuarterPeriod(period);
+  const year = String(period.year).padStart(4, "0");
+  if (format === "hyphenated") return `${year}-Q${period.quarter}`;
+  if (format === "quarter-first") return `Q${period.quarter} ${year}`;
+  return `${year}Q${period.quarter}`;
+}
+
+export function compareQuarterPeriods(a: QuarterPeriod | string, b: QuarterPeriod | string): number {
+  const left = typeof a === "string" ? parseQuarterPeriod(a) : assertQuarterPeriod(a);
+  const right = typeof b === "string" ? parseQuarterPeriod(b) : assertQuarterPeriod(b);
+  return quarterIndex(left) - quarterIndex(right);
+}
+
+export function sortQuarterPeriods<T extends QuarterPeriod | string>(periods: readonly T[]): T[] {
+  return [...periods].sort(compareQuarterPeriods);
+}
+
+export function quarterIndex(period: QuarterPeriod): number {
+  assertQuarterPeriod(period);
+  return period.year * 4 + period.quarter - 1;
+}
+
+export function addQuarters(period: QuarterPeriod | string, count: number): QuarterPeriod {
+  if (!Number.isSafeInteger(count)) {
+    throw new ReservingError("BAD_ORIGIN", `Quarter offset must be an integer; got ${count}`);
+  }
+  const parsed = typeof period === "string" ? parseQuarterPeriod(period) : assertQuarterPeriod(period);
+  const index = quarterIndex(parsed) + count;
+  const year = Math.floor(index / 4);
+  const quarter = ((index % 4 + 4) % 4 + 1) as QuarterNumber;
+  return assertQuarterPeriod({ year, quarter });
+}
+
+/**
+ * Development age in months. The default reflects quarter-end snapshots:
+ * the first observation in an origin quarter is age 3. Select `elapsed` only
+ * when the source genuinely defines a same-quarter observation as age zero.
+ */
+export function developmentAgeMonths(
+  origin: QuarterPeriod | string,
+  valuation: QuarterPeriod | string,
+  convention: DevelopmentAgeConvention = "quarter-end-first-observation",
+): number {
+  const o = typeof origin === "string" ? parseQuarterPeriod(origin) : assertQuarterPeriod(origin);
+  const v = typeof valuation === "string" ? parseQuarterPeriod(valuation) : assertQuarterPeriod(valuation);
+  const elapsed = quarterIndex(v) - quarterIndex(o);
+  if (elapsed < 0) {
+    throw new ReservingError(
+      "BAD_DATE",
+      `Valuation quarter ${formatQuarterPeriod(v)} precedes origin quarter ${formatQuarterPeriod(o)}`,
+    );
+  }
+  return (elapsed + (convention === "quarter-end-first-observation" ? 1 : 0)) * 3;
+}
+
+export interface PolicyPeriodOptions {
+  /** First calendar quarter in the policy/fiscal year. Defaults to Q1. */
+  startQuarter?: QuarterNumber;
+  /** Caller override for nonstandard labels or boundaries. */
+  mapper?: (period: QuarterPeriod) => string;
+}
+
+/** Maps a calendar quarter to the starting year of its policy/fiscal period. */
+export function policyPeriodLabel(
+  period: QuarterPeriod | string,
+  options: PolicyPeriodOptions = {},
+): string {
+  const parsed = typeof period === "string" ? parseQuarterPeriod(period) : assertQuarterPeriod(period);
+  if (options.mapper) return options.mapper({ ...parsed });
+  const startQuarter = options.startQuarter ?? 1;
+  if (![1, 2, 3, 4].includes(startQuarter)) {
+    throw new ReservingError("BAD_ORIGIN", `Policy-year startQuarter must be 1 through 4; got ${startQuarter}`);
+  }
+  const startYear = startQuarter === 1 || parsed.quarter >= startQuarter ? parsed.year : parsed.year - 1;
+  return String(startYear);
+}
+
+export interface CompleteQuarterCutoffOptions {
+  /** Include the in-progress quarter. Default false: only completed quarters. */
+  includePartial?: boolean;
+}
+
+/** Returns the latest included quarter for an ISO calendar date. */
+export function completeQuarterCutoff(
+  asOfDate: string,
+  options: CompleteQuarterCutoffOptions = {},
+): QuarterPeriod {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(asOfDate);
+  if (!match) throw new ReservingError("BAD_DATE", `asOfDate must be YYYY-MM-DD; got ${JSON.stringify(asOfDate)}`);
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+  const daysInMonth = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (year < 1 || year > 9999 || month < 1 || month > 12 || day < 1 || day > daysInMonth[month - 1]!) {
+    throw new ReservingError("BAD_DATE", `asOfDate is not a valid calendar date: ${asOfDate}`);
+  }
+  const quarter = (Math.floor((month - 1) / 3) + 1) as QuarterNumber;
+  if (options.includePartial) return { year, quarter };
+  const endMonth = quarter * 3;
+  const endDay = daysInMonth[endMonth - 1]!;
+  if (month === endMonth && day === endDay) return { year, quarter };
+  return addQuarters({ year, quarter }, -1);
+}
+
+export interface CompleteQuarterlyCutoffsOptions {
+  originAsOfDate?: string;
+  valuationAsOfDate?: string;
+  includePartialOrigin?: boolean;
+  includePartialValuation?: boolean;
+}
+
+/** Explicit origin and valuation cutoffs, independently configurable. */
+export function completeQuarterlyCutoffs(
+  asOfDate: string,
+  options: CompleteQuarterlyCutoffsOptions = {},
+): { originThrough: QuarterPeriod; valuationThrough: QuarterPeriod } {
+  return {
+    originThrough: completeQuarterCutoff(options.originAsOfDate ?? asOfDate, {
+      includePartial: options.includePartialOrigin,
+    }),
+    valuationThrough: completeQuarterCutoff(options.valuationAsOfDate ?? asOfDate, {
+      includePartial: options.includePartialValuation,
+    }),
+  };
+}
+
+function assertQuarterPeriod(period: QuarterPeriod): QuarterPeriod {
+  if (
+    !Number.isSafeInteger(period.year) ||
+    period.year < 1 ||
+    period.year > 9999 ||
+    ![1, 2, 3, 4].includes(period.quarter)
+  ) {
+    throw new ReservingError("BAD_ORIGIN", `Invalid quarter period ${JSON.stringify(period)}`);
+  }
+  return period;
+}