@actuarial-ts/core 0.8.1 → 0.9.0

package/src/analysisExpressions.ts

@@ -0,0 +1,223 @@
+import type {
+  AnalysisDefinition, AnalysisDerivedMeasureDefinition, AnalysisMeasureExpression,
+  AnalysisResultValue, AnalysisDerivedComponent, CustomizationCapabilityFinding,
+} from "./customizationContracts.js";
+import { canonicalJson } from "./canonical.js";
+import { isDiagnosticPlainRecord, isDiagnosticToken, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { DiagnosticValidationError } from "./types.js";
+
+type Factors = Readonly<Record<string, number>>;
+export type CompiledAnalysisExpression = { readonly definition: AnalysisDerivedMeasureDefinition; readonly unit: string; readonly unitFactors: Factors; readonly dependencies: readonly string[] };
+const invalid = (message: string, path = "$.definition.derivedMeasures", code: "invalid-configuration" | "unknown-reference" | "incompatible-semantics" | "expression-limit" | "cycle" = "invalid-configuration"): never => {
+  throw new DiagnosticValidationError([{ domain: "definition", code, path, message }]);
+};
+
+function normalizedFactors(raw: unknown): Factors {
+  if (!isDiagnosticPlainRecord(raw) || Object.keys(raw).length > 32) return invalid("Unit factors require a bounded record of integer powers");
+  const result: [string, number][] = [];
+  for (const [unit, power] of Object.entries(raw)) {
+    if (!isDiagnosticToken(unit) || typeof power !== "number" || !Number.isSafeInteger(power) || Math.abs(power) > 32)
+      return invalid("Unit factors require valid unit names and integer powers between -32 and 32");
+    if (power !== 0) result.push([unit, power]);
+  }
+  return Object.fromEntries(result.sort(([a], [b]) => a.localeCompare(b)));
+}
+function combine(left: Factors, right: Factors, direction: 1 | -1): Factors {
+  const result = new Map(Object.entries(left));
+  for (const [unit, power] of Object.entries(right)) result.set(unit, (result.get(unit) ?? 0) + direction * power);
+  return normalizedFactors(Object.fromEntries(result));
+}
+export function formatAnalysisUnit(factors: Factors): string {
+  const normalized = normalizedFactors(factors);
+  const part = (sign: 1 | -1) => Object.entries(normalized).filter(([, power]) => power * sign > 0).map(([unit, power]) => {
+    const atom = /[*/^()[\]{}]/.test(unit) ? `[${unit}]` : unit;
+    return Math.abs(power) === 1 ? atom : `${atom}^${Math.abs(power)}`;
+  }).join("*");
+  const numerator = part(1) || "1";
+  const denominator = part(-1);
+  return denominator ? `${numerator}/${denominator.includes("*") ? `(${denominator})` : denominator}` : numerator;
+}
+
+/** Validates a bounded dependency graph and resolves dimensions without evaluating any values. */
+export function compileAnalysisExpressions(definition: AnalysisDefinition): readonly CompiledAnalysisExpression[] {
+  const derived = definition.derivedMeasures ?? [];
+  if (derived.length > 64) return invalid("At most 64 derived measures are supported", undefined, "expression-limit");
+  const base = new Map(definition.measures.map((m) => [m.id, m]));
+  const declarations = new Map(derived.map((m) => [m.id, m]));
+  if (base.size !== definition.measures.length || declarations.size !== derived.length || derived.some((m) => !isDiagnosticToken(m.id) || base.has(m.id)))
+    return invalid("Base and derived measure IDs must be distinct valid tokens");
+  const compiled = new Map<string, CompiledAnalysisExpression>();
+  const visiting = new Set<string>();
+  let totalNodes = 0;
+  const resolve = (id: string): Factors => {
+    const raw = base.get(id);
+    if (raw) return normalizedFactors(raw.unitFactors ?? { [raw.unit]: 1 });
+    const prior = compiled.get(id);
+    if (prior) return prior.unitFactors;
+    const measure = declarations.get(id);
+    if (!measure) return invalid(`Unknown measure ${id}`, undefined, "unknown-reference");
+    if (visiting.has(id)) return invalid(`Derived measure cycle at ${id}`, undefined, "cycle");
+    visiting.add(id);
+    const dependencies = new Set<string>();
+    const walk = (raw: unknown, depth: number, ancestors: ReadonlySet<object>): Factors => {
+      if (++totalNodes > 1024 || depth > 16) return invalid("Derived expressions exceed 1024 total nodes or 16 nested levels", undefined, "expression-limit");
+      if (!isDiagnosticPlainRecord(raw)) return invalid("Expression nodes must be objects");
+      if (ancestors.has(raw)) return invalid("Expression contains an object cycle", undefined, "cycle");
+      const next = new Set(ancestors).add(raw);
+      const keys: Record<string, string[]> = { measure: ["op", "measureId"], exposure: ["op", "exposureId"], constant: ["op", "value", "unitFactors"], add: ["op", "terms"], subtract: ["op", "left", "right"], multiply: ["op", "left", "right"], divide: ["op", "numerator", "denominator"] };
+      const allowed = typeof raw.op === "string" && Object.hasOwn(keys, raw.op) ? keys[raw.op] : undefined;
+      if (!allowed || Object.keys(raw).some((key) => !allowed.includes(key))) return invalid("Unknown expression operator or field");
+      if (raw.op === "measure") {
+        if (!isDiagnosticToken(raw.measureId)) return invalid("Invalid measure reference");
+        dependencies.add(raw.measureId);
+        return resolve(raw.measureId);
+      }
+      if (raw.op === "exposure") {
+        const exposure = definition.exposures.find((item) => item.id === raw.exposureId);
+        if (!exposure) return invalid(`Unknown exposure ${String(raw.exposureId)}`, undefined, "unknown-reference");
+        return normalizedFactors({ [exposure.unit]: 1 });
+      }
+      if (raw.op === "constant") {
+        if (typeof raw.value !== "number" || !Number.isFinite(raw.value)) return invalid("Constants must be finite numbers");
+        return normalizedFactors(raw.unitFactors);
+      }
+      if (raw.op === "add") {
+        if (!Array.isArray(raw.terms) || raw.terms.length < 1 || raw.terms.length > 32) return invalid("Addition requires 1 to 32 terms");
+        const terms = raw.terms.map((term) => walk(term, depth + 1, next));
+        if (terms.some((term) => canonicalJson(term) !== canonicalJson(terms[0]))) return invalid("Addition requires matching units", undefined, "incompatible-semantics");
+        return terms[0]!;
+      }
+      const left = walk(raw.op === "divide" ? raw.numerator : raw.left, depth + 1, next);
+      const right = walk(raw.op === "divide" ? raw.denominator : raw.right, depth + 1, next);
+      if (raw.op === "subtract") {
+        if (canonicalJson(left) !== canonicalJson(right)) return invalid("Subtraction requires matching units", undefined, "incompatible-semantics");
+        return left;
+      }
+      return combine(left, right, raw.op === "divide" ? -1 : 1);
+    };
+    const unitFactors = walk(measure.expression, 0, new Set());
+    if (measure.developmentSemantics !== "point-in-time") {
+      const dimensionlessConstant = (expression: AnalysisMeasureExpression) => expression.op === "constant" && Object.keys(normalizedFactors(expression.unitFactors)).length === 0;
+      const checkStage = (expression: AnalysisMeasureExpression): void => {
+        if (expression.op === "constant") return;
+        if (expression.op === "measure") {
+          const referenced = base.get(expression.measureId) ?? declarations.get(expression.measureId)!;
+          if (referenced.developmentSemantics !== measure.developmentSemantics)
+            invalid("Cumulative/incremental expressions require components with matching development meaning", undefined, "incompatible-semantics");
+          return;
+        }
+        if (expression.op === "add") { expression.terms.forEach(checkStage); return; }
+        if (expression.op === "subtract") { checkStage(expression.left); checkStage(expression.right); return; }
+        if (expression.op === "multiply" && dimensionlessConstant(expression.left)) { checkStage(expression.right); return; }
+        if (expression.op === "multiply" && dimensionlessConstant(expression.right)) { checkStage(expression.left); return; }
+        if (expression.op === "divide" && dimensionlessConstant(expression.denominator)) { checkStage(expression.numerator); return; }
+        invalid("Ratios, products and exposure expressions require point-in-time development meaning unless scaling by a dimensionless constant", undefined, "incompatible-semantics");
+      };
+      checkStage(measure.expression);
+    }
+    compiled.set(id, { definition: measure, unit: formatAnalysisUnit(unitFactors), unitFactors, dependencies: [...dependencies].sort() });
+    visiting.delete(id);
+    return unitFactors;
+  };
+  for (const measure of derived) resolve(measure.id);
+  return snapshotDiagnosticJson([...compiled.values()]);
+}
+
+/** Resolves requested outputs and their transitive statistic dependencies. */
+export function analysisExpressionDependencies(compiled: readonly CompiledAnalysisExpression[], requested: ReadonlySet<string>): ReadonlySet<string> {
+  const dependencies = new Set(requested);
+  const pending = [...requested];
+  while (pending.length) {
+    const id = pending.pop()!;
+    for (const dependency of compiled.find((item) => item.definition.id === id)?.dependencies ?? []) {
+      if (!dependencies.has(dependency)) { dependencies.add(dependency); pending.push(dependency); }
+    }
+  }
+  return dependencies;
+}
+
+/** Executes post-aggregation expressions on one exact origin/evaluation coordinate. */
+export function evaluateAnalysisExpressions(input: {
+  readonly definition: AnalysisDefinition;
+  readonly values: readonly AnalysisResultValue[];
+  readonly coordinates: AnalysisResultValue["coordinates"];
+  readonly exposures: ReadonlyMap<string, number>;
+  readonly exposureFindings: ReadonlyMap<string, readonly CustomizationCapabilityFinding[]>;
+  readonly requested: ReadonlySet<string>;
+}): readonly AnalysisResultValue[] {
+  const compiled = compileAnalysisExpressions(input.definition);
+  if (compiled.length === 0) return [];
+  for (const id of input.requested)
+    if (!input.definition.measures.some((measure) => measure.id === id) && !compiled.some((item) => item.definition.id === id))
+      return invalid(`Unknown requested measure ${id}`, undefined, "unknown-reference");
+  const required = analysisExpressionDependencies(compiled, input.requested);
+  for (const value of input.values) {
+    if (canonicalJson(value.coordinates) !== canonicalJson(input.coordinates))
+      return invalid("Expression components must share the exact origin/evaluation coordinate", undefined, "incompatible-semantics");
+    const measure = input.definition.measures.find((m) => m.id === value.measureId);
+    if (!measure || value.unit !== measure.unit || (value.value !== null && !Number.isFinite(value.value)))
+      return invalid("Expression components must match declared base measures, units and finite values", undefined, "incompatible-semantics");
+  }
+  if (new Set(input.values.map((value) => value.measureId)).size !== input.values.length)
+    return invalid("Expression components contain duplicate measure results");
+  const values = new Map(input.values.map((value) => [value.measureId, value]));
+  const output: AnalysisResultValue[] = [];
+  for (const item of compiled) {
+    if (!required.has(item.definition.id)) continue;
+    const components = new Map<string, AnalysisDerivedComponent>();
+    const findings: CustomizationCapabilityFinding[] = [];
+    const unavailable = (message: string): null => {
+      findings.push({ code: "missing-prerequisite", capability: "derived-analysis-measures", path: `$.derivedMeasures.${item.definition.id}`, message });
+      return null;
+    };
+    let numerator: number | null = null;
+    let denominator: number | null = null;
+    const evaluate = (expression: AnalysisMeasureExpression, root = false): number | null => {
+      if (expression.op === "constant") return expression.value;
+      if (expression.op === "measure") {
+        const value = values.get(expression.measureId);
+        if (value) {
+          components.set(`measure:${expression.measureId}`, { kind: "measure", id: expression.measureId, unit: value.unit, value: value.value, status: value.status, contributingObservations: value.contributingObservations, excludedObservations: value.excludedObservations });
+          findings.push(...value.findings);
+        } else {
+          const unit = input.definition.measures.find((m) => m.id === expression.measureId)?.unit ?? compiled.find((m) => m.definition.id === expression.measureId)!.unit;
+          components.set(`measure:${expression.measureId}`, { kind: "measure", id: expression.measureId, unit, value: null, status: "unavailable", contributingObservations: 0, excludedObservations: 0 });
+        }
+        return !value || value.status !== "available" || value.value === null || value.excludedObservations > 0
+          ? unavailable(`Measure ${expression.measureId} requires a complete available result`) : value.value;
+      }
+      if (expression.op === "exposure") {
+        const value = input.exposures.get(expression.exposureId);
+        const exposureFindings = input.exposureFindings.get(expression.exposureId) ?? [];
+        findings.push(...exposureFindings);
+        const available = value !== undefined && Number.isFinite(value) && exposureFindings.length === 0;
+        components.set(`exposure:${expression.exposureId}`, { kind: "exposure", id: expression.exposureId, unit: input.definition.exposures.find((e) => e.id === expression.exposureId)!.unit, value: available ? value : null, status: available ? "available" : "unavailable", contributingObservations: 0, excludedObservations: 0 });
+        return available ? value : unavailable(`Exposure ${expression.exposureId} requires an available allocated result`);
+      }
+      let value: number;
+      if (expression.op === "add") {
+        const terms = expression.terms.map((term) => evaluate(term));
+        if (terms.some((term) => term === null)) return null;
+        value = terms.reduce<number>((sum, term) => sum + term!, 0);
+      } else {
+        const left = evaluate(expression.op === "divide" ? expression.numerator : expression.left);
+        const right = evaluate(expression.op === "divide" ? expression.denominator : expression.right);
+        if (root && expression.op === "divide") { numerator = left; denominator = right; }
+        if (left === null || right === null) return null;
+        if (expression.op === "divide" && right <= 0) return unavailable("Division requires a strictly positive denominator");
+        value = expression.op === "subtract" ? left - right : expression.op === "multiply" ? left * right : left / right;
+      }
+      return Number.isFinite(value) ? value : unavailable("Expression arithmetic overflowed; no finite result is available");
+    };
+    const value = evaluate(item.definition.expression, true);
+    const result: AnalysisResultValue = {
+      measureId: item.definition.id, unit: item.unit, coordinates: input.coordinates, value,
+      status: value === null ? "unavailable" : "available", contributingObservations: 0, excludedObservations: 0, exact: true,
+      numerator, denominator, findings: [...new Map(findings.map((finding) => [canonicalJson(finding), finding])).values()],
+      derivation: { stage: "post-aggregation", unitFactors: item.unitFactors, components: [...components.values()] },
+    };
+    values.set(result.measureId, result);
+    output.push(result);
+  }
+  return snapshotDiagnosticJson(output);
+}

package/src/analysisFinancialUnits.ts

@@ -0,0 +1,55 @@
+import type { AnalysisDefinition, AnalysisRecipe } from "./customizationContracts.js";
+import { formatAnalysisUnit } from "./analysisExpressions.js";
+import { DiagnosticValidationError } from "./types.js";
+
+const incompatible = (message: string): never => {
+  throw new DiagnosticValidationError([{ domain: "configuration", code: "incompatible-semantics", path: "$.recipe.steps", message }]);
+};
+
+/** Resolves the declared output units of an ordered financial pipeline before calculating results. */
+export function resolveAnalysisFinancialUnits(definition: AnalysisDefinition, recipe: AnalysisRecipe): AnalysisDefinition {
+  const step = recipe.steps.find((item) => item.kind === "apply-financial-pipeline");
+  if (step?.kind !== "apply-financial-pipeline") return definition;
+  const stages = step.stageIds.map((id) => definition.financialAdjustments?.find((item) => item.id === id));
+  if (!stages.some((stage) => stage?.kind === "currency")) return definition;
+  const rawUnits = new Map<string, Set<string>>();
+  for (const measure of definition.measures) {
+    if (measure.statistic.kind !== "sum") continue;
+    const id = measure.statistic.measureId;
+    const units = rawUnits.get(id) ?? new Set<string>();
+    units.add(measure.unit);
+    rawUnits.set(id, units);
+  }
+  const rawUnit = (id: string): string => {
+    const units = rawUnits.get(id);
+    if (!units || units.size !== 1) return incompatible(`Currency conversion needs one declared sum unit for ${id}`);
+    return [...units][0]!;
+  };
+  const initialUnit = rawUnit(step.amountMeasureId);
+  let outputUnit = initialUnit;
+  for (const stage of stages) {
+    if (!stage) continue;
+    if (stage.kind === "currency") {
+      if (stage.fromUnit !== outputUnit) return incompatible(`Currency stage ${stage.id} expects ${stage.fromUnit}, not ${outputUnit}`);
+      outputUnit = stage.toUnit;
+    } else if (stage.kind === "include-expense" || stage.kind === "exclude-expense" || stage.kind === "net-recovery") {
+      const id = stage.kind === "net-recovery" ? stage.recoveryMeasureId : stage.expenseMeasureId;
+      if (rawUnit(id) !== outputUnit) return incompatible(`Financial component ${id} must use the current pipeline unit ${outputUnit}`);
+    }
+  }
+  const effectiveUnit = (id: string): string => id === step.amountMeasureId ? outputUnit : definition.exposures.find((e) => e.id === id)?.unit ?? rawUnit(id);
+  const measures = definition.measures.map((measure) => {
+    const statistic = measure.statistic;
+    if (statistic.kind === "ratio") {
+      if (statistic.numeratorMeasureId !== step.amountMeasureId && statistic.denominatorMeasureId !== step.amountMeasureId) return measure;
+      const numerator = effectiveUnit(statistic.numeratorMeasureId);
+      const denominator = effectiveUnit(statistic.denominatorMeasureId);
+      const factors = numerator === denominator ? {} : { [numerator]: 1, [denominator]: -1 };
+      return { ...measure, unit: numerator === denominator ? "ratio" : formatAnalysisUnit(factors), unitFactors: factors };
+    }
+    if ("measureId" in statistic && statistic.measureId === step.amountMeasureId)
+      return { ...measure, unit: outputUnit, unitFactors: { [outputUnit]: 1 } };
+    return measure;
+  });
+  return { ...definition, measures };
+}

package/src/analysisRecipe.ts

@@ -23,6 +23,8 @@ import type {
 } from "./customizationContracts.js";
 import { calculateAnalysisStatistic } from "./descriptiveStatistics.js";
 import { calculateRecipeExposureRatio } from "./analysisRecipeStatistics.js";
+import { compileAnalysisExpressions, analysisExpressionDependencies, evaluateAnalysisExpressions } from "./analysisExpressions.js";
+import { resolveAnalysisFinancialUnits } from "./analysisFinancialUnits.js";
 import { compareAnalysisEvaluations, compareAnalysisResults } from "./analysisComparison.js";
 export { compareAnalysisResults } from "./analysisComparison.js";
 import { isDiagnosticToken, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
@@ -75,7 +77,7 @@ function recipeIssues(
       hasCalculate = true;
     if (step.kind === "calculate")
       step.measureIds.forEach((id) => {
-        if (!definition.measures.some((measure) => measure.id === id))
+        if (![...definition.measures, ...(definition.derivedMeasures ?? [])].some((measure) => measure.id === id))
           issues.push({ domain: "configuration", code: "unknown-reference", path: `$.recipe.steps[${index}].measureIds`, message: `Unknown measure ${id}` });
       });
     if (step.kind === "earn-exposure")
@@ -166,6 +168,8 @@ export function runAnalysisRecipe(input: {
 }): AnalysisResult {
   const issues = recipeIssues(input.recipe, input.definition, input.history);
   if (issues.length > 0) throw new DiagnosticValidationError(issues);
+  const outputDefinition = resolveAnalysisFinancialUnits(input.definition, input.recipe);
+  const expressions = compileAnalysisExpressions(outputDefinition);
   const prepared = prepareHistoricalDataset(input.history);
   const evaluationDate = input.evaluationDate ?? maxEvaluationDate(prepared.observations);
   const selected = selectedAt(prepared.observations, evaluationDate, input.definition.period.observationSelection);
@@ -280,16 +284,18 @@ export function runAnalysisRecipe(input: {
     if (group === undefined) groups.set(origin.originId, { label: origin.label, observations: [observation] });
     else group.observations.push(observation);
   }
-  const measureIds = new Set(
+  const requestedMeasureIds = new Set(
     input.recipe.steps.filter((step) => step.kind === "calculate").flatMap((step) => step.measureIds),
   );
+  const measureIds = analysisExpressionDependencies(expressions, requestedMeasureIds);
   // When preparation excluded every observation, retain visible unavailable
   // output instead of hiding the preparation findings in an empty result.
   if (groups.size === 0 && prepared.findings.length > 0)
     groups.set("unassigned", { label: "Unavailable history", observations: [] });
   const values: AnalysisResultValue[] = [];
   for (const [originId, group] of [...groups].sort(([left], [right]) => left.localeCompare(right))) {
-    for (const measure of input.definition.measures.filter((candidate) => measureIds.has(candidate.id))) {
+    const start = values.length;
+    for (const measure of outputDefinition.measures.filter((candidate) => measureIds.has(candidate.id))) {
       let measureObservations = measure.populationScopeId === input.definition.scopes.financial.id
         ? group.observations
         : group.observations.filter((observation) => reportingKeys.has(key(observation)));
@@ -357,9 +363,18 @@ export function runAnalysisRecipe(input: {
         findings: statistic.findings,
       });
     }
+    values.push(...evaluateAnalysisExpressions({
+      definition: outputDefinition,
+      values: values.slice(start),
+      coordinates: { originId, originLabel: group.label, evaluationDate },
+      exposures: exposedByTarget.get(originId) ?? new Map(),
+      exposureFindings: exposureFindingsByMeasure,
+      requested: requestedMeasureIds,
+    }));
   }
   if (originFailures.length > 0) {
-    for (const measure of input.definition.measures.filter((candidate) => measureIds.has(candidate.id))) {
+    const start = values.length;
+    for (const measure of outputDefinition.measures.filter((candidate) => measureIds.has(candidate.id))) {
       const originFindings = originFailures
         .filter(({ observation }) => measure.populationScopeId === input.definition.scopes.financial.id || reportingKeys.has(key(observation)))
         .map(({ finding }) => finding);
@@ -378,6 +393,12 @@ export function runAnalysisRecipe(input: {
         findings: originFindings,
       });
     }
+    values.push(...evaluateAnalysisExpressions({
+      definition: outputDefinition,
+      values: values.slice(start),
+      coordinates: { originId: "unassigned", originLabel: "Unavailable origin", evaluationDate },
+      exposures: new Map(), exposureFindings: exposureFindingsByMeasure, requested: requestedMeasureIds,
+    }));
   }
   const calculationInput = {
     corePackageVersion: CORE_PACKAGE_VERSION,

package/src/customizationContracts.ts

@@ -13,6 +13,7 @@ export const CUSTOMIZATION_CAPABILITIES = [
   "exposure-earning",
   "typed-populations",
   "descriptive-statistics",
+  "derived-analysis-measures",
   "reserving-triangle-adapter",
   "bounded-execution",
   "shared-financial-terms",
@@ -426,12 +427,39 @@ export type AnalysisStatisticDefinition =
 export interface AnalysisMeasureDefinitionV1 {
   readonly id: string;
   readonly unit: string;
+  /** Optional explicit dimensions for composing already-derived units. Unit labels are otherwise opaque atoms. */
+  readonly unitFactors?: Readonly<Record<string, number>>;
   readonly developmentSemantics: "cumulative" | "incremental" | "point-in-time";
   readonly statistic: AnalysisStatisticDefinition;
   readonly populationScopeId: string;
   readonly condition?: AnalysisPredicate;
 }
 
+export type AnalysisMeasureExpression =
+  | { readonly op: "measure"; readonly measureId: string }
+  | { readonly op: "exposure"; readonly exposureId: string }
+  | { readonly op: "constant"; readonly value: number; readonly unitFactors: Readonly<Record<string, number>> }
+  | { readonly op: "add"; readonly terms: readonly AnalysisMeasureExpression[] }
+  | { readonly op: "subtract" | "multiply"; readonly left: AnalysisMeasureExpression; readonly right: AnalysisMeasureExpression }
+  | { readonly op: "divide"; readonly numerator: AnalysisMeasureExpression; readonly denominator: AnalysisMeasureExpression };
+
+/** Post-aggregation arithmetic. Each referenced statistic retains its own population and condition. */
+export interface AnalysisDerivedMeasureDefinition {
+  readonly id: string;
+  readonly expression: AnalysisMeasureExpression;
+  readonly developmentSemantics: "point-in-time" | "cumulative" | "incremental";
+}
+
+export interface AnalysisDerivedComponent {
+  readonly kind: "measure" | "exposure";
+  readonly id: string;
+  readonly unit: string;
+  readonly value: number | null;
+  readonly status: "available" | "unavailable";
+  readonly contributingObservations: number;
+  readonly excludedObservations: number;
+}
+
 export type AnalysisObservationSelection =
   | {
       readonly kind: "evaluation-date";
@@ -562,6 +590,7 @@ export interface AnalysisDefinition {
   readonly period: AnalysisPeriodDefinition;
   readonly exposures: readonly ExposureMeasureDefinitionV1[];
   readonly measures: readonly AnalysisMeasureDefinitionV1[];
+  readonly derivedMeasures?: readonly AnalysisDerivedMeasureDefinition[];
   readonly financialTerms: readonly FinancialTermDefinition[];
   readonly financialAdjustments?: readonly FinancialAmountAdjustment[];
 }
@@ -672,6 +701,12 @@ export interface AnalysisResultValue {
   readonly numerator: number | null;
   readonly denominator: number | null;
   readonly findings: readonly CustomizationCapabilityFinding[];
+  /** Counts on a derived value are not additive population counts; inspect each component instead. */
+  readonly derivation?: {
+    readonly stage: "post-aggregation";
+    readonly unitFactors: Readonly<Record<string, number>>;
+    readonly components: readonly AnalysisDerivedComponent[];
+  };
 }
 
 export interface AnalysisResult {

package/src/index.ts

@@ -12,6 +12,8 @@ export * from "./reservingAdapter.js";
 export * from "./financialTerms.js";
 export * from "./financialPipeline.js";
 export * from "./analysisRecipe.js";
+export * from "./analysisExpressions.js";
+export * from "./analysisFinancialUnits.js";
 export * from "./util.js";
 export * from "./canonical.js";
 export {

package/src/version.ts

@@ -1,2 +1,2 @@
 /** This package's runtime version. A test pins it to package.json. */
-export const CORE_PACKAGE_VERSION = "0.8.1";
+export const CORE_PACKAGE_VERSION = "0.9.0";