th-6fdd1c: document the park-ordering mechanism and how to trust a green port

[brentrager]

Docs only — no code. Records three things that cost real time to rediscover during th-ef78d0 / th-6fdd1c, in spec/conformance/scenarios/README.md.

(This was meant to ride along with #523 but missed the squash by a minute.)

1. Do not copy Rust's park ordering

In all five servers the toolCall chunk is emitted from the server's own stream loop, never from inside the engine — so it is always interceptable. The trap is that Rust has no ordering code at all: its chunk goes through a separate event-translator task (one extra queue hop) while both park bridges write to the sink directly, so the correct order falls out of tokio's scheduler. That's a scheduler property; it does not port to goroutines, JS microtasks or .NET Task continuations. Anyone reading Rust to learn "how it's done" finds nothing to copy.

The portable restatement — what Go, TypeScript, Python and .NET all do — is the mechanism their write-confirmation gate already used: skip the chunk in the stream loop on a tool-name predicate, then re-emit it from the park path right after the park event.

2. Two footguns that drop a chunk silently

Both fail quietly rather than loudly, which is why they're worth writing down:

• The predicate must match only the request_<kind> raise tools, never the generic submit_interaction tool — it raises no park event, so nothing would ever re-emit its deferred chunk.
• Every non-park exit of the raise tool must re-emit immediately (the parse-error return and the conversational-fallback return). Miss these and interaction-conversational-fallback breaks, because that path has no park event to trail.

3. How to trust a green port

.NET's scenario runner lives in dotnet/server/integration-tests, not dotnet/server/tests. I ran the latter first and got a clean 405-test pass that said nothing whatsoever about this corpus.

A port that passes and a port whose runner never executed the scenario look identical from outside — the exact failure this corpus exists to catch. So the README now documents the control: add the language to a scenario's knownDivergences, re-run, and confirm the build fails with remove <lang> from knownDivergences … it now passes. Only a scenario that ran and passed can produce that message. Then take the marker back out.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6501ec6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR