@actuarial-ts/core 0.4.0 → 0.6.0

package/README.md

@@ -1,244 +1,94 @@
 # @actuarial-ts/core
 
-A pure, zero-dependency P&C loss reserving engine for TypeScript. The
-deterministic shelf: triangles, development factors, chain ladder,
-Bornhuetter-Ferguson, Benktander, Cape Cod (with the Gluck decay
-generalization), Expected Claims, frequency-severity, Berquist-Sherman,
-Munich chain ladder, case-outstanding development, Fisher-Lange,
-salvage/subrogation, ULAE, tail fitting, large-loss capping and ILF
-restoration, trend and premium on-leveling, discounting (built to the June
-2026 ASOP No. 20), and assumption diagnostics. The stochastic layer, fully
-seeded and reproducible: Mack standard errors, the ODP bootstrap,
-Merz-Wuthrich one-year risk, and Clark growth-curve MLE — every method
-validated against published actuarial literature where published values
-exist.
-
-`@actuarial-ts/core` is the numeric kernel of the actuarial-ts SDK. It is
-**designed to support the actuary's compliance with the Actuarial Standards of
-Practice** (ASOP Nos. 43, 23, 41, 56, 20, and 21) by making
-methods, assumptions, and their diagnostics explicit and reportable.
-Responsibility for compliance remains with the credentialed actuary; no
-software can be "ASOP-approved" and this one does not claim to be.
+Pure, framework-free P&C actuarial math for TypeScript. It includes triangles, deterministic and stochastic reserving, trends/on-leveling, limits and ILFs, discounting, and generalized definition-driven casualty diagnostics.
+
+The package is designed to support an actuary’s work under applicable ASOPs; it does not make a work product compliant and is not “ASOP-approved.” The credentialed actuary remains responsible for data, assumptions, selections, review, and communication.
 
 ## Install
 
 ```bash
-npm install @actuarial-ts/core
+npm install @actuarial-ts/core@0.6.0
 ```
 
-ESM, TypeScript-first, zero runtime dependencies, Node >= 20.
+ESM, TypeScript-first, zero runtime dependencies, Node 20+.
 
-## Quick start
+## Reserving quick start
 
 ```ts
-import {
-  buildTriangles,
-  computeDevelopmentFactors,
-  runChainLadder,
-  runMack,
-  fitAllTails,
-} from "@actuarial-ts/core";
-
-// One row per claim per evaluation snapshot (the standard loss-run shape).
-const { paid, incurred } = buildTriangles(claimSnapshots, {
-  cadence: "annual",
-  asOfDate: "2025-12-31",
-});
+import { buildTriangles, computeDevelopmentFactors, runChainLadder, runMack } from "@actuarial-ts/core";
 
-// The averages menu: all-year/n-year straight and volume-weighted, medial,
-// geometric. Selection is YOUR judgment; the engine never picks for you.
-const factors = computeDevelopmentFactors(paid);
-const selected = factors.averages.find((a) => a.spec.key === "all-wtd")!.values;
+const { paid } = buildTriangles(claimSnapshots, { cadence: "annual", asOfDate: "2025-12-31" });
+const selected = computeDevelopmentFactors(paid).averages.find((item) => item.spec.key === "all-wtd")!.values;
+const chainLadder = runChainLadder(paid, { selected, tailFactor: 1.02 });
+const mack = runMack(paid, { selected, tailFactor: 1.02 });
+```
 
-const tails = fitAllTails(selected);
-const tail = tails.exponentialDecay.valid ? tails.exponentialDecay.tailFactor : 1;
+Unobservable triangle cells are `null`. Volume-weighted factors are sum/sum over rows where both cells exist. CDFs multiply right-to-left, tail last. Missing, zero, or negative divisors yield `null`, never `NaN`.
 
-const cl = runChainLadder(paid, { selected, tailFactor: tail });
-const mack = runMack(paid, { selected, tailFactor: tail });
+## Generalized diagnostics
 
-console.log(cl.totals.unpaid, mack.totals.standardError, cl.warnings);
-```
+The model deliberately separates five concerns:
 
-## The contract
-
-Three rules hold everywhere:
-
-1. **Null is a first-class citizen.** Unobservable triangle cells are `null`.
-   Division by a missing, zero, or negative denominator yields `null` ("no
-   factor") — never an exception, never `NaN`.
-2. **Three-tier severity.** Impossible input throws `ReservingError` with a
-   machine-readable code from the exported `RESERVING_ERROR_CODES` registry.
-   Degraded-but-legal situations compute anyway and explain themselves in the
-   result's `warnings: string[]`. Missing data is `null`, not an error.
-3. **Judgment belongs to the caller.** The engine computes evidence (factor
-   menus, tail fits, diagnostics) and applies *your* selections (LDFs, tails,
-   a-prioris, trends, caps). It never silently selects.
-
-## Method inventory
-
-| Module | Methods | Primary literature |
-|---|---|---|
-| `triangle` | `buildTriangles` (7 triangle kinds from claim-level snapshots, annual/quarterly), `triangleFromGrid` | Friedland, *Estimating Unpaid Claims Using Basic Techniques* |
-| `factors` | `computeDevelopmentFactors` (averages menu), `factorVolatility` | Friedland ch. 7; Mack (1993) factor conventions |
-| `chainladder` | `runChainLadder` | Friedland ch. 7 |
-| `mack` | `runMack` — distribution-free standard errors on the selected basis, with tail | Mack (1993) ASTIN 23(2); Mack (1999) ASTIN 29(2) |
-| `bf` | `runBornhuetterFerguson` (per-origin/global/derived a-priori) | Bornhuetter & Ferguson (1972) |
-| `elrMethods` | `runCapeCod`, `runExpectedClaims` | Stanard-Buhlmann; Friedland chs. 8, 10 |
-| `tail` | `fitTail`, `fitAllTails` (exponential decay, Sherman inverse power, validity gates) | Sherman (1984); Boor (2006) |
-| `berquist` | `berquistCaseAdequacy`, `berquistSettlement` | Berquist & Sherman (1977); Friedland ch. 13 |
-| `benktander` | `runBenktander` — the iterated BF credibility blend | Mack (2000) ASTIN 30(2); Benktander (1976) |
-| `freqSev` | `runFrequencySeverity`, `severityTriangle` | Friedland ch. 11 |
-| `munichChainLadder` | `runMunichChainLadder` — closes the paid/incurred gap | Quarg & Mack (2004), Variance 2:2 |
-| `caseOutstanding` | `runCaseOutstanding` | Friedland ch. 12 |
-| `fisherLange` | `runFisherLange` — disposal-rate frequency-severity | Fisher & Lange (1973); Friedland ch. 11 |
-| `salvageSubro` | `runSalvageSubro`, `netOfRecoveries` | Friedland ch. 14 |
-| `ulae` | `ulaeRatios`, `ulaeReserve`, `ULAE_WEIGHT_PRESETS` | Conger & Nolibos (2003); Kittel (1981) |
-| `discounting` | `payoutPatternFromChainLadder`, `discountUnpaid` | ASOP No. 20 (June 2026 edition) |
-| `stochastic` | `createRng` (seeded), `summarizeSample`, `StochasticResult` | — |
-| `triangleAlgebra` | `cumulativeToIncremental`, `incrementalToCumulative`, `addTriangles`, `subtractTriangles` | — |
-| `odpBootstrap` | `odpFit` (GLM == chain ladder identity), `runOdpBootstrap` | England & Verrall (1999/2002); Shapland, CAS Monograph 4 |
-| `merzWuthrich` | `runMerzWuthrich` — one-year CDR MSEP vs Mack's ultimate view | Merz & Wuthrich (2008), CAS E-Forum |
-| `clark` | `clarkGrowth`, `runClarkLdf`, `runClarkCapeCod` — MLE + delta-method variances | Clark (2003), CAS Forum |
-| `capping` | `capClaims`, `claimSizeDiagnostics` (per-occurrence caps, indexed) | standard large-loss practice |
-| `ilf` | censored-MLE severity fits (lognormal, Pareto), Kaplan-Meier checks, ILF table interpolation, uncap factors | Klugman et al., *Loss Models*; standard ILF practice |
-| `trend` | `analyzeTrend`, `trendValue` (log-linear, windowed) | Werner & Modlin, *Basic Ratemaking* ch. 6 |
-| `onlevel` | `parallelogramOnLevel` (exact piecewise-linear earning geometry) | Werner & Modlin ch. 5 |
-| `diagnostics` | `runDiagnostics` (paid/incurred drift, case adequacy, closure rates), `calendarYearTest` | Mack (1994) calendar-year rank test |
-| `metricDiagnostics` | generic ratio-of-sums metrics, claim-level amount layers, emergence/triangle/maturity views, optional 20-metric casualty preset | actuarial diagnostic practice |
-| `periods` | quarterly parse/format/compare, development age, fiscal/policy mapping, complete-quarter cutoffs | explicit SDK conventions |
-| `canonical` | `canonicalJson` (RFC 8785 / JCS canonical serialization), `fnv1a64` (integrity tagging aid — not a security control) | RFC 8785 |
-
-## Quarterly metric diagnostics
-
-`runMetricDiagnostics` is the generic engine behind the optional
-`CASUALTY_QUARTERLY_METRICS` preset. A metric is a versioned definition with
-caller-selected additive component expressions. The engine sums components at
-the requested group/origin/valuation grain and divides once; it never averages
-row ratios. Each result retains the raw numerator, denominator, component
-values, labels, basis, scale, and structured warnings.
+1. A measure declares source, quantity kind, unit, development semantics, sum aggregation, missingness, and its population/basis.
+2. A formula template declares reusable arithmetic over typed roles.
+3. An instance binds formula roles to measure expressions.
+4. Calculation identity covers arithmetic, bindings, and all dependent measure/population/basis semantics.
+5. Presentation and review rules remain visible in full definition identity without pretending to change the arithmetic.
 
 ```ts
 import {
-  CASUALTY_QUARTERLY_METRICS,
+  CASUALTY_FORMULA_TEMPLATES,
+  compileDiagnosticDefinition,
+  createCasualtyMetricInstances,
+  prepareDiagnosticData,
   runMetricDiagnostics,
 } from "@actuarial-ts/core";
 
-const result = runMetricDiagnostics({
-  losses: [{
-    id: "snapshot-1",
-    group: "commercial-auto",
-    origin: "2025Q1",
-    valuation: "2025Q1",
-    ageMonths: 3,
-    policyPeriod: "PY2024",
-    measures: {
-      reportedCount: 80,
-      openCount: 30,
-      closedNoPayCount: 20,
-      closedWithPayCount: 30,
-      paid250: 450_000,
-      incurred250: 700_000,
-      paidPrimary: 600_000,
-      incurredPrimary: 950_000,
-    },
-  }],
-  exposures: [{
-    key: "fleet-2025Q1",
-    group: "commercial-auto",
-    origin: "2025Q1",
-    measures: { exposure: 1_600_000 },
-  }],
-  metrics: CASUALTY_QUARTERLY_METRICS,
+const instances = createCasualtyMetricInstances({
+  counts: { reported: "reported", open: "open", closedNoPay: "closed-no-pay", closedWithPay: "closed-with-pay" },
+  exposure: "earned-vehicle-years",
+  amountBindings: [
+    { id: "gross", paid: "gross-paid", incurred: "gross-incurred" },
+    { id: "primary-250k", paid: "primary-paid", incurred: "primary-incurred" },
+  ],
 });
 
-const reported = result.emergence[0]!.metrics["reported-frequency"]!;
-console.log(reported.value, reported.rawNumerator, reported.rawDenominator);
-console.log(result.triangles[0]!.values, result.latestDiagonal);
+const compiled = compileDiagnosticDefinition({
+  diagnosticDefinitionVersion: "1.0.0",
+  id: "fleet-diagnostics",
+  version: "1.0.0",
+  lossRowGrain: "aggregate",
+  measures,
+  countPopulations,
+  exposureBases,
+  amountBases,
+  derivedMeasures: [],
+  formulas: CASUALTY_FORMULA_TEMPLATES,
+  instances,
+  reviewRules,
+  periodAxis,
+});
+
+const prepared = prepareDiagnosticData({ definition: compiled, losses, exposures });
+const result = runMetricDiagnostics({ prepared, groupMap: { fleet: "all-fleet" } });
 ```
 
-Missing components remain null by default. An explicit `sparsePolicy:
-"zero-fill"` is required to treat sparse values as zero. A missing,
-non-finite, zero, or negative denominator produces a null metric and an
-`INVALID_DENOMINATOR` warning; negative numerators remain valid.
-`diagnosticWarningToFinding` adapts these warning payloads to the existing core
-`DiagnosticFinding` severity vocabulary when a consumer wants one findings
-stream; ASOP-oriented `DataReviewReport` statuses remain a separate contract.
-
-Use `createCasualtyQuarterlyMetrics` to override the source component keys,
-exposure key, frequency scale/unit, definition version, basis labels, and
-display metadata. The exported `CASUALTY_QUARTERLY_METRICS` constant is the
-standard one-million-scale configuration. `groupMap` combines arbitrary source
-groups at a requested output grain by summing their components first. When
-exposure rows are supplied, every contributing source group/origin must have
-exposure; a missing contributor makes the combined exposure null with an
-`INCOMPLETE_EXPOSURE` warning instead of using a partial denominator. Dated
-exposure copies honor valuation filters, while exposure rows without a
-valuation remain timeless.
-
-### Amount layers
-
-`deriveAmountLayers` evaluates a declarative layer on each claim row before
-aggregation. `CASUALTY_AMOUNT_LAYERS` documents two reference bases:
-
-- `$250K pre-capped total` reads already-limited paid and incurred components
-  as additive measures. The SDK does not attempt to recreate a lost
-  claim-level cap from an aggregate.
-- `Primary: $1M capped indemnity plus unlimited expense` caps paid and incurred
-  indemnity on each claim row, then adds expense without a cap.
-
-This distinction is intentional: capping an aggregate after summation is not
-equivalent to a claim-level layer and is not offered by the API.
-`createCasualtyAmountLayers` configures every source/output key, identifier,
-display label, and indemnity limit; arbitrary caller layers can be authored
-directly as `AmountLayerDefinition` values.
-
-### Views and periods
-
-The engine derives audited emergence points, nullable metric triangles, and a
-ragged latest diagonal from the same aggregated records. `sameMaturity` and
-`commonMaturity` select comparable points for any caller group IDs.
-`parseQuarterPeriod`, `compareQuarterPeriods`, `developmentAgeMonths`,
-`policyPeriodLabel`, `completeQuarterCutoff`, and
-`completeQuarterlyCutoffs` make period assumptions explicit. The default
-quarter-end convention starts at age 3; select the `elapsed` convention only
-for genuine age-zero observations.
-
-Core results deliberately contain no provenance, persistence state, or
-arbitrary application filter state. Use `createDiagnosticsProvenance` from
-`@actuarial-ts/compliance`, embed its record in
-`createBundle(...).parameters`, and record material judgment in the assumption
-ledger. Interchange consumers can carry the same record in `extensions`. No
-diagnostic-specific interchange schema is claimed.
-
-## Validation against published results
-
-The test suite reproduces the following, each transcribed from the primary
-source into `test/fixtures/`. Five of them additionally carry a full research
-transcription with context and caveats under `docs/research/` (Clark,
-Merz-Wuthrich, England/Verrall, Munich, ULAE); for the rest the transcription
-notes live in the fixture file itself.
-
-- Mack (1993), ASTIN 23(2): Taylor/Ashe and mortgage-guarantee factors,
-  reserves, sigma-squared (including the extrapolated column), standard errors.
-- Mack (1994), CAS Forum: the RAA triangle's calendar-year test (Appendix H)
-  and factor-correlation test (Appendix G), every printed statistic.
-- Mack (1999), ASTIN 29(2): ultimates under the published 1.05 tail.
-- Mack (2000), ASTIN 30(2): the Benktander numerical example.
-- Gluck (1997), PCAS LXXXIV: Generalized Cape Cod Tables 1-4.
-- England (2002), IME 31: ODP bootstrap prediction errors and percentiles
-  on Taylor/Ashe — all nine published accident years plus the Table 3
-  predictive distribution. Asserted within the sampling error the publication
-  itself exhibits, because a bootstrap figure is one finite sample and cannot
-  be reproduced to the digit the way Mack's closed form can.
-- Merz & Wuthrich (2008): the Table 4 one-year CDR volatilities.
-- Clark (2003): both methods' fitted parameters, reserves, and variance
-  decompositions (to ~1e-5).
-- Quarg & Mack (2004): the fire-portfolio example's every printed parameter
-  row and projected cell.
-
-These published-value tests are the package's change contract: math changes
-are wrong until they pass.
+The six built-in formulas are basis-independent. The factory creates ten count instances plus six per amount basis (`10 + 6 × basisCount`): one basis produces 16, two produce 22. A `$250K`, primary, gross, net, or ceded calculation is represented by caller-declared amount measures and a structured `AmountBasisDefinition`; it does not need a separate capped formula. Claim-level caps use `claim-layer` derivations before aggregation. Pre-limited external values record their source/transformation instead of implying the SDK recreated an unavailable claim-level operation.
+
+All metrics are ratio-of-sums: measures are aggregated at source-group/origin/valuation, groups are mapped and merged, then division happens once. Measure-local `missing: "unknown" | "zero"` is explicit. Exposure timing is either `origin-static` or `valuation-specific`. Calendar and ordered axes derive normalized origins, valuations, development ages, and units; input rows cannot assert a trusted age.
+
+Compilation validates the whole graph atomically: IDs, sources, role types, compatibility groups, development semantics, derivation acyclicity, expression limits, rule operands, basis/population references, and period coordinates. Authentic compiled/prepared objects are owner-branded and frozen. Formula, calculation, definition, preparation, and result identities are deterministic FNV-1a/JCS integrity aids—not cryptographic signatures.
+
+See the generated [formula and instance catalog](https://github.com/yerromnitsuj/actng/blob/v0.6.0/docs/reference/diagnostic-formulas.md) and [0.6 migration guide](https://github.com/yerromnitsuj/actng/blob/v0.6.0/docs/migrations/0.6-generalized-diagnostics.md).
+
+## Main method families
+
+- Reserving: chain ladder, Mack, Bornhuetter-Ferguson, Benktander, Cape Cod/Gluck, Expected Claims, frequency-severity, Fisher-Lange, Munich chain ladder, Clark, ODP bootstrap, and Merz-Wüthrich one-year risk.
+- Adjustments: Berquist-Sherman, salvage/subrogation, ULAE, tails, trends, premium on-leveling, discounting, capping, severity models, and ILFs.
+- Infrastructure: triangle algebra, seeded RNG, RFC 8785 canonical JSON, integrity tags, traditional triangle diagnostics, and generalized metric diagnostics.
+
+Published-value tests are the numerical contract. A reserving math change is not acceptable until those fixtures still pass.
 
 ## License
 
-Apache-2.0. Copyright 2026 Justin Morrey.
+Apache-2.0. See LICENSE and NOTICE.

package/dist/casualtyDiagnostics.d.ts

@@ -1,53 +1,23 @@
-import { type AmountLayerDefinition, type MetricDefinition } from "./metricDiagnostics.js";
-export interface CasualtyDiagnosticComponentKeys {
-    reported: string;
-    open: string;
-    closedNoPay: string;
-    closedWithPay: string;
-    exposure: string;
-    paid250: string;
-    incurred250: string;
-    paidPrimary: string;
-    incurredPrimary: string;
+import { CASUALTY_FORMULA_TEMPLATES } from "./diagnosticFormulas.js";
+import type { DiagnosticMetricInstance, DiagnosticMetricPresentation } from "./diagnosticDefinitions.js";
+export { CASUALTY_FORMULA_TEMPLATES };
+export interface CasualtyCountBindings {
+    readonly reported: string;
+    readonly open: string;
+    readonly closedNoPay: string;
+    readonly closedWithPay: string;
 }
-export declare const CASUALTY_DIAGNOSTIC_COMPONENTS: Readonly<CasualtyDiagnosticComponentKeys>;
-type MetricDisplayOverride = Partial<Pick<MetricDefinition, "displayName" | "description" | "unit" | "numeratorLabel" | "denominatorLabel" | "basis">>;
-export interface CasualtyMetricPresetOptions {
-    /** Caller source/output measure keys, including the exposure key. */
-    components?: Partial<CasualtyDiagnosticComponentKeys>;
-    frequencyScale?: number;
-    frequencyUnit?: MetricDefinition["unit"];
-    definitionVersion?: string;
-    basisLabels?: {
-        limited250?: string;
-        primary?: string;
-        counts?: string;
-    };
-    /** Per-metric display/basis overrides; formulas remain the documented preset formulas. */
-    displayOverrides?: Readonly<Record<string, MetricDisplayOverride>>;
+export interface CasualtyAmountBinding {
+    readonly id: string;
+    readonly paid: string;
+    readonly incurred: string;
 }
-/** Builds the optional 20-metric reference preset from caller-selected keys and display metadata. */
-export declare function createCasualtyQuarterlyMetrics(options?: CasualtyMetricPresetOptions): readonly MetricDefinition[];
-export declare const CASUALTY_QUARTERLY_METRICS: readonly MetricDefinition[];
-export interface CasualtyAmountLayerOptions {
-    components?: Partial<Pick<CasualtyDiagnosticComponentKeys, "paid250" | "incurred250" | "paidPrimary" | "incurredPrimary">>;
-    limited250?: {
-        id?: string;
-        displayName?: string;
-        paidSourceMeasure?: string;
-        incurredSourceMeasure?: string;
-    };
-    primary?: {
-        id?: string;
-        displayName?: string;
-        indemnityPaidMeasure?: string;
-        indemnityIncurredMeasure?: string;
-        expensePaidMeasure?: string;
-        expenseIncurredMeasure?: string;
-        indemnityLimit?: number;
-    };
+export type DiagnosticMetricPresentationOverride = Partial<DiagnosticMetricPresentation>;
+export interface CreateCasualtyMetricInstancesInput {
+    readonly counts: CasualtyCountBindings;
+    readonly exposure: string;
+    readonly amountBindings: readonly CasualtyAmountBinding[];
+    readonly presentationOverrides?: Readonly<Record<string, DiagnosticMetricPresentationOverride>>;
 }
-export declare function createCasualtyAmountLayers(options?: CasualtyAmountLayerOptions): readonly AmountLayerDefinition[];
-export declare const CASUALTY_AMOUNT_LAYERS: readonly AmountLayerDefinition[];
-export {};
+export declare function createCasualtyMetricInstances(input: CreateCasualtyMetricInstancesInput): readonly DiagnosticMetricInstance[];
 //# sourceMappingURL=casualtyDiagnostics.d.ts.map

package/dist/casualtyDiagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"casualtyDiagnostics.d.ts","sourceRoot":"","sources":["../src/casualtyDiagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,qBAAqB,EAE1B,KAAK,gBAAgB,EAEtB,MAAM,wBAAwB,CAAC;AAahC,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,+BAA+B,CAU3E,CAAC;AAEX,KAAK,qBAAqB,GAAG,OAAO,CAAC,IAAI,CACvC,gBAAgB,EAChB,aAAa,GAAG,aAAa,GAAG,MAAM,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,OAAO,CACzF,CAAC,CAAC;AAEH,MAAM,WAAW,2BAA2B;IAC1C,qEAAqE;IACrE,UAAU,CAAC,EAAE,OAAO,CAAC,+BAA+B,CAAC,CAAC;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC;CACpE;AA6CD,qGAAqG;AACrG,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,2BAAgC,GACxC,SAAS,gBAAgB,EAAE,CAwC7B;AAED,eAAO,MAAM,0BAA0B,6BAAmC,CAAC;AAE3E,MAAM,WAAW,0BAA0B;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,SAAS,GAAG,aAAa,GAAG,aAAa,GAAG,iBAAiB,CAAC,CAAC,CAAC;IAC3H,UAAU,CAAC,EAAE;QACX,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,OAAO,CAAC,EAAE;QACR,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,sBAAsB,CAAC,EAAE,MAAM,CAAC;QAChC,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,0BAA+B,GACvC,SAAS,qBAAqB,EAAE,CA6BlC;AAED,eAAO,MAAM,sBAAsB,kCAA+B,CAAC"}
+{"version":3,"file":"casualtyDiagnostics.d.ts","sourceRoot":"","sources":["../src/casualtyDiagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,KAAK,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAC;AAEzG,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,MAAM,WAAW,qBAAqB;IAAG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE;AACzJ,MAAM,WAAW,qBAAqB;IAAG,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AAChH,MAAM,MAAM,oCAAoC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;AACzF,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1D,QAAQ,CAAC,qBAAqB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oCAAoC,CAAC,CAAC,CAAC;CACjG;AA+BD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,kCAAkC,GAAG,SAAS,wBAAwB,EAAE,CAgD5H"}

package/dist/casualtyDiagnostics.js

@@ -1,122 +1,92 @@
-import { measureExpressionComponents, } from "./metricDiagnostics.js";
-import { ReservingError } from "./types.js";
-const m = (measure) => ({ op: "measure", measure });
+import { CASUALTY_FORMULA_TEMPLATES } from "./diagnosticFormulas.js";
+import { DiagnosticValidationError } from "./types.js";
+export { CASUALTY_FORMULA_TEMPLATES };
+const m = (measureId) => ({ op: "measure", measureId });
 const sub = (left, right) => ({ op: "subtract", left, right });
-function definedProperties(value) {
-    if (value === undefined)
-        return {};
-    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+function validToken(value) {
+    if (value.length === 0 || /^[\t-\r ]|[\t-\r ]$/.test(value) || value.includes("\0"))
+        return false;
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(++index);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return false;
+    }
+    return true;
 }
-export const CASUALTY_DIAGNOSTIC_COMPONENTS = {
-    reported: "reportedCount",
-    open: "openCount",
-    closedNoPay: "closedNoPayCount",
-    closedWithPay: "closedWithPayCount",
-    exposure: "exposure",
-    paid250: "paid250",
-    incurred250: "incurred250",
-    paidPrimary: "paidPrimary",
-    incurredPrimary: "incurredPrimary",
-};
-function metric(id, displayName, description, unit, scale, numerator, denominator, numeratorLabel, denominatorLabel, basis, version, override, warningRules) {
-    const definition = {
-        id,
-        version,
-        displayName,
-        description,
-        unit,
-        scale,
-        numerator,
-        denominator,
-        numeratorLabel,
-        denominatorLabel,
-        basis,
-        requiredComponents: [...new Set([
-                ...measureExpressionComponents(numerator),
-                ...measureExpressionComponents(denominator),
-            ])],
-        warningRules,
-    };
-    return { ...definition, ...definedProperties(override) };
+function encodeBindingId(value) { return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`); }
+function presentation(displayName, description, displayUnit, numeratorLabel, denominatorLabel) {
+    return { displayName, description, displayUnit, scale: 1, numeratorLabel, denominatorLabel };
 }
-const paidWarning = [{
-        code: "PAID_EXCEEDS_INCURRED",
-        when: "numerator-greater-than-denominator",
-        message: "Paid exceeds incurred on the selected amount basis",
-        tolerance: 1e-9,
-    }];
-/** Builds the optional 20-metric reference preset from caller-selected keys and display metadata. */
-export function createCasualtyQuarterlyMetrics(options = {}) {
-    const C = {
-        ...CASUALTY_DIAGNOSTIC_COMPONENTS,
-        ...definedProperties(options.components),
-    };
-    const frequencyScale = options.frequencyScale ?? 1_000_000;
-    if (!Number.isFinite(frequencyScale) || frequencyScale <= 0) {
-        throw new ReservingError("BAD_RATIO", `Casualty frequency scale must be positive; got ${frequencyScale}`);
-    }
-    const version = options.definitionVersion ?? "casualty-quarterly-v1";
-    const frequencyUnit = options.frequencyUnit ?? (frequencyScale === 1_000_000
-        ? "count-per-million"
-        : "count-per-exposure-scale");
-    const limitedBasis = options.basisLabels?.limited250 ?? "$250K pre-capped total";
-    const primaryBasis = options.basisLabels?.primary ?? "$1M capped indemnity plus unlimited expense";
-    const countBasis = options.basisLabels?.counts ?? "count";
-    const override = (id) => options.displayOverrides?.[id];
-    const nonClosedNoPay = sub(m(C.reported), m(C.closedNoPay));
-    return [
-        metric("reported-frequency", "Reported claim frequency", "Reported claims per scaled exposure units", frequencyUnit, frequencyScale, m(C.reported), m(C.exposure), "reported claims", "exposure", countBasis, version, override("reported-frequency")),
-        metric("open-frequency", "Open claim frequency", "Open claims per scaled exposure units", frequencyUnit, frequencyScale, m(C.open), m(C.exposure), "open claims", "exposure", countBasis, version, override("open-frequency")),
-        metric("closed-no-pay-frequency", "Closed-no-pay frequency", "Closed-no-pay claims per scaled exposure units", frequencyUnit, frequencyScale, m(C.closedNoPay), m(C.exposure), "closed-no-pay claims", "exposure", countBasis, version, override("closed-no-pay-frequency")),
-        metric("closed-with-pay-frequency", "Closed-with-pay frequency", "Closed-with-pay claims per scaled exposure units", frequencyUnit, frequencyScale, m(C.closedWithPay), m(C.exposure), "closed-with-pay claims", "exposure", countBasis, version, override("closed-with-pay-frequency")),
-        metric("non-closed-no-pay-frequency", "Non-closed-no-pay frequency", "Reported less closed-no-pay claims per scaled exposure units", frequencyUnit, frequencyScale, nonClosedNoPay, m(C.exposure), "reported less closed-no-pay claims", "exposure", countBasis, version, override("non-closed-no-pay-frequency")),
-        metric("closed-no-pay-share", "Closed-no-pay share", "Closed-no-pay claims divided by reported claims", "ratio", 1, m(C.closedNoPay), m(C.reported), "closed-no-pay claims", "reported claims", countBasis, version, override("closed-no-pay-share")),
-        metric("closed-with-pay-share", "Closed-with-pay share", "Closed-with-pay claims divided by reported claims", "ratio", 1, m(C.closedWithPay), m(C.reported), "closed-with-pay claims", "reported claims", countBasis, version, override("closed-with-pay-share")),
-        metric("open-share", "Open share", "Open claims divided by reported claims", "ratio", 1, m(C.open), m(C.reported), "open claims", "reported claims", countBasis, version, override("open-share")),
-        metric("paid-to-incurred-250", "Paid-to-incurred ($250K)", "Paid divided by incurred on the pre-capped $250K basis", "ratio", 1, m(C.paid250), m(C.incurred250), "$250K paid", "$250K incurred", limitedBasis, version, override("paid-to-incurred-250"), paidWarning),
-        metric("paid-to-incurred-primary", "Paid-to-incurred (primary)", "Paid divided by incurred on the primary basis", "ratio", 1, m(C.paidPrimary), m(C.incurredPrimary), "primary paid", "primary incurred", primaryBasis, version, override("paid-to-incurred-primary"), paidWarning),
-        metric("incurred-250-per-exposure", "Incurred per exposure ($250K)", "$250K incurred divided by exposure", "currency-per-exposure", 1, m(C.incurred250), m(C.exposure), "$250K incurred", "exposure", limitedBasis, version, override("incurred-250-per-exposure")),
-        metric("incurred-primary-per-exposure", "Incurred per exposure (primary)", "Primary incurred divided by exposure", "currency-per-exposure", 1, m(C.incurredPrimary), m(C.exposure), "primary incurred", "exposure", primaryBasis, version, override("incurred-primary-per-exposure")),
-        metric("incurred-250-per-non-cnp", "Incurred severity ($250K)", "$250K incurred divided by reported less closed-no-pay claims", "currency-per-claim", 1, m(C.incurred250), nonClosedNoPay, "$250K incurred", "reported less closed-no-pay claims", limitedBasis, version, override("incurred-250-per-non-cnp")),
-        metric("incurred-primary-per-non-cnp", "Incurred severity (primary)", "Primary incurred divided by reported less closed-no-pay claims", "currency-per-claim", 1, m(C.incurredPrimary), nonClosedNoPay, "primary incurred", "reported less closed-no-pay claims", primaryBasis, version, override("incurred-primary-per-non-cnp")),
-        metric("paid-250-per-exposure", "Paid per exposure ($250K)", "$250K paid divided by exposure", "currency-per-exposure", 1, m(C.paid250), m(C.exposure), "$250K paid", "exposure", limitedBasis, version, override("paid-250-per-exposure")),
-        metric("paid-primary-per-exposure", "Paid per exposure (primary)", "Primary paid divided by exposure", "currency-per-exposure", 1, m(C.paidPrimary), m(C.exposure), "primary paid", "exposure", primaryBasis, version, override("paid-primary-per-exposure")),
-        metric("paid-250-per-closed-with-pay", "Paid severity ($250K)", "$250K paid divided by closed-with-pay claims", "currency-per-claim", 1, m(C.paid250), m(C.closedWithPay), "$250K paid", "closed-with-pay claims", limitedBasis, version, override("paid-250-per-closed-with-pay")),
-        metric("paid-primary-per-closed-with-pay", "Paid severity (primary)", "Primary paid divided by closed-with-pay claims", "currency-per-claim", 1, m(C.paidPrimary), m(C.closedWithPay), "primary paid", "closed-with-pay claims", primaryBasis, version, override("paid-primary-per-closed-with-pay")),
-        metric("case-250-per-open", "Case reserve per open claim ($250K)", "$250K incurred less paid divided by open claims", "currency-per-claim", 1, sub(m(C.incurred250), m(C.paid250)), m(C.open), "$250K incurred less paid", "open claims", limitedBasis, version, override("case-250-per-open")),
-        metric("case-primary-per-open", "Case reserve per open claim (primary)", "Primary incurred less paid divided by open claims", "currency-per-claim", 1, sub(m(C.incurredPrimary), m(C.paidPrimary)), m(C.open), "primary incurred less paid", "open claims", primaryBasis, version, override("case-primary-per-open")),
-    ];
+function overridePresentation(id, base, overrides) {
+    const override = overrides?.[id];
+    if (!override)
+        return base;
+    for (const [key, value] of Object.entries(override))
+        if (value === undefined)
+            throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-type", path: `$.presentationOverrides[${JSON.stringify(id)}].${key}`, message: "Presentation override cannot contain undefined" }]);
+    const result = { ...base, ...override };
+    if (!Number.isFinite(result.scale) || result.scale <= 0)
+        throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-number", path: `$.presentationOverrides[${JSON.stringify(id)}].scale`, message: "Presentation scale must be finite and positive" }]);
+    return result;
 }
-export const CASUALTY_QUARTERLY_METRICS = createCasualtyQuarterlyMetrics();
-export function createCasualtyAmountLayers(options = {}) {
-    const C = {
-        ...CASUALTY_DIAGNOSTIC_COMPONENTS,
-        ...definedProperties(options.components),
-    };
-    const limit = options.primary?.indemnityLimit ?? 1_000_000;
-    if (!Number.isFinite(limit) || limit <= 0) {
-        throw new ReservingError("BAD_CAP", `Primary indemnity limit must be positive; got ${limit}`);
+export function createCasualtyMetricInstances(input) {
+    for (const [key, value] of Object.entries({ ...input.counts, exposure: input.exposure }))
+        if (!validToken(value))
+            throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-string", path: `$.${key}`, message: "Measure binding must be a token" }]);
+    const ids = new Set();
+    for (const [index, binding] of input.amountBindings.entries()) {
+        if (!validToken(binding.id) || !validToken(binding.paid) || !validToken(binding.incurred))
+            throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-string", path: `$.amountBindings[${index}]`, message: "Amount binding fields must be tokens" }]);
+        if (ids.has(binding.id))
+            throw new DiagnosticValidationError([{ domain: "configuration", code: "duplicate-id", path: `$.amountBindings[${index}].id`, message: `Duplicate amount binding ${binding.id}` }]);
+        ids.add(binding.id);
     }
-    return [
-        {
-            id: options.limited250?.id ?? "250k-pre-capped-total",
-            displayName: options.limited250?.displayName ?? "$250K pre-capped total",
-            paidMeasure: C.paid250,
-            incurredMeasure: C.incurred250,
-            paid: { op: "measure", measure: options.limited250?.paidSourceMeasure ?? "preCapped250Paid" },
-            incurred: { op: "measure", measure: options.limited250?.incurredSourceMeasure ?? "preCapped250Incurred" },
-            basis: "pre-capped-additive",
-        },
-        {
-            id: options.primary?.id ?? "primary-1m-indemnity-plus-expense",
-            displayName: options.primary?.displayName ?? "Primary: $1M capped indemnity plus unlimited expense",
-            paidMeasure: C.paidPrimary,
-            incurredMeasure: C.incurredPrimary,
-            paid: { op: "add", terms: [{ op: "claim-cap", measure: options.primary?.indemnityPaidMeasure ?? "indemnityPaid", limit }, { op: "measure", measure: options.primary?.expensePaidMeasure ?? "expensePaid" }] },
-            incurred: { op: "add", terms: [{ op: "claim-cap", measure: options.primary?.indemnityIncurredMeasure ?? "indemnityIncurred", limit }, { op: "measure", measure: options.primary?.expenseIncurredMeasure ?? "expenseIncurred" }] },
-            basis: "claim-level-cap",
-        },
+    const nonClosedNoPay = sub(m(input.counts.reported), m(input.counts.closedNoPay));
+    const countSpecs = [
+        ["reported-frequency", "frequency", m(input.counts.reported), m(input.exposure), presentation("Reported frequency", "Reported count divided by exposure", "count per exposure", "reported", "exposure")],
+        ["open-frequency", "frequency", m(input.counts.open), m(input.exposure), presentation("Open frequency", "Open count divided by exposure", "count per exposure", "open", "exposure")],
+        ["closed-no-pay-frequency", "frequency", m(input.counts.closedNoPay), m(input.exposure), presentation("Closed-no-pay frequency", "Closed-no-pay count divided by exposure", "count per exposure", "closed-no-pay", "exposure")],
+        ["closed-with-pay-frequency", "frequency", m(input.counts.closedWithPay), m(input.exposure), presentation("Closed-with-pay frequency", "Closed-with-pay count divided by exposure", "count per exposure", "closed-with-pay", "exposure")],
+        ["non-closed-no-pay-frequency", "frequency", nonClosedNoPay, m(input.exposure), presentation("Non-closed-no-pay frequency", "Reported less closed-no-pay count divided by exposure", "count per exposure", "reported less closed-no-pay", "exposure")],
+        ["closed-no-pay-share", "share", m(input.counts.closedNoPay), m(input.counts.reported), presentation("Closed-no-pay share", "Closed-no-pay count divided by reported count", "ratio", "closed-no-pay", "reported")],
+        ["closed-with-pay-share", "share", m(input.counts.closedWithPay), m(input.counts.reported), presentation("Closed-with-pay share", "Closed-with-pay count divided by reported count", "ratio", "closed-with-pay", "reported")],
+        ["closed-with-pay-share-of-non-closed-no-pay", "share", m(input.counts.closedWithPay), nonClosedNoPay, presentation("Closed-with-pay share of non-closed-no-pay", "Closed-with-pay count divided by reported less closed-no-pay count", "ratio", "closed-with-pay", "reported less closed-no-pay")],
+        ["open-share", "share", m(input.counts.open), m(input.counts.reported), presentation("Open share", "Open count divided by reported count", "ratio", "open", "reported")],
+        ["open-share-of-non-closed-no-pay", "share", m(input.counts.open), nonClosedNoPay, presentation("Open share of non-closed-no-pay", "Open count divided by reported less closed-no-pay count", "ratio", "open", "reported less closed-no-pay")],
     ];
+    const specs = [];
+    for (const [suffix, formulaId, numerator, denominator, display] of countSpecs) {
+        const id = `casualty/count/${suffix}`;
+        const bindings = formulaId === "frequency"
+            ? { claims: numerator, exposure: denominator }
+            : { part: numerator, whole: denominator };
+        specs.push({ id, formulaId, bindings, presentation: display, rules: [] });
+    }
+    for (const binding of input.amountBindings) {
+        const prefix = `casualty/amount/${encodeBindingId(binding.id)}`;
+        const amountSpecs = [
+            ["paid-to-incurred", "paid-to-incurred", { paid: m(binding.paid), incurred: m(binding.incurred) }, presentation("Paid to incurred", "Paid divided by incurred on the bound amount basis", "ratio", "paid", "incurred")],
+            ["incurred-per-exposure", "amount-per-exposure", { amount: m(binding.incurred), exposure: m(input.exposure) }, presentation("Incurred per exposure", "Incurred divided by exposure", "amount per exposure", "incurred", "exposure")],
+            ["incurred-per-non-closed-no-pay-claim", "amount-per-claim", { amount: m(binding.incurred), claims: nonClosedNoPay }, presentation("Incurred per non-closed-no-pay claim", "Incurred divided by reported less closed-no-pay count", "amount per claim", "incurred", "reported less closed-no-pay")],
+            ["paid-per-exposure", "amount-per-exposure", { amount: m(binding.paid), exposure: m(input.exposure) }, presentation("Paid per exposure", "Paid divided by exposure", "amount per exposure", "paid", "exposure")],
+            ["paid-per-closed-with-pay-claim", "amount-per-claim", { amount: m(binding.paid), claims: m(input.counts.closedWithPay) }, presentation("Paid per closed-with-pay claim", "Paid divided by closed-with-pay count", "amount per claim", "paid", "closed-with-pay")],
+            ["case-per-open-claim", "case-per-open", { incurred: m(binding.incurred), paid: m(binding.paid), open: m(input.counts.open) }, presentation("Case reserve per open claim", "Incurred less paid divided by open count", "amount per claim", "incurred less paid", "open")],
+        ];
+        for (const [suffix, formulaId, bindings, display] of amountSpecs) {
+            const id = `${prefix}/${suffix}`;
+            const rules = suffix === "paid-to-incurred" ? [{ id: `${id}/rule/paid-exceeds-incurred`, code: "paid-exceeds-incurred", message: "Paid exceeds incurred on the bound amount basis", severity: "warning", when: { left: { source: "calculation", field: "numerator" }, operator: "gt", right: { source: "calculation", field: "denominator" }, tolerance: { absolute: 0, relative: 0 } } }] : suffix === "case-per-open-claim" ? [{ id: `${id}/rule/negative-case`, code: "negative-case", message: "Incurred less paid is negative on the bound amount basis", severity: "warning", when: { left: { source: "calculation", field: "numerator" }, operator: "lt", right: { source: "constant", value: 0 }, tolerance: { absolute: 0, relative: 0 } } }] : [];
+            specs.push({ id, formulaId, bindings: { ...bindings }, presentation: display, rules });
+        }
+    }
+    const validIds = new Set(specs.map((spec) => spec.id));
+    for (const key of Object.keys(input.presentationOverrides ?? {}))
+        if (!validIds.has(key))
+            throw new DiagnosticValidationError([{ domain: "configuration", code: "unknown-reference", path: `$.presentationOverrides[${JSON.stringify(key)}]`, message: "Presentation override names an unknown generated instance" }]);
+    return Object.freeze(specs.map((spec) => Object.freeze({ id: spec.id, version: "1.0.0", formulaId: spec.formulaId, bindings: spec.bindings, presentation: overridePresentation(spec.id, spec.presentation, input.presentationOverrides), rules: spec.rules })));
 }
-export const CASUALTY_AMOUNT_LAYERS = createCasualtyAmountLayers();
 //# sourceMappingURL=casualtyDiagnostics.js.map