Fact Contract

A fact contract is the schema-level commitment that defines a single fact tracked by Thin Gold’s pipeline. Each contract specifies:

• The stable fact_key (e.g., unemployment.u3)
• The expected unit (percent, count, days, USD)
• The fetcher responsible (BLS API, FRED, Wikipedia dateline, or null for LLM-parsed)
• Expected sources (slugs of the upstream sources the fact draws from)
• Expected refresh cadence (daily, weekly, monthly, on-change, event)
• Staleness threshold (how old a value can get before the system raises an alarm)

The contract is the editorial commitment. When a fact’s contract says it refreshes daily and the latest as_of is 26 hours old, the pipeline raises a freshness alarm; readers see the value caveated as stale. When the contract specifies which sources are valid, the pipeline rejects writes that draw from outside that list.

Fact contracts are the load-bearing artifact behind Thin Gold’s provenance manifest. They make every numeric claim auditable and traceable.