Skip to content

Commit dcfa37f

Browse files
committed
docs(lifecycle): /ready now gates on data-driver health, /health deliberately does not
The drift check flagged protocol/kernel/lifecycle.mdx — its endpoint table said /ready means 'kernel is running and ready to accept requests', which #3765 makes incomplete. Records the liveness-vs-readiness split and the fail-open rule, and notes that PluginHealthMonitor covers plugins rather than driver connections. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T9VBCNvg9Zixrf1A9Rnwdd
1 parent e321754 commit dcfa37f

1 file changed

Lines changed: 16 additions & 3 deletions

File tree

content/docs/protocol/kernel/lifecycle.mdx

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -573,18 +573,31 @@ ObjectStack includes **built-in health monitoring** to validate system state.
573573
```
574574
GET /health
575575
→ 200 with { status, version, uptime } if the process is alive (liveness)
576+
→ never fails on a dependency — see below
576577
577578
GET /ready
578-
→ 200 if the kernel is running and ready to accept requests (readiness)
579+
→ 200 if the kernel is running AND every data driver answers (readiness)
579580
→ 503 while still booting or shutting down
581+
→ 503 with { state, drivers: [...] } when a data driver stops answering
580582
```
581583

584+
The two probes answer deliberately different questions (#3756). `/health`
585+
checks nothing but the process, because a failing *liveness* probe makes the
586+
orchestrator restart the pod — which cannot fix an unreachable database, but
587+
would put every replica into a restart storm for the length of the outage.
588+
`/ready` pings the data drivers (bounded, memoized ~1s) because its failure mode
589+
— leave the load-balancer rotation — is the one that helps a replica that would
590+
otherwise fail 100% of its requests. The readiness check fails **open**: a
591+
kernel with no data engine, or a probe that itself errors, still reads as ready
592+
rather than black-holing a working deployment.
593+
582594
<Callout type="info">
583595
`GET /health` returns a compact liveness body (`status`, `version`, `uptime`) and
584596
`GET /ready` returns readiness. The richer per-subsystem report and the
585597
plugin-declared custom checks below describe the internal health-monitor model
586-
(`PluginHealthMonitor`) — they are **not yet** exposed as a dedicated HTTP
587-
endpoint or as a declarative plugin field.
598+
(`PluginHealthMonitor`), which covers **plugins, not driver connections** — they
599+
are **not yet** exposed as a dedicated HTTP endpoint or as a declarative plugin
600+
field.
588601
</Callout>
589602

590603
### Health Status Response

0 commit comments

Comments
 (0)