@transitrix/diagrams 1.0.0

package/src/compliance-matrix/types.ts

@@ -0,0 +1,102 @@
+// Compliance matrix model (vkgeorgia/strategy#84 Phase 2).
+//
+// The matrix is Products × Requirements. Each cell is the status of the
+// (Product, Requirement) ASSERTION when one exists, or a gap when none does.
+// Pure data — the layout is computed by `build.ts`; the Studio preview renders
+// it. Non-product-subject assertions (CAPABILITY / PROCESS) belong to the
+// single-product / single-law views (Phase 3) and are ignored here.
+
+import type { AssertionStatus } from '../assertion/types.js';
+
+/** A row of the matrix — a discovered PRODUCT element. */
+export interface MatrixProduct {
+  id: string;
+  name: string;
+  /** True when the product was discovered only as an assertion subject (no
+   *  product element file resolves it) — a dangling subject reference. */
+  unresolved?: boolean;
+}
+
+/** A column of the matrix — a discovered REQUIREMENT. */
+export interface MatrixRequirement {
+  id: string;
+  name: string;
+  /** Organisation-defined priority (high | medium | low), used by the filter. */
+  severity?: string;
+  /** Typed IDs of the codex sources this requirement derives from (verbatim
+   *  from `derived_from`). Carried so the renderer can surface provenance and
+   *  resolve jurisdictions without re-scanning. */
+  derived_from?: string[];
+  /** Jurisdictions resolved by walking `derived_from` → codex artefacts and
+   *  collecting their `jurisdiction` (Codex §1.1). Unique, sorted. Empty when
+   *  no codex source resolves with a jurisdiction (internal-only requirements,
+   *  or codex artefacts the scan did not find / has no jurisdiction). The
+   *  toolbar jurisdiction filter (F16) keys on this set. */
+  jurisdictions?: string[];
+}
+
+/** A codex source document the matrix uses to resolve `Requirement.jurisdictions`. */
+export interface MatrixCodexDoc {
+  id: string;
+  jurisdiction?: string;
+}
+
+/** The assertion fields the matrix needs (a projection of the full Assertion). */
+export interface MatrixAssertionRef {
+  id: string;
+  about: string;
+  subject: string;
+  status: AssertionStatus;
+  assessed_at?: string;
+  next_review_at?: string;
+}
+
+/** One grid cell. `status === undefined` is a gap (no assertion for the pair). */
+export interface MatrixCell {
+  productId: string;
+  requirementId: string;
+  /** The assertion filling this cell, when one exists. */
+  assertionId?: string;
+  status?: AssertionStatus;
+  assessed_at?: string;
+  next_review_at?: string;
+}
+
+export interface ComplianceMatrix {
+  /** Rows, sorted by id. */
+  products: MatrixProduct[];
+  /** Columns, sorted by id. */
+  requirements: MatrixRequirement[];
+  /** `cells[rowIndex][colIndex]`, aligned to `products` × `requirements`. */
+  cells: MatrixCell[][];
+  /** Counts for the summary strip. */
+  summary: {
+    products: number;
+    requirements: number;
+    assertions: number;
+    /** Cells with no assertion (compliance gaps). */
+    gaps: number;
+  };
+}
+
+export interface ComplianceMatrixInput {
+  products: MatrixProduct[];
+  requirements: MatrixRequirement[];
+  assertions: MatrixAssertionRef[];
+  /** Codex source documents — used to resolve each Requirement's jurisdictions
+   *  by walking `derived_from`. Optional: when omitted the builder still works
+   *  and every requirement's `jurisdictions` is left empty. */
+  codex?: MatrixCodexDoc[];
+}
+
+/** Toolbar filter — empty/omitted fields mean "no filter on that dimension". */
+export interface MatrixFilter {
+  /** Keep only requirement columns whose severity is in this set. */
+  severities?: string[];
+  /** Keep only the cell status badges in this set; others render as filtered. */
+  statuses?: AssertionStatus[];
+  /** Keep only requirement columns whose resolved jurisdictions intersect this
+   *  set. Requirements with no resolved jurisdiction are filtered out when this
+   *  is non-empty (F16, epic #84). */
+  jurisdictions?: string[];
+}

package/src/confidence/__tests__/score.test.ts

@@ -0,0 +1,254 @@
+// Pins CONTRACT §11 — source-trust scale, freshness curve, element confidence,
+// view composite, unsourced handling, manifest decay resolution, A–D bands.
+
+import { describe, it, expect } from 'vitest';
+import {
+  IMPLICIT_DECAY_DEFAULTS,
+  composeView,
+  confidenceBand,
+  formatConfidenceHeader,
+  freshness,
+  resolveDecayParams,
+  scoreElement,
+  scoreView,
+  sourceTrustWeight,
+} from '../score.js';
+import type { ConfidenceDecayConfig, DecayParams } from '../types.js';
+
+const D: DecayParams = { fresh_days: 100, stale_days: 200, floor: 0.3 };
+
+describe('sourceTrustWeight (§11.2)', () => {
+  it('matches the closed scale', () => {
+    expect(sourceTrustWeight('authoritative')).toBe(1.0);
+    expect(sourceTrustWeight('corroborated')).toBe(0.8);
+    expect(sourceTrustWeight('single_source')).toBe(0.5);
+    expect(sourceTrustWeight('unverified')).toBe(0.25);
+  });
+});
+
+describe('freshness (§11.3)', () => {
+  const today = '2026-06-05';
+
+  it('returns 1.0 when age ≤ fresh_days', () => {
+    expect(freshness('2026-05-01', today, D)).toBe(1.0);
+    expect(freshness('2026-06-05', today, D)).toBe(1.0);
+  });
+
+  it('returns floor when age ≥ stale_days', () => {
+    expect(freshness('2025-01-01', today, D)).toBeCloseTo(0.3, 10);
+    const exactlyStale = '2025-11-17';
+    expect(freshness(exactlyStale, today, { fresh_days: 100, stale_days: 200, floor: 0.3 })).toBeCloseTo(0.3, 10);
+  });
+
+  it('interpolates linearly between fresh_days and stale_days', () => {
+    // midpoint: age 150 → 1.0 − (1.0 − 0.3) · (150 − 100) / (200 − 100) = 0.65
+    const midAge = new Date(Date.UTC(2026, 5, 5));
+    midAge.setUTCDate(midAge.getUTCDate() - 150);
+    const iso = midAge.toISOString().slice(0, 10);
+    expect(freshness(iso, today, D)).toBeCloseTo(0.65, 10);
+  });
+
+  it('clamps future-dated admitted_at to 1.0', () => {
+    expect(freshness('2030-01-01', today, D)).toBe(1.0);
+  });
+
+  it('treats absent admitted_at as fully stale (returns floor)', () => {
+    expect(freshness(undefined, today, D)).toBe(0.3);
+  });
+
+  it('treats unparseable admitted_at as fully stale', () => {
+    expect(freshness('not-a-date', today, D)).toBe(0.3);
+    expect(freshness('2026/06/05', today, D)).toBe(0.3);
+    expect(freshness('2026-13-01', today, D)).toBe(0.3);
+  });
+
+  it('returns floor when stale_days <= fresh_days (degenerate config) and age exceeds fresh', () => {
+    // age 365d for 2025-06-05; both branches collapse to floor.
+    expect(freshness('2025-06-05', today, { fresh_days: 100, stale_days: 100, floor: 0.4 })).toBe(0.4);
+    expect(freshness('2025-06-05', today, { fresh_days: 200, stale_days: 100, floor: 0.4 })).toBe(0.4);
+  });
+});
+
+describe('resolveDecayParams (§11.3 + MANIFEST §2)', () => {
+  const config: ConfidenceDecayConfig = {
+    defaults: { fresh_days: 180, stale_days: 730, floor: 0.3 },
+    by_type: {
+      CAPABILITY: { fresh_days: 365, stale_days: 1825 },
+      APPLICATION: { fresh_days: 180, stale_days: 730 },
+    },
+  };
+
+  it('uses by_type overrides and inherits missing fields from defaults', () => {
+    // Pins the §11.3 example: CAPABILITY overrides fresh/stale but inherits floor=0.3.
+    expect(resolveDecayParams('CAPABILITY', config)).toEqual({ fresh_days: 365, stale_days: 1825, floor: 0.3 });
+  });
+
+  it('falls back to defaults for an unknown TYPE', () => {
+    expect(resolveDecayParams('PROCESS', config)).toEqual({ fresh_days: 180, stale_days: 730, floor: 0.3 });
+  });
+
+  it('falls back to §11.3 implicit defaults when the whole block is omitted', () => {
+    expect(resolveDecayParams('CAPABILITY', undefined)).toEqual(IMPLICIT_DECAY_DEFAULTS);
+    expect(resolveDecayParams('CAPABILITY', {})).toEqual(IMPLICIT_DECAY_DEFAULTS);
+  });
+
+  it('fills missing defaults fields from §11.3 implicit defaults', () => {
+    const partial: ConfidenceDecayConfig = { defaults: { floor: 0.5 } };
+    expect(resolveDecayParams('PROCESS', partial)).toEqual({
+      fresh_days: IMPLICIT_DECAY_DEFAULTS.fresh_days,
+      stale_days: IMPLICIT_DECAY_DEFAULTS.stale_days,
+      floor: 0.5,
+    });
+  });
+});
+
+describe('scoreElement (§11.4–11.5)', () => {
+  const today = '2026-06-05';
+
+  it('takes the max source-trust weight (§11.4): extra weak sources never subtract', () => {
+    const score = scoreElement(
+      { type: 'CAPABILITY', admitted_at: today, sources: ['unverified', 'authoritative', 'single_source'] },
+      today,
+    );
+    expect(score.source_trust).toBe(1.0);
+    expect(score.confidence).toBe(1.0);
+    expect(score.sourced).toBe(true);
+  });
+
+  it('multiplies source_trust by freshness', () => {
+    // §11.4 worked example: authoritative · floor.
+    const score = scoreElement(
+      { type: 'X', admitted_at: '2024-01-01', sources: ['authoritative'] },
+      today,
+      { defaults: D },
+    );
+    expect(score.source_trust).toBe(1.0);
+    expect(score.freshness).toBeCloseTo(0.3, 10);
+    expect(score.confidence).toBeCloseTo(0.3, 10);
+  });
+
+  it('marks unsourced elements at the unverified floor (§11.5) and sourced=false', () => {
+    const undef = scoreElement({ type: 'X', admitted_at: today }, today);
+    const empty = scoreElement({ type: 'X', admitted_at: today, sources: [] }, today);
+    for (const score of [undef, empty]) {
+      expect(score.source_trust).toBe(0.25);
+      expect(score.sourced).toBe(false);
+      expect(score.confidence).toBeCloseTo(0.25, 10);
+    }
+  });
+
+  it('distinguishes unsourced (counted separately) from sourced-but-unverified', () => {
+    const unsourced = scoreElement({ type: 'X', admitted_at: today }, today);
+    const sourcedUnverified = scoreElement(
+      { type: 'X', admitted_at: today, sources: ['unverified'] },
+      today,
+    );
+    expect(unsourced.source_trust).toBe(sourcedUnverified.source_trust);
+    expect(unsourced.sourced).toBe(false);
+    expect(sourcedUnverified.sourced).toBe(true);
+  });
+});
+
+describe('confidenceBand (§11.6)', () => {
+  it('uses the documented thresholds', () => {
+    expect(confidenceBand(1.0)).toBe('A');
+    expect(confidenceBand(0.8)).toBe('A');
+    expect(confidenceBand(0.79)).toBe('B');
+    expect(confidenceBand(0.6)).toBe('B');
+    expect(confidenceBand(0.59)).toBe('C');
+    expect(confidenceBand(0.4)).toBe('C');
+    expect(confidenceBand(0.39)).toBe('D');
+    expect(confidenceBand(0)).toBe('D');
+  });
+});
+
+describe('composeView (§11.6)', () => {
+  it('headlines weakest link, reports mean and coverage', () => {
+    const composite = composeView([
+      { source_trust: 1.0, freshness: 1.0, confidence: 1.0, sourced: true },
+      { source_trust: 0.5, freshness: 0.8, confidence: 0.4, sourced: true },
+      { source_trust: 0.25, freshness: 1.0, confidence: 0.25, sourced: false },
+    ]);
+    expect(composite.weakest_link).toBeCloseTo(0.25, 10);
+    expect(composite.band).toBe('D');
+    expect(composite.mean).toBeCloseTo((1.0 + 0.4 + 0.25) / 3, 10);
+    expect(composite.coverage).toBeCloseTo(2 / 3, 10);
+    expect(composite.element_count).toBe(3);
+    expect(composite.unsourced_count).toBe(1);
+  });
+
+  it('returns a degenerate composite (band D, counts 0) for an empty set', () => {
+    const composite = composeView([]);
+    expect(composite.element_count).toBe(0);
+    expect(composite.weakest_link).toBe(0);
+    expect(composite.mean).toBe(0);
+    expect(composite.coverage).toBe(0);
+    expect(composite.band).toBe('D');
+  });
+});
+
+describe('scoreView end-to-end', () => {
+  const today = '2026-06-05';
+
+  it('composes weakest-link / mean / coverage / band from heterogenous elements', () => {
+    const view = scoreView(
+      [
+        // weakest link = 0.50 → band C
+        { type: 'X', admitted_at: today, sources: ['authoritative'] },  // 1.00
+        { type: 'X', admitted_at: today, sources: ['corroborated'] },   // 0.80
+        { type: 'X', admitted_at: today, sources: ['single_source'] },  // 0.50
+        { type: 'X', admitted_at: today, sources: ['corroborated'] },   // 0.80
+      ],
+      today,
+    );
+    expect(view.composite.weakest_link).toBeCloseTo(0.5, 10);
+    expect(view.composite.band).toBe('C');
+    expect(view.composite.mean).toBeCloseTo((1.0 + 0.8 + 0.5 + 0.8) / 4, 10);
+    expect(view.composite.coverage).toBe(1);
+    expect(view.composite.unsourced_count).toBe(0);
+    expect(view.today).toBe(today);
+  });
+
+  it('accepts Date for today and converts to ISO', () => {
+    const view = scoreView(
+      [{ type: 'X', admitted_at: '2026-06-05', sources: ['authoritative'] }],
+      new Date(Date.UTC(2026, 5, 5)),
+    );
+    expect(view.today).toBe('2026-06-05');
+    expect(view.composite.band).toBe('A');
+  });
+
+  it('reports band D and 0% coverage when every element is unsourced and fully stale', () => {
+    const view = scoreView(
+      [
+        { type: 'X' },
+        { type: 'X' },
+      ],
+      '2026-06-05',
+      { defaults: D },
+    );
+    // unsourced (0.25) · freshness floor (0.3) = 0.075 → band D.
+    expect(view.composite.coverage).toBe(0);
+    expect(view.composite.unsourced_count).toBe(2);
+    expect(view.composite.band).toBe('D');
+    expect(view.composite.weakest_link).toBeCloseTo(0.075, 10);
+  });
+});
+
+describe('formatConfidenceHeader (§11.6)', () => {
+  it('renders the documented header shape', () => {
+    const view = scoreView(
+      [{ type: 'X', admitted_at: '2026-06-05', sources: ['corroborated'] }],
+      '2026-06-05',
+    );
+    // corroborated (0.8) · freshness 1.0 = 0.80 → band A (A is ≥ 0.8).
+    expect(formatConfidenceHeader(view)).toBe(
+      'Data confidence (as of 2026-06-05): A (weakest link) · 0.80 mean · 100% sourced',
+    );
+  });
+
+  it('returns an empty string for an empty composite', () => {
+    const view = scoreView([], '2026-06-05');
+    expect(formatConfidenceHeader(view)).toBe('');
+  });
+});

package/src/confidence/index.ts

@@ -0,0 +1,21 @@
+export {
+  IMPLICIT_DECAY_DEFAULTS,
+  composeView,
+  confidenceBand,
+  formatConfidenceHeader,
+  freshness,
+  resolveDecayParams,
+  scoreElement,
+  scoreView,
+  sourceTrustWeight,
+} from './score.js';
+export type {
+  ConfidenceBand,
+  ConfidenceDecayConfig,
+  DecayParams,
+  ElementScore,
+  ScoringElement,
+  SourceQuality,
+  ViewComposite,
+  ViewScore,
+} from './types.js';

package/src/confidence/score.ts

@@ -0,0 +1,243 @@
+// Pure confidence-scoring per methodology CONTRACT §11. No I/O, no mutation:
+// callers (Studio previews, DSM React) pass already-resolved element inputs
+// and a `today` reference; this module returns the per-element scores and
+// the view composite. Lives in @transitrix/diagrams so Studio and DSM share
+// one implementation (see vkgeorgia/strategy#159 — DQ-1).
+
+import type {
+  ConfidenceBand,
+  ConfidenceDecayConfig,
+  DecayParams,
+  ElementScore,
+  ScoringElement,
+  SourceQuality,
+  ViewComposite,
+  ViewScore,
+} from './types.js';
+
+/** §11.3 implicit defaults — used when the adopter omits `confidence_decay`. */
+export const IMPLICIT_DECAY_DEFAULTS: DecayParams = {
+  fresh_days: 180,
+  stale_days: 730,
+  floor: 0.3,
+};
+
+/** §11.2 source-trust weights. The fallback for an unknown label is `unverified`. */
+const SOURCE_TRUST_WEIGHTS: Record<SourceQuality, number> = {
+  authoritative: 1.0,
+  corroborated: 0.8,
+  single_source: 0.5,
+  unverified: 0.25,
+};
+
+/** Weight for the `unverified` floor — both an explicit label and the unsourced fallback. */
+const UNVERIFIED_WEIGHT = SOURCE_TRUST_WEIGHTS.unverified;
+
+export function sourceTrustWeight(q: SourceQuality): number {
+  return SOURCE_TRUST_WEIGHTS[q] ?? UNVERIFIED_WEIGHT;
+}
+
+/**
+ * Resolves the decay parameters for one element TYPE: `by_type[type]` overrides
+ * `defaults`, which overrides {@link IMPLICIT_DECAY_DEFAULTS}. Each field
+ * resolves independently — a `by_type` entry that sets only `fresh_days` /
+ * `stale_days` inherits `floor` from `defaults` (per the §11.3 example).
+ */
+export function resolveDecayParams(
+  type: string,
+  config?: ConfidenceDecayConfig,
+): DecayParams {
+  const typeOverride = config?.by_type?.[type] ?? {};
+  const defaults = config?.defaults ?? {};
+  return {
+    fresh_days: pick(typeOverride.fresh_days, defaults.fresh_days, IMPLICIT_DECAY_DEFAULTS.fresh_days),
+    stale_days: pick(typeOverride.stale_days, defaults.stale_days, IMPLICIT_DECAY_DEFAULTS.stale_days),
+    floor: pick(typeOverride.floor, defaults.floor, IMPLICIT_DECAY_DEFAULTS.floor),
+  };
+}
+
+function pick(...values: (number | undefined)[]): number {
+  for (const v of values) if (typeof v === 'number' && Number.isFinite(v)) return v;
+  // The trailing implicit default is always finite; this is only reached if a
+  // caller passes a non-finite implicit default — which we treat as 0.
+  return 0;
+}
+
+/**
+ * Computes freshness per CONTRACT §11.3.
+ *
+ * ```
+ * freshness = 1.0      if age_days ≤ fresh_days
+ *           = floor    if age_days ≥ stale_days
+ *           = 1.0 − (1.0 − floor) · (age_days − fresh_days) / (stale_days − fresh_days)   otherwise
+ * ```
+ *
+ * Future-dated `admitted_at` (negative age) is clamped to 1.0. An absent or
+ * unparseable `admitted_at` returns `floor` — the element is treated as fully
+ * stale, never as fresh.
+ */
+export function freshness(
+  admittedAt: string | undefined,
+  today: string,
+  params: DecayParams,
+): number {
+  if (!admittedAt) return params.floor;
+  const age = daysBetween(admittedAt, today);
+  if (age === null) return params.floor;
+  if (age <= params.fresh_days) return 1.0;
+  if (age >= params.stale_days) return params.floor;
+  // Linear interpolation. Guard against a degenerate fresh==stale config: the
+  // two equalities above would already have returned, but if a caller passes
+  // stale_days < fresh_days we keep monotonic behaviour by returning floor.
+  const span = params.stale_days - params.fresh_days;
+  if (span <= 0) return params.floor;
+  return 1.0 - (1.0 - params.floor) * ((age - params.fresh_days) / span);
+}
+
+/**
+ * Scores one element per §11.4–11.5. The element's `sources` list is the
+ * resolved `derived_from` provenance: max trust wins (`max` in §11.4), and
+ * an empty / absent list marks the element unsourced — scored at the
+ * `unverified` floor and `sourced: false` so the view composite can count
+ * it separately per §11.5.
+ */
+export function scoreElement(
+  element: ScoringElement,
+  today: string,
+  config?: ConfidenceDecayConfig,
+): ElementScore {
+  const sources = element.sources ?? [];
+  const sourced = sources.length > 0;
+  const source_trust = sourced
+    ? Math.max(...sources.map(sourceTrustWeight))
+    : UNVERIFIED_WEIGHT;
+  const params = resolveDecayParams(element.type, config);
+  const f = freshness(element.admitted_at, today, params);
+  return {
+    source_trust,
+    freshness: f,
+    confidence: source_trust * f,
+    sourced,
+  };
+}
+
+/** Confidence band per §11.6: A ≥ 0.8, B ≥ 0.6, C ≥ 0.4, D < 0.4. */
+export function confidenceBand(confidence: number): ConfidenceBand {
+  if (confidence >= 0.8) return 'A';
+  if (confidence >= 0.6) return 'B';
+  if (confidence >= 0.4) return 'C';
+  return 'D';
+}
+
+/**
+ * Rolls per-element scores up to the view composite per §11.6. The weakest
+ * link is the headline; mean and coverage are reported alongside. An empty
+ * element set returns a degenerate composite (`weakest_link` and `mean` of 0,
+ * coverage 0, band `D`) — callers should detect `element_count === 0` if they
+ * want to suppress the header entirely rather than display the floor.
+ */
+export function composeView(scores: ElementScore[]): ViewComposite {
+  if (scores.length === 0) {
+    return {
+      weakest_link: 0,
+      mean: 0,
+      coverage: 0,
+      band: 'D',
+      element_count: 0,
+      unsourced_count: 0,
+    };
+  }
+  let min = Infinity;
+  let sum = 0;
+  let sourcedCount = 0;
+  for (const s of scores) {
+    if (s.confidence < min) min = s.confidence;
+    sum += s.confidence;
+    if (s.sourced) sourcedCount += 1;
+  }
+  const mean = sum / scores.length;
+  return {
+    weakest_link: min,
+    mean,
+    coverage: sourcedCount / scores.length,
+    band: confidenceBand(min),
+    element_count: scores.length,
+    unsourced_count: scores.length - sourcedCount,
+  };
+}
+
+/**
+ * Scores a view's elements end-to-end. The caller passes the rendered set,
+ * the adopter manifest's `confidence_decay` block (optional), and the
+ * reference date (`today`); the result is purely derived and never stored
+ * — re-running on the same inputs yields the same numbers (§11.6).
+ */
+export function scoreView(
+  elements: ScoringElement[],
+  today: string | Date,
+  config?: ConfidenceDecayConfig,
+): ViewScore {
+  const todayIso = toIsoDate(today);
+  const elementScores = elements.map(e => scoreElement(e, todayIso, config));
+  return {
+    elements: elementScores,
+    composite: composeView(elementScores),
+    today: todayIso,
+  };
+}
+
+/**
+ * Renders the §11.6 example header line, e.g.:
+ *
+ * ```
+ * Data confidence (as of 2026-06-05): B (weakest link) · 0.71 mean · 92% sourced
+ * ```
+ *
+ * Shared between Studio (DQ-2) and DSM (DQ-5) so the banding/labels stay
+ * consistent across the two consumers. Returns an empty string for an empty
+ * composite — callers decide whether to suppress the header in that case.
+ */
+export function formatConfidenceHeader(view: ViewScore): string {
+  const c = view.composite;
+  if (c.element_count === 0) return '';
+  const mean = c.mean.toFixed(2);
+  const coverage = Math.round(c.coverage * 100);
+  return `Data confidence (as of ${view.today}): ${c.band} (weakest link) · ${mean} mean · ${coverage}% sourced`;
+}
+
+// ── Date helpers ────────────────────────────────────────────────────────────
+
+/** Strict ISO-date parser. Accepts `YYYY-MM-DD`; returns null on anything else. */
+const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+function parseIsoDate(s: string): Date | null {
+  const m = ISO_DATE_RE.exec(s);
+  if (!m) return null;
+  const year = Number(m[1]);
+  const month = Number(m[2]);
+  const day = Number(m[3]);
+  // UTC to avoid the host TZ shifting age_days by ±1.
+  const d = new Date(Date.UTC(year, month - 1, day));
+  if (
+    d.getUTCFullYear() !== year ||
+    d.getUTCMonth() !== month - 1 ||
+    d.getUTCDate() !== day
+  ) return null;
+  return d;
+}
+
+function toIsoDate(d: string | Date): string {
+  if (typeof d === 'string') return d;
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+function daysBetween(fromIso: string, toIso: string): number | null {
+  const from = parseIsoDate(fromIso);
+  const to = parseIsoDate(toIso);
+  if (!from || !to) return null;
+  const ms = to.getTime() - from.getTime();
+  return Math.floor(ms / (24 * 60 * 60 * 1000));
+}