A contract here is a set of JSON files that describe one part of Bytestream the way the code runs it: what it reads, what it writes, which states it moves through, how it fails and which alert reaches a person. A validator checks the files against each other, against the code on main and against real runs, so a contract that drifts from the code fails a check instead of going quietly out of date.

Contract sets

Catalog pipeline

The scheduled job that builds the channel catalog from public sources and publishes one slice per platform, with its alerts and watchdog.

Web first load

How a cold load of bytestream.tv reaches a usable Watch: the files it asks for, its boot states, its failures, what it reports and the budgets it is built to.
Each new set gets its own folder under docs/contracts/, its own validator under scripts/contracts/, and a page in this group.

What a contract set holds

Every set has the same six kinds of file, plus the evidence that tests them. Next to those six: golden/ holds real runs and probes the rules are tested against, evals.json the bars the golden set must meet, decisions.json the decisions that change the contract, open-questions.json what is still open, and system-card.md a one-page summary.

Live, planned and pending merge

Every row in a contract has a status.
  • Live: what the code on main does today. A live row cites the file and line that does it, and the validator checks that line still says so.
  • Planned: decided and not built. A planned row is the spec its change is built and tested against, so it must name its trigger, what the run prints, the alert text, the files that change and the test that will prove it.
  • Pending merge: built on a branch that has not merged. The row names the branch and what main does until the merge.
A live row that a decision changes keeps describing today and carries a planned block for the target, or names the planned row that replaces it. Each decision in decisions.json lists every row it touches, and each of those rows names the decision back. The validator checks both directions.

Run a validator

From the atlas repo root, load .env.local so the live checks can reach Supabase, then run the set’s validator:
Add --offline to skip the live checks. The validator sends nothing and writes nothing. It exits 0 when the contracts pass and every live failure is explained by a known incident, 1 when a contract check fails, and 2 when a live check fails for a reason no incident explains. The contract pages are generated from the JSON. After editing a contract, rebuild them: