feat(sep-xxxx): Conformance suite for triggers and events

[panyam]

Draft, and it must not merge as it stands. MCP Events has no SEP number, so every check id here carries a placeholder sep-9999- prefix. Renaming it is a merge blocker rather than a follow-up: plan.modelcontextprotocol.io builds from main, so a draft is invisible to it, but a merge would publish SEP 9999 as though it were real. See The number question below, which is still the one decision I would most like input on.

What changes

Adds a requirement-traceability yaml for MCP Events, plus the five server scenarios that score an implementation against it. Everything here is extracted from the design sketch that merged on main of modelcontextprotocol/experimental-ext-triggers-events on 2026-09-08.

Scenario	What it grades	Rows
events-discovery	the capability declaration, events/list, the descriptor fields, the error-code range	12
events-poll	poll delivery, the EventOccurrence shape, the cursor lifecycle	33
events-push	a long-lived events/stream: confirmation, heartbeats, event frames, cancellation	17
events-webhook	events/subscribe, the subscription key, TTL negotiation, events/unsubscribe	27
events-webhook-delivery	what the server POSTs: verification, Standard Webhooks signing, retries, control envelopes, SSRF	28

Together they emit 117 of the 135 declared rows. The other 18 need a prerequisite no implementation exposes over the wire yet — a catalog that can change mid-run, two principals, or the four capability rows the sketch has only just gained — and are listed under Out of scope with what each needs. Five is the whole plan, so what is left is rows inside these files rather than more files.

Three scenarios (events-poll, events-webhook, events-webhook-delivery) landed in the two earlier commits on this branch; the first revision of this description covered only discovery.ts and poll.ts, and this rewrite catches it up to the diff.

Provenance

panyam offered an Events conformance suite in #triggers-events-wg on 2026-08-28 and Peter Alexander accepted on 2026-08-31 ("No objections, that would be great!"). It follows the SEP-2640 suite (#330) in shape: extract the requirements into a traceability yaml first, then write scenarios that emit one check per row.

Per AGENTS.md this would normally start as an issue. The WG conversation is that discussion, and the extraction is easier to argue about as a diff than as prose, so it is here as a draft instead. Happy to split it into an issue if you would rather.

Prerequisite knowledge

• Events design sketch — the document every row is extracted from. Cursor Lifecycle carries most of events-poll; Subscribing and Event Delivery is the densest normative section and is what the three later scenarios cover.
• Standard Webhooks — the signing scheme the sketch adopts. sep-9999-delivery-signature-* grades the v1,<base64> signature over {id}.{timestamp}.{body}, keyed on the base64-decoded bytes after the whsec_ prefix.
• AGENTS.md § Scenario design and § Check conventions — why this is five scenarios with 117 checks rather than 117 scenarios, and why a missing prerequisite fails rather than skips (Standardize how scenarios report setup/execution failures #248).
• src/traceability/ — how a declared row becomes tested or untested. This is what makes declaring all 131 rows up front the right move rather than an overreach.
• src/seps/sep-2640.yaml — the closest precedent for the yaml's shape and for how much provenance belongs in its header.

The number question

This is the part I would most like a decision on, because it is the only thing blocking merge.

SEP numbers are PR numbers in modelcontextprotocol/modelcontextprotocol, and Events has no PR there — the work lives in its own repository. Both traceability gates are numeric: the directory filter at src/traceability/index.ts:174 (/^sep-\d+\.yaml$/) and the check-id filter at line 41 (/^sep-\d+-/). A file named events.yaml is silently dropped from the manifest rather than rejected, and src/new-sep/index.ts:163 refuses any argument that is not a positive integer. So there is no honest name that works today.

Three ways out, and I have no strong preference between the first two:

1. Reserve a number. Cleanest, and it makes this mergeable as-is after a mechanical rename.
2. Let the traceability layer carry pre-SEP extensions. Relax both regexes to accept a non-numeric key, so work like this can be tracked before it has a number. Wider change, but Events will not be the last extension in this position.
3. Keep it unnumbered and drop the yaml. Loses the traceability artifact, which is most of the value.

I used 9999 to unblock the extraction, deliberately far from the live range. The rename touches the filename, the sep: field, every sep-9999- id in the yaml, and the same ids under src/scenarios/server/events/ — mechanical, but wide enough that it is worth doing once, in the right direction.

Reviewer's guide

A restaurant can cook a dish that is not on the menu. The kitchen has the ingredients and the line knows the recipe, so if you somehow know to ask you get it — but nobody reading the menu ever orders it, so from the outside it may as well not exist. That is the state this suite found its first implementation in: events/list answers, all three delivery modes work, and nothing appears in capabilities.extensions, which is the menu a spec-following client reads before deciding what to ask for.

That shaped the whole suite, because the obvious design misses it. A harness normally treats an undeclared optional capability as not-applicable and skips, which is right for a restaurant that genuinely does not serve the dish and wrong for one that serves it off-menu: the skip reports a clean run over a surface no client can reach. So the capability gate asks before it skips — it calls events/list, and only a server that both declares nothing and implements nothing gets the skip. The same instinct runs through the rest of the diff: wherever a check cannot be exercised, the scenario names the missing prerequisite and fails, because the one thing worse than a red conformance run is a green one that tested nothing.

Read in this order. The first four are the whole argument; the rest is mechanism.

1. src/seps/sep-9999.yaml — start here, header first. It covers the placeholder, how 144 keyword occurrences became 135 declared rows and 30 excluded ones, which rows each scenario emits, and what the 18 unemitted rows are waiting for. The rows themselves are skimmable once the header lands.
2. src/scenarios/server/events/discovery.ts — the off-menu gate is at the top of checks(). Everything after it grades whatever the server actually serves, field by field, reporting the first offender per field so ids stay stable regardless of catalog size.
3. src/scenarios/server/events/webhook-delivery.ts — the densest file, and the one whose shape is least obvious. Note the first branch of deliveryChecks: with no EVENTS_WEBHOOK_CALLBACK_BASE the callback is a loopback URL, and that is the SSRF probe rather than a degraded run. A server that refuses it passes the SSRF rows and reports the delivery rows untestable; one that POSTs to 127.0.0.1 fails the SSRF rows and hands over real deliveries to grade everything else against. Both outcomes say something, and neither is a false green.
4. src/scenarios/server/events/webhook.ts — subscription management only; anything the server then POSTs belongs to the file above. identityChecks is the interesting part: the key is (principal, delivery.url, name, arguments), a run holds exactly one principal, so the three components the harness can vary are graded and the principal component is reported untestable by name rather than passing a cross-tenant row nothing exercised. Every subscription it creates is released before it returns — against a public server a leak is state held for a callback nobody reads.
5. src/scenarios/server/events/push.ts — one 35s observation window serves every timing row. The window has to outlast the document's 30s heartbeat SHOULD, which is why this scenario needs --timeout 60000: a shorter one cannot tell a silent server from a slow one, and reporting a compliant slow server as broken is worse than taking the time.
6. src/scenarios/server/events/stream.ts — why events-push cannot use conn.request(). It resolves on the response for its id, and that is exactly what a push stream withholds until the subscription ends, so awaiting it would block for the life of the subscription and see none of the notifications the scenario grades. This opens the POST itself and hands back a session while the stream is still live. Aborting it is also the Streamable HTTP cancel, so the cancellation rows come out of the same mechanism rather than a second code path.
7. src/scenarios/server/events/receiver.ts — the harness has to be the callback endpoint, because the signature, the headers, the verification challenge and the retry cadence are only observable from there. It records raw body bytes, since the signature covers those and re-serializing the JSON would change them. Per-path behaviour (accept, redirect, refuse, fail-then-accept, wrong-challenge) lets one receiver serve every probe.
8. src/scenarios/server/events/negative-fixture.ts and the four negative*.test.ts files — the negative controls, 100 cases over one fixture. The fixture is a stateless events server whose every option breaks exactly one rule, which is what makes a control a control: with two things wrong at once, a flipped check does not say which one it caught. It also does the six things no client can ask a real server for, so the rows that report untestable against both implementations are graded here at least once.
9. poll.ts, helpers.ts, index.ts, types.ts — in poll.ts, quietAdvanceChecks is what makes cursor advancement gradeable against a server where nothing is happening, which is the state a conformance fixture is usually in. In helpers.ts, EVENTS_EXTENSION_ID does double duty: ScenarioSource carries it as { extensionId }, which keeps these scenarios off the --spec-version timeline, and it is the key the capability itself lives under in capabilities.extensions. Those were two different things until 2026-09-22, and the story of how they became one is under Before/after. The rest is registration.

How it works

discovery:
  declared, value <- capabilities.extensions["io.modelcontextprotocol/events"]
  if not declared:
      probe <- events/list
      if probe is -32601:  skip everything          # genuinely does not do events
      else:                fail the declaration check, keep grading
  grade events/list, then each descriptor field across all descriptors
  probe one unknown event name -> grades NotFound and the server-range rule

poll:
  pick the first descriptor advertising "poll"; none -> untestable, not skip
  p1 <- poll(cursor=null)        # bootstrap: must replay nothing
  p2 <- poll(cursor=p1.cursor)   # quiet period: a cursor must still come back
  p3 <- poll(no cursor field)    # absent must be accepted as null
  p4 <- poll(maxEvents=1)        # batch must be capped
  p5/p6 <- maxAgeMs with and without a cursor
  poll forward from p1.cursor, waiting nextPollMs, to catch a real occurrence;
  grade the EventOccurrence rows only if one arrived

push:
  pick the first descriptor advertising "push"
  open events/stream and keep the POST open
  expect notifications/events/active within 3s -> cursor, truncated, _meta
  settle 35s                     # outlasts the 30s heartbeat SHOULD
  grade heartbeat cadence, event frames, foreign frames, SSE comments
  abort the request              # the Streamable HTTP cancel
  assert nothing more arrives, then grade the final result and the
  concurrency rules with a second and third stream

webhook:
  pick the first descriptor advertising "webhook"
  subscribe(https callback, fresh secret, ttlMs) -> id, refreshBefore, status
  same key again                 # must be an idempotent upsert, same id
  vary url / name / arguments    # must each produce a different id
  ttlMs omitted / null / absurd  # default, no-expiry, capped-not-refused
  reject: http:// url, a missing secret, one too short to be a secret,
    and a type whose delivery does not list webhook
  unsubscribe the key, then unsubscribe a key never held -> NotFound
  release every subscription created, including ones the server should
  have refused and did not

webhook-delivery:
  start an HTTP receiver; callback is EVENTS_WEBHOOK_CALLBACK_BASE or loopback
  subscribe with a fresh secret
  refused + loopback  -> the SSRF rows pass, delivery rows untestable
  refused + routable  -> nothing can be delivered, everything untestable
  accepted + loopback -> the SSRF rows fail, and grade the rest anyway
  wait up to 20s for the first POST, then 3s for more
  grade the verification handshake, transport and headers, the signature over
  the raw bytes, the event and control envelopes, redirect refusal, and the
  retry cadence on a path that fails before it accepts

Cursors are opaque by definition, so the harness cannot mint one old enough to fall outside a retention window; the truncated rows that need a stale cursor report untestable rather than skip. The same is true of DNS rebinding: sep-9999-ssrf-validate-at-delivery-time needs a hostname that resolves differently between subscribe and delivery, so it names that and fails rather than passing on the strength of the subscribe-time check.

Decision log

Carried forward from the first revision:

• All 135 rows are declared now, though only 117 are emitted. An undeclared requirement is invisible; an undeclared-and-unemitted one is indistinguishable from a requirement nobody noticed. Declaring the full set makes the outstanding rows surface as untested, which is the manifest working rather than a gap in this file.
• Pure MAY and OPTIONAL sentences get no row. Five initially got one and were demoted to excluded: rather than deleted, so the keyword sweep stays auditable against the source.
• Client, host, receiver and SDK-guidance obligations are excluded rather than declared. Roughly a fifth of the normative sentences address the client or the callback endpoint. Declaring them would inflate the denominator with rows no server-side scenario could ever emit.
• 88 of the 135 rows quote no RFC 2119 keyword. They come from the EventOccurrence field table, the error-code table and the descriptor fields, which the sketch states declaratively. Since "severity follows the keyword" is undefined for them, the yaml header states the rule used: a field the document marks required, or a wire fact a client cannot work without, is FAILURE; anything else drawn from an example payload is WARNING.
• The sketch is not a spec diff, so new-sep's PR lookup does not apply and specPathToUrl (src/new-sep/index.ts:19) hard-requires a docs/specification/draft/ prefix that does not exist here. Scaffolded with --spec-url. There are no section anchors to cite, so rows carry no per-row url.

Decided since:

• Five scenarios rather than one. A server may implement any non-empty subset of the three delivery modes, so poll-only and push-only servers are both conformant and grading them together would misreport each. Webhook splits again at the point where the server stops answering requests and starts making them: subscription management works against any reachable server, while delivery needs a callback URL the server under test can reach over https, which is the one prerequisite a local run cannot satisfy — the SSRF rules this suite checks require a conformant server to refuse localhost.
• The delivery scenario runs a real HTTP server rather than mocking the callback. Signing, headers, the challenge handshake and retry timing exist only at the endpoint. A mock would grade what the harness believes the server sent.
• The signature is verified over the raw bytes, per the document's own instruction to receivers, so the suite cannot accidentally pass a server that signs a re-serialization of its own JSON. This caught a real formula bug in the first implementation that its own client and receiver both agreed with.
• events-push sets its own clock. 35s of watching is most of the wall time in this suite. The alternative is a window shorter than the cadence the document permits, which grades the harness's patience rather than the server.
• Writing the controls found two bugs in the scenarios, which is the best argument for having them. webhook.ts listed 26 ids in the set it reports untestable when it bails, where its gradeable path emits 27: sep-9999-error-unsupported simply vanished from every run against a server with no webhook-capable type, instead of naming the prerequisite it was missing. And webhook-delivery.ts reported the gap and terminated envelope rows untestable unconditionally, even when the server had just POSTed one — the envelope was sitting in what the receiver recorded and nothing looked at it. Both are fixed here, and both are the class of defect a green run cannot show you.
• EVENTS_DELIVERY_SETTLE_MS is new, and it is how long the delivery scenario lets retries and the two non-retryable probes play out. It was three hard-coded 5s sleeps, which is most of that scenario's wall time and pure waste against a fixture that answers in microseconds. The default does not change.
• Rows the principal owns report untestable rather than passing. Cross-tenant isolation, per-principal verification caching and subscribe-time authorization all need a second credential. The runner cannot send even the first one today, which is the next thing I would like to add (see Out of scope).

Risk / blast radius

• Affects: additive. Five new scenarios, one new yaml, one new entry in EXTENSION_IDS. No existing scenario, suite list or check id changes.
• Not selected by default. source is { extensionId }, so matchesSpecVersion returns false for every --spec-version and these never join a dated run. They are also in the pending list. Reaching them takes --scenario events-* or --suite all.
• Tests: npm run build, npm run lint and npm test pass — 725 tests across 51 files. The controls take the suite from 163s to 254s, most of it the delivery ones waiting out retry windows. The two timing-heavy files import the scenario once and run their cases concurrently for that reason; sequentially they were 425s, which is a lot to pay on every pre-push.
• Negative controls cover all five scenarios — 100 cases across negative.test.ts, negative-push.test.ts, negative-webhook.test.ts and negative-delivery.test.ts, over one shared fixture in negative-fixture.ts. Each pairs a conformant in-process server with one broken in exactly one way, and every divergence in the table below has a case, so a red run against a real server can be trusted rather than re-derived. The fixture also does the six things no client can ask a real server for — fail upstream, lose its replay window, terminate a subscription, close a stream itself, and send the gap and terminated control envelopes — which are the only evidence those checks work, since they report untestable against both implementations.
• Be paranoid about: the capability gate. It is the one place this suite deliberately departs from how every other extension scenario here behaves, and it is load-bearing for the headline finding. If you think an undeclared-but-serving server should skip, say so — that choice is the difference between a green run and a red one. There is an inline comment on it.
• src/seps/traceability.json will drift once these ids are emitted in a real run. Per AGENTS.md the traceability workflow refreshes it by PR and it is not a gate, so this leaves it alone.

Before / after

There was no Events suite before, so what matters is what an implementation looks like when scored. Two were, both re-measured 2026-09-21: mcpkit's examples/events/kitchen-sink, and metronome-mcp.fly.dev, Peter's own server, announced 2026-09-10 and written by the author of the sketch.

Scenario	kitchen-sink	metronome
events-discovery	8/11	10/11
events-poll	26/29	27/29
events-push	11/15	13/15
events-webhook	17/23	20/23
events-webhook-delivery	12/21	3/27

metronome's delivery number is not a result about metronome: it refuses the loopback callback, correctly, so 24 rows report untestable for want of a routable one. Point EVENTS_WEBHOOK_CALLBACK_BASE at a tunnel and that run becomes meaningful. Its other four scenarios fail nothing real except the capability placement row below.

Fourteen rows fail in kitchen-sink for a real reason rather than a missing prerequisite, each observed against the running server rather than read out of its source. Nine are new here, from the three later scenarios:

Check	What the server does
sep-9999-stream-subscription-id-meta	puts the stream's correlation id in params.requestId, not params._meta["io.modelcontextprotocol/subscriptionId"], so a client holding two streams cannot route by what the document tells it to read
sep-9999-stream-exempt-from-concurrency-cap	counts events/stream opens against the per-principal subscription cap, which the document exempts them from
sep-9999-subscribe-url-https-required	accepts an http:// callback and subscribes to it
sep-9999-unsubscribe-unknown-not-found	answers success for a subscription key it never held, so a client cannot tell teardown from a typo
sep-9999-delivery-signature-formula	keys the HMAC on the literal whsec_… string instead of the base64-decoded bytes after the prefix, so no Standard Webhooks receiver verifies its signatures
sep-9999-verification-required-before-delivery	delivers with no challenge handshake — the handshake does not exist yet
sep-9999-ssrf-validate-callback-url	delivers to http://127.0.0.1

The signature and verification rows are the same shape of problem and worth reading together: nothing proves the callback endpoint wanted the deliveries, and what arrives there cannot be authenticated. metronome fails neither. The SSRF row is fixture configuration rather than a library hole — that fixture sets an allow-private-networks flag so its demo can reach a local receiver — but the row fails and should, because the suite grades the server it was pointed at.

Both implementations failed sep-9999-capability-events-object, for different reasons, and that row is where this got interesting. mcpkit declared nothing at all. metronome declared events under capabilities.extensions["io.modelcontextprotocol/events"], the SEP-2133 extensions map, where the document said top-level capabilities.events — so the suite was scoring the sketch author's own server as non-conformant against his own document.

Rather than pick a side I asked, on 2026-09-22. The document was the thing that was wrong. Extension negotiation is where a capability belongs, metronome had been right all along, and PR 7 moves the sketch there. This suite now reads the extensions map, and mcpkit's original pass-then-fail on that row turns out to be an artifact of following a document that did not yet say what its author meant.

Two smaller things came out of the same conversation. metronome's -32603-instead-of--32602 on arguments that violate inputSchema was a framework default surfacing, and was fixed the same day. And the reason events only appear on the 2026-07-28 wire is that extension negotiation did not exist before it, so a 2025-11-25 run reporting the extension as absent is correct rather than a gap.

That is the case for the suite better than any pass count: scoring two implementations found a defect in the specification. The tables above are dated 2026-09-21 and predate all three fixes, so they need re-measuring before anyone quotes them.

Running a suite against an implementation nobody wrote it for is also what finds the suite's own bugs. Two are fixed in this branch and both were invisible against a single target: minimalArguments gave up on any inputSchema with a required property, which scored metronome's poll at 1/34, and the occurrence rows were graded off a cursor: null poll that a conformant server answers empty. Same pattern as SEP-2640.

flowchart TD
    A[server under test] --> B{extension declared?}
    B -->|yes| G[grade everything]
    B -->|no| C{events/list answers?}
    C -->|"-32601"| D[SKIP all: does not do events]
    C -->|returns a catalog| E[FAIL the declaration check]
    E --> G
    G --> H{check exercisable?}
    H -->|yes| I[SUCCESS or FAILURE]
    H -->|no| J[untestable: FAIL and name the prerequisite]

Loading

Running them

node dist/index.js server --url <url> --scenario events-discovery
node dist/index.js server --url <url> --scenario events-poll
node dist/index.js server --url <url> --scenario events-webhook
node dist/index.js server --url <url> --scenario events-push --timeout 60000
node dist/index.js server --url <url> --scenario events-webhook-delivery --timeout 180000

Use a spec version of 2026-07-28 or later. Extension negotiation did not exist before it, so nothing earlier can declare Events, and an older run reports the extension as absent by design. The runner's default already lands there.

events-push needs the longer timeout for the reason above; EVENTS_PUSH_WATCH_MS overrides the window. EVENTS_WEBHOOK_CALLBACK_BASE makes the delivery rows gradeable against a server that correctly refuses loopback. One caution from running all five in sequence against one fixture process: subscriptions the earlier scenarios hold can exhaust a per-principal cap and starve the last one, which then reports almost everything untestable. Each scenario releases what it creates, so this is a property of the fixture's cap rather than of the suite, but it is worth knowing before reading a 1/29.

Out of scope

• The 18 unemitted rows. Seven (schema-evolution-additive, breaking-change-new-name, list-changed-notification, four removal-*) need a server whose catalog can be made to change mid-run. Four are error-table rows already provoked by other checks and simply not claimed in their own right yet; two of those look cheap. Two need a second principal. Four are the capability rows the sketch gained on 2026-09-23, of which fallback-method-not-found is the one already within reach. payload-minimality is a SHOULD about payload content, and delivery-body-size probably measures as much of it as a harness can see. Each is declared and reports untested, which is the traceability layer doing its job.
• An auth option on the server runner — a bearer token or a repeatable --header. Scoring metronome at all needs a local proxy in front of it to inject the header, and the two authz rows need two credentials. Its own PR, and it would retire the proxy.
• The sep-9999-* rename, once the number question above is settled. Merge blocker.

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/@modelcontextprotocol/conformance@504

commit: 2323122

[panyam]

Flagging this deliberately, because it is the one place this suite departs from how every other extension scenario in the repo behaves, and the departure is what turns the run against mcpkit red rather than green.

Everywhere else here, an optional capability the server never declared is a clean SKIP. That is correct when the server genuinely does not implement the feature. It is wrong when the server implements it and never says so: mcpkit answers events/list, serves all three delivery modes, and declares nothing under capabilities.events, so a client that reads capabilities to decide what to call never reaches any of it. A SKIP reports that as a clean run over a surface no client can use.

So the gate asks before it skips. One extra events/list separates "does not do events" (-32601, skip everything) from "does events off-menu" (returns a catalog, fail the declaration check and keep grading the rest).

The precedent is declaredSkillsCapability in src/scenarios/server/skills/helpers.ts, split out from skillsCapability for the same reason: a malformed declaration was being folded into "not declared" and skipping the whole suite, which "reads as a clean run against a server that is plainly wrong". This applies that argument to an absent declaration rather than a malformed one.

The cost is one extra request against servers that do not implement events at all. If you would rather pay nothing there and accept the false SKIP, say so, but the finding seems worth the request.

[panyam]

Updated for the capability-location resolution (d3d26e0).

The rows put the declaration at the top level, under capabilities.events, because that is what the design sketch said. Two implementations read that sentence and landed in different places: this suite's target followed the document, and metronome-mcp.fly.dev used the SEP-2133 extensions map. Rather than pick a side or accept both, I asked @Poita on 2026-09-22.

The document was the thing that was wrong. experimental-ext-triggers-events#7 moves the declaration into Extension Negotiation, keyed by io.modelcontextprotocol/events. These rows now follow that PR.

What changed here

• declaredEventsCapability and the four scenarios that probe the declaration read capabilities.extensions[...]. EVENTS_CAPABILITY is gone, and EVENTS_EXTENSION_ID absorbed its job — it previously carried a comment saying in as many words not to read the capability at that key.
• sep-9999-capability-events-object and -capability-list-changed-flag restated from PR 7.
• Four new rows for what else PR 7 specifies: the empty settings object, the optional client declaration, listChanged gating whether a server may send notifications/events/list_changed, and the -32601 fallback for a server that does not offer the extension. All four are declared and not yet emitted, so they report untested.
• The negative controls moved with them, which is how the one message I had missed got caught.

These rows track an unmerged PR, which the yaml header now says. Same posture as the SEP-2350 scope-challenge scenarios against #481: a red row means the head moved rather than that an implementation regressed.

One other thing this suite turned up and @Poita has since fixed: arguments violating inputSchema answered -32603 where the document requires -32602.

So across two implementations the suite found a defect in each and one in the document. That last one only surfaced because the rows were not softened to let both sides pass, which felt pedantic at the time and is the reason the sketch is being corrected now.

[panyam]

Closing in favour of a fresh PR from the same branch, so the description reads against the finished diff rather than as a sixth revision of one written when two of the five scenarios existed. Same commits, nothing dropped. Link in a moment.

[panyam]

Replaced by #521, same branch and same commits.