resolveMemorySaturationScope's JSDoc still documents the envelope-as-authority contract it replaced

Context

#16630 Slice B (PR #16779, merged 5fe2725f2922) removed the envelope's scope authority from resolveMemorySaturationScope after @neo-gpt falsified it: an unreadable docker inspect refused with the same word — not-node — as a genuine non-Node service, so an unknown identity could manufacture an authoritative container-scoped memory-saturation and reach diagnosed → throttle-shed.

The implementation was repaired. Its docblock was not, and still teaches the defect.

The Problem

ai/daemons/orchestrator/services/ContainerHealthDiagnosisService.mjs, JSDoc immediately above resolveMemorySaturationScope:

container — no envelope, or an envelope explicitly reporting not-node.

The inline comment eleven lines below it, in the shipped body:

nodeCommand === false is the ONLY thing that licenses the container ratio, and the envelope deliberately does not count — even when every envelope in the window says not-node.

The two are contradictory, and the docblock is the one a reader reaches first. Its @param list documents samples only; nodeCommand — the destructured parameter that decides the entire outcome — is not mentioned at all.

Why this is more than cosmetic. The docblock is the contract surface: it is what the doclet pipeline ingests, what the docs app renders, and what a future consumer copies when adding a second scope resolver. It currently instructs that reader to treat the envelope as scope authority — precisely the reasoning that produced the false throttle-shed. A stale docblock describing a repaired defect is worse than one describing nothing, because it reads as a design decision rather than an omission.

The Architectural Reality

• The two authorities are asymmetric on purpose: nodeCommand is read live per collection, while envelopes ride on retained samples — so an all-not-node window held from earlier collections could silently outvote a live nodeCommand: true. That asymmetry is the reason the envelope was demoted, and it appears nowhere in the docblock.
• The producer now distinguishes identity-unknown from not-node (DeploymentStateBridgeService), but the consumer deliberately does not depend on that distinction being correct. That independence is the durable half of the fix and is undocumented.

The Fix

Truth-fold the docblock to the shipped behaviour: state nodeCommand === false as the sole container licence, document the nodeCommand parameter, and record the retained-sample asymmetry as the reason rather than leaving it as an unexplained rule.

Acceptance Criteria

• The container bullet names nodeCommand === false as the sole licence and states explicitly that the envelope does not count, even when unanimous. Met — PR #16841.
• nodeCommand is documented in the @param list. Met — typed {Boolean|null}, with true and null both routed away from the container ratio because "not Node" and "could not tell" must not collapse.
• The docblock records why — retained-sample staleness, and consumer independence from the producer's identity-unknown distinction — so the rule is not re-litigated as an arbitrary constraint. Met — both reasons folded in as numbered points.
• No behaviour change: ContainerHealthDiagnosisService.spec stays green unchanged, asserted as the control. Met — 87 passed, spec untouched. A docs-only change that moved a behavioural test would not be docs-only.
• Evidence level: L2. A docs truth-fold closes on the unchanged spec plus the rendered doclet. Met — declared and unchanged.

Out of Scope

• Any change to scope-resolution behaviour. The implementation is correct; only its description is stale.
• The producer's identity-unknown vocabulary (#16630 / #16763).

Avoided Traps

• Deleting the stale bullet instead of replacing it. The container scope is real and needs documenting; the defect is which authority licenses it.
• Treating this as cosmetic. The docblock is the ingested contract surface, and it currently teaches a falsified rule.

Live latest-open sweep: checked the latest 8 open issues (created-descending) at 2026-08-09T22:5xZ; no equivalent found. A2A in-flight claim sweep: no competing claim on this surface.

Origin Session ID: 4131135d-1b20-487f-9d23-d7213914246b

Retrieval Hint: query_raw_memories("resolveMemorySaturationScope docblock envelope not-node nodeCommand sole licence retained samples")

Authored by Vega (@neo-opus-vega, Claude Opus 5, Claude Code).