runtime dispatcher's SSE-fallback `{ events }` body is off-envelope — the one non-conforming literal body left in dispatcher-plugin.ts after #9813's discovery flip

[huangyiirene]

Found while implementing #9813 (the discovery-body envelope flip), by predicting what scripts/check-route-envelope.mjs's new express-style scan population would read from packages/runtime/src/dispatcher-plugin.ts. Filed unassigned — recording, not starting. Measured on origin/main at 45862a5.

The site

In the dispatcher route wrapper's streaming branch, locate by text res.json({ events }) (around line 269 on the measured ref; line numbers drift). When a dispatch result declares stream: true but the transport's response object has no write/end streaming surface, the handler collects the SSE events into an array and answers:

// Fallback: collect events into array
const events = [];
for await (const event of result.events) {
 events.push(event);
}
res.json({ events });

That body has no success flag and carries its payload under a top-level events key — off BaseResponseSchema in the same one-key-short family as the discovery bodies #9436/#9813 enveloped, plus a stray top-level key.

Why it is not swept into #9813

#9813's inherited ruling covers the two discovery bodies only (the #9436 sibling class: machine-read discovery surfaces, measured-tolerant readers). This body has a different consumer population — callers that requested an SSE stream and got the JSON fallback — and no reader sweep has been run on it. Whether it should be enveloped ({ success: true, data: { events } }), left as-is with a written reason, or the fallback retired outright is an undecided fork, not an inherited fix.

Where it is pinned

#9813's PR registers dispatcher-plugin.ts in check-route-envelope.mjs's enumerated express-style population with unenveloped: 1 and a ratchet naming this issue — so the count can only tick down, and this card is what drives it to zero.

Related: #9813 (the discovery flip and the scan population) · #9436 (the mother ruling) · #9389 (the pre-auth exemption boundary, a closed list this body is not on) · #9559 (rest-server's own envelope conversion; this file is not in its scope).

---

Generated by Claude Code

[os-warren]

Triage: lands in packages/runtime/src/dispatcher-plugin.ts ⇒ domain:cli; queued, type Task.

Rationale: the ratchet in check-route-envelope.mjs already pins this site (unenveloped: 1) so the state is honest; what remains is driving it to zero. The #9436 mother ruling's direction (envelope machine-read bodies) is the inherited default, but this body's consumer population (SSE requesters receiving the JSON fallback) has not been reader-swept — so dispatch premise-first: run the reader sweep, apply the #9436 direction if no reader depends on the bare { events } shape, and report a fork instead of guessing if one does.

Dispatch note for the cli seat: changing this response shape is a contract accept/reject behaviour change — Clause-②: yes, contract-review tier applies per the dispatch rules.

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 25
Session: session_01WeN7F6jQFpcqW2BN56RdPa
Branch: claude/issue-9936-sse-fallback-envelope
Worktree: objectstack-issue-9936
Domain: domain:cli
File surface: packages/runtime/src/dispatcher-plugin.ts (the SSE-fallback body only), scripts/check-route-envelope.mjs (the declared count only — see the ratchet section), plus a pin and .changeset/** (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: contract-review tier (CONTRACT_REVIEW_TIER, scripts/pm/dispatch-gates.mjs:1628) — mandated by Clause ②, not by paths; --tier returns no path-derived mandate, ⛔ not recalled
Clause-②: yes — triage said so by name ("changing this response shape is a contract accept/reject behaviour change") and I concur: the body a caller receives changes shape
Serial constraints cleared: packages/runtime/src/dispatcher-plugin.ts 🔓 FREE as of this round — #9813 landed at 5989b0de90 (PR #9949 merged 10:10:39Z) and released it. ⚠️ Sibling PR #9950 (#9585) is open in packages/runtime but touches action-execution.ts / domains/actions.ts / flow-dispatch-status.ts / http-dispatcher.test.ts — not this file. Verified against its file list, not assumed.

The site — located by text on 5989b0de90

dispatcher-plugin.ts:264-269 (⚠️ the card's "~line 269" was measured on 45862a53d8; treat every number as stale and locate by text):

} else {
 // Fallback: collect events into array
 const events = [];
 for await (const event of result.events) {
 events.push(event);
 }
 res.json({ events });
}

⛔ This card is PREMISE-FIRST. Do not start by writing the flip.

Triage was explicit, and I am making it binding: "dispatch premise-first: run the reader sweep, apply the #9436 direction if no reader depends on the bare { events } shape, and report a fork instead of guessing if one does."

⇒ The reader sweep is the first deliverable, and it can end the card without a flip. The #9436 direction (envelope machine-read bodies) is the inherited default, ⛔ not an inherited fix — its ruling's operative text names packages/adapters/hono/src/index.ts, and this body has a different consumer population: callers that asked for an SSE stream and got the JSON fallback instead. Nobody has swept them.

State the population and the control for every sweep, the way #9813's PR did (it reported "38 hits across 4457 non-dist .ts files" — the denominator is what makes the numerator mean anything). A sweep with no denominator is not a reading.

⭐ The third fork the card names, and the one I most want measured

The fallback fires only when the transport's response object has no write/end:

if (typeof res.write === 'function' && typeof res.end === 'function') { …stream… } else { …this body… }

Which shipped transport lacks both? If none does, this body is unreachable in every real composition, and "retire the fallback outright" (the card's own third option) becomes the honest answer rather than enveloping dead code. ⚠️ Measure reachability before choosing — and if it is dead, ⛔ say so and stop; retiring a branch is a fork for me to route, not a widening you may take.

The ratchet — the one part where a wrong move is a gate weakening

#9813's PR registered this file in check-route-envelope.mjs (IHTTP_ROUTE_MODULES, around :706-718 on 5989b0de90):

'packages/runtime/src/dispatcher-plugin.ts': {
 unenveloped: 1,
 ratchet: '#9936 (envelope or rule on the SSE-fallback `{ events }` body)',

• If the body is enveloped, the declared unenveloped must go 1 → 0. That is the ratchet moving in its only legitimate direction, and it is the point of this card.
• ⛔ Never raise it, never add an exempt entry (option B was rejected on runtime dispatcher's two discovery bodies (.well-known + REST-less {prefix}/discovery fallback) are the machine-read { data } class #9436 ruled on, and sit outside check-route-envelope's scan #9813), never skip or quarantine the gate.
• ⚠️ If the sweep says "leave it as-is with a written reason", that does NOT mean touching the count. The declaration stays 1, the reason gets written down, and the card becomes a decision rather than a code change — and that outcome is mine to sign off, not yours to land. Report it, don't implement it.

Gates — ⚠️ read this, it just cost a sibling PR a round

Re-derive with node scripts/pm/dispatch-gates.mjs from the actually changed paths. check:route-envelope names this file literally — report its before/after counts.

⚠️ pnpm lint is NOT equivalent to CI's Lint & Repo Gates job. PR #9951 reported a fully green derived union plus pnpm lint and CI still came back red on check:test-source-alias, a gate the derivation never names because its trigger is a new cross-package import inside a test file — content, not paths. Filed as #9955. So: if you add or change a test that imports another workspace package, run pnpm check:test-source-alias explicitly. ⛔ Its registry is shrink-only — widening an entry is not the fix, and neither is skipping it.

Read verdicts from reported counts, ⛔ never a piped exit code (#9914: an ablation matching ZERO exits 0 and is indistinguishable from a pass).

Boundary

⛔ packages/spec/** belongs exclusively to the domain:spec seat. If the envelope shape needs a spec change, STOP and report.

Report at draft-PR time — ⛔ do not wait on CI. ⚠️ Post the report as an issue comment on this card with the os-dev-report marker FIRST, and read it back — the terminal copy is the accelerator, ⛔ not the record; that channel silently dropped two reports this shift.

---

Generated by Claude Code