data freshness LIVE

the two timestamps on every signal LIVE

Verified in lib/pipeline.js: the pipeline stamps each adapter's record after the adapter runs, so an adapter can never backdate or forward-date its own freshness:

The same contract covers MCP: lib/mcp.js stamps every tool result with retrieved_at / data_as_of under the comment "same contract as the /api/intel pipeline envelope." The out-of-Virginia boundary signal carries retrieved_at with data_as_of: null — it is local geometry with no upstream source date, so the pipeline honestly reports none.

one adapter declares a source date today LIVE

A full-tree search on 2026-09-29 found exactly one adapter that sets data_as_of: lib/signals/whole_region_rank.js (data_as_of: epochToDate(freshestState) — the freshest upstream state date it could see). Every other adapter ships data_as_of: null.

How to read this: a null data_as_of is an honest unknown, not a failure and not a staleness verdict. It tells you the adapter pulls from a source with no published as-of date (or the adapter author didn't declare one). As adapters start declaring source dates, they appear here — null flips to a real date in the response, no announcement needed.

degraded is a freshness signal too LIVE

When an adapter throws, the pipeline does not fail the call — it records the failure honestly (lib/pipeline.js, mirrored in lib/mcp.js and lib/parcels.js county pipelines):

{
  "signal_id": "example_signal",
  "status": "degraded",
  "adapter_version": "v0",
  "result": null,
  "evidence": [],
  "unavailable": ["adapter error: upstream timeout"],
  "confidence": "low",
  "retrieved_at": "2026-09-29T12:00:00.000Z",
  "data_as_of": null
}

A degraded record still carries retrieved_at — the timestamp of the failed attempt — so you can tell "the source was unreachable at 12:00" apart from "we never tried." The right move is to retry later; unavailable names the reason. A throwing adapter never becomes a 500 on the whole response.

caches that touch your data LIVE

These are the only caches between you and the sources, verified in the code. Everything else is computed fresh per request:

What this table is not: a staleness SLA. The 1-hour parcel cache is an engineering cache, not a data-refresh promise — the upstream GIS's own update cadence is the floor, and it is not published here because the code doesn't know it.

envelope fields that carry freshness LIVE

Beyond the per-signal stamps, the /api/intel envelope carries:

• pipeline_version — "v0.1.0" today. Pin it in your logs; when the pipeline's freshness behavior changes, this is what changes with it.
• top-level retrieved_at — the run instant, same value stamped on every signal in the response.
• geocode.retrieved — when the Census geocoder result was fetched for this call.
• registry — version, total_catalogued, live_in_poc, pending_adapters: how many signals exist, how many ran live in this response, how many are still pending. Regenerated from docs/ADAPTER-QUEUE.md — never hand-edited.
• trace — per-step timings ({step, note, ms}) for this run, useful for spotting a slow adapter dragging your retrieved_at late.

planned: freshness SLAs DRAFT

No freshness SLAs exist today — no guaranteed refresh cadence, no maximum-age promise, no "stale after N days" rule anywhere in the codebase. Planned: published freshness targets per signal family, so you can contract against staleness instead of eyeballing timestamps. Target numbers, tiers, and the SLA surface are not final — no numbers are printed here because any number would be invented. When SLAs ship, they land here, copied from the shipped code.

planned: per-signal refresh cadences DRAFT

Planned: a published cadence per signal (how often its upstream source refreshes and how often shinnslist re-pulls it), so data_as_of gains context. Not published today — the code doesn't track per-signal cadences, so none are listed here. Until then, retrieved_at and data_as_of are the complete picture.

what's planned, not yet shipped DRAFT

The full planned surface, in one list. Every item here is not final — names, numbers, tiers, and surfaces will be verified against the shipped code before they replace these bullets:

• freshness SLAs: published staleness targets per signal family — no numbers yet
• per-signal refresh cadences: upstream + re-pull cadence per signal — not tracked today
• more data_as_of declarations: adapters declaring upstream source dates — one adapter today

When the first SLA ships, the DRAFT badges on this page flip to LIVE and the bullets above become the verified reference.

how to read a record today

Three checks, in order:

• 1. status. degraded with unavailable naming the reason means "the source failed at retrieved_at" — retry later, don't treat result: null as "nothing found."
• 2. data_as_of. A real date is the upstream source's as-of date. null is an honest unknown — the adapter doesn't know its source's as-of date. It is not a staleness verdict.
• 3. retrieved_at. When this run computed the record. For parcel-heavy signals, remember the 1-hour KV parcel cache: the underlying parcels may be up to an hour older than the stamp.

Log pipeline_version with every call you care about — it's the one field that tells you the freshness rules themselves changed.