Replay checks API

A replay check replays a planned change of a work station on the replay set that guards the station's changes, compares it with the live config, and gives a verdict under the line's replay_check. spotlight replay check calls these endpoints from CI. They sit under /api/teams/{teamId}, answer JSON, and answer errors as application/problem+json, as on the resource API.

EndpointsCopy Anchor Link

A replay set's reads in the Replays API carry guardsChanges, true for the set that guards its station's changes. A station has at most one.

Start a checkCopy Anchor Link

{
  "lineId": "<line id>",
  "stationKey": "build",
  "station": {
    "key": "build",
    "name": "Build",
    "kind": "work",
    "harness": "claude-code",
    "prompt": "Build it, then drain the queue.",
    "passesTo": ["ship"]
  },
  "line": {
    "repositories": [{ "name": "acme/api", "setup": "npm ci" }]
  },
  "reference": { "commit": "4f7c2a9e1b3d", "pullRequest": 42 },
  "repeats": 1
}

The check:

1. Reads replay_check from the line as it is applied, never from the plan.
2. Replaces the planned block's check, judge, diffs and runners with the live station's, and records in keptLive each one the plan changed.
3. Checks the block as the line would be with the station replaced, as a replay candidate is checked.
4. Replays it, under the planned repositories, images and setup commands, on every run of the guarding set, repeats times, on the team's runners. When the set has no baseline of the current live config with at least as many copies, it also starts a baseline replay of the live config with the same repeats. See Ceiling.

A change that changes nothing about how the station's runs go is refused with 409 and the type urn:spotlight:problem:nothing-to-replay.

A change already checked is answered with that check, 200 and reused: true, while the earlier check is running, passed or failed, and only if it replayed the same runs of the set against the same live config, the same threshold, the same scoring and the same repeats. Otherwise a new check starts, with the next attempt. A request sent again with the same Idempotency-Key answers 201 with the check it started and the header Idempotent-Replayed: true.

CeilingCopy Anchor Link

The line's replay_check.ceiling caps each replay a check starts, each on its own:

• the replay of the planned change, which every check starts;
• the baseline replay of the live config, only when the guarding set has no baseline for the current live config with at least as many copies of each run. A baseline already there costs the check nothing.

So one check spends at most twice the ceiling, plus what runs already running spend after a replay reaches it. A run whose cost is not reported, or is in another currency, counts as the ceiling divided by the number of runs in the set times repeats: threshold.unpricedRun. When a replay reaches its ceiling, no more of its runs start, and runs already running finish, so it can end a little over. A check whose replay reached its ceiling is undecided, over-ceiling, unless it has already failed.

The check replays a candidate Spotlight names Planned change, PR #<n>, or after the commit's first 7 characters, or the date. It is not a replay candidate resource. A proposed replay candidate may not be named starting Planned change.

CheckCopy Anchor Link

VerdictsCopy Anchor Link

A task regressed as in a replay.

Who may read and changeCopy Anchor Link

Reading needs a person on the team or an owner or admin of its workspace, or a workspace token of the team's workspace with the read scope. Anyone else is answered 404. Marking a set and starting a check also need plan. See Team outcomes.

Starting a check is recorded as a configuration change of the kind replay-check. Marking or unmarking a set is recorded as an updated change of the kind replay-set.

ErrorsCopy Anchor Link