Handbook
Decisions v1.0.0· updated 2026-07-18

Kernel SLO Contract

The public /api/public/kernel/health endpoint is the single source of truth for system health. Its slo block is a stable contract external monitors can alarm on without re-deriving the logic.

Why a contract, not a dashboard. Dashboards drift; contracts don't. The health endpoint returns a slo.thresholds object (named limits) and a slo.breaches array (which named SLOs are currently over). Internal admin panels and external uptime monitors read the same JSON, so both audiences alarm on the same signal.

The six SLOs. failureRatePct (task failure rate, max 10%), deadBacklog (unresolved dead tasks, max 10), stuckRunning (running tasks past deadline, max 5), p95LatencyMs (task p95 latency, max 15000ms), copilotFollowRatePct (24h AI-suggestion follow rate, min 40%), copilotMissedP0 (P0 suggestions unfollowed within 60m, max 3). Thresholds are versioned in the endpoint response — never hardcoded in consumers.

How transitions become durable. The endpoint itself is stateless (safe to poll). A separate 5-minute cron (POST /api/public/kernel/slo-snapshot) diffs the live breach set against the last snapshot in kernel_events and writes copilot.slo.breach / copilot.slo.recovered rows. That gives operators a 7-day ledger, per-SLO MTTR, and open-breach age without turning the public GET into a writer.

Contract stability rule. Adding a new SLO is backward-compatible — a consumer that doesn't know it simply ignores it. Removing or renaming an existing SLO key requires a version bump on the endpoint and a deprecation window, because external monitors are alarming on that name.

References