Connection health
A connection carries a status, and a report is as healthy as its worst input — never its first, and never its newest.
Three rules make this readable rather than noisy:
- The pull that learns writes. A provider refusal is recorded by the pull that hit it, inside its own transaction — not inferred later by a sweep.
- A sweep never raises a red somebody else posted, and only a pull that verifiably succeeded clears one. A red does not decay into green because time passed.
provider_deniedleaves the door open. Unlikerevoked, it does not close the enqueue gate: the daily probe is the detector of restoration, and a verifiedokpull lifts the red without any console gesture. A denial is not a disablement.
revoked means the authorization
itself is dead and someone has to reconnect. provider_denied means the
authorization is alive — the token still refreshes — and the provider is refusing
the data this connection exists to collect.
The night, step by step
The platform writes the list of steps at dispatch, before the first one runs. That ordering is the whole design: a crash cannot erase a step it never got to close, so an unfinished step stays visibly unfinished. Four outcomes that cannot collapse into one another, plus one derived:
“No alert” is therefore never the answer to did it run? — the absence of a
record is itself a state with a name.
Where to look
A clock is one scheduled job. Reading one returns three things, never one: the declared cadence (what the platform decided), the observed one (what the scheduler is actually running), and the drift verdict between them —in_sync, drifted, missing_in_gcp, unmanaged_in_gcp or unknown.
Drift is rendered, never silently corrected. And when the scheduler cannot be
observed at all — no credential, no network — every verdict is unknown and the
observation is marked unreachable. Never in_sync: an observation that did not
run proves no synchronisation.
The console shows the same model on Platform Clocks — the beats, and one
level below them, what the beat actually did. Both surfaces serialise the same
read model and neither reshapes it: two answers to “is it in sync?” would be
the same as none.
There is no MCP tool for the nightly steps, and that is deliberate. The
clock tools exist because a drift verdict is configuration an agent can act
on. The nightly steps are the platform’s own execution history, and an agent
works inside a project: the question it actually has — why is yesterday’s data
missing? — already has doors at the right scale (
datastream_diagnose,
datastream_pull_history, list_datastream_runs), and the envelope it
receives already carries how stale the data is. Reading the platform’s dispatch
to explain one project’s data would be the opposite of the isolation the
product holds everywhere else.What an agent can ask
list_platform_clocks,get_platform_clock— the beats and their cadence.run_platform_clock_now,set_platform_clock_cadence,apply_platform_clock— changing when things happen.get_connector_activation_status,get_connector_verification_status,get_connector_installation_status— is this connector installed, proved, and pulling for this organization?datastream_diagnose,datastream_pull_history,list_datastream_runs— why did this one stop, and what did it do before.
Next Steps & Cross-References
Data Quality
The ten monitors that run once the rows have landed.
Universal Datastreams
What a pull does, and what it records while doing it.
Agent Tools
The operations profile, and what it takes to reach it.
Self-Hosting Guide
Turning the scheduler on, and where it runs.