@policyengine/calibration-tree 0.0.0-stage → 0.1.0

package/src/reforms.ts

@@ -0,0 +1,224 @@
+// Reform-validation data layer. Where calibration_diagnostics.json answers
+// "does the dataset reproduce its calibration targets", reform_validation.json
+// answers a downstream question: "does the dataset reproduce the budget effects
+// of policy reforms that an authority (JCT) has officially scored?".
+//
+// The cross-release external-comparison surface (the retired "External
+// checks" tab, its committed overrides, and the backfill automation) moved to
+// PolicyEngine/policyengine-scorecard (scorecard issue #15). What remains here
+// is the producer/consumer contract parsing the staging view uses to render a
+// candidate run's own reform_validation.json as release-gate telemetry.
+//
+// ---------------------------------------------------------------------------
+// reform_validation.json schema (v1) — the producer/consumer contract:
+//
+//   {
+//     "schema_version": 1,
+//     "release_id": "populace-us-2024-<sha>-...",
+//     "baseline_period": 2026,
+//     "scoring_window": "FY2025-2034",
+//     "reforms": [
+//       {
+//         "id": "obbba",                       // stable across releases
+//         "name": "One Big Beautiful Bill Act",
+//         "category": "OBBBA",                 // grouping label
+//         "description": "…",                  // optional
+//         "jct": {
+//           "score": -3700000000000,           // budget effect, USD (− = cost)
+//           "score_type": "conventional",      // or "dynamic"
+//           "window": "FY2025-2034",
+//           "source": "JCX-29-25",
+//           "source_url": "https://www.jct.gov/…",
+//           "published": "2025-05-..."         // optional ISO date
+//         },
+//         "microcosm": {
+//           "budget_effect": -3650000000000,   // Microcosm microsim, same window
+//           "window": "FY2025-2034",
+//           "annual": { "2025": -1.2e11, … }   // optional per-year series
+//         }
+//       }
+//     ]
+//   }
+// ---------------------------------------------------------------------------
+
+import { asObject } from "./latest-artifact";
+
+type JsonObject = Record<string, unknown>;
+
+export const REFORM_VALIDATION_FILE = "reform_validation.json";
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function stringOrNull(value: unknown): string | null {
+  return typeof value === "string" && value ? value : null;
+}
+
+export interface ReformValidationRow {
+  id: string;
+  name: string;
+  category: string | null;
+  description: string | null;
+  // in-sample reforms are JCT tax-expenditure *calibration targets* (the
+  // dataset was tuned to them); out-of-sample reforms (OBBBA provisions) are
+  // the genuine fidelity test.
+  in_sample: boolean;
+  period: number | null;
+  // How score/estimate are denominated. Budget-effect rows are
+  // "currency-USD"; baseline-level rate backtests (Census state SPM poverty
+  // rates) are "percent", carrying fractions (0.134 = 13.4%) in the same
+  // score fields. Missing unit (older payloads) means currency.
+  unit: "currency-USD" | "percent";
+  // The JCT figure we benchmark against — JCT's first full fiscal year
+  // (FY2027) for provisions effective 1/1/2026, since FY2026 is a partial ramp
+  // year vs microcosm's calendar-year liability. In-sample rows fall back to
+  // their annual figure. Error metrics below are all relative to this.
+  jct_score: number | null;
+  // The FY2026 figure, kept for reference (the partial ramp year).
+  jct_score_fy2026: number | null;
+  jct_score_type: string | null;
+  jct_window: string | null;
+  // The year/window the benchmark (jct_score) actually refers to — "FY2027"
+  // for OBBBA rows (the full-year default), the annual window for in-sample.
+  // Differs row to row, so it's shown as its own column.
+  jct_benchmark_window: string | null;
+  jct_source: string | null;
+  jct_source_url: string | null;
+  jct_published: string | null;
+  microcosm_estimate: number | null;
+  microcosm_window: string | null;
+  microcosm_annual: Record<string, number> | null;
+  // Derived (relative to jct_score, i.e. the FY2027 benchmark where available).
+  abs_error: number | null; // microcosm − jct (USD)
+  relative_error: number | null; // (microcosm − jct) / |jct|
+  abs_relative_error: number | null;
+  within_10pct: boolean | null;
+  direction: "over" | "under" | "exact" | null;
+}
+
+export interface ReformValidation {
+  available: true;
+  source: "huggingface_live";
+  release_id: string;
+  updated_at: string | null;
+  schema_version: unknown;
+  baseline_period: number | null;
+  scoring_window: string | null;
+  rows: ReformValidationRow[];
+  summary: {
+    n_reforms: number;
+    n_scored: number; // reforms with both a JCT score and a microcosm estimate
+    within_10pct: number;
+    mean_abs_relative_error: number | null;
+    median_abs_relative_error: number | null;
+    // The out-of-sample reforms only — the genuine fidelity test.
+    n_out_of_sample: number;
+    n_out_of_sample_scored: number;
+    out_of_sample_within_10pct: number;
+    out_of_sample_mean_abs_relative_error: number | null;
+  };
+}
+
+function enrichReform(raw: JsonObject): ReformValidationRow {
+  const jct = asObject(raw.jct);
+  const microcosm = asObject(raw.microcosm);
+  const calculation = Object.keys(microcosm).length
+    ? microcosm
+    : asObject(raw.populace);
+  const jctFy2026 = numberOrNull(jct.score);
+  const jctFy2027 = numberOrNull(jct.score_fy2027);
+  // Benchmark defaults to JCT's first full fiscal year (FY2027). FY2026 is a
+  // partial ramp year for provisions effective 1/1/2026, so error vs FY2026
+  // overstates the gap against microcosm's calendar-year liability. In-sample
+  // rows have no FY2027 figure, so they fall back to their annual (FY2026) one.
+  const benchmark = jctFy2027 ?? jctFy2026;
+  const estimate = numberOrNull(calculation.budget_effect);
+  const absError = benchmark != null && estimate != null ? estimate - benchmark : null;
+  // A zero benchmark has no meaningful relative error — leave it unscored
+  // rather than storing the raw dollar delta, which would otherwise be treated
+  // as a fraction and blow up within_10pct and the mean/median aggregates.
+  const relError =
+    benchmark != null && estimate != null && benchmark !== 0
+      ? (estimate - benchmark) / Math.abs(benchmark)
+      : null;
+  const absRel = relError == null ? null : Math.abs(relError);
+  const annual = asObject(calculation.annual);
+  const annualClean: Record<string, number> = {};
+  for (const [k, v] of Object.entries(annual)) {
+    const n = numberOrNull(v);
+    if (n != null) annualClean[k] = n;
+  }
+  return {
+    id: String(raw.id ?? raw.name ?? ""),
+    name: String(raw.name ?? raw.id ?? ""),
+    category: stringOrNull(raw.category),
+    description: stringOrNull(raw.description),
+    in_sample: raw.in_sample === true,
+    period: numberOrNull(raw.period),
+    unit: raw.unit === "percent" ? "percent" : "currency-USD",
+    jct_score: benchmark,
+    jct_score_fy2026: jctFy2026,
+    jct_score_type: stringOrNull(jct.score_type),
+    jct_window: stringOrNull(jct.window),
+    jct_benchmark_window: jctFy2027 != null ? "FY2027" : stringOrNull(jct.window),
+    jct_source: stringOrNull(jct.source),
+    jct_source_url: stringOrNull(jct.source_url),
+    jct_published: stringOrNull(jct.published),
+    microcosm_estimate: estimate,
+    microcosm_window: stringOrNull(calculation.window),
+    microcosm_annual: Object.keys(annualClean).length ? annualClean : null,
+    abs_error: absError,
+    relative_error: relError,
+    abs_relative_error: absRel,
+    within_10pct: absRel == null ? null : absRel <= 0.1,
+    direction:
+      absError == null ? null : absError > 0 ? "over" : absError < 0 ? "under" : "exact",
+  };
+}
+
+function median(values: number[]): number | null {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+export function buildReformValidation(
+  raw: JsonObject,
+  releaseId: string,
+  updatedAt: string | null = null,
+): ReformValidation {
+  const reforms = Array.isArray(raw.reforms) ? (raw.reforms as JsonObject[]) : [];
+  const rows = reforms.map((r) => enrichReform(asObject(r)));
+  const scored = rows.filter((r) => r.abs_relative_error != null);
+  const absRels = scored.map((r) => r.abs_relative_error as number);
+  const oos = rows.filter((r) => !r.in_sample);
+  const oosScored = oos.filter((r) => r.abs_relative_error != null);
+  const oosAbsRels = oosScored.map((r) => r.abs_relative_error as number);
+  return {
+    available: true,
+    source: "huggingface_live",
+    release_id: String(raw.release_id ?? releaseId),
+    updated_at: updatedAt,
+    schema_version: raw.schema_version ?? null,
+    baseline_period: numberOrNull(raw.baseline_period),
+    scoring_window: stringOrNull(raw.scoring_window),
+    rows,
+    summary: {
+      n_reforms: rows.length,
+      n_scored: scored.length,
+      within_10pct: scored.filter((r) => r.within_10pct === true).length,
+      mean_abs_relative_error: absRels.length
+        ? absRels.reduce((s, v) => s + v, 0) / absRels.length
+        : null,
+      median_abs_relative_error: median(absRels),
+      n_out_of_sample: oos.length,
+      n_out_of_sample_scored: oosScored.length,
+      out_of_sample_within_10pct: oosScored.filter((r) => r.within_10pct === true).length,
+      out_of_sample_mean_abs_relative_error: oosAbsRels.length
+        ? oosAbsRels.reduce((s, v) => s + v, 0) / oosAbsRels.length
+        : null,
+    },
+  };
+}

package/src/release-cut.ts

@@ -0,0 +1,32 @@
+// Microcosm publishes a constant-id release line (microcosm#823) as one
+// immutable Hugging Face tag per cut, `<release id>-<YYYYMMDDTHHMMSSZ>-<attempt>`,
+// while the cut's files stay under the line's own folder, `releases/<release id>/`.
+// The tag names the build; the folder names where its files live. Isomorphic:
+// the release picker labels cuts with the same grammar the publisher reads.
+
+export interface ReleaseCut {
+  /** The line's constant release id, which is also its `releases/` folder. */
+  releaseId: string;
+  /** The calibration attempt's instant, `YYYYMMDDTHHMMSSZ`. */
+  cutAt: string;
+  /** The calibration attempt's short identifier (8 hex digits). */
+  attempt: string;
+}
+
+const RELEASE_CUT_TAG_RE =
+  /^([A-Za-z0-9][A-Za-z0-9._-]*)-(\d{8}T\d{6}Z)-([0-9a-f]{8})$/;
+
+export function parseReleaseCutTag(tag: string): ReleaseCut | null {
+  const match = RELEASE_CUT_TAG_RE.exec(tag);
+  return match
+    ? { releaseId: match[1], cutAt: match[2], attempt: match[3] }
+    : null;
+}
+
+// A release folder is interpolated into Hugging Face URLs that carry the
+// server's token, so it passes the same allowlist as a release id.
+const RELEASE_DIRECTORY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export function isReleaseDirectory(value: unknown): value is string {
+  return typeof value === "string" && RELEASE_DIRECTORY_RE.test(value);
+}

package/src/release-record.ts

@@ -0,0 +1,277 @@
+// `releases.json`: the one record of which build of each release a Microcosm
+// dataset repository has published and which is current. The repository
+// publishes every build in its own folder, never changed after publishing:
+//
+//   releases.json
+//   releases/<release>/<build>/release_manifest.json
+//   releases/<release>/<build>/...
+//
+// Every reader finds the layout this way: a repository with releases.json is
+// read from it and its build folders only; a repository without one is read
+// from its tags and pointer files (`latest*.json`). No country registration
+// names the layout, so a repository's switch needs no dashboard change.
+//
+// The record's shape and rules are microcosm-emitter's
+// `microcosm_emitter_interface.releases` (microcosm-emitter#24), whose release
+// writer is the only program that changes the file. This module reads the
+// record with the same rules, so a record the writer would refuse is refused
+// here too, with one exception: JSON.parse reads `1.0` as the number 1, so a
+// `schema_version` of `1.0` passes here although the writer, which requires
+// an integer, refuses it. The writer itself always writes `1`. Isomorphic:
+// the release picker and the tree publisher share it.
+
+export const RELEASES_RECORD_PATH = "releases.json";
+export const RELEASES_RECORD_SCHEMA_VERSION = 1;
+export const RELEASE_MANIFEST_NAME = "release_manifest.json";
+// The interface's MAX_RECORD_BYTES: the largest releases.json the writer's
+// parser accepts, and the size its checks keep every record within.
+export const MAX_RELEASES_RECORD_BYTES = 4 * 1024 * 1024;
+
+// The interface's SAFE_IDENTIFIER and ROLE_IDENTIFIER.
+const SAFE_IDENTIFIER_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const ROLE_IDENTIFIER_RE = /^[a-z][a-z0-9_]{0,63}$/;
+const RECORD_KEYS = ["default", "releases", "schema_version"];
+const RELEASE_KEYS = ["builds", "current", "role"];
+const BUILD_KEYS = ["published_at", "withdrawn"];
+
+export interface RecordedBuildEntry {
+  /** As the writer recorded it; not reformatted. */
+  publishedAt: string;
+  withdrawn: boolean;
+}
+
+export interface RecordedRelease {
+  role: string;
+  /** Null while the release has no current build. */
+  current: string | null;
+  builds: Record<string, RecordedBuildEntry>;
+}
+
+export interface ReleasesRecord {
+  /** The release a repository's default dataset comes from, or null. */
+  default: string | null;
+  releases: Record<string, RecordedRelease>;
+}
+
+/** One listed build, with what the record says about it and its release. */
+export interface RecordedBuild {
+  release: string;
+  build: string;
+  /** The build's folder under `releases/`: `<release>/<build>`. */
+  id: string;
+  role: string;
+  publishedAt: string;
+  withdrawn: boolean;
+  /** The build is its release's current build. */
+  current: boolean;
+  /** The build's release is the record's default release. */
+  inDefaultRelease: boolean;
+}
+
+export class ReleasesRecordError extends Error {}
+
+function isSafeIdentifier(value: unknown): value is string {
+  return typeof value === "string" && SAFE_IDENTIFIER_RE.test(value);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasExactly(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const present = Object.keys(value).sort();
+  return present.length === keys.length && present.every((key, index) => key === keys[index]);
+}
+
+function refuse(message: string): never {
+  throw new ReleasesRecordError(message);
+}
+
+/**
+ * Parse `releases.json` and check it as the writer does: its exact shape,
+ * safe release and build names, and (`check_record`) that each `current`
+ * names a listed build that is not withdrawn and that `default` names a
+ * listed release.
+ */
+export function parseReleasesRecord(document: unknown): ReleasesRecord {
+  if (!isPlainObject(document) || !hasExactly(document, RECORD_KEYS)) {
+    refuse(`${RELEASES_RECORD_PATH} must have exactly ${RECORD_KEYS.join(", ")}.`);
+  }
+  if (document.schema_version !== RELEASES_RECORD_SCHEMA_VERSION) {
+    refuse(`${RELEASES_RECORD_PATH} schema_version must be ${RELEASES_RECORD_SCHEMA_VERSION}.`);
+  }
+  if (!isPlainObject(document.releases)) refuse("releases must be an object.");
+  const releases: Record<string, RecordedRelease> = {};
+  for (const [release, entry] of Object.entries(document.releases)) {
+    if (!isSafeIdentifier(release)) refuse("A release name is not a safe identifier.");
+    if (!isPlainObject(entry) || !hasExactly(entry, RELEASE_KEYS)) {
+      refuse(`Release ${release} must have ${RELEASE_KEYS.join(", ")}.`);
+    }
+    if (typeof entry.role !== "string" || !ROLE_IDENTIFIER_RE.test(entry.role)) {
+      refuse(`Release ${release} has an invalid role.`);
+    }
+    if (entry.current !== null && typeof entry.current !== "string") {
+      refuse(`Release ${release} current must be a build or null.`);
+    }
+    if (!isPlainObject(entry.builds)) refuse(`Release ${release} builds must be an object.`);
+    const builds: Record<string, RecordedBuildEntry> = {};
+    for (const [build, buildEntry] of Object.entries(entry.builds)) {
+      if (!isSafeIdentifier(build)) refuse("A build name is not a safe identifier.");
+      if (
+        !isPlainObject(buildEntry) ||
+        !hasExactly(buildEntry, BUILD_KEYS) ||
+        typeof buildEntry.published_at !== "string" ||
+        !buildEntry.published_at ||
+        typeof buildEntry.withdrawn !== "boolean"
+      ) {
+        refuse(`Build ${build} of ${release} is malformed.`);
+      }
+      builds[build] = {
+        publishedAt: buildEntry.published_at,
+        withdrawn: buildEntry.withdrawn,
+      };
+    }
+    releases[release] = { role: entry.role, current: entry.current, builds };
+  }
+  if (document.default !== null && typeof document.default !== "string") {
+    refuse("default must be a release name or null.");
+  }
+  const record: ReleasesRecord = { default: document.default, releases };
+  if (record.default != null && !Object.hasOwn(releases, record.default)) {
+    refuse(`Default ${record.default} is not listed.`);
+  }
+  for (const [release, entry] of Object.entries(releases)) {
+    if (entry.current == null) continue;
+    // Only the listed builds: `builds` is an ordinary object, so a name such
+    // as "constructor" would otherwise find an inherited property.
+    const current = Object.hasOwn(entry.builds, entry.current)
+      ? entry.builds[entry.current]
+      : undefined;
+    if (!current) refuse(`Current build ${entry.current} of ${release} is not listed.`);
+    if (current.withdrawn) refuse(`Current build ${entry.current} of ${release} is withdrawn.`);
+  }
+  return record;
+}
+
+/**
+ * Read `releases.json` from its bytes as the writer's `ReleasesRecord.parse`
+ * does: refuse a record larger than MAX_RELEASES_RECORD_BYTES or one that is
+ * not a readable JSON document, then check it with parseReleasesRecord.
+ */
+export function parseReleasesRecordBytes(bytes: Uint8Array): ReleasesRecord {
+  if (bytes.byteLength > MAX_RELEASES_RECORD_BYTES) {
+    refuse(`${RELEASES_RECORD_PATH} is larger than ${MAX_RELEASES_RECORD_BYTES} bytes.`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    refuse(`${RELEASES_RECORD_PATH} is not a readable JSON document.`);
+  }
+  return parseReleasesRecord(parsed);
+}
+
+// Hugging Face's error codes for a 404 that is not about the file: the
+// repository or the revision is missing (or unreadable with this token).
+const MISSING_REPOSITORY_OR_REVISION = new Set(["RepoNotFound", "RevisionNotFound"]);
+
+/**
+ * Read Hugging Face's answer to a request for releases.json: the record,
+ * checked as parseReleasesRecordBytes checks it, or null when the repository
+ * has no releases.json at that revision. Only a 404 means "no record", and
+ * only when Hugging Face's error code (`X-Error-Code`) does not say that the
+ * repository or the revision is missing. Any other failure throws, so a
+ * reader never falls back to tags or pointer files because of it.
+ */
+export async function releasesRecordFromResponse(
+  response: Response,
+): Promise<ReleasesRecord | null> {
+  const errorCode = response.headers.get("x-error-code");
+  if (response.status === 404 && (errorCode == null || !MISSING_REPOSITORY_OR_REVISION.has(errorCode))) {
+    return null;
+  }
+  if (!response.ok) {
+    throw new Error(
+      `Hugging Face returned ${response.status}${errorCode ? ` (${errorCode})` : ""} ` +
+        `for ${RELEASES_RECORD_PATH}.`,
+    );
+  }
+  return parseReleasesRecordBytes(new Uint8Array(await response.arrayBuffer()));
+}
+
+/** A build's folder under `releases/`, which identifies it: `<release>/<build>`. */
+export function buildFolderId(release: string, build: string): string {
+  if (!isSafeIdentifier(release) || !isSafeIdentifier(build)) {
+    throw new ReleasesRecordError("A release and a build must be safe identifiers.");
+  }
+  return `${release}/${build}`;
+}
+
+export function parseBuildFolderId(
+  value: unknown,
+): { release: string; build: string } | null {
+  if (typeof value !== "string") return null;
+  const segments = value.split("/");
+  if (segments.length !== 2 || !segments.every(isSafeIdentifier)) return null;
+  return { release: segments[0], build: segments[1] };
+}
+
+export function isBuildFolderId(value: unknown): value is string {
+  return parseBuildFolderId(value) != null;
+}
+
+/**
+ * A folder under `releases/` that release files are read from: a release
+ * folder (`<release id>`) or a build folder (`<release>/<build>`). Folders
+ * are interpolated into Hugging Face URLs that carry the server's token, so
+ * each segment passes the release-id allowlist and none can leave `releases/`.
+ */
+export function isReleaseDirectory(value: unknown): value is string {
+  return isSafeIdentifier(value) || isBuildFolderId(value);
+}
+
+/** Every listed build, ordered by release, then build, as the writer sorts them. */
+export function recordedBuilds(record: ReleasesRecord): RecordedBuild[] {
+  const byName = (left: string, right: string) => (left < right ? -1 : left > right ? 1 : 0);
+  return Object.keys(record.releases).sort(byName).flatMap((release) => {
+    const entry = record.releases[release];
+    return Object.keys(entry.builds).sort(byName).map((build) => ({
+      release,
+      build,
+      id: buildFolderId(release, build),
+      role: entry.role,
+      publishedAt: entry.builds[build].publishedAt,
+      withdrawn: entry.builds[build].withdrawn,
+      current: entry.current === build,
+      inDefaultRelease: record.default === release,
+    }));
+  });
+}
+
+/**
+ * The repository's current build: the current build of its default release,
+ * or null while the record names no default release or that release has no
+ * current build.
+ */
+export function currentDefaultBuild(
+  record: ReleasesRecord,
+): { release: string; build: string; id: string } | null {
+  const release = record.default;
+  const build = release == null ? null : record.releases[release]?.current ?? null;
+  if (release == null || build == null) return null;
+  return { release, build, id: buildFolderId(release, build) };
+}
+
+/**
+ * Whether a build folder's release manifest names that release and build:
+ * the writer's `check_repository` rule, read from the manifest's top-level
+ * `release` and `build`. Manifests written before the build folders keep
+ * `build` as an object whose `build_id` is the release, and never match.
+ */
+export function releaseManifestNamesBuild(
+  manifest: unknown,
+  release: string,
+  build: string,
+): boolean {
+  return isPlainObject(manifest) && manifest.release === release && manifest.build === build;
+}

package/src/source-label.ts

@@ -0,0 +1,5 @@
+import { sourceAuthorityLabel } from "./source-labels";
+
+export function sourceLabel(source: string): string {
+  return sourceAuthorityLabel(source);
+}

package/src/source-labels.ts

@@ -0,0 +1,71 @@
+// Shared presentation names for source authorities. Keys remain stable data
+// identifiers; these labels are display-only and never participate in filters
+// or joins.
+const SOURCE_LABELS: Record<string, string> = {
+  bea: "BEA",
+  cbo: "CBO",
+  census_acs: "Census · American Community Survey",
+  census_pep: "Census · Population Estimates Program",
+  census_population: "Census population",
+  census_population_projections: "Census · Population Projections",
+  census_stc: "Census · State Tax Collections",
+  cms_aca: "CMS · ACA marketplace",
+  cms_medicaid: "CMS · Medicaid / CHIP",
+  cms_medicare: "CMS · Medicare",
+  cms_nhe: "CMS · National Health Expenditure Accounts",
+  ed_fsa: "ED · Federal Student Aid",
+  eurostat: "Eurostat",
+  federal_reserve: "Federal Reserve",
+  hhs_acf_liheap: "HHS · LIHEAP",
+  hhs_acf_tanf: "HHS · TANF",
+  ici: "Investment Company Institute",
+  irs_soi: "IRS Statistics of Income",
+  jct: "JCT",
+  jrc: "JRC",
+  kff: "KFF",
+  ssa: "SSA",
+  statbel: "Statbel",
+  onss: "ONSS",
+  sfpd: "SFPD",
+  nasa: "NASA",
+  state_income_tax: "State income tax",
+  usda_snap: "USDA · SNAP",
+};
+
+const SOURCE_ACRONYMS = new Set([
+  "aca",
+  "acf",
+  "acs",
+  "api",
+  "bea",
+  "cbo",
+  "cms",
+  "hhs",
+  "ici",
+  "irs",
+  "jct",
+  "jrc",
+  "kff",
+  "liheap",
+  "nhe",
+  "pep",
+  "soi",
+  "ssa",
+  "onss",
+  "sfpd",
+  "stc",
+  "tanf",
+  "usda",
+]);
+
+export function sourceAuthorityLabel(source: string): string {
+  if (Object.hasOwn(SOURCE_LABELS, source)) return SOURCE_LABELS[source];
+  return source
+    .split("_")
+    .map((word) =>
+      SOURCE_ACRONYMS.has(word.toLowerCase())
+        ? word.toUpperCase()
+        : word.charAt(0).toUpperCase() + word.slice(1),
+    )
+    .join(" ");
+}