A shared relay must now treat some payloads specially: do you let its body inspect the payload, or require callers to supply the operation?

## What is actually being spent The relay's signature is a promise to callers you will never meet: *for every payload type a caller names, this behaves the same way*. That promise is the only thing that makes a shared relay shareable — it is why a new team can adopt it by reading the signature rather than by reading the body, and why a new payload type needs no change to shared code. Special-casing spends that promise, and it spends it silently. The signature is unchanged, so nothing at any call site records that behaviour now depends on which type was named. The next reader reasons from a sentence that is no longer true. ## The two routes, compared | | Body inspects the payload | Caller supplies the operation | |---|---|---| | Signature after the change | Unchanged, and no longer accurate | Wider, and still accurate | | Where per-type knowledge lives | In shared code, far from the type's owner | With the team that owns the type | | Cost of a new payload type | An edit to shared code, by someone who does not own the type | Nothing; the caller brings its own step | | Visibility to callers | None — the exception list is invisible | Explicit at every call site | | Migration cost now | Near zero | Every call site updated once | | Platform portability | Needs the type choice to survive to run time, which not every platform provides | None required | The asymmetry is the point: inspection is cheap today and charges rent forever, while supplying the operation charges once and then costs nothing per new type. ## How to decide 1. **Ask who owns the knowledge.** If the differing step is knowledge about the payload type, it belongs to whoever owns that type, not to the relay. That answers most cases outright. 2. **Ask how many special cases there will be.** "Just one" is almost never true; the second request arrives from the team that saw the first one granted. 3. **Ask what the call sites can see.** A behaviour that cannot be read off the signature is a behaviour that will surprise someone during an incident. 4. **Ask whether a narrower promise is honest.** If most callers genuinely need the special handling, the general signature may have been the wrong shape and a **declared limit on the placeholder** — a signature that admits only payloads offering some capability — is the honest replacement. ## The middle path, and when it is right Where the special case really cannot move outward, the discipline is to keep the general promise honest and publish the exception beside it: - Keep the universally quantified entry point **exactly as promised**, with no exceptions in its body. - Add a **second, explicitly narrower entry point** whose signature states what it requires and what it does differently. - Let callers choose between them at the call site, where the choice is visible. This costs a slightly larger surface and buys a surface that is true. Two honest signatures beat one signature with an undocumented exception list, and a team reading the API can now see the fork instead of discovering it. ## What to set as a standard For a platform team the rule worth writing down is short: **a published signature that quantifies over every caller-chosen type may never grow a special case in its body.** The exception goes in a new signature or in an argument, and the general one stays true. Enforce it at review time, because nothing mechanical will catch it — the change compiles, the tests for the special case pass, and the promise it broke was made to callers who are not in the diff. The one consideration that usually settles a debate: the relay's value to the organisation is proportional to how many teams can adopt it without reading its body. Every special case reduces that number, and it never goes back up.