Saphan StudioDocs
Security

Capability: what a machine is trusted to be able to do

Fleet configuration accumulates claims — "this machine has the toolchain", "this machine can run that backend".

Fleet configuration accumulates claims — "this machine has the toolchain", "this machine can run that backend". Those claims rot: a machine is reimaged, a tool is removed, a version moves. A configuration file cannot tell you whether its claims are still true or were ever checked.

Capability claims here therefore carry a provenance grade on three ordered rungs:

RungEstablished by
DeclaredThe machine's own manifest. Nothing has checked it.
Probe-confirmedA probe run by the control plane, which passed.
History-provenExercised in real recorded runs.

Five rules make the grade load-bearing:

  • Declaration and proof never merge. Declared fields are written only from a manifest, probe fields only from a probe result.
  • No rung can be skipped. Reaching probe-confirmed requires a passing probe result to point at. Rungs are raised by a fresh pass and never lowered by one.
  • Claims expire. Each record carries a lease with a TTL. A record goes stale for exactly one of three recorded reasons — lease expiry, manifest drift, or probe failure — recomputed lazily on read. There is no fourth path and no manual override, so a stale record always says why.
  • Only proven capability receives work. Eligibility requires at least probe-confirmed and not stale. A merely declared capability never wins a dispatch.
  • The capability vocabulary is closed — nine names. An unrecognised name is a refusal, not a new entry.

A probe never installs anything. The commands a probe may issue come from a closed catalogue with a single substitution position, and an independent check inspects the fully assembled command line. Widening the catalogue later trips the second check rather than quietly permitting more.