Clarify Event.destination_id vs matched destinations

[alexluong]

Context

Event.destination_id stores the publish input — the optional destination the caller explicitly targeted when publishing an event. It does NOT represent which destinations the event was actually routed to. This distinction is already documented in code comments (#676), but the field name doesn't communicate this.

Why it's confusing

When someone reads event.destination_id, the natural interpretation is "the destination this event belongs to" or "the destination this event was delivered to." In reality it means "the destination the publisher requested" — which may not even match (e.g. if the destination is disabled or the topic/filter doesn't match, the event still stores that destination_id but routes to zero destinations).

It also creates an inconsistency at the API level: GET /events?destination_id=... would need to filter by matched destinations, not by Event.destination_id — so there's a query parameter with the same name as a field on the model but with completely different semantics.

If we later add something like matched_destination_ids (#688), having two destination-related fields with very different semantics and no obvious naming distinction makes this worse.

Options

1. Rename destination_id → target_destination_id (or requested_destination_id) — makes the intent clear, but is a breaking change across model, DB column, API request/response, and OpenAPI spec
2. Leave as-is — rely on docs to explain the difference
3. Drop destination_id from persistence — it's only used transiently during Handle() routing. After matching, the value has served its purpose. Nothing downstream reads events.destination_id from the DB. This removes the confusion entirely

Question for the team

Which approach do we want to take?

[leggetter]

The destination ID is really about the publish request, isn't it? The fact that it's stored on the event itself seems wrong. Off the top of my head, I'd probably go with option 3: I'd drop it from persistence on the event. It's only there for routing; it's not actually part of the event itself and is related to the publish-only.

[alexbouchardd]

(e.g. if the destination is disabled or the topic/filter doesn't match, the event still stores that destination_id but routes to zero destinations).

That's not correct, if it doesn't match it won't be stored, in which case I think the semantics are completely fine?

That being said I'm also okay with #3

[alexluong]

if it doesn't match it won't be stored

Yes, this is correct, if it doesn't match = the event isn't stored.

It's mainly the semantics that's confusing, especially if we're going to introduce GET /events?destination_id=...

[alexbouchardd]

Yeah, agreed