Clearing-Layer Health Verdict
One deterministic tenant/environment diagnosis shared byte-for-byte by REST, Connect, MCP, CLI, and dashboard.
- Scope
- Tenant + environment + bounded observation window
- Evidence
- Fresh Postgres aggregates and dependency snapshots
- Surfaces
- REST, Connect, MCP, CLI, and dashboard
Ductor computes one deterministic operational diagnosis. Clients render the versioned result; they do not reinterpret charts or ask an LLM whether production is healthy.
Surfaces
| Client | Operation |
|---|---|
| REST | GET /api/operational-health/report |
| Authorized scopes | GET /api/operational-health/scopes |
| Connect | ductor.api.OperationalHealthService/GetOperationalHealthReport |
| MCP | api_operationalhealthservice_getoperationalhealthreport |
| CLI | ductor report health |
| Dashboard | /workspaces/{tenant}/health |
All surfaces consume the same v1 report id, scope, bounded time window, source
freshness, verdict, confidence, stable reason codes, safe numeric evidence, and fixed
runbook-backed next steps.
Verdicts
healthyEvery required source is available and no warning threshold is crossed.
degradedWork continues, but at least one warning threshold is crossed.
unhealthyFailure, backlog, incompatibility, or stall evidence crosses a hard threshold.
unknownRequired data is missing, stale, unavailable, skewed, or unclassified.
unknown is fail-closed. Missing telemetry never becomes healthy inactivity.
Current ruleset
| Signal | Degraded | Unhealthy / unknown |
|---|---|---|
| Telemetry age | — | unknown after 5 minutes |
| Source clock skew | — | unknown beyond 30 seconds |
| Dependency snapshot age | — | unknown after 30 seconds |
| Workflow failure ratio (minimum 5 terminals) | 10% | 25% |
| Recoverable running runs idle for 5 minutes | 1 | 5 |
| Ready queue depth | 100 | 1,000 |
| Oldest ready item | 15 minutes | 1 hour |
| Incompatible active attempts | 1 | 10 |
| Unreplayed workflow DLQ entries | 1 | 100 |
The successful bounded Postgres observation is itself the workflow telemetry heartbeat, so a genuinely idle environment can remain fresh without inventing business activity.
Authority and privacy
The request principal supplies tenant authority. Environment filtering is checked against that principal before the tenant-bounded aggregate query runs. Reports cache for 15 seconds by tenant, environment, and period. The report id hashes the pinned ruleset plus sanitized aggregates.
Output and audit contain ids, scope, verdict, confidence, reason codes, and safe numbers. Workflow payloads, prompts, raw dependency errors, and credentials are never report fields.
CLI example
ductor report health --environment production --period 1hTreat unknown first as an evidence-path incident: restore the stale or unavailable
source before interpreting downstream workflow ratios.
Change policy
Threshold or classification changes require a new ruleset version and frozen fixtures for flowing, idle, stalled, failing, backlogged, incompatible, and stale scenarios. A client-specific threshold override is intentionally unsupported.