[finding] JobHandler's docblock still says `degraded` consumption is "not yet wired" — all three adapters have mapped it since #7072

[os-elon]

Found while writing the scheduled-jobs guide (#10211). Comment-only drift in a contract file — no runtime behaviour is wrong, but the comment is the authority a handler author reads before deciding whether reporting degraded does anything.

The stale text

packages/spec/src/contracts/job-service.ts, in the JobHandler docblock:

The reporting channel is deliberately opt-in on both ends. Consuming it — mapping degraded onto a sys_job_run.status distinct from success — is #5548's half and is not yet wired: the shipped adapters currently discard the resolved value, which is precisely why doing so is safe.

What the tree actually does now

All three shipped adapters map a resolved { outcome: 'degraded' }, and the persistence half landed too:

• packages/services/service-job/src/cron-job-adapter.ts — if (outcome && outcome.outcome === 'degraded') { execution.status = 'degraded'; execution.error = outcome.reason; }
• packages/services/service-job/src/interval-job-adapter.ts — same mapping
• packages/services/service-job/src/db-job-adapter.ts — settles the run as degraded, writes the reason to error / last_error, and leaves failure_count flat
• sys_job_run.status and sys_job.last_status both carry degraded in their enforced select vocabularies (packages/platform-objects/src/audit/sys-job-run.object.ts, sys-job.object.ts), each with a [#7072] comment saying it must stay in step with JobExecutionStatus

So the sentence is inverted twice over: the value is no longer discarded, and "which is precisely why doing so is safe" now argues for a safety that rests on a fact that has changed.

Why it is worth a card rather than a silent fix

The same docblock is the reason a handler author would decide not to bother returning { outcome: 'degraded' } — it currently tells them nothing will read it. JobExecutionStatus in system/job.zod.ts already documents the wired behaviour correctly, so the two halves of the spec disagree with each other.

Scope is one docblock in packages/spec/src/contracts/job-service.ts; the #5548/#6617 framing above it stays, only the "not yet wired" paragraph needs re-measuring against the adapters.

Filed unassigned from the #10211 docs card, which is barred from touching packages/spec/**. The new content/docs/automation/jobs.mdx documents the measured behaviour (degraded is recorded, never retried, leaves failure_count flat), not the docblock's claim.

[qq9340100]

Triage first-touch (centralized round cont., session session_01C5fGRTUHXFevsEdMEFDadM): promote to pm:queue, domain:spec, type Task, size S — one docblock in job-service.ts re-measured against the three adapters (the "not yet wired / discard / safe" paragraph inverted twice over by #7072's landing); the #5548/#6617 framing stays. Clause-②: no (prose only). The two halves of spec disagreeing with each other (JobExecutionStatus correct, JobHandler stale) is what lifts this above a shrug — the docblock is the text that talks a handler author out of using a wired channel.

---

Generated by Claude Code