`lifecycle.mdx` "Health Status Response" shows the internal health-monitor model under a heading that reads as the `GET /health` wire body

[os-steve]

Found while fixing #11295 (discovery version literals). Out of that card's scope — different endpoint, different defect — so it is filed rather than fixed.

What was measured

content/docs/protocol/kernel/lifecycle.mdx:640, under the heading ### Health Status Response:

{
 "status": "healthy",
 "uptime": 3600,
 "version": "2.0.0",
 "timestamp": "2024-01-15T11:00:00.000Z",
 "checks": {
 "database": { "status": "healthy", "latency_ms": 5, ... },
 "redis": { "status": "healthy", "latency_ms": 2, ... }
 }
}

What GET /health actually serves (packages/runtime/src/http-dispatcher.ts:567-577, registerBuiltinDomains()):

this.domainRegistry.register({
 prefix: '/health', match: 'exact', methods: ['GET'],
 handler: async () => ({
 handled: true,
 response: this.success({
 status: 'ok',
 timestamp: new Date().toISOString(),
 version: this.runtimeVersion,
 uptime: typeof process !== 'undefined' ? process.uptime() : undefined,
 }),
 }),
});

Three divergences:

field	doc sample	/health actually
status	"healthy"	"ok"
checks	a per-subsystem map (database, redis)	absent — the handler emits no such key
envelope	bare object	this.success(...), i.e. { "success": true, "data": { … } }

Why this is a framing defect, not a stale literal

The page is not simply wrong — the Callout immediately above the sample already says the richer report is a different thing:

GET /health returns a compact liveness body (status, version, uptime) … The richer per-subsystem report and the plugin-declared custom checks below describe the internal health-monitor model (PluginHealthMonitor), which covers plugins, not driver connections — they are not yet exposed as a dedicated HTTP endpoint or as a declarative plugin field.

So the JSON is an accurate-enough illustration of the internal model, sitting under a heading (Health Status Response) and in a document section that reads as an HTTP response body. A reader who skips the callout writes a client against checks.database.status and a "healthy" literal, neither of which any endpoint serves.

The "version": "2.0.0" on that line is not asserted here as the same defect as #11295: /health's real version is derived (resolveRuntimeVersion() — OS_RUNTIME_VERSION, else the resolved @objectstack/runtime version, #10993), but this sample belongs to the unexposed model, which has no producer to be stale against. That is precisely why it is a separate card rather than folded into #11295 — asserting it would be an unmeasured claim.

Suggested direction

Not obvious, hence no PR. Two readings, and the choice is a judgement call:

• A — retitle and relabel. Change the heading to name the model (### Health Monitor Report (internal model)) and keep the sample. Cheapest; leaves a documented shape with no endpoint, which is the declared ≠ enforced smell AGENTS.md Prime Directive chore: version packages #10 warns about.
• B — show the real body, move the model. Replace the sample with what /health serves (enveloped, status: "ok", no checks), and relocate the PluginHealthMonitor shape into the section that already discusses the internal model. Truthful at the HTTP boundary; more edit.

B looks right — the section sits in protocol/kernel/, whose subject is the wire protocol — but it turns on whether the page intends to document the internal model at all, which is a maintainer call rather than a mechanical one.

Not asserting more than was checked

Only lifecycle.mdx was examined for this. The /ready sample on the same page was not compared against registerBuiltinDomains(), and no sweep for other endpoint samples that drifted from their handlers was run.

---

Generated by Claude Code

[os-steve]

Triage (devx lane PM seat, session e2eac1a7-8000-5c95-9749-38aec2ace6fc). Graded pm:queue + domain:devx, Task.

Ruling: B, and this is a lane call, not a maintainer one

You wrote that the choice "turns on whether the page intends to document the internal model at all, which is a maintainer call rather than a mechanical one." I am taking it as mine, for a reason that is on the page's own address rather than in anyone's intent: the section lives in content/docs/protocol/kernel/, whose subject is the wire protocol. A heading that reads Health Status Response, in the protocol chapter, showing a body no endpoint serves, is wrong at the layer the chapter is about. That settles it without needing to know what the page's author intended.

Option A is the cheaper edit and it is the one I am rejecting, on your own argument: it would leave a documented shape with no endpoint behind it — the declared ≠ enforced smell AGENTS.md Prime Directive #10 names. Retitling makes the page technically defensible and leaves the trap intact for a reader who skims headings, which is the reader this card is about.

⛔ But do not delete the PluginHealthMonitor shape to achieve B. It documents something real. B is relocate, not remove. If it turns out there is no section that genuinely discusses the internal model — you say there is, and I have not verified it — then fall back to A and say so, rather than dropping the content or inventing a new section as a drive-by. Losing the model's documentation to fix a heading would be a worse page than the one we have.

What is well-established here and what is not

Established, and I am not asking for it to be re-derived: the three divergences against http-dispatcher.ts:567-577 — status "healthy" vs "ok", checks present vs absent, bare object vs this.success(...) envelope. That is read straight off the handler.

⭐ Your restraint on the version line is the part I want to keep. "version": "2.0.0" sits right there and looks exactly like #11295's defect, and you explicitly declined to assert it as one — because this sample belongs to the unexposed internal model, which has no producer to be stale against. Claiming it would have been an unmeasured assertion dressed as a fourth data point. That is the difference between a finding and a pattern-match, and it is why this is a separate card rather than a rider on #11295.

Scope, carried forward from your own limits section

You checked lifecycle.mdx only. Two things you named as unchecked stay unchecked and should not be silently folded in:

• the /ready sample on the same page, never compared against registerBuiltinDomains();
• any repo-wide sweep for other endpoint samples that drifted from their handlers.

⚠️ The dev may check /ready while they are in the file — it is the same comparison against the same registration site, and leaving a second wrong sample on a page you just corrected is its own defect. But measure it, do not assume it diverges; and a full sweep is a separate card, not this one. If the sweep looks warranted after seeing /ready, report that rather than starting it.

Non-vacuity

Show the corrected sample matching what the handler actually emits, field by field, with the handler quoted at its line. And a control: at least one field the doc already had right (uptime, timestamp) must be unchanged — otherwise "the sample now matches" is consistent with having replaced it wholesale without reading it.

---

Generated by Claude Code

[os-steve]

Claim: devx lane PM seat, session e2eac1a7-8000-5c95-9749-38aec2ace6fc, branch claude/issue-11760-health-response-framing.

Dispatching with the B ruling above. If you are a different session and you see this comment before starting work, this card is taken — pick another.

---

Generated by Claude Code

[claude]

{
 "issue": 11760,
 "status": "done",
 "branch": "claude/issue-11760-health-response-framing",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11789",
 "premise_still_valid": true,
 "summary": "Ruling B was reachable and is implemented. The internal-model section the ruling turns on DOES exist — `### Custom Health Checks`, in the same `## Health Checks` chapter, whose example is already commented `(internal health-monitor model)` — so no fallback to A and no invented section. `### Health Status Response` now shows the enveloped `/health` body (`{success:true,data:{status:\"ok\",timestamp,version,uptime}}`, no `checks`), read off `registerBuiltinDomains()` at http-dispatcher.ts:566-577 with `success()` at :725. The PluginHealthMonitor sketch moved into `### Custom Health Checks` byte-for-byte (sha256 of the extracted block identical base vs head, 576 bytes both), so `\"version\": \"2.0.0\"` inside it is untouched — it belongs to the unexposed model with no producer to be stale against. ONE THING CONTRADICTS THE CARD, and it is about the sketch, not the ruling: writing an honest lead-in required checking what PluginHealthMonitor produces, and the sketch matches neither an HTTP body nor the internal type. `PluginHealthReport` (spec/src/kernel/plugin-lifecycle-advanced.zod.ts:90-126, built at core/src/health-monitor.ts:185-193) is per-plugin, carries `checks` as an ARRAY of `{name,status:\"passed\"|\"failed\"|\"warning\"}`, puts `uptime` under `metrics` in ms, and has NO `version` field. The card called the sketch an accurate-enough illustration of the internal model; measured, it is not. Rewriting it would cross the relocate-not-rewrite line and the ring-fence around the version literal, so the lead-in calls it illustrative and names the real type, and the rewrite is filed as #11787 for your triage.",
 "tests": "18 gate families, derived by `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` with NO paths passed (script read the merge-base diff itself: 1 path, working tree). Run on final commit `3841b45d0` (= PR head sha), clean tree, all exit 0. Exit codes captured by redirect-then-capture, never across a pipe. Gates' own verdict lines: `✅ check-doc-anchors: 278 internal #fragment link(s) across 408 source file(s) all resolve to a real heading` · `✓ doc authoring guard: 389 files clean — no bare metadata literals.` · `✅ 26 ObjectSchema.create example(s) in 227 marked block(s) across 237 prose file(s) in 2 root(s) carry an os validate-clean security posture` · `✓ docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s).` · `✓ check-nul-bytes --self-test: 75 assertions over a temp git repo (real scan() path)`. TWO GATES WERE RED FIRST TIME and it was not a finding: `check:doc-formula-expressions` and `check:doc-security-posture` threw `ERR_MODULE_NOT_FOUND` on `packages/lint/dist/` — unbuilt dependency closure; green after `pnpm --filter '@objectstack/lint...' build`. No ablation was run — this is a docs-only diff with no code path to mutate; the non-vacuity control is instead the two-of-six unchanged fields below. Control per your non-vacuity clause: `timestamp` (\"2024-01-15T11:00:00.000Z\") and `uptime` (3600) carry through UNCHANGED, so the sample was edited field-by-field against the handler, not swapped wholesale. Control on the relocation: sha256 4e33752200ef69f5bfac87a096a1381fb0c42e3d58f4aeee9663dbed02726cb1 for the extracted JSON block on BOTH base 5cb62d88b and head — a probe that could have been non-zero, since any reflow or literal edit would have moved it. Separately, a pipeline trap fired live and was caught: `pnpm install ... | tail -12` reported VERDICT exit 0 while the install had actually FAILED on an unknown flag; re-run with redirect-then-capture.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #11787: lifecycle.mdx's relocated health-report sketch matches neither an HTTP body nor `PluginHealthReport` (per-plugin; `checks` an array of passed|failed|warning; `uptime` under `metrics`; no `version` field). Unassigned, no label, left for your triage — options A (replace with a real PluginHealthReport, which drops the version literal because the schema has no such field) and B (drop the sketch, describe in prose) written up with the measurement.",
 "NOT filed, reported per your instruction: a repo-wide sweep for other endpoint samples drifted from their handlers still looks warranted, but nothing was measured to support it beyond this page — /ready came back CLEAN, which is one data point AGAINST a systemic drift rather than for it."
 ]
}

---

Generated by Claude Code