COLA Insight 如何建立可審計的 2027 年美國社會保障 COLA 公開數據管道

The hardest part of a government-data project is often not the formula. It is preserving the difference between what can be calculated, what has been forecast, and what an agency has officially announced.

I ran into this while building COLA Insight, an independent tracker for the 2027 Social Security cost-of-living adjustment. The final result is now official: the Social Security Administration announced a 3.6% COLA. But the application existed before all required CPI-W observations were available, so a single rate field was not enough.

This article explains the data-contract decisions that made the tracker auditable before and after the announcement.

1. Model status as data, not page copy

The pipeline uses three explicit states:

forecast: one or more required third-quarter CPI-W observations are unavailable;
computed: all required observations are available and the statutory formula can be reproduced, but SSA has not yet confirmed the result;
official: SSA has published the benefit-year COLA and the record has been matched to that confirmation.

Those states represent three different claims. A mathematically reproducible result is not automatically an official agency determination.

type ColaStatus = "forecast" | "computed" | "official";

type ColaRate = {
  displayed: number | null;
  forecast: number | null;
  computed: number | null;
  official: number | null;
  unit: "percent";
};

function displayedRate(rate: ColaRate) {
  return rate.official ?? rate.computed ?? rate.forecast;
}

The fallback order is convenient for the interface, but the API still returns every field. A client can see why the displayed value is present instead of receiving an unlabeled percentage.

2. Publish the observations behind the headline

Social Security uses the CPI-W, U.S. city average, all items, not seasonally adjusted. The relevant BLS series is CWUR0000SA0.

For the 2027 adjustment:

2025 Q3 average: 317.265
2026 Q3 average: 328.746

(328.746 - 317.265) / 317.265 * 100 = about 3.6197%

Applying the statutory rounding rule produces 3.6%.

Publishing only that percentage would make the result hard to audit. The public record therefore carries the series identifier, units, baseline quarter, monthly observations, and the state of each observation:

{
  "status": "official",
  "rate": {
    "displayed": 3.6,
    "forecast": null,
    "computed": 3.6,
    "official": 3.6,
    "unit": "percent"
  },
  "cpiW": {
    "seriesId": "CWUR0000SA0",
    "baseline": { "quarter": "2025-Q3", "average": 317.265 },
    "observations": [
      { "month": "2026-07", "value": 327.104, "state": "published" },
      { "month": "2026-08", "value": 328.481, "state": "published" },
      { "month": "2026-09", "value": 330.654, "state": "published" }
    ]
  }
}

This makes common errors visible: using CPI-U instead of CPI-W, using seasonally adjusted data, comparing September with September, or rounding intermediate values too early.

3. Store provenance beside the number

A source URL in a footer helps a reader, but it is not enough for downstream software. Provenance belongs inside the record.

The response separates the original publisher, the retrieval path, and the official confirmation:

{
  "sources": {
    "cpiW": {
      "publisher": "U.S. Bureau of Labor Statistics",
      "url": "https://www.bls.gov/developers/home.htm"
    },
    "retrievedVia": {
      "kind": "fred_api",
      "label": "FRED API, BLS series CWUR0000SA0",
      "url": "https://fred.stlouisfed.org/series/CWUR0000SA0"
    },
    "officialConfirmation": {
      "publisher": "U.S. Social Security Administration",
      "url": "https://www.ssa.gov/cola/"
    }
  }
}

Those three sources are not always the same. Keeping them separate makes a fallback visible instead of silently presenting a mirror as the primary authority.

The record also includes an observation timestamp and schema version, so consumers can make an informed caching decision and handle future contract changes.

4. Treat history as append-only evidence

An early forecast should not disappear after the official result arrives.

Overwriting an old estimate with the final answer makes the current page look accurate, but destroys the evidence needed to evaluate the forecast. COLA Insight stores a new snapshot when an observation, rate, retrieval path, or status changes.

Each snapshot preserves:

timestamp and status;
available CPI-W observations;
assumptions for unavailable values;
calculated or forecast rate;
retrieval and source links;
an explanation of the change.

The human-readable timeline can then derive entries such as:

August CPI-W: pending -> 328.481
Status: forecast -> computed
Tracked rate: 3.5% -> 3.6%

This pattern applies beyond COLA data. Forecasts, election models, public-health estimates, and economic indicators all benefit from preserving what was known at each point in time.

5. Generate every output from one record

The same stored snapshots power:

a readable methodology and data dictionary;
a public JSON endpoint;
downloadable CSV files;
SVG and PNG charts;
a read-only MCP server;
a dated Zenodo release with a persistent DOI.

Maintaining these as independent copies invites drift. One stored record prevents the article from saying one number while the chart shows another and the API serves yesterday's status.

The public API uses a four-hour edge cache because the underlying government data changes infrequently:

return Response.json(record, {
  headers: {
    "access-control-allow-origin": "*",
    "cache-control": "public, max-age=14400, stale-while-revalidate=3600",
    "link": "https://www.colainsight.com/data-dictionary; rel=describedby",
    "x-content-type-options": "nosniff"
  }
});

That reduces unnecessary origin work without creating a meaningful freshness problem for scheduled releases.

6. Make AI-facing tools read-only and source-linked

The MCP server exposes four read-only tools: current COLA data, an educational benefit calculation, preserved history, and primary sources.

Responses include the same status, observations, timestamps, and source links as the public API. The server instructions tell clients to keep forecast, computed, and official distinct and never present an estimate as an SSA benefit determination.

That cannot guarantee how every client will phrase an answer, but it makes the safe interpretation part of the machine-readable contract instead of hiding it on an About page.

7. Fail closed when an official input is missing

The same rule applies to 2027 Medicare Part B data.

As of October 25, 2026, CMS has not published the official 2027 standard Part B premium and deductible. The API therefore keeps official premium and net-benefit fields null. It does not insert a rumored value just to complete the table.

{
  "status": "pending",
  "official2027StandardPremiumUsd": null,
  "official2027DeductibleUsd": null
}

Once CMS publishes the official figures, a verified snapshot can update the page, calculator, CSV, JSON, SVG, and PNG together.

Seven rules I would reuse

Model evidence states explicitly.
Return underlying observations, not just the headline.
Separate publisher, retrieval path, and official confirmation.
Append new snapshots instead of rewriting history.
Generate every format from the same record.
Leave unknown official values null.
Put provenance and caveats in the contract used by humans and agents.

The public resources are available here:

COLA Insight is independent and is not affiliated with SSA, BLS, CMS, or the U.S. government. I would be interested in hearing how other developers represent the boundary between a reproducible calculation and an official determination.