@actuarial-ts/core 0.7.0 → 0.8.0

package/README.md

@@ -4,10 +4,15 @@ Pure, framework-free P&C actuarial math for TypeScript. It includes triangles, d
 
 The package is designed to support the actuary's compliance with the 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.
 
+SDK 0.8 adds versioned loss history, irregular period and exposure contracts,
+population statistics, shared financial terms, and deterministic recipe and
+scenario execution. See the [0.8 adoption guide](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/migrations/0.8-reusable-customization.md)
+and [customization reference](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/reference/reusable-customization.md).
+
 ## Install
 
 ```bash
-npm install @actuarial-ts/core@0.7.0
+npm install @actuarial-ts/core@0.8.0
 ```
 
 ESM, TypeScript-first, zero runtime dependencies, Node 20+.
@@ -73,6 +78,45 @@ const prepared = prepareDiagnosticData({ definition: compiled, losses, exposures
 const result = runMetricDiagnostics({ prepared, groupMap: { fleet: "all-fleet" } });
 ```
 
+### Eager and compact paths
+
+The example above uses the retained eager APIs. The additive compact APIs,
+introduced in 0.7.0, expose the same numeric views while retaining complete audit
+and identity evidence behind authenticated owners instead of eagerly expanding
+it. Choose matching preparation, calculation, and maturity functions:
+
+| Operation | Eager | Compact |
+|---|---|---|
+| Prepare inputs | `prepareDiagnosticData` | `prepareDiagnosticDataCompact` |
+| Calculate metric views | `runMetricDiagnostics` | `runMetricDiagnosticsCompact` |
+| Select one development age | `sameMaturity` | `sameMaturityCompact` |
+| Select the latest common age across output groups | `commonMaturity` | `commonMaturityCompact` |
+
+The original maturity signatures remain unchanged; compact results use the
+separately named helpers, not casts to eager results. Development ages use the
+result's declared age unit. Review evaluations are available through
+`pageDiagnosticReviewEvaluations`, with source references separately available
+through `pageDiagnosticReviewEvaluationSources`. Passing and not-evaluated
+evaluations remain available; paging is not sampling.
+
+Use owner-controlled identity documents and `iterateDiagnosticIdentityJson`
+when complete canonical text is needed. `materializePreparedDiagnosticData` and
+`materializeMetricDiagnosticsResult` intentionally expand the eager evidence;
+they are explicit compatibility choices, not a memory-saving export path.
+Cloning or parsing an owner does not recreate its authority. Compact storage is
+not a dataset-capacity or bounded-memory guarantee for an entire application.
+
+SDK 0.8 adds authenticated compact selection helpers for metric, source-group,
+whole-origin, and valuation/age scopes. Eligible clean aggregate preparations
+share immutable cells while preserving the same fresh preparation and result
+identities; an ineligible scope returns `undefined` so the data gateway can use
+ordinary preparation. These functions do not issue review or execution receipts.
+
+These are lower-level calculation APIs. For a host import or analysis boundary
+that enforces both review and metric execution policy, use the validated gateway
+in `@actuarial-ts/data`. The runnable [compact adoption guide](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/migrations/0.7-compact-diagnostics.md)
+covers the complete workflow and [streamed replay](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/reference/diagnostic-replay-stream.md).
+
 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.
@@ -88,7 +132,7 @@ numeric exposure values. This is a bounded capacity, not an unlimited scale clai
 
 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.7.0/docs/reference/diagnostic-formulas.md) and [0.6 migration guide](https://github.com/yerromnitsuj/actng/blob/v0.7.0/docs/migrations/0.6-generalized-diagnostics.md).
+See the generated [formula and instance catalog](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/reference/diagnostic-formulas.md) and [0.6 migration guide](https://github.com/yerromnitsuj/actng/blob/v0.8.0/docs/migrations/0.6-generalized-diagnostics.md).
 
 ## Main method families
 

package/dist/analysisRecipe.d.ts

@@ -0,0 +1,55 @@
+import type { AnalysisDefinition, AnalysisRecipe, AnalysisResult, AnalysisScenario, AnalysisScenarioGrid, AnalysisScenarioDifference, AnalysisScenarioRun, AnalysisRollForward, AnalysisScenarioBridgeStep, AnalysisResultCache, CustomizationResourceLimits, CustomizationExposureObservation, ExposureAllocationTarget, ExposureRevisionSelection, HistoricalDatasetInput } from "./customizationContracts.js";
+/** Executes the closed, deterministic recipe vocabulary over loss history and exposure inputs. */
+export declare function runAnalysisRecipe(input: {
+    readonly history: HistoricalDatasetInput;
+    readonly definition: AnalysisDefinition;
+    readonly recipe: AnalysisRecipe;
+    readonly exposureObservations?: readonly CustomizationExposureObservation[];
+    readonly exposureTargets?: readonly ExposureAllocationTarget[];
+    readonly exposureRevisionSelection?: ExposureRevisionSelection;
+    readonly evaluationDate?: string;
+}): AnalysisResult;
+export declare function applyAnalysisScenario(definition: AnalysisDefinition, scenario: AnalysisScenario): AnalysisDefinition;
+export declare function compareAnalysisResults(baseline: AnalysisResult, scenario: AnalysisResult): readonly AnalysisScenarioDifference[];
+/** Runs a bounded list of controlled scenarios against one immutable baseline. */
+export declare function runAnalysisScenarios(input: {
+    readonly history: HistoricalDatasetInput;
+    readonly definition: AnalysisDefinition;
+    readonly recipe: AnalysisRecipe;
+    readonly scenarios: readonly AnalysisScenario[];
+    readonly limits: Pick<CustomizationResourceLimits, "maximumActiveScenarios">;
+    readonly exposureObservations?: readonly CustomizationExposureObservation[];
+    readonly exposureTargets?: readonly ExposureAllocationTarget[];
+    readonly exposureRevisionSelection?: ExposureRevisionSelection;
+    readonly evaluationDate?: string;
+}): readonly AnalysisScenarioRun[];
+/** Expands a closed Cartesian parameter grid after proving its product is bounded. */
+export declare function expandAnalysisScenarioGrid(grid: AnalysisScenarioGrid, limits: Pick<CustomizationResourceLimits, "maximumActiveScenarios">): readonly AnalysisScenario[];
+/** Expands and runs a bounded parameter grid against one immutable baseline. */
+export declare function runAnalysisScenarioGrid(input: Omit<Parameters<typeof runAnalysisScenarios>[0], "scenarios"> & {
+    readonly grid: AnalysisScenarioGrid;
+}): readonly AnalysisScenarioRun[];
+/** Complete dependency identity for exact full-result reuse, including lineage. */
+export declare function analysisRecipeDependencyIdentity(input: Parameters<typeof runAnalysisRecipe>[0]): string;
+/** Uses caller-owned cache storage; a hit is returned only for the complete dependency identity. */
+export declare function runAnalysisRecipeCached(input: Parameters<typeof runAnalysisRecipe>[0] & {
+    readonly cache: AnalysisResultCache;
+}): {
+    readonly cacheStatus: "hit" | "miss";
+    readonly dependencyIdentity: string;
+    readonly result: AnalysisResult;
+};
+/** Preserves the prior result and recipe while executing a later immutable valuation. */
+export declare function rollForwardAnalysisRecipe(input: Parameters<typeof runAnalysisRecipe>[0] & {
+    readonly priorEvaluationDate: string;
+    readonly currentEvaluationDate: string;
+}): AnalysisRollForward;
+/** Applies explicitly ordered, one-change scenario steps and reports each incremental bridge. */
+export declare function runAnalysisScenarioBridge(input: Parameters<typeof runAnalysisRecipe>[0] & {
+    readonly scenarios: readonly AnalysisScenario[];
+    readonly limits: Pick<CustomizationResourceLimits, "maximumActiveScenarios">;
+}): {
+    readonly baseline: AnalysisResult;
+    readonly steps: readonly AnalysisScenarioBridgeStep[];
+};
+//# sourceMappingURL=analysisRecipe.d.ts.map

package/dist/analysisRecipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysisRecipe.d.ts","sourceRoot":"","sources":["../src/analysisRecipe.ts"],"names":[],"mappings":"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"}