Skip to content

docs(qa): record dispatcher-plugin.ts as deliberately outside the #2992 transport tripwire set - #9522

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-9410-dispatcher-plugin-out-of-watched-set
Aug 18, 2026
Merged

docs(qa): record dispatcher-plugin.ts as deliberately outside the #2992 transport tripwire set#9522
os-zhuang merged 1 commit into
mainfrom
claude/issue-9410-dispatcher-plugin-out-of-watched-set

Conversation

@os-zhuang

@os-zhuang os-zhuang commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Fixes #9410

packages/runtime/src/dispatcher-plugin.ts has both properties that make a file a plausible landing site for a realtime transport, and until now neither the conformance test nor the protocol page said anything about it:

  1. It mounts routes/actions, /automation and /packages, the registration path separate from the @objectstack/rest one.
  2. It already writes SSE — two text/event-stream sites (:248, :356) with no-cache and keep-alive, i.e. working plumbing an agent could extend without writing any new transport mechanics.

None of the five #2992 / ADR-0096 D4 transport tripwires watch it, so a subscribe/fan-out transport wired there mints no TRANSPORT-WIRED key, produces no UNCLASSIFIED surface and reds no build. The protocol page stated the general limitation ("a transport wired outside the watched files produces no key and no failure") without naming the specific, already-SSE-capable file sitting inside it.

What this PR does

Per the maintainer ruling on the card (2026-08-18): option C now, option A as a named precondition of #8347.

This is a recording. It changes no behaviour — no probe is added, no key is minted, and no matrix row is written for the two existing sites. Option B (watching the file with the full mechanics pattern and classifying the two AI-streaming sites) was rejected in the ruling by name, because it would put two non-realtime surfaces into the TRANSPORT-WIRED vocabulary.

The reason, recorded

Both text/event-stream sites are per-request AI response streaming, not realtime subscription fan-out. Verified in source rather than assumed:

  • Each drains one AsyncIterable that the route handler itself returned into that same request's response body, then calls res.end(). The second site's own source comment names its producer as the AI routes.
  • No subscriber is registered and no event is delivered to a set of recipients.
  • The file carries no upgrade handler, no subscribe registration and no realtime-service call. Grepped for handleUpgrade / WebSocket / EventSource / subscribe / realtime / fan-out: zero hits, against a control showing the same query hitting ten other files under packages/runtime/src. The only publish hits in the file are ADR-0033 metadata package publishing, an unrelated sense of the word.

Watching it with the existing mechanics pattern would therefore mint a key on day one for a surface the tripwires are not about, leaving only two exits: classify two non-realtime sites in the matrix, or weaken the pattern.

Where the recording went, and why there

  • packages/qa/dogfood/test/authz-conformance.test.ts — the note closes the #2992 tripwire probe list, immediately after the last tripwire probe and before the unrelated MCP block. A reader who has just finished enumerating the watched set reads that set's boundary in the same breath, which is the moment the question "is that all?" actually arises. It sits beside, and explicitly distinguishes itself from, the pre-existing #5519 mention of the same file at :96 — that one is about anonymous gates on the mounted routes and is a different point, so a reader must not read it as the exclusion already having been recorded.
  • content/docs/protocol/kernel/realtime-protocol.mdx — extends the identity-admission callout at the exact sentence that states the general limitation.

The boundary is drawn on fan-out, not on the SSE content type

Both records say so explicitly, because that is the part that goes stale silently: wiring an upgrade handler, a subscribe registration or a realtime-service call into that file puts it back inside the hazard while the recorded boundary still claims otherwise, and nothing in CI will fail for whoever does it. Promoting the file into the tripwire population with such a fan-out-specific marker (not the bare SSE content type, which is precisely what would over-match the two sites above) belongs to #8347.

That precondition is already on record there: the triage seat posted the companion comment on #8347 at ruling time (comment 5322879847, 2026-08-18T02:49:06Z), naming the fan-out-specific marker and excluding the bare content type. This PR therefore adds no second comment and does not edit that card's body — #8347 remains open and is not addressed here.

Verification

Union re-run at final commit 5bb3cb0a3.

  • pnpm --filter '@objectstack/dogfood^...' build — exit 0 (dependency closure built first).
  • Targeted: vitest run test/authz-conformance.test.ts1 file passed, 27 tests passed, exit 0.
  • Whole dogfood suite: 110 files passed / 1 skipped, 792 tests passed / 3 skipped, exit 0.
  • Path-derived gate union from the actual changed paths (node scripts/pm/dispatch-gates.mjs), all green: check:cross-package-test-inputs, check:changeset-gate-self-tests, check:objectui-changeset, check:docs-audit-scope, check:docs-redirects, check:role-word, check:test-source-alias, check:type-source-resolution, check:nul-bytes, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, docs-audit/check-affected-docs, plus the spec-liveness family (check:empty-state, check:liveness, check:strictness-ledger, check:variant-docs) and the convention-triggered check:engine-double-contract, check:where-matcher, check:query-options-erasure, check:type-check-coverage.

Reverse verification of the declaration reasoning

The new comment names two repo paths, so check:cross-package-test-inputs is load-bearing here. Both are covered by pre-existing dogfood globs (packages/runtime/src/**, and realtime-protocol.mdx declared verbatim by the earlier tripwire card), so no glob was added — but "already covered" is only meaningful if the gate actually reads comment text. Injecting an undeclared path into the new comment turned it red, naming the injected path and this file exactly:

FAIL: cross-package test inputs are not declared consistently.
  - @objectstack/dogfood names path(s) no declared glob covers
      packages/objectql/src/engine.ts   (named in packages/qa/dogfood/test/authz-conformance.test.ts)

Restoring returned it to OK: 12 package(s) read outside themselves, all declared. The gate does see the new prose; the coupling it enforces is real (editing the protocol page can make this recorded boundary wrong, which is exactly when the test should re-run); and no prose was reworded to dodge the scanner.


Generated by Claude Code

… transport tripwire set (#9410)

packages/runtime/src/dispatcher-plugin.ts mounts routes (/actions,
/automation, /packages — the registration path separate from the
@objectstack/rest one) and already writes SSE at two sites, yet none of the
five #2992 / ADR-0096 D4 transport tripwires watch it. A subscribe/fan-out
transport wired there mints no TRANSPORT-WIRED key and reds no build, and
the protocol page stated that limitation only in general terms.

This is a recording. No probe is added, no key is minted, and no matrix row
is written for the two existing sites.

The reason, recorded because a reader cannot re-derive it cheaply: both
text/event-stream sites are per-request AI response streaming, not realtime
subscription fan-out. Each drains one AsyncIterable returned by the route
handler into that same request's response body and then calls res.end();
no subscriber is registered, no event reaches a set of recipients, and the
file carries no upgrade handler, no subscribe registration and no
realtime-service call. Watching it with the existing mechanics pattern
would mint a key on day one for a surface the tripwires are not about.

The boundary is drawn on fan-out, not on the SSE content type, and both
records say so. Promoting the file into the population with a
fan-out-specific marker is written into #8347's acceptance as a
precondition of the WebSocket/SSE transport landing.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012WKSnqAaoqtW3QX7SSf1Vk
@github-actions

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

@github-actions github-actions Bot added documentation Improvements or additions to documentation tests tooling labels Aug 18, 2026
@os-zhuang
os-zhuang marked this pull request as ready for review August 18, 2026 07:18
@os-zhuang
os-zhuang added this pull request to the merge queue Aug 18, 2026
Merged via the queue into main with commit 0bb8dbd Aug 18, 2026
29 checks passed
@os-zhuang
os-zhuang deleted the claude/issue-9410-dispatcher-plugin-out-of-watched-set branch August 18, 2026 07:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/s tests tooling

Projects

None yet

2 participants