/** * v1.10.0 — the coverage / confidence model + the `Derived` builders. * * `deriveCoverage` turns the raw "what does this metric want vs what is * present, and how much history backs it" facts into a `DerivedCoverage` * + a `DerivedConfidence` band. `buildOk` / `buildInsufficient` are the * two terminal constructors every pure compute function returns — they * attach coverage + confidence + provenance at compute time, inside the * pure function, so no surface ever has to bolt them on per-screen. * * Confidence model (carried from the metric catalogue, §2.1): * - history scales the band width — < `minHistoryDays` nights → no band * (the caller returns `insufficient`); 7d → low, 14d → medium, * 30d+ → high. * - for composites, the present/required input ratio drops the score * monotonically as `missing` grows. * Confidence is a blend of the history fraction and the input-presence * fraction so that a fully-covered short-history metric and a * long-history partially-covered composite both land honestly. * * Client-safe — pure functions, no server imports. */ import type { Derived, DerivedConfidence, DerivedConfidenceBand, DerivedCoverage, DerivedProvenance, } from "./types"; /** Clamp helper. */ function clamp(value: number, lo: number, hi: number): number { return Math.max(lo, Math.min(hi, value)); } /** * Map a 0..100 score onto the confidence band the shared meter renders. * `draft` is reserved for a value computed below its minimum-history * floor but still surfaced (value-only, no band) — callers that gate * hard return `insufficient` instead and never reach this. */ export function scoreToBand(score: number): DerivedConfidenceBand { if (score >= 75) return "high"; if (score >= 50) return "medium"; if (score >= 25) return "low"; return "draft"; } export interface DeriveCoverageArgs { /** Inputs the metric wants (its full input set; ≥ 1). */ requiredInputs: number; /** Inputs actually present. */ presentInputs: number; /** Days of history backing the value. */ historyDays: number; /** Named inputs still missing. */ missing: string[]; /** * History-day count at which the band reaches full width / full * history confidence. Defaults to 30 (the typical-range engine's * 30-day window); composites pass their own. */ fullHistoryDays?: number; } /** * Build the `DerivedCoverage` + `DerivedConfidence` pair from the raw * coverage facts. Confidence = the product of the history fraction * (capped at `fullHistoryDays`) and the input-presence fraction, scaled * to 0..100 and floored so a present-but-sparse value never reports 0. */ export function deriveCoverage(args: DeriveCoverageArgs): { coverage: DerivedCoverage; confidence: DerivedConfidence; } { const requiredInputs = Math.max(1, args.requiredInputs); const presentInputs = clamp(args.presentInputs, 0, requiredInputs); const historyDays = Math.max(0, args.historyDays); const fullHistoryDays = Math.max(1, args.fullHistoryDays ?? 30); const historyFraction = clamp(historyDays / fullHistoryDays, 0, 1); const inputFraction = presentInputs / requiredInputs; // Geometric-ish blend: both axes must be healthy for a high score, but // a fully-covered short-history metric still earns a non-trivial score // and a long-history partially-covered composite is penalised by its // missing inputs. Floor at 1 so a real (non-insufficient) value never // reads as 0 confidence. const rawScore = historyFraction * inputFraction * 100; const score = presentInputs > 0 && historyDays > 0 ? Math.round(clamp(rawScore, 1, 100)) : 0; return { coverage: { requiredInputs, presentInputs, historyDays, missing: [...args.missing], }, confidence: { score, band: scoreToBand(score) }, }; } /** * Terminal constructor — a successful derived value. Attaches coverage + * confidence + provenance computed by the caller (via `deriveCoverage`). */ export function buildOk(args: { value: T; coverage: DerivedCoverage; confidence: DerivedConfidence; provenance: DerivedProvenance; }): Derived { return { status: "ok", value: args.value, coverage: args.coverage, confidence: args.confidence, provenance: args.provenance, }; } /** * Terminal constructor — a gated derived value. Carries coverage + * provenance so the surface renders the shared "track N more days" state. */ export function buildInsufficient(args: { coverage: DerivedCoverage; provenance: DerivedProvenance; reason: string; }): Derived { return { status: "insufficient", coverage: args.coverage, provenance: args.provenance, reason: args.reason, }; } /** ISO 8601 timestamp with offset — the provenance `computedAt` source. */ export function nowProvenanceTimestamp(now: Date = new Date()): string { return now.toISOString(); }