@actuarial-ts/core 0.7.0 → 0.8.0

package/src/policyPeriods.ts

@@ -0,0 +1,375 @@
+import type {
+  AnalysisComparisonCoordinate,
+  AnalysisOriginAssignment,
+  MatchedAccidentCohort,
+  AnalysisPeriodDefinition,
+  HistoricalScalar,
+  PolicyCoveragePeriod,
+  PolicyPeriodAssignment,
+  PreparedHistoricalObservation,
+} from "./customizationContracts.js";
+import { isRealIsoDate, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+
+function compareText(left: string, right: string): number {
+  return left === right ? 0 : left < right ? -1 : 1;
+}
+
+function scheduleIssues(schedule: readonly PolicyCoveragePeriod[]): DiagnosticValidationIssue[] {
+  const issues: DiagnosticValidationIssue[] = [];
+  const ids = new Set<string>();
+  schedule.forEach((period, index) => {
+    if (ids.has(period.id))
+      issues.push({
+        domain: "configuration",
+        code: "duplicate-id",
+        path: `$.policySchedule[${index}].id`,
+        message: "Policy period ID is duplicated",
+      });
+    ids.add(period.id);
+    if (!isRealIsoDate(period.startDate) || !isRealIsoDate(period.endDate) || period.startDate >= period.endDate)
+      issues.push({
+        domain: "configuration",
+        code: "invalid-period",
+        path: `$.policySchedule[${index}]`,
+        message: "Policy period requires real dates with startDate before endDate",
+      });
+  });
+  return issues;
+}
+
+export function validatePolicyCoverageSchedule(
+  schedule: readonly PolicyCoveragePeriod[],
+): readonly PolicyCoveragePeriod[] {
+  const issues = scheduleIssues(schedule);
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+  return snapshotDiagnosticJson(
+    [...schedule].sort(
+      (left, right) =>
+        compareText(left.startDate, right.startDate) ||
+        compareText(left.endDate, right.endDate) ||
+        compareText(left.id, right.id),
+    ),
+  );
+}
+
+function scalarMatches(actual: HistoricalScalar | readonly HistoricalScalar[] | undefined, expected: HistoricalScalar): boolean {
+  return Array.isArray(actual) ? actual.some((value) => Object.is(value, expected)) : Object.is(actual, expected);
+}
+
+function scopeMatches(
+  observation: PreparedHistoricalObservation,
+  period: PolicyCoveragePeriod,
+): boolean {
+  return Object.entries(period.scope).every(([id, expected]) =>
+    scalarMatches(observation.dimensions[id], expected),
+  );
+}
+
+export interface AssignPolicyPeriodInput {
+  readonly observation: PreparedHistoricalObservation;
+  readonly schedule: readonly PolicyCoveragePeriod[];
+  readonly relationship: "policy" | "coverage" | "date-only";
+  readonly dateBasis?: "accident" | "report";
+}
+
+export function assignPolicyPeriod(input: AssignPolicyPeriodInput): PolicyPeriodAssignment {
+  const schedule = validatePolicyCoverageSchedule(input.schedule);
+  let candidates: PolicyCoveragePeriod[];
+  if (input.relationship === "policy") {
+    const ids = new Set(input.observation.relationships.policyIds ?? []);
+    candidates = schedule.filter((period) => ids.has(period.id));
+  } else if (input.relationship === "coverage") {
+    const ids = new Set(input.observation.relationships.coverageIds ?? []);
+    candidates = schedule.filter((period) => ids.has(period.id));
+  } else {
+    const date =
+      input.dateBasis === "report"
+        ? input.observation.reportDate
+        : input.observation.accidentDate;
+    if (date === null)
+      return snapshotDiagnosticJson({
+        status: "unavailable",
+        period: null,
+        candidates: [],
+        finding: {
+          code: "missing-prerequisite",
+          capability: "irregular-periods",
+          path: `$.observations.${input.observation.sourceNamespace}.${input.observation.claimId}`,
+          message: `Date-only policy assignment requires ${input.dateBasis === "report" ? "reportDate" : "accidentDate"}`,
+          requiredFields: [input.dateBasis === "report" ? "reportDate" : "accidentDate"],
+        },
+      });
+    candidates = schedule.filter(
+      (period) => period.startDate <= date && date < period.endDate && scopeMatches(input.observation, period),
+    );
+  }
+  const candidateIds = candidates.map((period) => period.id).sort(compareText);
+  if (candidates.length === 1)
+    return snapshotDiagnosticJson({
+      status: "assigned",
+      period: candidates[0]!,
+      candidates: candidateIds,
+      finding: null,
+    });
+  if (candidates.length > 1)
+    return snapshotDiagnosticJson({
+      status: "ambiguous",
+      period: null,
+      candidates: candidateIds,
+      finding: {
+        code: "ambiguous-attribution",
+        capability: "irregular-periods",
+        path: `$.observations.${input.observation.sourceNamespace}.${input.observation.claimId}`,
+        message: `Policy assignment matches multiple periods: ${candidateIds.join(", ")}`,
+      },
+    });
+  return snapshotDiagnosticJson({
+    status: "unavailable",
+    period: null,
+    candidates: [],
+    finding: {
+      code: "missing-prerequisite",
+      capability: "irregular-periods",
+      path: `$.observations.${input.observation.sourceNamespace}.${input.observation.claimId}`,
+      message: "No policy period matches the declared relationship, date, and scope",
+    },
+  });
+}
+
+function calendarLabel(date: string, cadence: "month" | "quarter" | "year"): string {
+  const [year, month] = date.split("-").map(Number) as [number, number, number];
+  if (cadence === "year") return String(year).padStart(4, "0");
+  if (cadence === "quarter") return `${String(year).padStart(4, "0")}Q${Math.floor((month - 1) / 3) + 1}`;
+  return `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}`;
+}
+
+function fiscalLabel(
+  date: string,
+  cadence: "quarter" | "year",
+  startMonth: number,
+): string {
+  const [calendarYear, calendarMonth] = date.split("-").map(Number) as [number, number, number];
+  const offset = (calendarMonth - startMonth + 12) % 12;
+  const fiscalStartYear = calendarMonth >= startMonth ? calendarYear : calendarYear - 1;
+  const fiscalYear = startMonth === 1 ? fiscalStartYear : fiscalStartYear + 1;
+  return cadence === "year"
+    ? `FY${fiscalYear}`
+    : `FY${fiscalYear}Q${Math.floor(offset / 3) + 1}`;
+}
+
+export function assignAnalysisOrigin(
+  observation: PreparedHistoricalObservation,
+  period: AnalysisPeriodDefinition,
+  schedule: readonly PolicyCoveragePeriod[] = [],
+): AnalysisOriginAssignment {
+  if (period.originBasis === "policy") {
+    const assignment = assignPolicyPeriod({
+      observation,
+      schedule,
+      relationship:
+        (observation.relationships.coverageIds?.length ?? 0) > 0
+          ? "coverage"
+          : (observation.relationships.policyIds?.length ?? 0) > 0
+            ? "policy"
+            : "date-only",
+      dateBasis: "accident",
+    });
+    return snapshotDiagnosticJson({
+      status: assignment.status,
+      originId: assignment.period?.id ?? null,
+      label: assignment.period?.label ?? null,
+      period: assignment.period,
+      finding: assignment.finding,
+    });
+  }
+  const date = period.originBasis === "accident" ? observation.accidentDate : observation.reportDate;
+  if (date === null)
+    return snapshotDiagnosticJson({
+      status: "unavailable",
+      originId: null,
+      label: null,
+      period: null,
+      finding: {
+        code: "missing-prerequisite",
+        capability: "irregular-periods",
+        path: `$.observations.${observation.sourceNamespace}.${observation.claimId}`,
+        message: `${period.originBasis} origin requires its source date`,
+        requiredFields: [period.originBasis === "accident" ? "accidentDate" : "reportDate"],
+      },
+    });
+  if (period.grouping.kind === "policy-schedule")
+    return snapshotDiagnosticJson({
+      status: "unavailable",
+      originId: null,
+      label: null,
+      period: null,
+      finding: {
+        code: "unsupported-operation",
+        capability: "irregular-periods",
+        path: "$.period.grouping",
+        message: "Accident/report origins require calendar or fiscal grouping",
+      },
+    });
+  const label =
+    period.grouping.kind === "calendar"
+      ? calendarLabel(date, period.grouping.cadence)
+      : fiscalLabel(date, period.grouping.cadence, period.grouping.startMonth);
+  return snapshotDiagnosticJson({
+    status: "assigned",
+    originId: label,
+    label,
+    period: null,
+    finding: null,
+  });
+}
+
+function daysFromCivil(date: string): number {
+  let [year, month, day] = date.split("-").map(Number) as [number, number, number];
+  year -= month <= 2 ? 1 : 0;
+  const era = Math.floor(year / 400);
+  const yearOfEra = year - era * 400;
+  const shiftedMonth = month + (month > 2 ? -3 : 9);
+  const dayOfYear = Math.floor((153 * shiftedMonth + 2) / 5) + day - 1;
+  const dayOfEra = yearOfEra * 365 + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100) + dayOfYear;
+  return era * 146097 + dayOfEra;
+}
+
+export function daysBetweenIsoDates(startDate: string, endDate: string): number {
+  if (!isRealIsoDate(startDate) || !isRealIsoDate(endDate))
+    throw new DiagnosticValidationError([
+      {
+        domain: "configuration",
+        code: "invalid-period",
+        path: "$.date",
+        message: "Day difference requires real Gregorian dates",
+      },
+    ]);
+  return daysFromCivil(endDate) - daysFromCivil(startDate);
+}
+
+function leapYear(year: number): boolean {
+  return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+}
+
+/** Converts a source-system inclusive expiration to the internal end-exclusive boundary. */
+export function inclusiveExpirationToEndExclusive(expirationDate: string): string {
+  if (!isRealIsoDate(expirationDate))
+    throw new DiagnosticValidationError([{ domain: "input", code: "invalid-period", path: "$.expirationDate", message: "Inclusive expiration must be a real Gregorian date" }]);
+  let [year, month, day] = expirationDate.split("-").map(Number) as [number, number, number];
+  const days = [31, leapYear(year) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  day += 1;
+  if (day > days[month - 1]!) { day = 1; month += 1; }
+  if (month > 12) { month = 1; year += 1; }
+  if (year > 9999)
+    throw new DiagnosticValidationError([{ domain: "input", code: "invalid-period", path: "$.expirationDate", message: "Inclusive expiration cannot be represented as an end-exclusive date" }]);
+  return `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+
+/**
+ * Selects the same relative accident-day window inside each irregular policy
+ * period. Each claim stays namespaced and appears at most once per period.
+ */
+export function matchAccidentCohorts(input: {
+  readonly observations: readonly PreparedHistoricalObservation[];
+  readonly periods: readonly PolicyCoveragePeriod[];
+  readonly startOffsetDays: number;
+  readonly endOffsetDays: number;
+}): readonly MatchedAccidentCohort[] {
+  if (!Number.isSafeInteger(input.startOffsetDays) || !Number.isSafeInteger(input.endOffsetDays) || input.startOffsetDays < 0 || input.endOffsetDays <= input.startOffsetDays)
+    throw new DiagnosticValidationError([{ domain: "configuration", code: "invalid-period", path: "$.cohortOffsets", message: "Matched cohort offsets require nonnegative safe integers with end after start" }]);
+  const periods = validatePolicyCoverageSchedule(input.periods);
+  return snapshotDiagnosticJson(periods.map((period) => {
+    const keys = new Set<string>();
+    for (const observation of input.observations) {
+      if (observation.accidentDate === null || !scopeMatches(observation, period)) continue;
+      const offset = daysBetweenIsoDates(period.startDate, observation.accidentDate);
+      if (offset >= input.startOffsetDays && offset < input.endOffsetDays)
+        keys.add(`${observation.sourceNamespace}:${observation.claimId}`);
+    }
+    return {
+      periodId: period.id,
+      startOffsetDays: input.startOffsetDays,
+      endOffsetDays: input.endOffsetDays,
+      observationKeys: [...keys].sort(compareText),
+    };
+  }));
+}
+
+function completeCalendarMonths(start: string, end: string): number {
+  const [startYear, startMonth, startDay] = start.split("-").map(Number) as [number, number, number];
+  const [endYear, endMonth, endDay] = end.split("-").map(Number) as [number, number, number];
+  let months = (endYear - startYear) * 12 + endMonth - startMonth;
+  if (months > 0 && endDay < startDay) months -= 1;
+  if (months < 0 && endDay > startDay) months += 1;
+  return months;
+}
+
+export function analysisComparisonCoordinate(input: {
+  readonly period: AnalysisPeriodDefinition;
+  readonly evaluationDate: string;
+  readonly policyPeriod?: PolicyCoveragePeriod | null;
+}): AnalysisComparisonCoordinate {
+  if (!isRealIsoDate(input.evaluationDate))
+    throw new DiagnosticValidationError([
+      {
+        domain: "view",
+        code: "invalid-period",
+        path: "$.evaluationDate",
+        message: "evaluationDate must be a real Gregorian date",
+      },
+    ]);
+  const clock = input.period.comparisonClock;
+  if (clock === "common-evaluation-date")
+    return snapshotDiagnosticJson({
+      status: "available",
+      clock,
+      evaluationDate: input.evaluationDate,
+      age: null,
+      ageUnit: null,
+      finding: null,
+    });
+  if (clock === "matched-accident-cohorts")
+    return snapshotDiagnosticJson({
+      status: "unavailable",
+      clock,
+      evaluationDate: input.evaluationDate,
+      age: null,
+      ageUnit: null,
+      finding: {
+        code: "missing-prerequisite",
+        capability: "irregular-periods",
+        path: "$.period.comparisonClock",
+        message: "Matched accident cohorts require an explicit constituent-cohort definition",
+        requiredFields: ["matchedCohortDefinition"],
+      },
+    });
+  if (input.policyPeriod === undefined || input.policyPeriod === null)
+    return snapshotDiagnosticJson({
+      status: "unavailable",
+      clock,
+      evaluationDate: input.evaluationDate,
+      age: null,
+      ageUnit: null,
+      finding: {
+        code: "missing-prerequisite",
+        capability: "irregular-periods",
+        path: "$.policyPeriod",
+        message: `${clock} requires an assigned policy period`,
+        requiredFields: ["policyPeriod"],
+      },
+    });
+  const start = clock === "since-period-start" ? input.policyPeriod.startDate : input.policyPeriod.endDate;
+  const age =
+    input.period.ageConvention === "exact-days"
+      ? daysFromCivil(input.evaluationDate) - daysFromCivil(start)
+      : completeCalendarMonths(start, input.evaluationDate);
+  return snapshotDiagnosticJson({
+    status: "available",
+    clock,
+    evaluationDate: input.evaluationDate,
+    age,
+    ageUnit: input.period.ageConvention === "exact-days" ? "day" : "month",
+    finding: null,
+  });
+}

package/src/populations.ts

@@ -0,0 +1,307 @@
+import type {
+  AnalysisDimensionDefinition,
+  AnalysisPopulationMembership,
+  AnalysisPredicate,
+  AnalysisPredicateOutcome,
+  AnalysisScopeDefinition,
+  HistoricalScalar,
+  PreparedHistoricalObservation,
+} from "./customizationContracts.js";
+import { isRealIsoDate, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+
+const MAX_PREDICATE_DEPTH = 64;
+const MAX_PREDICATE_NODES = 1_000;
+
+function scalarType(value: HistoricalScalar): "string" | "number" | "boolean" | "null" {
+  if (value === null) return "null";
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  return "boolean";
+}
+
+function compatible(
+  value: HistoricalScalar,
+  dimension: AnalysisDimensionDefinition,
+): boolean {
+  if (value === null) return true;
+  if (dimension.type === "date") return typeof value === "string" && isRealIsoDate(value);
+  if (dimension.type === "entity-reference") return typeof value === "string";
+  return typeof value === dimension.type && (typeof value !== "number" || Number.isFinite(value));
+}
+
+/** Validates the closed predicate vocabulary, references, types, and bounds. */
+export function validateAnalysisPredicate(
+  predicate: AnalysisPredicate,
+  dimensions: readonly AnalysisDimensionDefinition[],
+): AnalysisPredicate {
+  const byId = new Map(dimensions.map((dimension) => [dimension.id, dimension]));
+  const issues: DiagnosticValidationIssue[] = [];
+  const stack: { value: AnalysisPredicate; path: string; depth: number }[] = [
+    { value: predicate, path: "$", depth: 1 },
+  ];
+  let nodes = 0;
+  while (stack.length > 0) {
+    const { value, path, depth } = stack.pop()!;
+    nodes += 1;
+    if (nodes > MAX_PREDICATE_NODES) {
+      issues.push({
+        domain: "definition",
+        code: "expression-limit",
+        path: "$",
+        message: `Predicate exceeds ${MAX_PREDICATE_NODES} nodes`,
+      });
+      break;
+    }
+    if (depth > MAX_PREDICATE_DEPTH) {
+      issues.push({
+        domain: "definition",
+        code: "expression-limit",
+        path,
+        message: `Predicate exceeds depth ${MAX_PREDICATE_DEPTH}`,
+      });
+      continue;
+    }
+    if ("terms" in value) {
+      if (value.terms.length === 0)
+        issues.push({
+          domain: "definition",
+          code: "invalid-configuration",
+          path: `${path}.terms`,
+          message: `${value.op} requires at least one term`,
+        });
+      value.terms.forEach((term, index) => stack.push({ value: term, path: `${path}.terms[${index}]`, depth: depth + 1 }));
+      continue;
+    }
+    if ("term" in value) {
+      stack.push({ value: value.term, path: `${path}.term`, depth: depth + 1 });
+      continue;
+    }
+    if (!("dimensionId" in value)) continue;
+    const dimension = byId.get(value.dimensionId);
+    if (dimension === undefined) {
+      issues.push({
+        domain: "definition",
+        code: "unknown-reference",
+        path: `${path}.dimensionId`,
+        message: `Predicate references unknown dimension ${value.dimensionId}`,
+      });
+      continue;
+    }
+    if (value.op === "eq" && !compatible(value.value, dimension))
+      issues.push({
+        domain: "definition",
+        code: "incompatible-semantics",
+        path: `${path}.value`,
+        message: `Value type ${scalarType(value.value)} is incompatible with ${dimension.type} dimension ${dimension.id}`,
+      });
+    if (value.op === "in")
+      value.values.forEach((item, index) => {
+        if (!compatible(item, dimension))
+          issues.push({
+            domain: "definition",
+            code: "incompatible-semantics",
+            path: `${path}.values[${index}]`,
+            message: `Value type ${scalarType(item)} is incompatible with ${dimension.type} dimension ${dimension.id}`,
+          });
+      });
+    if (value.op === "range") {
+      if (dimension.type !== "number" && dimension.type !== "date")
+        issues.push({
+          domain: "definition",
+          code: "incompatible-semantics",
+          path,
+          message: `Range requires a number or date dimension; ${dimension.id} is ${dimension.type}`,
+        });
+      for (const [field, endpoint] of [
+        ["minimum", value.minimum],
+        ["maximum", value.maximum],
+      ] as const)
+        if (
+          endpoint !== undefined &&
+          !compatible(endpoint, dimension)
+        )
+          issues.push({
+            domain: "definition",
+            code: "incompatible-semantics",
+            path: `${path}.${field}`,
+            message: `Range endpoint is incompatible with ${dimension.type} dimension ${dimension.id}`,
+          });
+    }
+  }
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+  return snapshotDiagnosticJson(predicate);
+}
+
+function invert(value: AnalysisPredicateOutcome): AnalysisPredicateOutcome {
+  return value === "match" ? "no-match" : value === "no-match" ? "match" : "unknown";
+}
+
+function valuesOf(
+  dimensions: Readonly<Record<string, HistoricalScalar | readonly HistoricalScalar[]>>,
+  id: string,
+): readonly HistoricalScalar[] | undefined {
+  const value = dimensions[id];
+  return value === undefined ? undefined : Array.isArray(value) ? value : [value as HistoricalScalar];
+}
+
+function compareRange(
+  value: HistoricalScalar,
+  predicate: Extract<AnalysisPredicate, { op: "range" }>,
+): boolean {
+  if (typeof value !== "number" && typeof value !== "string") return false;
+  const compare = (left: number | string, right: number | string): number => {
+    if (typeof left !== typeof right) return Number.NaN;
+    if (typeof left === "number" && typeof right === "number")
+      return left === right ? 0 : left < right ? -1 : 1;
+    if (typeof left === "string" && typeof right === "string")
+      return left === right ? 0 : left < right ? -1 : 1;
+    return Number.NaN;
+  };
+  const lower =
+    predicate.minimum === undefined ||
+    (predicate.includeMinimum
+      ? compare(value, predicate.minimum) >= 0
+      : compare(value, predicate.minimum) > 0);
+  const upper =
+    predicate.maximum === undefined ||
+    (predicate.includeMaximum
+      ? compare(value, predicate.maximum) <= 0
+      : compare(value, predicate.maximum) < 0);
+  return lower && upper;
+}
+
+function observationDimensions(
+  observation: PreparedHistoricalObservation,
+): Readonly<Record<string, HistoricalScalar | readonly HistoricalScalar[]>> {
+  return {
+    ...observation.dimensions,
+    sourceNamespace: observation.sourceNamespace,
+    claimId: observation.claimId,
+    evaluationDate: observation.evaluationDate,
+    ...(observation.accidentDate === null ? {} : { accidentDate: observation.accidentDate }),
+    ...(observation.reportDate === null ? {} : { reportDate: observation.reportDate }),
+    ...(observation.status === null ? {} : { status: observation.status }),
+    ...(observation.relationships.claimantIds === undefined
+      ? {}
+      : { claimantIds: observation.relationships.claimantIds }),
+    ...(observation.relationships.occurrenceId === undefined
+      ? {}
+      : { occurrenceId: observation.relationships.occurrenceId }),
+    ...(observation.relationships.policyIds === undefined
+      ? {}
+      : { policyIds: observation.relationships.policyIds }),
+    ...(observation.relationships.coverageIds === undefined
+      ? {}
+      : { coverageIds: observation.relationships.coverageIds }),
+  };
+}
+
+export function evaluateAnalysisPredicate(
+  predicateInput: AnalysisPredicate,
+  dimensions: Readonly<Record<string, HistoricalScalar | readonly HistoricalScalar[]>>,
+  catalog: readonly AnalysisDimensionDefinition[],
+): AnalysisPredicateOutcome {
+  const predicate = validateAnalysisPredicate(predicateInput, catalog);
+  const evaluate = (value: AnalysisPredicate): AnalysisPredicateOutcome => {
+    if (!("dimensionId" in value)) {
+      if (value.op === "true") return "match";
+      if (value.op === "not") return invert(evaluate(value.term));
+      const terms = value.terms.map(evaluate);
+      return value.op === "and"
+        ? terms.includes("no-match")
+          ? "no-match"
+          : terms.includes("unknown")
+            ? "unknown"
+            : "match"
+        : terms.includes("match")
+          ? "match"
+          : terms.includes("unknown")
+            ? "unknown"
+            : "no-match";
+    }
+    const actual = valuesOf(dimensions, value.dimensionId);
+    if (value.op === "missing")
+      return (actual === undefined || actual.every((item) => item === null)) === value.isMissing
+        ? "match"
+        : "no-match";
+    if (actual === undefined || actual.every((item) => item === null)) return "unknown";
+    const observed = actual.filter((item) => item !== null);
+    if (value.op === "eq") return observed.some((item) => Object.is(item, value.value)) ? "match" : "no-match";
+    if (value.op === "in")
+      return observed.some((item) => value.values.some((expected) => Object.is(item, expected)))
+        ? "match"
+        : "no-match";
+    if (value.op === "range")
+      return observed.some((item) => compareRange(item, value)) ? "match" : "no-match";
+    return "no-match";
+  };
+  return evaluate(predicate);
+}
+
+function latestOnOrBefore(
+  history: readonly PreparedHistoricalObservation[],
+  asOfDate: string,
+): PreparedHistoricalObservation | undefined {
+  return history
+    .filter((observation) => observation.evaluationDate <= asOfDate)
+    .sort((left, right) =>
+      left.evaluationDate === right.evaluationDate
+        ? 0
+        : left.evaluationDate < right.evaluationDate
+          ? 1
+          : -1,
+    )[0];
+}
+
+export function evaluateAnalysisScope(input: {
+  readonly scope: AnalysisScopeDefinition;
+  readonly observation: PreparedHistoricalObservation;
+  readonly claimHistory: readonly PreparedHistoricalObservation[];
+  readonly dimensions: readonly AnalysisDimensionDefinition[];
+}): AnalysisPopulationMembership {
+  const classification = input.scope.classification;
+  const asOfDate = classification.kind === "as-observed" ? null : classification.asOfDate;
+  const classified =
+    classification.kind === "as-observed"
+      ? input.observation
+      : latestOnOrBefore(input.claimHistory, classification.asOfDate);
+  if (classified === undefined)
+    return snapshotDiagnosticJson({
+      scopeId: input.scope.id,
+      sourceNamespace: input.observation.sourceNamespace,
+      claimId: input.observation.claimId,
+      evaluationDate: input.observation.evaluationDate,
+      outcome: "unknown",
+      classificationDate: asOfDate!,
+      finding: {
+        code: "missing-prerequisite",
+        capability: "typed-populations",
+        path: `$.scopes.${input.scope.id}`,
+        message: `No classification observation exists on or before ${asOfDate}`,
+        requiredFields: ["classification observation"],
+      },
+    });
+  const outcome = evaluateAnalysisPredicate(
+    input.scope.predicate,
+    observationDimensions(classified),
+    input.dimensions,
+  );
+  return snapshotDiagnosticJson({
+    scopeId: input.scope.id,
+    sourceNamespace: input.observation.sourceNamespace,
+    claimId: input.observation.claimId,
+    evaluationDate: input.observation.evaluationDate,
+    outcome,
+    classificationDate: classified.evaluationDate,
+    finding:
+      outcome !== "unknown"
+        ? null
+        : {
+            code: "missing-prerequisite",
+            capability: "typed-populations",
+            path: `$.scopes.${input.scope.id}.predicate`,
+            message: "Predicate result is unknown because a required dimension is missing",
+          },
+  });
+}